@aigne/agent-runtime 1.12.0-beta.5

package/dist/providers/basic/ash/dist/index.mjs

@@ -0,0 +1,1807 @@
+import { joinURL } from "ufo";
+import { AFSNotFoundError, SCRIPT_EVENT_TYPES, getPlatform, makeNsLog } 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 { z } from "zod";
+
+//#region ../../providers/basic/ash/dist/index.mjs
+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;
+}
+/**
+* Read-class pairing: a grant of `list` on a data root implies `query` (the
+* collection-query standard action) — both are readPaths-class observation
+* privileges, and the agent default tooling rule says standard observation
+* comes with the data root, not per-tool opt-in. Idempotent.
+*/
+function withQueryPairing(ops) {
+	if (ops.includes("list") && !ops.includes("query")) return [...ops, "query"];
+	return ops;
+}
+/**
+* Match an actual path against a declaration pattern.
+*
+* Supports:
+* - Exact: "/a/b" matches "/a/b"
+* - Single-level `*`: "/a/*" matches "/a/b" but NOT "/a/b/c"
+* - Multi-level `**`: "/a/**" matches "/a/b/c" up to `maxDepth` levels from `**` position
+*
+* @param maxDepth Maximum levels `**` can consume. Defaults to 0 (no expansion).
+*/
+function matchPath(actual, pattern, maxDepth = 0) {
+	if (actual === pattern) return true;
+	const patternParts = pattern.split("/");
+	const actualParts = actual.split("/");
+	const dstarIdx = patternParts.indexOf("**");
+	if (dstarIdx === -1) return matchSingleLevel(actualParts, patternParts);
+	const prefix = patternParts.slice(0, dstarIdx);
+	const suffix = patternParts.slice(dstarIdx + 1);
+	if (actualParts.length < prefix.length + suffix.length) return false;
+	for (let i = 0; i < prefix.length; i++) {
+		if (prefix[i] === "*") continue;
+		if (prefix[i] !== actualParts[i]) return false;
+	}
+	const suffixStart = actualParts.length - suffix.length;
+	if (suffixStart < prefix.length) return false;
+	for (let i = 0; i < suffix.length; i++) {
+		if (suffix[i] === "*") continue;
+		if (suffix[i] !== actualParts[suffixStart + i]) return false;
+	}
+	const dstarLevels = actualParts.length - prefix.length - suffix.length;
+	return dstarLevels >= 0 && dstarLevels <= maxDepth;
+}
+/** Single-level * matching (no **). */
+function matchSingleLevel(actualParts, patternParts) {
+	if (!patternParts.some((p) => p === "*")) return false;
+	if (actualParts.length === patternParts.length) {
+		for (let i = 0; i < patternParts.length; i++) {
+			if (patternParts[i] === "*") continue;
+			if (patternParts[i] !== actualParts[i]) return false;
+		}
+		return true;
+	}
+	if (actualParts.length < patternParts.length) {
+		for (let i = actualParts.length; i < patternParts.length; i++) if (patternParts[i] !== "*") return false;
+		for (let i = 0; i < actualParts.length; i++) if (patternParts[i] !== "*" && patternParts[i] !== actualParts[i]) return false;
+		return true;
+	}
+	return false;
+}
+/**
+* Extract the action name from an exec path.
+* E.g., "/modules/github/issues/42/.actions/close-issue" → "close-issue"
+*/
+function extractActionName(path) {
+	const idx = path.lastIndexOf("/.actions/");
+	if (idx === -1) return void 0;
+	return path.slice(idx + 10).split("/")[0];
+}
+/**
+* Validate a tool_call's path and operation against the tools declaration.
+*/
+function validateToolCall(path, op, tools) {
+	if (hasUnsafePathSyntax(path)) return {
+		allowed: false,
+		reason: `Unsafe path syntax in '${path}'`
+	};
+	let basePath;
+	if (op === "exec") {
+		const idx = path.indexOf("/.actions/");
+		if (idx !== -1) basePath = path.slice(0, idx);
+	}
+	let pathMatched = false;
+	for (const entry of tools) {
+		const md = entry.maxDepth ?? 0;
+		if (!matchPath(path, entry.path, md) && !(basePath && matchPath(basePath, entry.path, md))) continue;
+		pathMatched = true;
+		if (!entry.ops.includes(op)) continue;
+		if (op === "exec" && entry.exclude_actions?.length) {
+			const actionName = extractActionName(path);
+			if (actionName && entry.exclude_actions.includes(actionName)) return {
+				allowed: false,
+				reason: `Action '${actionName}' is excluded on '${entry.path}'`
+			};
+		}
+		return { allowed: true };
+	}
+	if (pathMatched) return {
+		allowed: false,
+		reason: `Operation '${op}' not allowed on '${path}'`
+	};
+	return {
+		allowed: false,
+		reason: `Path '${path}' not in tools declaration`
+	};
+}
+function hasUnsafePathSyntax(path) {
+	if (path.includes("..") || path.includes("{") || path.includes("\\") || path.includes("\0")) return true;
+	try {
+		const decoded = decodeURIComponent(path);
+		return decoded !== path && hasUnsafePathSyntax(decoded);
+	} catch {
+		return true;
+	}
+}
+function isChildPath(childPath, parentPath, parentMaxDepth) {
+	if (childPath === parentPath) return true;
+	const childHasGlob = childPath.includes("**") || childPath.includes("*");
+	const parentHasGlob = parentPath.includes("**") || parentPath.includes("*");
+	if (!parentHasGlob && !childHasGlob) return childPath === parentPath;
+	if (parentHasGlob && !childHasGlob) return matchPath(childPath, parentPath, parentMaxDepth);
+	if (parentHasGlob && childHasGlob) {
+		const parentBase = parentPath.replace(/\/\*\*$/, "").replace(/\/\*$/, "");
+		const childBase = childPath.replace(/\/\*\*$/, "").replace(/\/\*$/, "");
+		return childBase === parentBase || childBase.startsWith(`${parentBase}/`);
+	}
+	return false;
+}
+/**
+* Intersect two ToolEntry[] arrays. Returns the effective tool list for a
+* child agent: only entries that both parent and child declare, with ops
+* narrowed to the intersection and maxDepth capped by the parent.
+*
+* Violations are silently absent (no errors). This is a pure function.
+*/
+function intersectTools(parent, child) {
+	if (parent.length === 0 || child.length === 0) return [];
+	const result = [];
+	for (const c of child) {
+		if (hasUnsafePathSyntax(c.path)) continue;
+		let bestParent = null;
+		for (const p of parent) {
+			if (hasUnsafePathSyntax(p.path)) continue;
+			if (!isChildPath(c.path, p.path, p.maxDepth ?? 0)) continue;
+			bestParent = p;
+			break;
+		}
+		if (!bestParent) continue;
+		const ops = c.ops.filter((op) => bestParent.ops.includes(op));
+		if (ops.length === 0) continue;
+		const entry = {
+			path: c.path,
+			ops
+		};
+		if (c.path.includes("**")) {
+			const parentDepth = bestParent.maxDepth ?? 0;
+			const childDepth = c.maxDepth ?? 0;
+			entry.maxDepth = Math.min(parentDepth, childDepth);
+		} else if (c.maxDepth != null) entry.maxDepth = bestParent.maxDepth != null ? Math.min(bestParent.maxDepth, c.maxDepth) : c.maxDepth;
+		const excludes = /* @__PURE__ */ new Set();
+		if (bestParent.exclude_actions) for (const a of bestParent.exclude_actions) excludes.add(a);
+		if (c.exclude_actions) for (const a of c.exclude_actions) excludes.add(a);
+		if (excludes.size > 0) entry.exclude_actions = [...excludes];
+		result.push(entry);
+	}
+	return result;
+}
+/**
+* Validate an ash action path against the manifest's tools whitelist.
+* Used by the ash runner to enforce that compiled ash scripts only call
+* paths permitted by the agent manifest.
+*
+* Returns { allowed: true } or { allowed: false, code, path, reason }.
+*/
+function validateActionPath(actionPath, tools) {
+	if (hasUnsafePathSyntax(actionPath)) return {
+		allowed: false,
+		code: "PATH_TRAVERSAL",
+		path: actionPath,
+		reason: `Unsafe path syntax detected in '${actionPath}'`
+	};
+	if (tools.length === 0) return {
+		allowed: false,
+		code: "TOOL_WHITELIST_VIOLATION",
+		path: actionPath,
+		reason: `No tools declared — action '${actionPath}' is not permitted`
+	};
+	const result = validateToolCall(actionPath, "exec", tools);
+	if (!result.allowed) return {
+		allowed: false,
+		code: "TOOL_WHITELIST_VIOLATION",
+		path: actionPath,
+		reason: result.reason
+	};
+	return { allowed: true };
+}
+const log = makeNsLog("provider:ash");
+/** Lazily resolved docs directory path */
+let _docsDir;
+function getDocsDir() {
+	if (!_docsDir) {
+		const platform = getPlatform();
+		const moduleDir = platform.path.dirname(new URL(import.meta.url).pathname);
+		_docsDir = platform.path.join(moduleDir, "..", "docs");
+	}
+	return _docsDir;
+}
+async function readDoc(relativePath) {
+	const platform = getPlatform();
+	return platform.fs.readTextFile(platform.path.join(getDocsDir(), relativePath));
+}
+/**
+* Dedup deprecation warning for the legacy `/ash/.actions/agent-run`
+* alias — log once per process, not on every call.
+*/
+let ashAgentRunDeprecationLogged = false;
+function sanitizeErrorPath(msg) {
+	return msg.replace(/'\/[^']*'/g, "'[path]'").replace(/"\/[^"]*"/g, "\"[path]\"");
+}
+function normalizeAbsoluteAfsPath(path) {
+	if (!path.startsWith("/")) return path;
+	const segments = [];
+	for (const segment of path.split("/")) {
+		if (!segment || segment === ".") continue;
+		if (segment === "..") segments.pop();
+		else segments.push(segment);
+	}
+	return `/${segments.join("/")}`;
+}
+async function writeFileAtomic(path, data) {
+	const platform = getPlatform();
+	const fs = platform.fs;
+	if (!fs.rename) {
+		await fs.writeFile(path, data);
+		return;
+	}
+	const dir = platform.path.dirname(path);
+	const base = platform.path.basename(path);
+	const suffix = platform.crypto?.randomUUID() ?? `${Date.now()}-${Math.random()}`;
+	const tmpPath = platform.path.join(dir, `.${base}.${suffix}.tmp`);
+	await fs.writeFile(tmpPath, data);
+	try {
+		await fs.rename(tmpPath, path);
+	} catch (error) {
+		await fs.rm(tmpPath).catch(() => {});
+		throw error;
+	}
+}
+/**
+* Normalize an entry's content into a flat record for ASH pipeline access.
+*
+* Object content is spread so scripts can reference fields directly
+* (`${state}`, `${attributes.temperature}`, etc.). String / null / array
+* content is returned as-is under `content` — providers that need structured
+* field access are responsible for returning objects from their read path
+* (e.g. JSON, markdown, registry providers all do this).
+*/
+function normalizeContent(content) {
+	if (content == null) return {};
+	if (typeof content === "object" && !Array.isArray(content)) return {
+		content,
+		...content
+	};
+	return { content };
+}
+function normalizeAfsEntry(entry, fallbackPath) {
+	const path = entry.path ?? fallbackPath;
+	return {
+		path,
+		name: path.split("/").filter(Boolean).pop(),
+		...entry.meta,
+		...normalizeContent(entry.content)
+	};
+}
+function querySearchNeedle(query) {
+	if (!query || query.op !== "contains") return void 0;
+	if (query.field !== "content" && query.field !== "_content" && query.field !== "summary") return void 0;
+	if (Array.isArray(query.value)) return void 0;
+	const needle = String(query.value);
+	return needle === "" ? void 0 : needle;
+}
+async function readAfsRecords(afs, localWorld, path, query) {
+	const local = await localWorld.read(path, query);
+	if (local.length > 0) return local;
+	const searchNeedle = querySearchNeedle(query);
+	if (searchNeedle && afs.search) try {
+		const searchResult = await afs.search(path, searchNeedle, { limit: 1e3 });
+		if (searchResult.data.length > 0) return searchResult.data.map((entry) => normalizeAfsEntry(entry, path));
+	} catch {}
+	if (afs.list) try {
+		const listResult = await afs.list(path, query ? { query } : {});
+		if (listResult.data.length > 0) {
+			const needsEnrich = listResult.data.some((entry) => entry.content == null);
+			let entries = listResult.data;
+			if (needsEnrich && afs.read) {
+				const afsRead = afs.read.bind(afs);
+				entries = await Promise.all(listResult.data.map(async (entry) => {
+					if (entry.content != null) return entry;
+					try {
+						const result = await afsRead(entry.path, {});
+						return result.data ? {
+							...entry,
+							content: result.data.content
+						} : entry;
+					} catch {
+						return entry;
+					}
+				}));
+			}
+			return entries.map((entry) => normalizeAfsEntry(entry, path));
+		}
+	} catch {}
+	if (afs.read) try {
+		const readResult = await afs.read(path, {});
+		if (readResult.data) return [normalizeAfsEntry(readResult.data, path)];
+	} catch {}
+	return [];
+}
+/**
+* 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",
+			agentMdPath: new URL("../docs/agent.md", import.meta.url).pathname,
+			schema: z.object({
+				name: z.string().optional(),
+				description: z.string().optional(),
+				allowRootActions: z.array(z.enum([
+					"agent-run",
+					"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();
+	writeQueues = /* @__PURE__ */ new Map();
+	afsRoot;
+	scriptsDir;
+	dataDir;
+	allowRootActions;
+	triggerSubs = /* @__PURE__ */ new Map();
+	cronJobs = /* @__PURE__ */ new Map();
+	/** Cron registry for alarm-driven execution (CF Worker DOs where setTimeout is unreliable). */
+	cronRegistry = /* @__PURE__ */ new Map();
+	externalScripts = /* @__PURE__ */ new Map();
+	externalScriptSubs = [];
+	/** Pending trigger execution promises — for testing/awaiting async triggers. */
+	pendingTriggers = /* @__PURE__ */ new Set();
+	/** Per-script AFS override for program-scoped triggers (scriptName → program AFS). */
+	triggerAfsOverrides = /* @__PURE__ */ new Map();
+	/** Script trigger keys owned by each program trigger registration. */
+	programTriggerKeys = /* @__PURE__ */ new Map();
+	/** Namespace prefixes registered via registerProgramTriggers (e.g. "/blocklets/evan"). */
+	programNamespaces = /* @__PURE__ */ new Set();
+	/** Runtime AFSes promoted to program-AFS. When events arrive on these,
+	*  the onMount-installed `initTriggers` subscription skips to avoid
+	*  duplicate registration — `registerProgramTriggers` owns them. */
+	programAfses = /* @__PURE__ */ new WeakSet();
+	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",
+			"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;
+		const fs = getPlatform().fs;
+		if (this.scriptsDir) await fs.mkdir(this.scriptsDir, { recursive: true });
+		if (this.dataDir) await fs.mkdir(this.dataDir, { recursive: true });
+		this.dirsReady = true;
+	}
+	async ensureDirs() {
+		if (!this.dirsReady) await this.ready();
+	}
+	async enqueueWrite(key, fn) {
+		const previous = this.writeQueues.get(key) ?? Promise.resolve();
+		let release;
+		const current = new Promise((resolve) => {
+			release = resolve;
+		});
+		this.writeQueues.set(key, previous.then(() => current, () => current));
+		await previous.catch(() => {});
+		try {
+			return await fn();
+		} finally {
+			release();
+			if (this.writeQueues.get(key) === current) this.writeQueues.delete(key);
+		}
+	}
+	async getScript(name) {
+		if (this.scriptsDir) {
+			const platform = getPlatform();
+			const filePath = platform.path.join(this.scriptsDir, `${name}.ash`);
+			try {
+				return {
+					source: await platform.fs.readTextFile(filePath),
+					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 writeFileAtomic(getPlatform().path.join(this.scriptsDir, `${name}.ash`), script.source);
+		}
+		this.scripts.set(name, script);
+	}
+	async hasScript(name) {
+		if (this.scriptsDir) try {
+			const platform = getPlatform();
+			await platform.fs.stat(platform.path.join(this.scriptsDir, `${name}.ash`));
+			return true;
+		} catch {
+			return false;
+		}
+		return this.scripts.has(name);
+	}
+	async removeScript(name) {
+		if (this.scriptsDir) try {
+			const platform = getPlatform();
+			await platform.fs.rm(platform.path.join(this.scriptsDir, `${name}.ash`));
+		} catch {}
+		this.scripts.delete(name);
+	}
+	async getAllScriptNames() {
+		if (this.scriptsDir) try {
+			return (await getPlatform().fs.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.enqueueWrite(`data:${path}`, async () => {
+			await this.ensureDirs();
+			await writeFileAtomic(getPlatform().path.join(this.dataDir, this.dataFileName(path)), JSON.stringify(data));
+		});
+	}
+	async updateScript(name, update) {
+		return this.enqueueWrite(`script:${name}`, async () => {
+			const next = await update(await this.getScript(name));
+			if (next) await this.setScript(name, next);
+			else await this.removeScript(name);
+			return next;
+		});
+	}
+	/** Load all persisted data files into a dataStore */
+	async loadPersistedData() {
+		const store = {};
+		if (!this.dataDir) return store;
+		const platform = getPlatform();
+		try {
+			const files = await platform.fs.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 platform.fs.readTextFile(platform.path.join(this.dataDir, file)));
+				} catch {}
+			}
+		} catch {}
+		return store;
+	}
+	onMount(afs) {
+		this.destroy();
+		this.afsRoot = afs;
+		this.initTriggers().catch(() => {});
+		if (afs.subscribe) this.externalScriptSubs = [afs.subscribe({ type: SCRIPT_EVENT_TYPES.REGISTERED }, (evt) => {
+			if (evt.data?.runtime !== "ash") return;
+			if (this.isFromProgramNamespace(evt.path)) return;
+			if (this.programAfses.has(afs)) return;
+			this.trackPendingTrigger(this.registerExternalScript(evt.path).catch(() => {}));
+		}), afs.subscribe({ type: SCRIPT_EVENT_TYPES.UNREGISTERED }, (evt) => {
+			if (evt.data?.runtime !== "ash") return;
+			if (this.isFromProgramNamespace(evt.path)) return;
+			if (this.programAfses.has(afs)) return;
+			this.unregisterExternalScript(evt.path);
+		})];
+	}
+	/** Check if a global event path belongs to a registered program namespace. */
+	isFromProgramNamespace(path) {
+		if (path.startsWith("/blocklets/")) return true;
+		for (const ns of this.programNamespaces) if (path.startsWith(`${ns}/`)) return true;
+		return false;
+	}
+	async registerExternalScript(path) {
+		const afs = this.afsRoot;
+		if (!afs?.read) return;
+		for (const ns of this.programNamespaces) if (this.triggerAfsOverrides.has(`${ns}:${path}`)) return;
+		for (const key of this.triggerSubs.keys()) if (key.endsWith(`:${path}`)) 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);
+	}
+	/** Wait for all pending trigger executions to complete. Useful in tests. */
+	async flushTriggers() {
+		while (this.pendingTriggers.size > 0) await Promise.allSettled([...this.pendingTriggers]);
+	}
+	trackPendingTrigger(promise) {
+		this.pendingTriggers.add(promise);
+		promise.finally(() => {
+			this.pendingTriggers.delete(promise);
+		});
+	}
+	/** 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();
+		this.triggerAfsOverrides.clear();
+		this.programTriggerKeys.clear();
+		this.programNamespaces.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 triggers for all .ash scripts in a program's /program/scripts/ directory.
+	* Uses the program's runtime AFS for both event subscription and action execution,
+	* ensuring triggered jobs operate in the correct program namespace (e.g., accessing
+	* the program's own telegram/slack providers instead of the host's).
+	*/
+	/**
+	* Register triggers for all .ash scripts in a program's script directories.
+	* @param runtimeAFS - The program's runtime AFS instance
+	* @param namespace - Optional namespace prefix to avoid key collisions when
+	*                    multiple blocklets share the same ASH provider instance.
+	*                    e.g. "/blocklets/telegram-assistant" → keys become
+	*                    "/blocklets/telegram-assistant:/program/scripts/foo.ash"
+	*/
+	async registerProgramTriggers(runtimeAFS, namespace) {
+		if (!runtimeAFS.list || !runtimeAFS.read) return;
+		if (namespace) this.programNamespaces.add(namespace);
+		this.programAfses.add(runtimeAFS);
+		const keyPrefix = namespace ? `${namespace}:` : "";
+		const programKey = namespace ?? "__default__";
+		const subKey = `${keyPrefix}__program__`;
+		this.unregisterProgramTriggers(programKey);
+		this.unregisterProgramSubscription(subKey);
+		let registeredCount = 0;
+		for (const dir of [
+			"/packages/scripts",
+			"/instance/scripts",
+			"/instance"
+		]) try {
+			const scriptsList = await runtimeAFS.list(dir, {});
+			for (const entry of scriptsList.data) {
+				if (!entry.path.endsWith(".ash")) continue;
+				const scriptPath = entry.path.startsWith("/") ? entry.path : `${dir}/${entry.path}`;
+				try {
+					const readResult = await runtimeAFS.read(scriptPath, {});
+					const source = String(readResult.data?.content ?? "");
+					if (!source.trim()) continue;
+					const result = compileSource(source);
+					if (!result.program) continue;
+					if (!result.program.units.some((u) => u.kind === "job" && u.trigger)) continue;
+					if (this.triggerSubs.has(scriptPath)) {
+						this.unregisterTriggers(scriptPath);
+						this.externalScripts.delete(scriptPath);
+					}
+					this.registerProgramScriptTrigger(programKey, keyPrefix + scriptPath, source, runtimeAFS);
+					registeredCount++;
+				} catch {}
+			}
+		} catch {}
+		log.debug(`[ASH] registerProgramTriggers ns=${namespace ?? "(none)"} registered=${registeredCount}`);
+		if (runtimeAFS.subscribe) {
+			const unsub = runtimeAFS.subscribe({ type: SCRIPT_EVENT_TYPES.REGISTERED }, (evt) => {
+				if (evt.data?.runtime !== "ash") return;
+				const p = (async () => {
+					try {
+						const readResult = await runtimeAFS.read(evt.path, {});
+						const source = String(readResult.data?.content ?? "");
+						if (!source.trim()) return;
+						this.registerProgramScriptTrigger(programKey, keyPrefix + evt.path, source, runtimeAFS);
+					} catch {}
+				})();
+				this.trackPendingTrigger(p);
+			});
+			this.triggerSubs.set(subKey, [unsub]);
+		}
+	}
+	registerProgramScriptTrigger(programKey, scriptName, source, runtimeAFS) {
+		this.registerTriggers(scriptName, source, runtimeAFS);
+		const keys = this.programTriggerKeys.get(programKey) ?? /* @__PURE__ */ new Set();
+		keys.add(scriptName);
+		this.programTriggerKeys.set(programKey, keys);
+	}
+	unregisterProgramTriggers(programKey) {
+		const keys = this.programTriggerKeys.get(programKey);
+		if (!keys) return;
+		for (const scriptName of keys) this.unregisterTriggers(scriptName);
+		this.programTriggerKeys.delete(programKey);
+	}
+	unregisterProgramSubscription(subKey) {
+		const existing = this.triggerSubs.get(subKey);
+		if (!existing) return;
+		for (const unsub of existing) unsub();
+		this.triggerSubs.delete(subKey);
+	}
+	/**
+	* Register EventBus subscriptions and cron schedules for all triggers in a script.
+	* Replaces any previous subscriptions/schedules for the same script name.
+	*
+	* When `afsOverride` is provided (program-scoped triggers), events are subscribed
+	* on the program AFS and the override is stored for use by `executeTriggerJob`.
+	* When re-registered without an explicit override (e.g., via script:registered),
+	* any existing program-scoped override is preserved.
+	*/
+	registerTriggers(scriptName, source, afsOverride) {
+		const effectiveOverride = afsOverride ?? this.triggerAfsOverrides.get(scriptName);
+		this.unregisterTriggers(scriptName);
+		if (effectiveOverride) this.triggerAfsOverrides.set(scriptName, effectiveOverride);
+		const result = compileSource(source);
+		if (!result.program) return;
+		const afs = effectiveOverride ?? 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,
+					type: trigger.event ? `*:${trigger.event}` : void 0
+				};
+				const unsub = afs.subscribe(filter, (evt) => {
+					const p = this.executeTriggerJob(scriptName, jobName, evt);
+					this.trackPendingTrigger(p);
+				});
+				unsubs.push(unsub);
+			} else if (trigger.kind === "cron") try {
+				new CronPattern(trigger.expression);
+				const cronKey = `${scriptName}:${jobName}`;
+				this.cronRegistry.set(cronKey, {
+					expression: trigger.expression,
+					scriptName,
+					jobName,
+					lastFiredMinute: 0
+				});
+				const cron = new Cron(trigger.expression, { protect: true }, () => {
+					const reg = this.cronRegistry.get(cronKey);
+					if (reg) reg.lastFiredMinute = Math.floor(Date.now() / 6e4);
+					const syntheticEvent = {
+						type: "cron",
+						path: `/cron/${scriptName}/${jobName}`,
+						source: "ash-cron",
+						timestamp: Date.now()
+					};
+					const p = this.executeTriggerJob(scriptName, jobName, syntheticEvent);
+					this.trackPendingTrigger(p);
+				});
+				crons.push(cron);
+			} catch (err) {
+				log.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);
+		}
+		for (const key of this.cronRegistry.keys()) if (key.startsWith(`${scriptName}:`)) this.cronRegistry.delete(key);
+		this.triggerAfsOverrides.delete(scriptName);
+	}
+	/**
+	* Tick all registered cron triggers — called by external alarm (e.g., DO alarm).
+	* Checks each cron expression against the current minute and fires matching jobs.
+	* Uses lastFiredMinute to prevent double-firing (croner timer may also fire).
+	*/
+	tickCronTriggers() {
+		const now = Date.now();
+		const currentMinute = Math.floor(now / 6e4);
+		for (const [, entry] of this.cronRegistry) {
+			if (entry.lastFiredMinute >= currentMinute) continue;
+			try {
+				if (!new Cron(entry.expression).match(new Date(now))) continue;
+			} catch {
+				continue;
+			}
+			entry.lastFiredMinute = currentMinute;
+			const syntheticEvent = {
+				type: "cron",
+				path: `/cron/${entry.scriptName}/${entry.jobName}`,
+				source: "ash-cron-tick",
+				timestamp: now
+			};
+			const p = this.executeTriggerJob(entry.scriptName, entry.jobName, syntheticEvent);
+			this.trackPendingTrigger(p);
+		}
+	}
+	/**
+	* 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 {
+				const readAFS = this.triggerAfsOverrides.get(scriptName) ?? this.afsRoot;
+				const colonIdx = scriptName.indexOf(":");
+				const readPath = colonIdx >= 0 ? scriptName.slice(colonIdx + 1) : scriptName;
+				if (readAFS?.read) try {
+					const file = await readAFS.read(readPath, {});
+					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 afsOverride = this.triggerAfsOverrides.get(scriptName);
+			const effectiveAFS = afsOverride ?? this.afsRoot;
+			const { world, written } = await this.createAsyncWorld(afsOverride);
+			const ctx = {
+				world: effectiveAFS ? {
+					read: (path, query) => readAfsRecords(effectiveAFS, world, path, query),
+					write: (path, data) => {
+						world.write(path, data);
+					},
+					publish: (topic, data) => {
+						world.publish(topic, data);
+					},
+					exec: world.exec && afsOverride ? async (path, input, params) => {
+						const augmentedInput = input.map((item) => typeof item === "object" && item !== null ? {
+							...item,
+							_scope_afs: afsOverride
+						} : item);
+						return world.exec(path, augmentedInput, params);
+					} : world.exec
+				} : world,
+				caps: new Set(["*"]),
+				logger: { log() {} },
+				output: { output() {} }
+			};
+			const initialStream = [{ ...event }];
+			const jobResult = await job.execute(ctx, initialStream);
+			if (jobResult.status !== "ok") log.error(`[ASH trigger] ${scriptName}/${jobName} status=${jobResult.status}`, jobResult.errors);
+			if (effectiveAFS?.write) for (const [path, data] of Object.entries(written)) if (path.endsWith(".log")) {
+				const content = `${data.map((item) => JSON.stringify(item)).join("\n")}\n`;
+				await effectiveAFS.write(path, { content }, { mode: "append" });
+			} else await effectiveAFS.write(path, { content: JSON.stringify(data) });
+		} catch (err) {
+			log.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"]
+				}
+			}
+		}] };
+	}
+	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: await readDoc(joinURL("cookbook", file)),
+			meta: { kind: "ash:documentation" }
+		};
+	}
+	async readAgentMd(_ctx) {
+		return {
+			id: "/.meta/agent.md",
+			path: "/.meta/agent.md",
+			content: await 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" }
+				}],
+				resources: { caps: [
+					{
+						op: "read",
+						path: "/*",
+						description: "Read scripts and results"
+					},
+					{
+						op: "write",
+						path: "/scripts/*",
+						description: "Write ASH script files"
+					},
+					{
+						op: "exec",
+						path: "/.actions/*",
+						description: "Execute root actions (run, validate)"
+					},
+					{
+						op: "exec",
+						path: "/scripts/*/.actions/*",
+						description: "Execute a script"
+					}
+				] }
+			},
+			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 rawContent = typeof entry === "string" ? entry : entry.content;
+		let existed = false;
+		const stored = await this.updateScript(name, async (existing) => {
+			existed = existing !== void 0;
+			if (rawContent === void 0 && existing) return {
+				source: existing.source,
+				createdAt: existing.createdAt,
+				updatedAt: now
+			};
+			return {
+				source: typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent) ?? "",
+				createdAt: existing?.createdAt ?? now,
+				updatedAt: now
+			};
+		});
+		if (!stored) throw new AFSNotFoundError(ctx.path, `Script not found: ${name}`);
+		this.registerTriggers(name, stored.source);
+		return {
+			data: this.buildScriptEntry(name, stored),
+			message: existed ? "Script updated" : "Script created"
+		};
+	}
+	async deleteScript(ctx) {
+		const name = ctx.params.scriptName.replace(/\.ash$/, "");
+		let existed = false;
+		await this.updateScript(name, async (existing) => {
+			existed = existing !== void 0 || await this.hasScript(name);
+		});
+		if (!existed) throw new AFSNotFoundError(ctx.path, `Script not found: ${name}`);
+		this.unregisterTriggers(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._scope_afs;
+				return this.runJob(source, jobName, args, { afsOverride: runtimeAFS$1 });
+			}
+			const hasCaps = Array.isArray(args.caps) && args.caps.length > 0;
+			const runtimeAFS = args._scope_afs;
+			const returnWrittenData = args._return_written_data === true;
+			const skipWritePrefix = typeof args._skip_write_prefix === "string" ? args._skip_write_prefix : void 0;
+			const cleanArgs = { ...args };
+			delete cleanArgs._scope_afs;
+			delete cleanArgs._return_written_data;
+			delete cleanArgs._skip_write_prefix;
+			return this.runAsh(source, cleanArgs, {
+				allowWriteBack: hasCaps,
+				afsOverride: runtimeAFS,
+				returnWrittenData,
+				skipWritePrefix
+			});
+		}
+		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") {
+			if (!ashAgentRunDeprecationLogged) {
+				log.warn("[ash] DEPRECATED: /ash/.actions/agent-run — use /dev/agent/.actions/run instead. This alias will be removed in a future version.");
+				ashAgentRunDeprecationLogged = true;
+			}
+			const afs = args._scope_afs ?? this.afsRoot;
+			if (!afs?.exec) return {
+				success: false,
+				error: {
+					code: "AGENT_RUN_ALIAS_NO_AFS",
+					message: "AFS root not available"
+				}
+			};
+			return afs.exec("/dev/agent/.actions/run", args, {});
+		}
+		if (actionName === "register-triggers") {
+			const runtimeAFS = args._scope_afs;
+			const namespace = typeof args.namespace === "string" ? args.namespace : void 0;
+			if (runtimeAFS) await this.registerProgramTriggers(runtimeAFS, namespace);
+			return {
+				success: true,
+				data: { registered: !!runtimeAFS }
+			};
+		}
+		if (actionName === "tick-crons") {
+			this.tickCronTriggers();
+			return {
+				success: true,
+				data: { cronCount: this.cronRegistry.size }
+			};
+		}
+		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: await 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[normalizeAbsoluteAfsPath(path)] ?? [];
+				},
+				write(path, data) {
+					const normalizedPath = normalizeAbsoluteAfsPath(path);
+					if (normalizedPath.startsWith(selfPrefix) || normalizedPath.startsWith("/scripts") || normalizedPath.startsWith("/.actions") || normalizedPath.startsWith("/.meta")) throw new Error(`Write blocked: '${path}' is a protected ASH provider path`);
+					writeCounts[normalizedPath] = (writeCounts[normalizedPath] ?? 0) + 1;
+					if (written[normalizedPath]) written[normalizedPath].push(...data);
+					else written[normalizedPath] = [...data];
+					dataStore[normalizedPath] = written[normalizedPath];
+					persistData(normalizedPath, data);
+				},
+				publish(topic, data) {
+					published[topic] = data;
+				},
+				async exec(path, input, params) {
+					const normalizedPath = normalizeAbsoluteAfsPath(path);
+					const rootActionMatch = /^\/\.actions\/([^/]+)$/.exec(normalizedPath) ?? (/* @__PURE__ */ new RegExp(`^${selfPrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\.actions\\/([^/]+)$`)).exec(normalizedPath);
+					if (!(rootActionMatch !== null && allowRootActions.has(rootActionMatch[1])) && (normalizedPath.startsWith(selfPrefix) || normalizedPath.startsWith("/.actions") || normalizedPath.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);
+						const mergeContext = (inputArgs, outputData) => {
+							const items = Array.isArray(outputData) ? outputData : [outputData];
+							const { _scope_afs: _, ...context } = inputArgs;
+							return items.map((d) => typeof d === "object" && d !== null ? {
+								...context,
+								...d
+							} : d);
+						};
+						const execAndCheck = async (mergedArgs) => {
+							const result = await afsRoot.exec(normalizedPath, mergedArgs, {});
+							if (!result.success) {
+								const errMsg = typeof result.error === "object" && result.error !== null ? result.error.message ?? JSON.stringify(result.error) : typeof result.data?.error === "string" ? result.data.error : `Action failed: ${normalizedPath}`;
+								throw new Error(errMsg);
+							}
+							return mergeContext(mergedArgs, result.data);
+						};
+						if (records.length <= 1) {
+							const mergedArgs = {
+								...records[0] ?? {},
+								...baseParams
+							};
+							if (afsOverride) mergedArgs._scope_afs = afsOverride;
+							return execAndCheck(mergedArgs);
+						}
+						const results = [];
+						for (const record of records) {
+							const mergedArgs = {
+								...record,
+								...baseParams
+							};
+							if (afsOverride) mergedArgs._scope_afs = afsOverride;
+							results.push(...await execAndCheck(mergedArgs));
+						}
+						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);
+			}
+		};
+	}
+	/**
+	* 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: ${result.diagnostics.map((d) => d.message).join("; ") || "unknown error"}`,
+				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 bridgedWorld = effectiveAFS ? {
+			read: (path, query) => readAfsRecords(effectiveAFS, world, path, query),
+			write: (path, data) => {
+				world.write(path, data);
+			},
+			publish: (topic, data) => {
+				world.publish(topic, data);
+			},
+			exec: world.exec
+		} : world;
+		let outputResult;
+		const ctx = {
+			world: bridgedWorld,
+			caps: new Set(["*"]),
+			logger: { log() {} },
+			output: { output(event$1) {
+				outputResult = event$1.content;
+			} }
+		};
+		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)) if (path.endsWith(".log")) {
+			const content = `${data.map((item) => JSON.stringify(item)).join("\n")}\n`;
+			await afs.write(path, { content }, { mode: "append" });
+		} else await afs.write(path, { content: JSON.stringify(data) });
+		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,
+				...outputResult !== void 0 ? { result: outputResult } : {}
+			}
+		};
+	}
+	async runAsh(source, args, options) {
+		const result = compileSource(this.applyParamOverridesToSource(source, args));
+		if (result.diagnostics.filter((d) => d.severity !== "warning").length > 0 || !result.program) {
+			const sanitizedDiags = result.diagnostics.map((d) => ({
+				...d,
+				message: sanitizeErrorPath(d.message)
+			}));
+			return {
+				success: false,
+				data: {
+					error: `Compilation failed: ${sanitizedDiags.filter((d) => d.severity !== "warning").map((d) => d.message).join("; ") || "unknown error"}`,
+					diagnostics: sanitizedDiags,
+					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: (path, query) => readAfsRecords(effectiveAFS, world, path, query),
+			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 {
+					if (path.endsWith(".log")) {
+						const content = `${data.map((item) => JSON.stringify(item)).join("\n")}\n`;
+						await afs.write(path, { content }, { mode: "append" });
+					} else 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", void 0, { effect: "write" })], AFSAsh.prototype, "execScript", null);
+__decorate([Exec("/scripts/:scriptName")], AFSAsh.prototype, "execScriptDirect", null);
+__decorate([Actions.Exec("/", void 0, void 0, { effect: "write" })], 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);
+
+//#endregion
+export { intersectTools, validateActionPath, validateToolCall, withQueryPairing };
+//# sourceMappingURL=index.mjs.map