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

package/dist/agent-durable.d.ts

@@ -1,5 +1,6 @@
 import { Channel, ChannelFactory } from "@junejs/core/agent-config";
 import { AuthorizeAnswer, ChannelPolicy, InboundEvent, InputAnnouncement, Model, Msg, NoteKind, ProactiveTrigger, SessionStore, Tool, TurnError, TurnEvent, TurnFailurePhase } from "@junejs/core/agent-runtime";
+import { FileStore } from "@junejs/core/agent-files";
 import { Connection } from "@junejs/core/connections";
 import { Resources } from "@junejs/core/resources";
 //#region src/agent-durable.d.ts
@@ -63,6 +64,7 @@ export type DoAgentDef = {
   }) => void | Promise<void>;
   authorizeAnswer?: AuthorizeAnswer;
   onInputAnnouncement?: (a: InputAnnouncement) => void | Promise<void>;
+  files?: FileStore;
 };
 export declare class AgentDurableObject {
   private session;
@@ -83,6 +85,7 @@ export declare class AgentDurableObject {
   private readonly authorizeAnswer?;
   private readonly onInputAnnouncement?;
   private readonly storage;
+  private readonly files;
   private announceFailures;
   private resolveResources;
   private resolveConnections;
@@ -140,5 +143,6 @@ export declare function durableChannelSurface(getNamespace: () => DurableObjectN
   env: unknown;
   services?: (env: unknown) => unknown;
   waitUntil?: (p: Promise<unknown>) => void;
+  files?: FileStore;
 }): (req: Request) => Promise<Response | null>;
 //#endregion

package/dist/agent-durable.js

@@ -2,7 +2,8 @@ import { observeTurnEvents } from "./turn-events.js";
 import { isolateLocal } from "./isolate-local.js";
 import { assertCoreRuntimeVersion } from "./core-version.js";
 import { DeliverUnsupportedError, actionToTool, channelDispatch, resolveChannel } from "@junejs/core/agent-config";
-import { AgentSession, ResumeAuthorizationError, grantAnswer, withSystem } from "@junejs/core/agent-runtime";
+import { AgentSession, FatalToolError, ResumeAuthorizationError, grantAnswer, withSystem } from "@junejs/core/agent-runtime";
+import { blobFileStore } from "@junejs/core/agent-files";
 import { connectAll } from "@junejs/core/connections";
 import { ensureScope, runInScope } from "@junejs/db";
 //#region src/agent-durable.ts
@@ -111,6 +112,7 @@ var AgentDurableObject = class {
 	authorizeAnswer;
 	onInputAnnouncement;
 	storage;
+	files;
 	announceFailures = 0;
 	resolveResources() {
 		return this.resourcesOpened ??= Promise.resolve(typeof this.resourcesInput === "function" ? this.resourcesInput(this.doEnv) : this.resourcesInput ?? {});
@@ -145,6 +147,11 @@ var AgentDurableObject = class {
 		this.onInputAnnouncement = def.onInputAnnouncement;
 		this.storage = state.storage;
 		const name = def.name ?? "agent";
+		this.files = def.files ?? blobFileStore(async () => {
+			const blob = (await this.resolveResources()).blob;
+			if (!blob) throw new FatalToolError(`agent "${name}": no file store — declare a blob resource (DoAgentDef.resources) or pass DoAgentDef.files`);
+			return blob;
+		});
 		const sink = new InProcEventSink();
 		sink.subscribe((e) => {
 			if (e.type === "turn.started") this.armWatchdog();
@@ -202,6 +209,7 @@ var AgentDurableObject = class {
 		if (key !== void 0 && key !== "self" && stored === void 0) this.store.setSessionKey(key);
 		this.sessionKey = resolved;
 		this.session = new AgentSession(this.name, resolved, this.store, this.sink, this.model, this.tools, crossDoUnsupported, this.channelInstructions);
+		this.session.files = this.files;
 		this.session.onDequeue = (heldTurnId, held) => {
 			if (held.hostContext?.deliver && held.event) this.deliverHeld(this.session, heldTurnId, held.event);
 		};
@@ -260,7 +268,10 @@ var AgentDurableObject = class {
 			this.ready().then((resources) => runInScope({
 				resources,
 				services: this.services
-			}, () => channel.deliver(target, events, { session: this.sessionKey }))).catch(logRenderFailure).finally(() => {
+			}, () => channel.deliver(target, events, {
+				session: this.sessionKey,
+				files: this.files
+			}))).catch(logRenderFailure).finally(() => {
 				it.return?.();
 			});
 		} catch (err) {
@@ -355,7 +366,10 @@ var AgentDurableObject = class {
 					Promise.resolve().then(() => runInScope({
 						resources,
 						services: this.services
-					}, () => deliverChannel.deliver(target, events, { session: this.sessionKey }))).catch(logRenderFailure).finally(() => {
+					}, () => deliverChannel.deliver(target, events, {
+						session: this.sessionKey,
+						files: this.files
+					}))).catch(logRenderFailure).finally(() => {
 						it.return?.();
 					});
 				} catch (err) {
@@ -419,7 +433,10 @@ var AgentDurableObject = class {
 					Promise.resolve().then(() => runInScope({
 						resources,
 						services: this.services
-					}, () => resumeChannel.deliverResume(target, events, { session: this.sessionKey }))).catch(logRenderFailure).finally(() => {
+					}, () => resumeChannel.deliverResume(target, events, {
+						session: this.sessionKey,
+						files: this.files
+					}))).catch(logRenderFailure).finally(() => {
 						it.return?.();
 					});
 				} catch (err) {
@@ -612,6 +629,7 @@ function durableChannelSurface(getNamespace, opts) {
 		},
 		services: resolveServices(opts.services, opts.env, opts.agentName),
 		waitUntil: opts.waitUntil,
+		files: opts.files,
 		run: async (message, o) => {
 			const namespace = getNamespace();
 			if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");

package/dist/agent-native.d.ts

@@ -1,6 +1,7 @@
 import { SyncSqlite } from "./sqlite-driver.js";
 import { AgentDefinition, ChannelContext } from "@junejs/core/agent-config";
 import { AgentSession, ChannelPolicy, InputAnnouncement, Model, Runtime, Tool } from "@junejs/core/agent-runtime";
+import { FileStore } from "@junejs/core/agent-files";
 //#region src/agent-native.d.ts
 export type AgentDef = {
   model: Model;
@@ -12,6 +13,7 @@ export type AgentDef = {
 export declare function toAgentDef(agent: AgentDefinition, model: Model): AgentDef;
 export type NativeRuntimeOptions = {
   maxSessions?: number;
+  files?: FileStore;
 };
 export declare class NativeRuntime implements Runtime {
   private actors;
@@ -20,6 +22,7 @@ export declare class NativeRuntime implements Runtime {
   private readonly announceRetry;
   private readonly maxSessions;
   private closing;
+  readonly files: FileStore | undefined;
   constructor(agents: Record<string, AgentDef>, db: SyncSqlite, opts?: NativeRuntimeOptions);
   agentDef(name: string): AgentDef | undefined;
   session(agent: string, id: string): AgentSession;
@@ -35,7 +38,10 @@ export declare class MemoryRuntime implements Runtime {
   private readonly agents;
   private readonly announceRetry;
   private closed;
-  constructor(agents: Record<string, AgentDef>);
+  readonly files: FileStore | undefined;
+  constructor(agents: Record<string, AgentDef>, opts?: {
+    files?: FileStore;
+  });
   agentDef(name: string): AgentDef | undefined;
   session(agent: string, id: string): AgentSession;
   close(): Promise<void>;
@@ -43,16 +49,19 @@ export declare class MemoryRuntime implements Runtime {
 export type AgentBackend = "native" | "memory" | "durable";
 export type InProcessRuntime = Runtime & {
   close(): Promise<void>;
+  readonly files?: FileStore;
 };
 export declare function createAgentRuntime(agents: Record<string, AgentDef>, opts?: {
   backend?: AgentBackend;
   path?: string;
   maxSessions?: number;
+  files?: FileStore;
 }): Promise<InProcessRuntime>;
 export declare function mountAgent(agent: AgentDefinition, runtime: Runtime, opts?: {
   chatPath?: string;
   channels?: boolean;
   services?: unknown;
+  files?: FileStore;
 }): {
   surface: (req: Request) => Promise<Response | null>;
   fetch: (req: Request) => Promise<Response | null>;

package/dist/agent-native.js

@@ -158,10 +158,12 @@ var NativeRuntime = class {
 	});
 	maxSessions;
 	closing;
+	files;
 	constructor(agents, db, opts = {}) {
 		assertCoreRuntimeVersion("NativeRuntime");
 		this.agents = agents;
 		this.db = db;
+		this.files = opts.files;
 		const max = opts.maxSessions ?? 1e3;
 		if (!(Number.isInteger(max) && max >= 1) && max !== Infinity) throw new RangeError(`NativeRuntime: maxSessions must be an integer >= 1 (or Infinity for no cap), got ${max}`);
 		this.maxSessions = max;
@@ -183,7 +185,9 @@ var NativeRuntime = class {
 		if (!def) throw new Error(`unknown agent: ${agent}`);
 		const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
 		const sink = new InProcEventSink();
-		const session = wireAnnouncements(new AgentSession(agent, id, new SqliteSessionStore(this.db, key), sink, model, def.tools, this, def.channelInstructions), def, this.announceRetry);
+		const built = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), sink, model, def.tools, this, def.channelInstructions);
+		built.files = this.files;
+		const session = wireAnnouncements(built, def, this.announceRetry);
 		this.evictIdle();
 		this.actors.set(key, {
 			session,
@@ -294,9 +298,11 @@ var MemoryRuntime = class {
 		this.session(agent, id).flushAnnouncements();
 	});
 	closed = false;
-	constructor(agents) {
+	files;
+	constructor(agents, opts = {}) {
 		assertCoreRuntimeVersion("MemoryRuntime");
 		this.agents = agents;
+		this.files = opts.files;
 	}
 	agentDef(name) {
 		return this.agents[name];
@@ -311,7 +317,9 @@ var MemoryRuntime = class {
 			const store = new MemorySessionStore();
 			this.stores.set(key, store);
 			const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
-			a = wireAnnouncements(new AgentSession(agent, id, store, new InProcEventSink(), model, def.tools, this, def.channelInstructions), def, this.announceRetry);
+			const built = new AgentSession(agent, id, store, new InProcEventSink(), model, def.tools, this, def.channelInstructions);
+			built.files = this.files;
+			a = wireAnnouncements(built, def, this.announceRetry);
 			this.actors.set(key, a);
 		}
 		return a;
@@ -325,8 +333,11 @@ var MemoryRuntime = class {
 };
 async function createAgentRuntime(agents, opts = {}) {
 	const backend = opts.backend ?? "native";
-	if (backend === "memory") return new MemoryRuntime(agents);
-	if (backend === "native") return createNativeRuntime(agents, opts.path, { maxSessions: opts.maxSessions });
+	if (backend === "memory") return new MemoryRuntime(agents, { files: opts.files });
+	if (backend === "native") return createNativeRuntime(agents, opts.path, {
+		maxSessions: opts.maxSessions,
+		files: opts.files
+	});
 	throw new Error("backend 'durable' is the Cloudflare Durable Object target — construct AgentDurableObject in your worker, not via createAgentRuntime");
 }
 function warnOnDrift(agent, runtime) {
@@ -346,6 +357,7 @@ function mountAgent(agent, runtime, opts = {}) {
 	const ctx = {
 		agent,
 		services: opts.services,
+		files: opts.files ?? runtime.files,
 		run: (message, o) => runtime.session(agent.name, o?.session ?? "default").turn({
 			turnId: o?.turnId,
 			userText: message,

package/dist/app.js

@@ -5,6 +5,7 @@ import { routeProblems, scanRoutes } from "./route-scan.js";
 import { createPipeline } from "./pipeline.js";
 import { resolveBoundary } from "./segment.js";
 import { memoizeResources } from "./resources.js";
+import { localBlob } from "./blob.js";
 import { MODULE_STYLES_URL, buildModuleCss, registerCssModules } from "./css-modules.js";
 import { CLIENT_SCRIPT_URL, bundleClientSplit, findClientEntry } from "./client-bundle.js";
 import { generateIslandRegistry } from "./island-registry.js";
@@ -15,6 +16,7 @@ import { existsSync, lstatSync, realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { blobFileStore, memoryFileStore } from "@junejs/core/agent-files";
 import { routeFromModule } from "@junejs/core/route";
 import { deployOrigin, resolveAgent, resolveClientRouter, resolveSpeculationRules } from "@junejs/core/config";
 import { runWithTrace } from "@junejs/core/instrumentation";
@@ -139,7 +141,12 @@ function createApp({ appDir: appDirInput, config = {} }) {
 			const def = await discoverAgent(agentDir);
 			const backend = agent.runtime.backend === "durable" ? "native" : agent.runtime.backend;
 			const model = anthropic({ model: def.model });
-			const rt = await createAgentRuntime({ [def.name]: toAgentDef(def, model) }, { backend });
+			let blobOpened;
+			const files = backend === "memory" ? memoryFileStore() : blobFileStore(() => blobOpened ??= resources().then(async (r) => r.blob ?? await localBlob().open()));
+			const rt = await createAgentRuntime({ [def.name]: toAgentDef(def, model) }, {
+				backend,
+				files
+			});
 			agentRuntime = rt;
 			const mounted = mountAgent(def, rt, {
 				chatPath: agent.runtime.chat.path,

package/dist/core-version.js

@@ -1,6 +1,6 @@
 import * as coreRuntime from "@junejs/core/agent-runtime";
 //#region src/core-version.ts
-const EXPECTED_CORE_RUNTIME_API = 6;
+const EXPECTED_CORE_RUNTIME_API = 7;
 function assertCoreRuntimeVersion(surface) {
 	checkCoreRuntimeVersion(surface, coreRuntime.RUNTIME_API_VERSION);
 }

package/dist/index.js

@@ -6,8 +6,8 @@ import { negotiate } from "./negotiate.js";
 import { createPipeline } from "./pipeline.js";
 import { d1 } from "./d1.js";
 import { bindWorkerResources, memoizeResources } from "./resources.js";
-import { createApp } from "./app.js";
 import { localBlob, r2 } from "./blob.js";
+import { createApp } from "./app.js";
 import { loadJuneConfig } from "./config-loader.js";
 import { freezeConfig } from "./config-freeze.js";
 import { collection, entry } from "./content.js";

package/dist/sqlite-driver.d.ts

@@ -19,6 +19,7 @@ export declare function nodeSqliteHelp(nodeVersion: string): string;
 export declare function isNodeSqliteExperimentalWarning(type: unknown, message: string): boolean;
 type EmitWarning = (warning: string | Error, ...rest: unknown[]) => void;
 export declare function makeWarningFilter(original: EmitWarning): EmitWarning;
+export declare function useDurableJournal(db: SyncSqlite, path: string): SyncSqlite;
 export declare function openLocalSqliteSync(path: string): Promise<SyncSqlite>;
 export declare function openLocalSqlite(path: string): Promise<JuneDb>;
 //#endregion

package/dist/sqlite-driver.js

@@ -72,10 +72,23 @@ function makeWarningFilter(original) {
 		original(warning, ...rest);
 	};
 }
+function useDurableJournal(db, path) {
+	if (path === ":memory:" || path === "") return db;
+	try {
+		db.exec("PRAGMA journal_mode=WAL");
+		db.exec("PRAGMA synchronous=FULL");
+	} catch (err) {
+		try {
+			db.close();
+		} catch {}
+		throw err;
+	}
+	return db;
+}
 async function openLocalSqliteSync(path) {
 	if (typeof Bun !== "undefined") {
 		const { Database } = await import("bun:sqlite");
-		return new Database(path, { create: true });
+		return useDurableJournal(new Database(path, { create: true }), path);
 	}
 	const specifier = "node:sqlite";
 	let mod;
@@ -89,14 +102,14 @@ async function openLocalSqliteSync(path) {
 		process.emitWarning = originalEmitWarning;
 	}
 	const db = new mod.DatabaseSync(path);
-	return {
+	return useDurableJournal({
 		query: (sql) => db.prepare(sql),
 		exec: (sql) => db.exec(sql),
 		close: () => db.close()
-	};
+	}, path);
 }
 async function openLocalSqlite(path) {
 	return asyncSqlite(await openLocalSqliteSync(path));
 }
 //#endregion
-export { NODE_SQLITE_MIN_LTS, NODE_SQLITE_MIN_ODD, isNodeSqliteExperimentalWarning, makeWarningFilter, nodeSqliteHelp, openLocalSqlite, openLocalSqliteSync };
+export { NODE_SQLITE_MIN_LTS, NODE_SQLITE_MIN_ODD, isNodeSqliteExperimentalWarning, makeWarningFilter, nodeSqliteHelp, openLocalSqlite, openLocalSqliteSync, useDurableJournal };

package/dist/worker.js

@@ -3,6 +3,7 @@ import { compareRoutePatterns, parseSegment } from "./route-rank.js";
 import { acceptTarget } from "./negotiate.js";
 import { createPipeline } from "./pipeline.js";
 import { RESERVED_PREFIX, contentTypeFor, safeRelativePath } from "./static-files.js";
+import { blobFileStore } from "@junejs/core/agent-files";
 //#region src/worker.ts
 function compilePattern(pattern) {
 	const names = [];
@@ -88,7 +89,12 @@ function createWorker(manifest, opts = {}) {
 				channels: manifest.agentChannels,
 				env: locals?.env,
 				services: servicesProvider,
-				waitUntil: locals?.ctx?.waitUntil?.bind(locals.ctx)
+				waitUntil: locals?.ctx?.waitUntil?.bind(locals.ctx),
+				files: provider ? blobFileStore(async () => {
+					const blob = (await provider(locals?.env)).blob;
+					if (!blob) throw new Error(`agent "${agentName}": no blob resource bound in this isolate — attached files can't be read`);
+					return blob;
+				}) : void 0
 			})(req);
 		};
 	})() : void 0;

package/package.json

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

package/src/agent-durable.ts

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

package/src/agent-native.ts

@@ -3,9 +3,9 @@
 // SessionStore = a session-scoped view over one shared synchronous SQLite handle
 // (bun:sqlite under Bun, node:sqlite under Node — the same handle openLocalSqlite
 // wraps as the async JuneDb, opened here directly because the durability tx must
-// be synchronous). Broadcaster = an in-process subscriber set. Turn serialization
+// be synchronous). EventSink = an in-process subscriber set. Turn serialization
 // comes from the AgentSession actor in core. On the edge target this same shape
-// is reimplemented over a Durable Object's ctx.storage.sql (build order step 5).
+// is reimplemented over a Durable Object's ctx.storage.sql (agent-durable.ts).
 
 import {
   AgentSession,
@@ -22,6 +22,7 @@ import {
   type Tool,
 } from "@junejs/core/agent-runtime";
 import { buildSystemPrompt, channelFetch, type AgentDefinition, type ChannelContext } from "@junejs/core/agent-config";
+import type { FileStore } from "@junejs/core/agent-files";
 import { openLocalSqliteSync, type SyncSqlite } from "./sqlite-driver";
 import { assertCoreRuntimeVersion } from "./core-version";
 import { observeTurnEvents } from "./turn-events";
@@ -221,6 +222,10 @@ export type NativeRuntimeOptions = {
   // dropped; their state is in SQLite, so the next session() rebuilds them transparently.
   // Busy actors are never dropped, so the count can exceed the cap while they run.
   maxSessions?: number;
+  // Where the sessions' tools store the files they produce (docs/rfc-agent-files.md), and
+  // where mountAgent's channels read them back to deliver. Absent: ctx.files.put fails the
+  // turn naming the missing configuration.
+  files?: FileStore;
 };
 
 // The native Runtime: a registry of agent definitions over one SQLite handle,
@@ -238,11 +243,13 @@ export class NativeRuntime implements Runtime {
   private readonly announceRetry = new AnnouncementRetry((agent, id) => { void this.session(agent, id).flushAnnouncements(); });
   private readonly maxSessions: number;
   private closing: Promise<void> | undefined; // set by close() (#317)
+  readonly files: FileStore | undefined;
 
   constructor(agents: Record<string, AgentDef>, db: SyncSqlite, opts: NativeRuntimeOptions = {}) {
     assertCoreRuntimeVersion("NativeRuntime"); // #94: fail power-on, not mid-turn
     this.agents = agents;
     this.db = db;
+    this.files = opts.files;
     const max = opts.maxSessions ?? 1000;
     // At least one actor is always retained (the one being handed out), so a cap below 1
     // means nothing, and NaN would compare false and evict every idle actor on each miss.
@@ -272,7 +279,9 @@ export class NativeRuntime implements Runtime {
     if (!def) throw new Error(`unknown agent: ${agent}`);
     const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
     const sink = new InProcEventSink();
-    const session = wireAnnouncements(new AgentSession(agent, id, new SqliteSessionStore(this.db, key), sink, model, def.tools, this, def.channelInstructions), def, this.announceRetry);
+    const built = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), sink, model, def.tools, this, def.channelInstructions);
+    built.files = this.files;
+    const session = wireAnnouncements(built, def, this.announceRetry);
     this.evictIdle();
     this.actors.set(key, { session, sink });
     return session;
@@ -397,9 +406,11 @@ export class MemoryRuntime implements Runtime {
   private readonly agents: Record<string, AgentDef>;
   private readonly announceRetry = new AnnouncementRetry((agent, id) => { void this.session(agent, id).flushAnnouncements(); }); // #260
   private closed = false; // set by close() (#317)
-  constructor(agents: Record<string, AgentDef>) {
+  readonly files: FileStore | undefined;
+  constructor(agents: Record<string, AgentDef>, opts: { files?: FileStore } = {}) {
     assertCoreRuntimeVersion("MemoryRuntime"); // #94: fail power-on, not mid-turn
     this.agents = agents;
+    this.files = opts.files;
   }
   agentDef(name: string): AgentDef | undefined { return this.agents[name]; }
   session(agent: string, id: string): AgentSession {
@@ -413,7 +424,9 @@ export class MemoryRuntime implements Runtime {
       this.stores.set(key, store);
       // Same def handling as NativeRuntime: switching backend must not change behavior.
       const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
-      a = wireAnnouncements(new AgentSession(agent, id, store, new InProcEventSink(), model, def.tools, this, def.channelInstructions), def, this.announceRetry);
+      const built = new AgentSession(agent, id, store, new InProcEventSink(), model, def.tools, this, def.channelInstructions);
+      built.files = this.files;
+      a = wireAnnouncements(built, def, this.announceRetry);
       this.actors.set(key, a);
     }
     return a;
@@ -440,15 +453,15 @@ export type AgentBackend = "native" | "memory" | "durable";
 // target is the DO the worker constructs, not an in-process object) — so the
 // choice is explicit and a mis-selection fails loudly.
 // An in-process runtime: a Runtime the host owns, so it can shut it down (#317).
-export type InProcessRuntime = Runtime & { close(): Promise<void> };
+export type InProcessRuntime = Runtime & { close(): Promise<void>; readonly files?: FileStore };
 
 export async function createAgentRuntime(
   agents: Record<string, AgentDef>,
-  opts: { backend?: AgentBackend; path?: string; maxSessions?: number } = {},
+  opts: { backend?: AgentBackend; path?: string; maxSessions?: number; files?: FileStore } = {},
 ): Promise<InProcessRuntime> {
   const backend = opts.backend ?? "native";
-  if (backend === "memory") return new MemoryRuntime(agents);
-  if (backend === "native") return createNativeRuntime(agents, opts.path, { maxSessions: opts.maxSessions });
+  if (backend === "memory") return new MemoryRuntime(agents, { files: opts.files });
+  if (backend === "native") return createNativeRuntime(agents, opts.path, { maxSessions: opts.maxSessions, files: opts.files });
   throw new Error("backend 'durable' is the Cloudflare Durable Object target — construct AgentDurableObject in your worker, not via createAgentRuntime");
 }
 
@@ -485,7 +498,7 @@ function warnOnDrift(agent: AgentDefinition, runtime: Runtime) {
 export function mountAgent(
   agent: AgentDefinition,
   runtime: Runtime,
-  opts: { chatPath?: string; channels?: boolean; services?: unknown } = {},
+  opts: { chatPath?: string; channels?: boolean; services?: unknown; files?: FileStore } = {},
 ): {
   surface: (req: Request) => Promise<Response | null>;
   fetch: (req: Request) => Promise<Response | null>;
@@ -498,6 +511,8 @@ export function mountAgent(
   const ctx: ChannelContext = {
     agent,
     services: opts.services, // same DI bag reachable from channel hooks (parity with durableChannelSurface)
+    // The runtime's file store, so a channel can deliver the files the turn's tools stored.
+    files: opts.files ?? (runtime as { files?: FileStore }).files,
     run: (message, o) =>
       runtime.session(agent.name, o?.session ?? "default").turn({ turnId: o?.turnId, userText: message, event: o?.event, trigger: o?.trigger, replace: o?.replace }),
     // FIRE-AND-FORGET (#77): start() without awaiting the result. Native has no waitUntil

package/src/app.ts

@@ -25,6 +25,8 @@ import {
 } from "@junejs/core/config";
 import type { DocumentConfig } from "@junejs/core/document";
 import { runWithTrace, type RequestTrace } from "@junejs/core/instrumentation";
+import { blobFileStore, memoryFileStore } from "@junejs/core/agent-files";
+import type { JuneBlob } from "@junejs/core/resources";
 
 import { findMiddlewareFile, isResourceFile, listRoutes, matchRouteTree, resolveNotFound, routeFiles, type SegmentMatch } from "./router";
 import { routeProblems, scanRoutes } from "./route-scan";
@@ -34,6 +36,7 @@ import { createAgentRuntime, mountAgent, toAgentDef, type InProcessRuntime } fro
 import { anthropic } from "@junejs/core/agent-models";
 import { resolveBoundary } from "./segment";
 import { memoizeResources } from "./resources";
+import { localBlob } from "./blob";
 import {
   findClientEntry,
   bundleClientSplit,
@@ -270,7 +273,15 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
       const model = anthropic({ model: def.model });
       // toAgentDef: tools, prompt AND the per-surface policies (#149) from the one
       // definition — channelInstructions was previously dropped on this path (#173).
-      const rt = await createAgentRuntime({ [def.name]: toAgentDef(def, model) }, { backend });
+      // Agent files (docs/rfc-agent-files.md) live in the app's blob resource; an app that
+      // declares none gets the local default directory. The memory backend keeps them in
+      // memory, like everything else it holds.
+      let blobOpened: Promise<JuneBlob> | undefined;
+      const files =
+        backend === "memory"
+          ? memoryFileStore()
+          : blobFileStore(() => (blobOpened ??= resources().then(async (r) => r.blob ?? (await localBlob().open()))));
+      const rt = await createAgentRuntime({ [def.name]: toAgentDef(def, model) }, { backend, files });
       agentRuntime = rt;
       const mounted = mountAgent(def, rt, { chatPath: agent.runtime.chat.path, channels: agent.runtime.channels });
       agentSurface = (req) => mounted.surface(req);

package/src/core-version.ts

@@ -15,7 +15,7 @@ import * as coreRuntime from "@junejs/core/agent-runtime";
 
 // The contract number this server tree is built against. Bump in lockstep with
 // core's RUNTIME_API_VERSION whenever the server↔core runtime contract changes.
-const EXPECTED_CORE_RUNTIME_API = 6;
+const EXPECTED_CORE_RUNTIME_API = 7;
 
 export function assertCoreRuntimeVersion(surface: string): void {
   checkCoreRuntimeVersion(surface, (coreRuntime as { RUNTIME_API_VERSION?: number }).RUNTIME_API_VERSION);

package/src/sqlite-driver.ts

@@ -135,6 +135,33 @@ export function makeWarningFilter(original: EmitWarning): EmitWarning {
 // runtime, which is exactly what the typeof guard checks.
 declare const Bun: unknown;
 
+// A file database commits durably: WAL, fsynced on every commit. SQLite's default
+// rollback journal (DELETE mode) commits by unlinking the journal, and at
+// synchronous=FULL it does not fsync the directory after that unlink — so a power
+// cut right after a commit can bring the journal back, and the next open rolls the
+// committed transaction back. On a VM power cut that lost the last committed agent
+// turn 5 times out of 5; with WAL + FULL, 0 of 5. FULL is set explicitly: it is a
+// build-time default, and WAL at synchronous=NORMAL skips the per-commit fsync.
+// journal_mode=WAL persists in the file; `:memory:` has no journal to change.
+// A PRAGMA that throws (a locked file mid-switch) closes the handle it was handed,
+// so a retry is not blocked by a descriptor nobody can reach; the original error
+// is what surfaces. Exported for the unit test of that path.
+export function useDurableJournal(db: SyncSqlite, path: string): SyncSqlite {
+  if (path === ":memory:" || path === "") return db;
+  try {
+    db.exec("PRAGMA journal_mode=WAL");
+    db.exec("PRAGMA synchronous=FULL");
+  } catch (err) {
+    try {
+      db.close();
+    } catch {
+      // the setup error is the one worth reporting
+    }
+    throw err;
+  }
+  return db;
+}
+
 // Open a LOCAL *synchronous* sqlite handle on whichever runtime we're under —
 // bun:sqlite under Bun, node:sqlite under Node. This is the raw synchronous
 // surface: asyncSqlite() wraps it as the edge-safe async JuneDb (below), while
@@ -148,7 +175,7 @@ export async function openLocalSqliteSync(path: string): Promise<SyncSqlite> {
     const { Database } = (await import(specifier)) as {
       Database: new (p: string, o?: { create?: boolean }) => SyncSqlite;
     };
-    return new Database(path, { create: true });
+    return useDurableJournal(new Database(path, { create: true }), path);
   }
 
   // Node: node:sqlite is a builtin, but only flag-free on a recent-enough
@@ -172,11 +199,14 @@ export async function openLocalSqliteSync(path: string): Promise<SyncSqlite> {
   }
   const db = new mod.DatabaseSync(path);
   // Adapt node:sqlite (prepare()) to the query()-shaped SyncSqlite surface.
-  return {
-    query: (sql) => db.prepare(sql),
-    exec: (sql) => db.exec(sql),
-    close: () => db.close(),
-  };
+  return useDurableJournal(
+    {
+      query: (sql) => db.prepare(sql),
+      exec: (sql) => db.exec(sql),
+      close: () => db.close(),
+    },
+    path,
+  );
 }
 
 // Open a LOCAL sqlite file (or ":memory:") as the async JuneDb — the single seam

package/src/worker.ts

@@ -18,6 +18,7 @@ import type { I18nConfig } from "@junejs/core/i18n";
 import type { Resources } from "@junejs/core/resources";
 
 import type { Channel, ChannelFactory } from "@junejs/core/agent-config";
+import { blobFileStore } from "@junejs/core/agent-files";
 
 import { createPipeline, type ExtraHandler, type LayoutComponent, type LoadingComponent, type Resolved, type ResolvedResource, type ResourceHandler } from "./pipeline";
 import { durableAgentSurface, durableChannelSurface, type DurableObjectNamespace } from "./agent-durable";
@@ -219,6 +220,15 @@ export function createWorker(
               env: locals?.env,
               services: servicesProvider,
               waitUntil: locals?.ctx?.waitUntil?.bind(locals.ctx),
+              // The blob resource the agent's Durable Object stores files in, opened from
+              // this isolate's env — the channels read attached files back from it.
+              files: provider
+                ? blobFileStore(async () => {
+                    const blob = (await provider(locals?.env)).blob;
+                    if (!blob) throw new Error(`agent "${agentName}": no blob resource bound in this isolate — attached files can't be read`);
+                    return blob;
+                  })
+                : undefined,
             });
             return channels(req);
           };