@aigne/afs-ash 1.11.0-beta.12

package/dist/index.mjs

@@ -0,0 +1,1715 @@
+import { readFileSync } from "node:fs";
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AFSNotFoundError, createProgramAFS, parseProgramManifest } from "@aigne/afs";
+import { AFSBaseProvider, Actions, Delete, Exec, Explain, List, Meta, Read, Search, Stat, Write } from "@aigne/afs/provider";
+import { ASH_REFERENCE, compileSource } from "@aigne/ash";
+import { Cron, CronPattern } from "croner";
+import { joinURL } from "ufo";
+import { parse } from "yaml";
+import { z } from "zod";
+
+//#region \0@oxc-project+runtime@0.108.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+//#endregion
+//#region src/index.ts
+const DOCS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "docs");
+function readDoc(relativePath) {
+	return readFileSync(join(DOCS_DIR, relativePath), "utf-8");
+}
+/**
+* Derive tool declarations for agent-run from a ProgramManifest.
+*
+* Generates tools for:
+* - `/program/**` — readonly (read, list, search, stat)
+* - `/data/**` — readwrite (read, list, write, delete, search, stat)
+* - `/{target}/**` — per mount ops from manifest
+*/
+function deriveToolsFromProgram(manifest) {
+	const tools = [{
+		path: "/program/**",
+		ops: [
+			"read",
+			"list",
+			"search",
+			"stat"
+		],
+		maxDepth: 10
+	}, {
+		path: "/data/**",
+		ops: [
+			"read",
+			"list",
+			"write",
+			"delete",
+			"search",
+			"stat"
+		],
+		maxDepth: 10
+	}];
+	for (const mount of manifest.mounts) {
+		const ops = mount.ops ?? ["read", "list"];
+		if (ops.length === 0) continue;
+		tools.push({
+			path: `${mount.target}/**`,
+			ops: [...ops],
+			maxDepth: 5
+		});
+	}
+	return tools;
+}
+function sanitizeErrorPath(msg) {
+	return msg.replace(/'\/[^']*'/g, "'[path]'").replace(/"\/[^"]*"/g, "\"[path]\"");
+}
+function normalizeContent(content) {
+	if (content == null) return {};
+	if (typeof content === "object" && !Array.isArray(content)) return {
+		content,
+		...content
+	};
+	if (typeof content === "string") try {
+		const parsed = parse(content);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return {
+			content,
+			...parsed
+		};
+	} catch {}
+	return { content };
+}
+/**
+* AFS ASH Provider
+*
+* Bridges ASH pipeline DSL to AFS. ASH scripts are stored in-memory and
+* executed against AFS via a world bridge that translates ASH's
+* read/write/publish to AFS read/write operations.
+*
+* Structure:
+* - `/` - root directory
+* - `/scripts` - stored .ash scripts
+* - `/scripts/{name}.ash` - individual script files (executable)
+* - `/.actions/run` - execute inline ASH code
+* - `/.actions/validate` - validate ASH source (compile + type-check)
+*/
+var AFSAsh = class AFSAsh extends AFSBaseProvider {
+	static manifest() {
+		return {
+			name: "ash",
+			description: "ASH pipeline DSL for deterministic data pipelines.\n- Store, validate, and execute ASH scripts\n- Commands: find, where, map, save, publish, tee, fanout, output, input, count, group-by, action, route, lookup\n- Read /.meta/.ash-reference for full syntax",
+			uriTemplate: "ash://",
+			category: "compute",
+			schema: z.object({
+				name: z.string().optional(),
+				description: z.string().optional(),
+				allowRootActions: z.array(z.enum([
+					"agent-run",
+					"mount",
+					"unmount",
+					"read",
+					"list",
+					"write",
+					"delete"
+				])).optional()
+			}),
+			tags: [
+				"ash",
+				"pipeline",
+				"etl",
+				"dsl"
+			],
+			capabilityTags: [
+				"read-write",
+				"search",
+				"auth:none",
+				"local"
+			],
+			security: {
+				riskLevel: "system",
+				resourceAccess: ["process-spawn"],
+				dataSensitivity: ["code"],
+				notes: ["Executes ASH pipeline scripts that can read/write data across mounted providers"]
+			},
+			capabilities: { crossProvider: { afsAccess: true } }
+		};
+	}
+	static treeSchema() {
+		return {
+			operations: [
+				"list",
+				"read",
+				"write",
+				"delete",
+				"exec",
+				"search",
+				"stat",
+				"explain"
+			],
+			tree: {
+				"/": {
+					kind: "ash:root",
+					operations: [
+						"list",
+						"read",
+						"exec"
+					],
+					actions: ["run", "validate"]
+				},
+				"/scripts": {
+					kind: "ash:directory",
+					operations: ["list", "read"]
+				},
+				"/scripts/{name}.ash": {
+					kind: "ash:script",
+					operations: [
+						"read",
+						"write",
+						"delete",
+						"exec"
+					],
+					actions: ["exec"]
+				}
+			},
+			auth: { type: "none" },
+			bestFor: [
+				"data pipelines",
+				"ETL scripts",
+				"deterministic DSL"
+			],
+			notFor: ["general-purpose code"]
+		};
+	}
+	static async load({ config } = {}) {
+		return new AFSAsh(config);
+	}
+	name;
+	description;
+	accessMode = "readwrite";
+	scripts = /* @__PURE__ */ new Map();
+	afsRoot;
+	scriptsDir;
+	dataDir;
+	allowRootActions;
+	triggerSubs = /* @__PURE__ */ new Map();
+	cronJobs = /* @__PURE__ */ new Map();
+	externalScripts = /* @__PURE__ */ new Map();
+	externalScriptSubs = [];
+	dirsReady = false;
+	constructor(options = {}) {
+		super();
+		this.name = options.name ?? "ash";
+		this.description = options.description ?? "ASH pipeline DSL for deterministic data pipelines";
+		this.scriptsDir = options.scriptsDir;
+		this.dataDir = options.dataDir;
+		const rawAllow = options.allowRootActions;
+		const allowList = Array.isArray(rawAllow) ? rawAllow : typeof rawAllow === "string" ? [rawAllow] : ["agent-run"];
+		const validActions = new Set([
+			"agent-run",
+			"mount",
+			"unmount",
+			"read",
+			"list",
+			"write",
+			"delete"
+		]);
+		const normalized = allowList.filter((a) => validActions.has(a));
+		this.allowRootActions = new Set(normalized.length > 0 ? normalized : ["agent-run"]);
+	}
+	async ready() {
+		if (this.dirsReady) return;
+		if (this.scriptsDir) await mkdir(this.scriptsDir, { recursive: true });
+		if (this.dataDir) await mkdir(this.dataDir, { recursive: true });
+		this.dirsReady = true;
+	}
+	async ensureDirs() {
+		if (!this.dirsReady) await this.ready();
+	}
+	async getScript(name) {
+		if (this.scriptsDir) {
+			const filePath = join(this.scriptsDir, `${name}.ash`);
+			try {
+				return {
+					source: await readFile(filePath, "utf-8"),
+					createdAt: /* @__PURE__ */ new Date(),
+					updatedAt: /* @__PURE__ */ new Date()
+				};
+			} catch {
+				return;
+			}
+		}
+		return this.scripts.get(name);
+	}
+	async setScript(name, script) {
+		if (this.scriptsDir) {
+			await this.ensureDirs();
+			await writeFile(join(this.scriptsDir, `${name}.ash`), script.source, "utf-8");
+		}
+		this.scripts.set(name, script);
+	}
+	async hasScript(name) {
+		if (this.scriptsDir) try {
+			await stat(join(this.scriptsDir, `${name}.ash`));
+			return true;
+		} catch {
+			return false;
+		}
+		return this.scripts.has(name);
+	}
+	async removeScript(name) {
+		if (this.scriptsDir) try {
+			await rm(join(this.scriptsDir, `${name}.ash`));
+		} catch {}
+		this.scripts.delete(name);
+	}
+	async getAllScriptNames() {
+		if (this.scriptsDir) try {
+			return (await readdir(this.scriptsDir)).filter((f) => f.endsWith(".ash")).map((f) => f.replace(/\.ash$/, ""));
+		} catch {
+			return [];
+		}
+		return Array.from(this.scripts.keys());
+	}
+	async getScriptCount() {
+		return (await this.getAllScriptNames()).length;
+	}
+	/** Sanitize an ASH path to a flat filename: /data/clean → data%2Fclean.json */
+	dataFileName(path) {
+		return `${path.replace(/^\/+/, "").replace(/\//g, "%2F")}.json`;
+	}
+	/** Persist save output to dataDir */
+	async persistData(path, data) {
+		if (!this.dataDir) return;
+		await this.ensureDirs();
+		await writeFile(join(this.dataDir, this.dataFileName(path)), JSON.stringify(data), "utf-8");
+	}
+	/** Load all persisted data files into a dataStore */
+	async loadPersistedData() {
+		const store = {};
+		if (!this.dataDir) return store;
+		try {
+			const files = await readdir(this.dataDir);
+			for (const file of files) {
+				if (!file.endsWith(".json")) continue;
+				const key = `/${file.replace(/\.json$/, "").replace(/%2F/gi, "/")}`;
+				try {
+					store[key] = JSON.parse(await readFile(join(this.dataDir, file), "utf-8"));
+				} catch {}
+			}
+		} catch {}
+		return store;
+	}
+	onMount(afs) {
+		this.destroy();
+		this.afsRoot = afs;
+		this.initTriggers().catch(() => {});
+		if (afs.subscribe) this.externalScriptSubs = [afs.subscribe({ type: "script:registered" }, (evt) => {
+			if (evt.data?.runtime !== "ash") return;
+			this.registerExternalScript(evt.path).catch(() => {});
+		}), afs.subscribe({ type: "script:unregistered" }, (evt) => {
+			if (evt.data?.runtime !== "ash") return;
+			this.unregisterExternalScript(evt.path);
+		})];
+	}
+	async registerExternalScript(path) {
+		const afs = this.afsRoot;
+		if (!afs?.read) return;
+		try {
+			const file = await afs.read(path, {});
+			const source = String(file.data?.content ?? "");
+			if (!source.trim()) return;
+			this.externalScripts.set(path, source);
+			this.registerTriggers(path, source);
+		} catch {}
+	}
+	unregisterExternalScript(path) {
+		this.externalScripts.delete(path);
+		this.unregisterTriggers(path);
+	}
+	/** Stop all cron jobs and unsubscribe all event triggers. Call on provider teardown. */
+	destroy() {
+		const allNames = new Set([...this.triggerSubs.keys(), ...this.cronJobs.keys()]);
+		for (const name of allNames) this.unregisterTriggers(name);
+		for (const unsub of this.externalScriptSubs) unsub();
+		this.externalScriptSubs = [];
+		this.externalScripts.clear();
+	}
+	async initTriggers() {
+		await this.ensureDirs();
+		for (const name of await this.getAllScriptNames()) {
+			const script = await this.getScript(name);
+			if (script) this.registerTriggers(name, script.source);
+		}
+	}
+	/**
+	* Register EventBus subscriptions and cron schedules for all triggers in a script.
+	* Replaces any previous subscriptions/schedules for the same script name.
+	*/
+	registerTriggers(scriptName, source) {
+		this.unregisterTriggers(scriptName);
+		const result = compileSource(source);
+		if (!result.program) return;
+		const afs = this.afsRoot;
+		const unsubs = [];
+		const crons = [];
+		for (const unit of result.program.units) {
+			if (unit.kind !== "job" || !unit.trigger) continue;
+			const jobName = unit.name;
+			const trigger = unit.trigger;
+			if (trigger.kind === "event") {
+				if (!afs?.subscribe) continue;
+				const filter = { path: trigger.path };
+				const unsub = afs.subscribe(filter, (evt) => {
+					this.executeTriggerJob(scriptName, jobName, evt);
+				});
+				unsubs.push(unsub);
+			} else if (trigger.kind === "cron") try {
+				new CronPattern(trigger.expression);
+				const cron = new Cron(trigger.expression, { protect: true }, () => {
+					const syntheticEvent = {
+						type: "cron",
+						path: `/cron/${scriptName}/${jobName}`,
+						source: "ash-cron",
+						timestamp: Date.now()
+					};
+					this.executeTriggerJob(scriptName, jobName, syntheticEvent);
+				});
+				crons.push(cron);
+			} catch (err) {
+				console.error(`[ASH cron] Invalid cron expression "${trigger.expression}" in ${scriptName}/${jobName}:`, err);
+			}
+		}
+		if (unsubs.length > 0) this.triggerSubs.set(scriptName, unsubs);
+		if (crons.length > 0) this.cronJobs.set(scriptName, crons);
+	}
+	/** Unsubscribe all event triggers and stop all cron jobs for a given script. */
+	unregisterTriggers(scriptName) {
+		const unsubs = this.triggerSubs.get(scriptName);
+		if (unsubs) {
+			for (const unsub of unsubs) unsub();
+			this.triggerSubs.delete(scriptName);
+		}
+		const crons = this.cronJobs.get(scriptName);
+		if (crons) {
+			for (const cron of crons) cron.stop();
+			this.cronJobs.delete(scriptName);
+		}
+	}
+	/**
+	* Execute a single triggered job reactively in response to an AFS event.
+	* Re-compiles the script, builds a bridged world context, executes the
+	* target job with event data as the initial stream, and writes results
+	* back to AFS.
+	*/
+	async executeTriggerJob(scriptName, jobName, event) {
+		try {
+			let source;
+			const script = await this.getScript(scriptName);
+			if (script) source = script.source;
+			else if (this.externalScripts.has(scriptName)) source = this.externalScripts.get(scriptName);
+			else if (this.afsRoot?.read) try {
+				const file = await this.afsRoot.read(scriptName, {});
+				source = String(file.data?.content ?? "");
+			} catch {}
+			if (!source) return;
+			const result = compileSource(source);
+			if (!result.program) return;
+			const job = result.program.units.find((u) => u.kind === "job" && u.name === jobName);
+			if (!job || job.kind !== "job") return;
+			const { world, written } = await this.createAsyncWorld();
+			const ctx = {
+				world: this.afsRoot ? {
+					read: async (path) => {
+						const local = await world.read(path);
+						if (local.length > 0) return local;
+						if (this.afsRoot?.list) {
+							const listResult = await this.afsRoot.list(path, {});
+							if (listResult.data.length > 0) {
+								const needsEnrich = listResult.data.some((e) => e.content == null);
+								let entries = listResult.data;
+								if (needsEnrich && this.afsRoot.read) {
+									const afsRead = this.afsRoot.read.bind(this.afsRoot);
+									entries = await Promise.all(listResult.data.map(async (e) => {
+										if (e.content != null) return e;
+										try {
+											const r = await afsRead(e.path, {});
+											return r.data ? {
+												...e,
+												content: r.data.content
+											} : e;
+										} catch {
+											return e;
+										}
+									}));
+								}
+								return entries.map((entry) => ({
+									path: entry.path,
+									name: entry.path.split("/").filter(Boolean).pop(),
+									...entry.meta,
+									...normalizeContent(entry.content)
+								}));
+							}
+						}
+						if (this.afsRoot?.read) try {
+							const readResult = await this.afsRoot.read(path, {});
+							if (readResult.data) {
+								const entry = readResult.data;
+								return [{
+									path: entry.path ?? path,
+									name: (entry.path ?? path).split("/").filter(Boolean).pop(),
+									...entry.meta,
+									...normalizeContent(entry.content)
+								}];
+							}
+						} catch {}
+						return [];
+					},
+					write: (path, data) => {
+						world.write(path, data);
+					},
+					publish: (topic, data) => {
+						world.publish(topic, data);
+					},
+					exec: world.exec
+				} : world,
+				caps: new Set(["*"]),
+				logger: { log() {} },
+				output: { output() {} }
+			};
+			const initialStream = [{ ...event }];
+			const jobResult = await job.execute(ctx, initialStream);
+			if (jobResult.status !== "ok") console.error(`[ASH trigger] ${scriptName}/${jobName} status=${jobResult.status}`, jobResult.errors);
+			const afs = this.afsRoot;
+			if (afs?.write) for (const [path, data] of Object.entries(written)) {
+				const content = JSON.stringify(data);
+				await afs.write(path, { content });
+			}
+		} catch (err) {
+			console.error(`[ASH trigger] ${scriptName}/${jobName} threw:`, err);
+		}
+	}
+	async listRoot(_ctx) {
+		return { data: [{
+			id: "/scripts",
+			path: "/scripts",
+			summary: "Stored ASH scripts",
+			meta: {
+				kind: "ash:directory",
+				type: "directory",
+				childrenCount: await this.getScriptCount()
+			}
+		}, {
+			id: "/cookbook",
+			path: "/cookbook",
+			summary: "ASH best practices and quick reference",
+			meta: {
+				kind: "ash:directory",
+				type: "directory",
+				childrenCount: 2
+			}
+		}] };
+	}
+	async listScripts(_ctx) {
+		const entries = [];
+		for (const name of await this.getAllScriptNames()) {
+			const script = await this.getScript(name);
+			if (!script) continue;
+			entries.push(this.buildScriptEntry(name, script));
+		}
+		return { data: entries };
+	}
+	async listScript(ctx) {
+		const name = ctx.params.scriptName.replace(/\.ash$/, "");
+		if (!await this.hasScript(name)) throw new AFSNotFoundError(ctx.path);
+		return { data: [] };
+	}
+	async listRootActions(_ctx) {
+		return { data: [
+			{
+				id: "run",
+				path: "/.actions/run",
+				summary: "Execute inline ASH code",
+				meta: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"],
+					name: "run",
+					description: "Execute inline ASH pipeline code",
+					inputSchema: {
+						type: "object",
+						properties: {
+							source: {
+								type: "string",
+								description: "ASH pipeline source code. Read /.meta/.ash-reference for syntax."
+							},
+							caps: {
+								type: "array",
+								items: { type: "string" },
+								description: "Capability paths. Required for write-back to AFS (default: no write-back without caps)"
+							}
+						},
+						required: ["source"]
+					}
+				}
+			},
+			{
+				id: "validate",
+				path: "/.actions/validate",
+				summary: "Validate ASH source code",
+				meta: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"],
+					name: "validate",
+					description: "Compile and type-check ASH source, return diagnostics",
+					inputSchema: {
+						type: "object",
+						properties: { source: {
+							type: "string",
+							description: "ASH pipeline source code to validate. Read /.meta/.ash-reference for syntax."
+						} },
+						required: ["source"]
+					}
+				}
+			},
+			{
+				id: "agent-run",
+				path: "/.actions/agent-run",
+				summary: "Run a single-task agentic loop",
+				meta: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"],
+					name: "agent-run",
+					description: "Execute a multi-round agentic loop: LLM inference → tool_call validation → ASH execution → result feedback. Stops when the LLM returns text or budget exhausts.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							task: {
+								type: "string",
+								description: "The task for the agent to accomplish"
+							},
+							model: {
+								type: "string",
+								description: "AigneHub model path, e.g. /modules/aignehub/defaults/chat"
+							},
+							tools: {
+								oneOf: [{
+									type: "array",
+									items: {
+										type: "object",
+										properties: {
+											path: {
+												type: "string",
+												description: "AFS path pattern. Use * for single-level glob, ** for multi-level glob"
+											},
+											ops: {
+												type: "array",
+												items: {
+													type: "string",
+													enum: [
+														"read",
+														"list",
+														"exec",
+														"search",
+														"write",
+														"stat",
+														"explain"
+													]
+												}
+											},
+											exclude_actions: {
+												type: "array",
+												items: { type: "string" },
+												description: "Action names to exclude from exec"
+											},
+											maxDepth: {
+												type: "number",
+												description: "Max directory depth for ** glob (default: 0, i.e. ** with no maxDepth matches nothing)"
+											}
+										},
+										required: ["path", "ops"]
+									}
+								}, {
+									type: "string",
+									enum: ["none"],
+									description: "Use 'none' for no tools (LLM-only)"
+								}],
+								description: "AFS capabilities the agent may use, or 'none' for LLM-only mode"
+							},
+							budget: {
+								type: "object",
+								properties: {
+									max_rounds: {
+										type: "number",
+										description: "Max LLM rounds (default 20)"
+									},
+									actions_per_round: {
+										type: "number",
+										description: "Max tool calls per round (default 10)"
+									},
+									total_tokens: {
+										type: "number",
+										description: "Token budget across all rounds"
+									}
+								}
+							},
+							system: {
+								type: "string",
+								description: "System prompt for the LLM"
+							}
+						},
+						required: ["task", "model"]
+					}
+				}
+			}
+		] };
+	}
+	async listScriptActions(ctx) {
+		const name = ctx.params.scriptName.replace(/\.ash$/, "");
+		const script = await this.getScript(name);
+		if (!script) throw new AFSNotFoundError(ctx.path);
+		const inputSchema = this.buildScriptExecInputSchema(script.source);
+		return { data: [{
+			id: "exec",
+			path: joinURL(joinURL("/scripts", ctx.params.scriptName, ".actions"), "exec"),
+			summary: `Execute script ${name}`,
+			meta: {
+				kind: "afs:executable",
+				kinds: ["afs:executable", "afs:node"],
+				name: "exec",
+				description: `Execute the ${name} ASH script`,
+				inputSchema
+			}
+		}] };
+	}
+	async readRoot(_ctx) {
+		return {
+			id: "/",
+			path: "/",
+			meta: {
+				type: "directory",
+				childrenCount: 2
+			},
+			actions: [{
+				name: "run",
+				description: "Execute inline ASH code"
+			}, {
+				name: "validate",
+				description: "Validate ASH source code"
+			}]
+		};
+	}
+	async readScriptsDir(_ctx) {
+		return {
+			id: "/scripts",
+			path: "/scripts",
+			summary: "Stored ASH scripts",
+			meta: {
+				kind: "ash:directory",
+				type: "directory",
+				childrenCount: await this.getScriptCount()
+			}
+		};
+	}
+	async readScript(ctx) {
+		const name = ctx.params.scriptName.replace(/\.ash$/, "");
+		const script = await this.getScript(name);
+		if (!script) throw new AFSNotFoundError(ctx.path, `Script not found: ${name}`);
+		return this.buildScriptEntry(name, script);
+	}
+	static COOKBOOK_FILES = ["patterns.md", "quickref.md"];
+	async listCookbook(_ctx) {
+		return { data: AFSAsh.COOKBOOK_FILES.map((file) => ({
+			id: joinURL("/cookbook", file),
+			path: joinURL("/cookbook", file),
+			summary: file === "patterns.md" ? "agent-run patterns and pitfalls" : "Quick reference card",
+			meta: { kind: "ash:documentation" }
+		})) };
+	}
+	async readCookbookDir(_ctx) {
+		return {
+			id: "/cookbook",
+			path: "/cookbook",
+			meta: {
+				kind: "ash:directory",
+				type: "directory",
+				childrenCount: AFSAsh.COOKBOOK_FILES.length
+			}
+		};
+	}
+	async listCookbookFile(_ctx) {
+		return { data: [] };
+	}
+	async readCookbook(ctx) {
+		const file = ctx.params.file;
+		if (!AFSAsh.COOKBOOK_FILES.includes(file)) throw new AFSNotFoundError(ctx.path);
+		return {
+			id: joinURL("/cookbook", file),
+			path: joinURL("/cookbook", file),
+			content: readDoc(joinURL("cookbook", file)),
+			meta: { kind: "ash:documentation" }
+		};
+	}
+	async readAgentMd(_ctx) {
+		return {
+			id: "/.meta/agent.md",
+			path: "/.meta/agent.md",
+			content: readDoc("agent.md"),
+			meta: {
+				kind: "ash:documentation",
+				description: "ASH agent usage guide"
+			}
+		};
+	}
+	async readAshReference(_ctx) {
+		return {
+			id: "/.meta/.ash-reference",
+			path: "/.meta/.ash-reference",
+			content: ASH_REFERENCE,
+			meta: {
+				kind: "ash:reference",
+				description: "ASH language reference for writing valid ASH pipelines"
+			}
+		};
+	}
+	async readCapabilities(_ctx) {
+		return {
+			id: "/.meta/.capabilities",
+			path: "/.meta/.capabilities",
+			content: {
+				schemaVersion: 1,
+				provider: this.name,
+				description: `${this.description}. Read /.meta/.ash-reference for ASH syntax.`,
+				tools: [],
+				operations: this.getOperationsDeclaration(),
+				actions: [{
+					description: "Root-level ASH actions",
+					catalog: [{
+						name: "run",
+						description: "Execute inline ASH code"
+					}, {
+						name: "validate",
+						description: "Validate ASH source code"
+					}],
+					discovery: { pathTemplate: "/.actions" }
+				}, {
+					kind: "ash:script",
+					description: "Script-level actions",
+					catalog: [{
+						name: "exec",
+						description: "Execute the script"
+					}],
+					discovery: { pathTemplate: "/scripts/:scriptName/.actions" }
+				}]
+			},
+			meta: {
+				kind: "afs:capabilities",
+				description: "ASH provider capabilities manifest",
+				operations: [
+					"list",
+					"read",
+					"write",
+					"delete",
+					"exec",
+					"stat",
+					"explain",
+					"search"
+				]
+			}
+		};
+	}
+	async readRootMeta(_ctx) {
+		return {
+			id: "/.meta",
+			path: "/.meta",
+			content: {
+				type: "directory",
+				childrenCount: 2
+			},
+			meta: {
+				type: "directory",
+				childrenCount: 2
+			}
+		};
+	}
+	async readCookbookMeta(_ctx) {
+		return {
+			id: "/cookbook/.meta",
+			path: "/cookbook/.meta",
+			content: {
+				kind: "ash:directory",
+				type: "directory",
+				childrenCount: AFSAsh.COOKBOOK_FILES.length
+			},
+			meta: {
+				kind: "ash:directory",
+				type: "directory",
+				childrenCount: AFSAsh.COOKBOOK_FILES.length
+			}
+		};
+	}
+	async readCookbookFileMeta(ctx) {
+		return {
+			id: joinURL("/cookbook", ctx.params.file, ".meta"),
+			path: joinURL("/cookbook", ctx.params.file, ".meta"),
+			content: { kind: "ash:documentation" },
+			meta: { kind: "ash:documentation" }
+		};
+	}
+	async readScriptsMeta(_ctx) {
+		return {
+			id: "/scripts/.meta",
+			path: "/scripts/.meta",
+			content: {
+				type: "directory",
+				childrenCount: await this.getScriptCount()
+			},
+			meta: {
+				type: "directory",
+				childrenCount: await this.getScriptCount()
+			}
+		};
+	}
+	async readScriptMeta(ctx) {
+		const name = ctx.params.scriptName.replace(/\.ash$/, "");
+		const script = await this.getScript(name);
+		if (!script) throw new AFSNotFoundError(ctx.path, `Script not found: ${name}`);
+		const entry = this.buildScriptEntry(name, script);
+		return {
+			id: joinURL("/scripts", ctx.params.scriptName, ".meta"),
+			path: joinURL("/scripts", ctx.params.scriptName, ".meta"),
+			content: entry.meta ?? {},
+			meta: entry.meta ?? {}
+		};
+	}
+	async writeScript(ctx, entry) {
+		const name = ctx.params.scriptName.replace(/\.ash$/, "");
+		const now = /* @__PURE__ */ new Date();
+		const existing = await this.getScript(name);
+		const rawContent = typeof entry === "string" ? entry : entry.content;
+		if (rawContent === void 0 && existing) {
+			const stored$1 = {
+				source: existing.source,
+				createdAt: existing.createdAt,
+				updatedAt: now
+			};
+			await this.setScript(name, stored$1);
+			return {
+				data: this.buildScriptEntry(name, stored$1),
+				message: "Script updated"
+			};
+		}
+		const source = typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent);
+		const stored = {
+			source,
+			createdAt: existing?.createdAt ?? now,
+			updatedAt: now
+		};
+		await this.setScript(name, stored);
+		this.registerTriggers(name, source);
+		return {
+			data: this.buildScriptEntry(name, stored),
+			message: existing ? "Script updated" : "Script created"
+		};
+	}
+	async deleteScript(ctx) {
+		const name = ctx.params.scriptName.replace(/\.ash$/, "");
+		if (!await this.hasScript(name)) throw new AFSNotFoundError(ctx.path, `Script not found: ${name}`);
+		this.unregisterTriggers(name);
+		await this.removeScript(name);
+		return { message: `Script '${name}' deleted` };
+	}
+	async deleteCatchAll(ctx) {
+		throw new AFSNotFoundError(ctx.path);
+	}
+	async execScript(ctx, args) {
+		const name = ctx.params.scriptName.replace(/\.ash$/, "");
+		const script = await this.getScript(name);
+		if (!script) return {
+			success: false,
+			data: { error: `Script not found: ${name}` }
+		};
+		return this.runAsh(script.source, args);
+	}
+	async execScriptDirect(ctx, args) {
+		return this.execScript(ctx, args);
+	}
+	async execRootAction(ctx, args) {
+		const actionName = ctx.params.action;
+		if (actionName === "run") {
+			const source = args.source;
+			if (typeof source !== "string") throw new Error("action 'run' requires 'source' parameter as string");
+			const jobName = args.job;
+			if (jobName) {
+				const runtimeAFS$1 = args._runtime_afs;
+				return this.runJob(source, jobName, args, { afsOverride: runtimeAFS$1 });
+			}
+			const hasCaps = Array.isArray(args.caps) && args.caps.length > 0;
+			const runtimeAFS = args._runtime_afs;
+			const cleanArgs = { ...args };
+			delete cleanArgs._runtime_afs;
+			return this.runAsh(source, cleanArgs, {
+				allowWriteBack: hasCaps,
+				afsOverride: runtimeAFS
+			});
+		}
+		if (actionName === "validate") {
+			const source = args.source;
+			if (typeof source !== "string") throw new Error("action 'validate' requires 'source' parameter as string");
+			const result = compileSource(source);
+			const errors = result.diagnostics.filter((d) => d.severity !== "warning");
+			const warnings = result.diagnostics.filter((d) => d.severity === "warning");
+			return {
+				success: true,
+				data: {
+					valid: errors.length === 0,
+					errors,
+					warnings,
+					jobCount: result.program?.jobs.length ?? 0,
+					sourceHash: result.sourceHash
+				}
+			};
+		}
+		if (actionName === "agent-run") return this.executeAgentRun(args);
+		throw new Error(`Unknown action: ${actionName}`);
+	}
+	async statRoot(_ctx) {
+		return { data: {
+			id: "/",
+			path: "/",
+			meta: {
+				type: "directory",
+				childrenCount: 1,
+				scriptCount: await this.getScriptCount()
+			}
+		} };
+	}
+	async statScriptsDir(_ctx) {
+		return { data: {
+			id: "/scripts",
+			path: "/scripts",
+			meta: {
+				type: "directory",
+				childrenCount: await this.getScriptCount()
+			}
+		} };
+	}
+	async statScript(ctx) {
+		const name = ctx.params.scriptName.replace(/\.ash$/, "");
+		const script = await this.getScript(name);
+		if (!script) throw new AFSNotFoundError(ctx.path, `Script not found: ${name}`);
+		return { data: {
+			id: joinURL("/scripts", `${name}.ash`),
+			path: joinURL("/scripts", `${name}.ash`),
+			createdAt: script.createdAt,
+			updatedAt: script.updatedAt,
+			meta: {
+				type: "file",
+				kind: "ash:script",
+				scriptName: name,
+				size: new TextEncoder().encode(script.source).length
+			}
+		} };
+	}
+	async explainRoot(_ctx) {
+		return {
+			format: "markdown",
+			content: readDoc("agent.md")
+		};
+	}
+	async explainScript(ctx) {
+		const name = ctx.params.scriptName.replace(/\.ash$/, "");
+		const script = await this.getScript(name);
+		if (!script) throw new AFSNotFoundError(ctx.path, `Script not found: ${name}`);
+		const result = compileSource(script.source);
+		const lines = [];
+		lines.push(`# Script: ${name}.ash`);
+		lines.push("");
+		lines.push("## Source");
+		lines.push("");
+		lines.push("```ash");
+		lines.push(script.source);
+		lines.push("```");
+		lines.push("");
+		lines.push("## Analysis");
+		lines.push("");
+		lines.push(`- **Jobs**: ${result.program?.jobs.length ?? 0}`);
+		lines.push(`- **Diagnostics**: ${result.diagnostics.length}`);
+		lines.push(`- **Size**: ${new TextEncoder().encode(script.source).length} bytes`);
+		lines.push("");
+		return {
+			format: "markdown",
+			content: lines.join("\n")
+		};
+	}
+	async searchScripts(_ctx, query) {
+		const results = [];
+		const lowerQuery = query.toLowerCase();
+		for (const name of await this.getAllScriptNames()) {
+			const script = await this.getScript(name);
+			if (!script) continue;
+			if (name.toLowerCase().includes(lowerQuery) || script.source.toLowerCase().includes(lowerQuery)) results.push(this.buildScriptEntry(name, script));
+		}
+		return { data: results };
+	}
+	buildScriptEntry(name, script) {
+		const inputSchema = this.buildScriptExecInputSchema(script.source);
+		return {
+			id: joinURL("/scripts", `${name}.ash`),
+			path: joinURL("/scripts", `${name}.ash`),
+			content: script.source,
+			createdAt: script.createdAt,
+			updatedAt: script.updatedAt,
+			meta: {
+				type: "file",
+				kind: "ash:script",
+				kinds: [
+					"ash:script",
+					"afs:executable",
+					"afs:node"
+				],
+				scriptName: name,
+				size: new TextEncoder().encode(script.source).length
+			},
+			actions: [{
+				name: "exec",
+				description: `Execute script ${name}`,
+				inputSchema
+			}]
+		};
+	}
+	buildScriptExecInputSchema(source) {
+		const properties = { caps: {
+			type: "array",
+			items: { type: "string" },
+			description: "Capability paths. Required for write-back to AFS (default: no write-back without caps)"
+		} };
+		const result = compileSource(source);
+		if (result.program) for (const [key, value] of result.program.params) properties[key] = {
+			type: typeof value === "number" ? "number" : "string",
+			description: `Override ASH param '${key}' at execution time`
+		};
+		return {
+			type: "object",
+			properties
+		};
+	}
+	/**
+	* Create an async-capable world that bridges ASH to AFS.
+	* Since ASH's WorldInterface is synchronous but AFS is async,
+	* we collect operations and replay them, or use a pre-loaded data approach.
+	*/
+	async createAsyncWorld(afsOverride) {
+		const dataStore = { ...await this.loadPersistedData() };
+		const written = {};
+		const published = {};
+		const writeCounts = {};
+		const afsRoot = afsOverride ?? this.afsRoot;
+		const selfPrefix = `/${this.name}/`;
+		const allowRootActions = this.allowRootActions;
+		const pendingPersist = [];
+		const persistData = (path, data) => {
+			pendingPersist.push(this.persistData(path, data).catch(() => {}));
+		};
+		return {
+			world: {
+				read(path) {
+					return dataStore[path] ?? [];
+				},
+				write(path, data) {
+					if (path.startsWith(selfPrefix) || path.startsWith("/scripts") || path.startsWith("/.actions") || path.startsWith("/.meta")) throw new Error(`Write blocked: '${path}' is a protected ASH provider path`);
+					writeCounts[path] = (writeCounts[path] ?? 0) + 1;
+					written[path] = data;
+					dataStore[path] = data;
+					persistData(path, data);
+				},
+				publish(topic, data) {
+					published[topic] = data;
+				},
+				async exec(path, input, params) {
+					const rootActionMatch = /^\/\.actions\/([^/]+)$/.exec(path) ?? (/* @__PURE__ */ new RegExp(`^${selfPrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\.actions\\/([^/]+)$`)).exec(path);
+					if (!(rootActionMatch !== null && allowRootActions.has(rootActionMatch[1])) && (path.startsWith(selfPrefix) || path.startsWith("/.actions") || path.startsWith("/scripts"))) throw new Error(`Exec blocked: self-referencing call to '${path}' would cause recursion`);
+					if (afsRoot?.exec) {
+						const baseParams = params ?? {};
+						const records = input.filter((r) => typeof r === "object" && r !== null);
+						if (records.length <= 1) {
+							const mergedArgs = {
+								...records[0] ?? {},
+								...baseParams
+							};
+							if (afsOverride) mergedArgs._runtime_afs = afsOverride;
+							const result = await afsRoot.exec(path, mergedArgs, {});
+							return Array.isArray(result.data) ? result.data : [result.data];
+						}
+						const results = [];
+						for (const record of records) {
+							const mergedArgs = {
+								...record,
+								...baseParams
+							};
+							if (afsOverride) mergedArgs._runtime_afs = afsOverride;
+							const result = await afsRoot.exec(path, mergedArgs, {});
+							if (Array.isArray(result.data)) results.push(...result.data);
+							else results.push(result.data);
+						}
+						return results;
+					}
+					return input;
+				},
+				async input(prompt) {
+					if (afsRoot?.exec) try {
+						const result = await afsRoot.exec("/ui/.actions/prompt", {
+							message: prompt,
+							type: "text"
+						}, {});
+						return String(result.data?.response ?? "");
+					} catch (err) {
+						if (err instanceof AFSNotFoundError) return "";
+						throw err;
+					}
+					return "";
+				}
+			},
+			written,
+			published,
+			writeCounts,
+			preload(path, data) {
+				dataStore[path] = data;
+			},
+			async flushPersist() {
+				await Promise.all(pendingPersist);
+			}
+		};
+	}
+	deriveTools(agentDir, extraTools, channelPath) {
+		const base = [{
+			path: `${agentDir}/**`,
+			ops: [
+				"read",
+				"list",
+				"write",
+				"search",
+				"stat",
+				"exec"
+			],
+			maxDepth: 10
+		}, {
+			path: "/modules/ash/.actions/*",
+			ops: ["exec"]
+		}];
+		if (channelPath) base.push({
+			path: `${channelPath}/**`,
+			ops: ["exec"],
+			maxDepth: 5
+		});
+		return [...base, ...extraTools];
+	}
+	async executeAgentRun(args) {
+		const runtimeAFSOverride = args._runtime_afs;
+		const cleanArgs = { ...args };
+		delete cleanArgs._runtime_afs;
+		const task = cleanArgs.task;
+		if (typeof task !== "string" || !task) throw new Error("agent-run requires 'task' parameter as string");
+		const model = cleanArgs.model;
+		if (typeof model !== "string" || !model) throw new Error("agent-run requires 'model' parameter as string");
+		const rawTools = cleanArgs.tools;
+		let tools = rawTools === "none" || rawTools === void 0 ? [] : rawTools;
+		if (!Array.isArray(tools)) throw new Error("agent-run 'tools' must be an array or 'none'");
+		const globalAFS = this.afsRoot;
+		if (!globalAFS && !runtimeAFSOverride) throw new Error("agent-run requires AFS root to be mounted");
+		const agentDir = cleanArgs.agent_dir;
+		let targetAFS = runtimeAFSOverride ?? globalAFS;
+		if (runtimeAFSOverride && agentDir) try {
+			const yamlResult = await runtimeAFSOverride.read(joinURL(agentDir, "program.yaml"), {});
+			const yamlContent = String(yamlResult.data?.content ?? "");
+			if (yamlContent.trim()) tools = deriveToolsFromProgram(parseProgramManifest(yamlContent));
+		} catch {}
+		else if (agentDir && globalAFS) {
+			let isProgram = false;
+			try {
+				await globalAFS.read(joinURL(agentDir, "program.yaml"), {});
+				isProgram = true;
+			} catch {}
+			if (isProgram) try {
+				const pyResult = await globalAFS.read(joinURL(agentDir, "program.yaml"), {});
+				const dataPath = joinURL("/.data", parseProgramManifest(String(pyResult.data?.content ?? "")).id);
+				try {
+					await globalAFS.write(joinURL(dataPath, ".keep"), { content: "" });
+				} catch {}
+				const { afs: runtimeAFS, manifest } = await createProgramAFS(agentDir, dataPath, globalAFS);
+				targetAFS = runtimeAFS;
+				tools = deriveToolsFromProgram(manifest);
+			} catch (err) {
+				return {
+					success: false,
+					error: {
+						code: "PROGRAM_INIT_ERROR",
+						message: sanitizeErrorPath(err instanceof Error ? err.message : String(err))
+					}
+				};
+			}
+			else {
+				const extraTools = cleanArgs.extra_tools ?? tools;
+				const channelPath = cleanArgs.channel_path;
+				tools = this.deriveTools(agentDir, extraTools, channelPath);
+			}
+		}
+		const afs = targetAFS;
+		const { runAgentLoop } = await import("./agent-run-CXJQ0jPV.mjs");
+		let enrichedTask = task;
+		if (typeof cleanArgs.text === "string" && cleanArgs.text) enrichedTask += `\n\nUser message: ${cleanArgs.text}`;
+		const result = await runAgentLoop({
+			task: enrichedTask,
+			model,
+			tools,
+			budget: cleanArgs.budget,
+			system: cleanArgs.system,
+			session: cleanArgs.session
+		}, {
+			callLLM: async (llmArgs) => {
+				if (!afs.exec) return {
+					success: false,
+					data: { error: "exec not supported" }
+				};
+				let resolvedModel = model;
+				if (!resolvedModel.startsWith("/")) resolvedModel = `/modules/aignehub/providers/${resolvedModel}`;
+				const modelPath = `${resolvedModel}/.actions/chat`;
+				const translated = { ...llmArgs };
+				if (Array.isArray(translated.messages)) translated.messages = translated.messages.map((msg) => {
+					const m = { ...msg };
+					if (m.role === "assistant") m.role = "agent";
+					if (m.role === "tool" && m.tool_call_id && !m.toolCallId) {
+						m.toolCallId = m.tool_call_id;
+						delete m.tool_call_id;
+					}
+					if (Array.isArray(m.toolCalls)) m.toolCalls = m.toolCalls.map((tc) => {
+						const fn = tc.function;
+						if (fn && typeof fn.arguments === "string") try {
+							return {
+								...tc,
+								function: {
+									...fn,
+									arguments: JSON.parse(fn.arguments)
+								}
+							};
+						} catch {
+							return tc;
+						}
+						return tc;
+					});
+					return m;
+				});
+				const raw = await afs.exec(modelPath, translated, {});
+				if (raw.success && raw.data) {
+					const result$1 = raw.data.result;
+					if (result$1) {
+						const usage = result$1.usage;
+						raw.data = {
+							text: result$1.text,
+							toolCalls: result$1.toolCalls,
+							inputTokens: usage?.inputTokens,
+							outputTokens: usage?.outputTokens
+						};
+					}
+				}
+				return raw;
+			},
+			runAsh: async (source, runArgs) => {
+				return this.runAsh(source, runArgs, {
+					returnWrittenData: true,
+					skipWritePrefix: "/.results/"
+				});
+			},
+			callAFS: async (op, path, opArgs) => {
+				switch (op) {
+					case "read": return {
+						success: true,
+						data: (await afs.read(path, opArgs ?? {})).data
+					};
+					case "list": return {
+						success: true,
+						data: (await afs.list(path, opArgs ?? {})).data
+					};
+					case "search":
+						if (!afs.search) return {
+							success: false,
+							data: { error: "search not supported" }
+						};
+						return {
+							success: true,
+							data: { results: (await afs.search(path, opArgs?.query ?? "", opArgs ?? {})).data }
+						};
+					case "write":
+						if (!afs.write) return {
+							success: false,
+							data: { error: "write not supported" }
+						};
+						return {
+							success: true,
+							data: { written: (await afs.write(path, opArgs ?? {})).data }
+						};
+					case "stat":
+						if (!afs.stat) return {
+							success: false,
+							data: { error: "stat not supported" }
+						};
+						return {
+							success: true,
+							data: { stat: (await afs.stat(path)).data }
+						};
+					case "explain":
+						if (!afs.explain) return {
+							success: false,
+							data: { error: "explain not supported" }
+						};
+						return {
+							success: true,
+							data: { content: (await afs.explain(path)).content }
+						};
+					case "exec": {
+						if (!afs.exec) return {
+							success: false,
+							data: { error: "exec not supported" }
+						};
+						const execArgs = opArgs?.args && typeof opArgs.args === "object" && !Array.isArray(opArgs.args) ? opArgs.args : opArgs ?? {};
+						return afs.exec(path, execArgs, {});
+					}
+					default: return {
+						success: false,
+						data: { error: `Unsupported direct op: ${op}` }
+					};
+				}
+			},
+			loadHistory: async (sessionPath) => {
+				const historyPath = `${sessionPath}/history.jsonl`;
+				try {
+					const result$1 = await afs.read(historyPath, {});
+					const content = String(result$1.data?.content ?? "");
+					if (!content.trim()) return [];
+					return content.trim().split("\n").flatMap((line) => {
+						try {
+							return [JSON.parse(line)];
+						} catch {
+							return [];
+						}
+					});
+				} catch {
+					return [];
+				}
+			},
+			saveHistory: async (sessionPath, messages) => {
+				const historyPath = `${sessionPath}/history.jsonl`;
+				const content = `${messages.map((m) => JSON.stringify(m)).join("\n")}\n`;
+				await afs.write(historyPath, { content });
+			}
+		});
+		return {
+			success: result.status === "completed",
+			data: result
+		};
+	}
+	/**
+	* Execute a single named job from an ASH source.
+	* Used by ProgramManager to run trigger jobs with event data.
+	*/
+	async runJob(source, jobName, args, options) {
+		const result = compileSource(this.applyParamOverridesToSource(source, args));
+		if (!result.program) return {
+			success: false,
+			data: {
+				error: "Compilation failed",
+				diagnostics: result.diagnostics
+			}
+		};
+		const job = result.program.units.find((u) => u.kind === "job" && u.name === jobName);
+		if (!job || job.kind !== "job") return {
+			success: false,
+			data: { error: `Job "${jobName}" not found in source` }
+		};
+		const afsOverride = options?.afsOverride;
+		const { world, written } = await this.createAsyncWorld(afsOverride);
+		const effectiveAFS = afsOverride ?? this.afsRoot;
+		const ctx = {
+			world: effectiveAFS ? {
+				read: async (path) => {
+					const local = await world.read(path);
+					if (local.length > 0) return local;
+					if (effectiveAFS.list) {
+						const listResult = await effectiveAFS.list(path, {});
+						if (listResult.data.length > 0) {
+							const needsEnrich = listResult.data.some((e) => e.content == null);
+							let entries = listResult.data;
+							if (needsEnrich && effectiveAFS.read) {
+								const afsRead = effectiveAFS.read.bind(effectiveAFS);
+								entries = await Promise.all(listResult.data.map(async (e) => {
+									if (e.content != null) return e;
+									try {
+										const r = await afsRead(e.path, {});
+										return r.data ? {
+											...e,
+											content: r.data.content
+										} : e;
+									} catch {
+										return e;
+									}
+								}));
+							}
+							return entries.map((entry) => ({
+								path: entry.path,
+								name: entry.path.split("/").filter(Boolean).pop(),
+								...entry.meta,
+								...normalizeContent(entry.content)
+							}));
+						}
+					}
+					if (effectiveAFS.read) try {
+						const readResult = await effectiveAFS.read(path, {});
+						if (readResult.data) {
+							const entry = readResult.data;
+							return [{
+								path: entry.path ?? path,
+								name: (entry.path ?? path).split("/").filter(Boolean).pop(),
+								...entry.meta,
+								...normalizeContent(entry.content)
+							}];
+						}
+					} catch {}
+					return [];
+				},
+				write: (path, data) => {
+					world.write(path, data);
+				},
+				publish: (topic, data) => {
+					world.publish(topic, data);
+				},
+				exec: world.exec
+			} : world,
+			caps: new Set(["*"]),
+			logger: { log() {} },
+			output: { output() {} }
+		};
+		const event = args.event;
+		const initialStream = event ? [{ ...event }] : [];
+		const jobResult = await job.execute(ctx, initialStream);
+		const afs = effectiveAFS;
+		if (afs?.write) for (const [path, data] of Object.entries(written)) {
+			const content = JSON.stringify(data);
+			await afs.write(path, { content });
+		}
+		if (jobResult.status !== "ok") return {
+			success: false,
+			data: {
+				error: `Job "${jobName}" failed`,
+				status: jobResult.status,
+				errors: jobResult.errors
+			}
+		};
+		return {
+			success: true,
+			data: {
+				job: jobName,
+				recordCount: jobResult.recordCount
+			}
+		};
+	}
+	async runAsh(source, args, options) {
+		const result = compileSource(this.applyParamOverridesToSource(source, args));
+		if (result.diagnostics.filter((d) => d.severity !== "warning").length > 0 || !result.program) return {
+			success: false,
+			data: {
+				error: "Compilation failed",
+				diagnostics: result.diagnostics.map((d) => ({
+					...d,
+					message: sanitizeErrorPath(d.message)
+				})),
+				sourceHash: result.sourceHash
+			}
+		};
+		const expectedHash = args.expectedHash;
+		if (typeof expectedHash === "string" && expectedHash !== result.sourceHash) return {
+			success: false,
+			data: {
+				error: "Source hash mismatch — code was modified between validate and run (TOCTOU)",
+				expectedHash,
+				actualHash: result.sourceHash
+			}
+		};
+		const capsArg = args.caps;
+		const caps = Array.isArray(capsArg) && capsArg.every((c) => typeof c === "string") ? new Set(capsArg) : new Set(["*"]);
+		const afsOverride = options?.afsOverride;
+		const { world, written, published, writeCounts, flushPersist } = await this.createAsyncWorld(afsOverride);
+		const effectiveAFS = afsOverride ?? this.afsRoot;
+		const bridgedWorld = effectiveAFS ? {
+			read: async (path) => {
+				const local = await world.read(path);
+				if (local.length > 0) return local;
+				if (effectiveAFS) {
+					if (effectiveAFS.list) {
+						const listResult = await effectiveAFS.list(path, {});
+						if (listResult.data.length > 0) {
+							const needsEnrich = listResult.data.some((e) => e.content == null);
+							let entries = listResult.data;
+							if (needsEnrich && effectiveAFS.read) {
+								const afsRead = effectiveAFS.read.bind(effectiveAFS);
+								entries = await Promise.all(listResult.data.map(async (e) => {
+									if (e.content != null) return e;
+									try {
+										const r = await afsRead(e.path, {});
+										return r.data ? {
+											...e,
+											content: r.data.content
+										} : e;
+									} catch {
+										return e;
+									}
+								}));
+							}
+							return entries.map((entry) => ({
+								path: entry.path,
+								name: entry.path.split("/").filter(Boolean).pop(),
+								...entry.meta,
+								...normalizeContent(entry.content)
+							}));
+						}
+					}
+					if (effectiveAFS.read) try {
+						const readResult = await effectiveAFS.read(path, {});
+						if (readResult.data) {
+							const entry = readResult.data;
+							return [{
+								path: entry.path ?? path,
+								name: (entry.path ?? path).split("/").filter(Boolean).pop(),
+								...entry.meta,
+								...normalizeContent(entry.content)
+							}];
+						}
+					} catch {}
+				}
+				return [];
+			},
+			write: (path, data) => {
+				world.write(path, data);
+			},
+			publish: (topic, data) => {
+				world.publish(topic, data);
+			},
+			exec: world.exec
+		} : world;
+		const logs = [];
+		const logger = { log(stage, action, detail) {
+			logs.push({
+				stage,
+				action,
+				detail
+			});
+		} };
+		const outputs = [];
+		const ctx = {
+			world: bridgedWorld,
+			caps,
+			logger,
+			output: { output(event) {
+				outputs.push(event.content);
+			} }
+		};
+		const jobResults = [];
+		for (const unit of result.program.units) if (unit.kind === "job") {
+			if (result.program.routeTargets?.has(unit.name)) continue;
+			if (unit.trigger) continue;
+			jobResults.push(await unit.execute(ctx));
+		} else await unit.execute(ctx);
+		const sanitizedJobs = jobResults.map(({ stages, ...rest }) => rest);
+		const allOk = jobResults.every((r) => r.status === "ok");
+		const allErrors = jobResults.flatMap((r) => r.errors).map(sanitizeErrorPath);
+		const afs = afsOverride ?? this.afsRoot;
+		const skipPrefix = options?.skipWritePrefix;
+		if (afs?.write && options?.allowWriteBack !== false) {
+			for (const [path, data] of Object.entries(written)) {
+				if (skipPrefix && path.startsWith(skipPrefix)) continue;
+				try {
+					await afs.write(path, { content: JSON.stringify(data) });
+				} catch {
+					allErrors.push("Failed to write to AFS");
+				}
+			}
+			for (const [topic, data] of Object.entries(published)) try {
+				await afs.write(topic, { content: JSON.stringify(data) });
+			} catch {
+				allErrors.push("Failed to publish to AFS");
+			}
+		}
+		const overwrittenPaths = Object.entries(writeCounts).filter(([, count]) => count > 1).map(([path, count]) => sanitizeErrorPath(`Path '${path}' was written ${count} times — only last write preserved`));
+		if (overwrittenPaths.length > 0) allErrors.push(...overwrittenPaths);
+		await flushPersist();
+		return {
+			success: allOk && allErrors.length === 0 && overwrittenPaths.length === 0,
+			data: {
+				jobs: sanitizedJobs,
+				written: Object.keys(written),
+				published: Object.keys(published),
+				outputs,
+				errors: allErrors.length > 0 ? allErrors : void 0,
+				warnings: result.diagnostics.filter((d) => d.severity === "warning").map((d) => ({
+					...d,
+					message: sanitizeErrorPath(d.message)
+				})),
+				sourceHash: result.sourceHash,
+				...options?.returnWrittenData ? { writtenData: written } : {}
+			}
+		};
+	}
+	applyParamOverridesToSource(source, args) {
+		const lines = source.split("\n");
+		let changed = false;
+		const replaced = lines.map((line) => {
+			const match = /^(\s*param\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*)(.+)$/.exec(line);
+			if (!match) return line;
+			const [, prefix, name] = match;
+			if (!name) return line;
+			const value = args[name];
+			if (typeof value !== "string" && typeof value !== "number") return line;
+			changed = true;
+			return `${prefix}${typeof value === "string" ? JSON.stringify(value) : String(value)}`;
+		});
+		return changed ? replaced.join("\n") : source;
+	}
+};
+__decorate([List("/")], AFSAsh.prototype, "listRoot", null);
+__decorate([List("/scripts")], AFSAsh.prototype, "listScripts", null);
+__decorate([List("/scripts/:scriptName")], AFSAsh.prototype, "listScript", null);
+__decorate([Actions("/")], AFSAsh.prototype, "listRootActions", null);
+__decorate([Actions("/scripts/:scriptName")], AFSAsh.prototype, "listScriptActions", null);
+__decorate([Read("/")], AFSAsh.prototype, "readRoot", null);
+__decorate([Read("/scripts")], AFSAsh.prototype, "readScriptsDir", null);
+__decorate([Read("/scripts/:scriptName")], AFSAsh.prototype, "readScript", null);
+__decorate([List("/cookbook")], AFSAsh.prototype, "listCookbook", null);
+__decorate([Read("/cookbook")], AFSAsh.prototype, "readCookbookDir", null);
+__decorate([List("/cookbook/:file")], AFSAsh.prototype, "listCookbookFile", null);
+__decorate([Read("/cookbook/:file")], AFSAsh.prototype, "readCookbook", null);
+__decorate([Read("/.meta/agent.md")], AFSAsh.prototype, "readAgentMd", null);
+__decorate([Read("/.meta/.ash-reference")], AFSAsh.prototype, "readAshReference", null);
+__decorate([Read("/.meta/.capabilities")], AFSAsh.prototype, "readCapabilities", null);
+__decorate([Meta("/")], AFSAsh.prototype, "readRootMeta", null);
+__decorate([Meta("/cookbook")], AFSAsh.prototype, "readCookbookMeta", null);
+__decorate([Meta("/cookbook/:file")], AFSAsh.prototype, "readCookbookFileMeta", null);
+__decorate([Meta("/scripts")], AFSAsh.prototype, "readScriptsMeta", null);
+__decorate([Meta("/scripts/:scriptName")], AFSAsh.prototype, "readScriptMeta", null);
+__decorate([Write("/scripts/:scriptName")], AFSAsh.prototype, "writeScript", null);
+__decorate([Delete("/scripts/:scriptName")], AFSAsh.prototype, "deleteScript", null);
+__decorate([Delete("/:path*")], AFSAsh.prototype, "deleteCatchAll", null);
+__decorate([Actions.Exec("/scripts/:scriptName", "exec")], AFSAsh.prototype, "execScript", null);
+__decorate([Exec("/scripts/:scriptName")], AFSAsh.prototype, "execScriptDirect", null);
+__decorate([Actions.Exec("/")], AFSAsh.prototype, "execRootAction", null);
+__decorate([Stat("/")], AFSAsh.prototype, "statRoot", null);
+__decorate([Stat("/scripts")], AFSAsh.prototype, "statScriptsDir", null);
+__decorate([Stat("/scripts/:scriptName")], AFSAsh.prototype, "statScript", null);
+__decorate([Explain("/")], AFSAsh.prototype, "explainRoot", null);
+__decorate([Explain("/scripts/:scriptName")], AFSAsh.prototype, "explainScript", null);
+__decorate([Search("/:path*")], AFSAsh.prototype, "searchScripts", null);
+var src_default = AFSAsh;
+
+//#endregion
+export { AFSAsh, src_default as default, deriveToolsFromProgram };
+//# sourceMappingURL=index.mjs.map