@aigne/afs 1.11.0-beta.5 → 1.11.0-beta.7

package/dist/afs.cjs

@@ -1,15 +1,48 @@
 const require_error = require('./error.cjs');
 const require_path = require('./path.cjs');
-const require_type = require('./type.cjs');
 let _aigne_uuid = require("@aigne/uuid");
-let strict_event_emitter = require("strict-event-emitter");
 let ufo = require("ufo");
-let zod = require("zod");
 
 //#region src/afs.ts
 const DEFAULT_MAX_DEPTH = 1;
 const MODULES_ROOT_DIR = "/modules";
 /**
+* Default timeout for mount check operations (10 seconds)
+*/
+const DEFAULT_MOUNT_TIMEOUT = 1e4;
+/**
+* Execute a promise with a timeout.
+* Throws an error if the promise does not resolve within the timeout.
+*/
+async function withTimeout(promise, ms) {
+	let timeoutId;
+	const timeoutPromise = new Promise((_, reject) => {
+		timeoutId = setTimeout(() => reject(/* @__PURE__ */ new Error(`Timeout after ${ms}ms`)), ms);
+	});
+	try {
+		return await Promise.race([promise, timeoutPromise]);
+	} finally {
+		clearTimeout(timeoutId);
+	}
+}
+/**
+* Get the timeout value for a provider.
+* Returns provider.timeout if set, otherwise DEFAULT_MOUNT_TIMEOUT.
+*/
+function getTimeout(provider) {
+	return provider.timeout ?? DEFAULT_MOUNT_TIMEOUT;
+}
+/**
+* Get error message from an error, handling timeout specially.
+*/
+function getMountErrorMessage(err, timeout) {
+	if (err instanceof Error) {
+		if (err.message.includes("Timeout")) return `Timeout after ${timeout}ms`;
+		return err.message;
+	}
+	return String(err);
+}
+/**
 * Characters forbidden in namespace names (security-sensitive)
 */
 const NAMESPACE_FORBIDDEN_CHARS = [
@@ -38,10 +71,19 @@ function validateNamespaceName(namespace) {
 	if (namespace.trim() === "") throw new Error("Namespace cannot be empty or whitespace-only");
 	for (const char of NAMESPACE_FORBIDDEN_CHARS) if (namespace.includes(char)) throw new Error(`Namespace contains forbidden character: '${char}'`);
 }
-var AFS = class extends strict_event_emitter.Emitter {
+var AFS = class {
 	name = "AFSRoot";
+	/**
+	* Injectable method for loading and mounting a provider from a URI.
+	* Injected by CLI layer (afs-loader.ts) with full pipeline:
+	*   1. ProviderRegistry.createProvider({ uri, path }) → provider instance
+	*   2. afs.mount(provider, path)
+	*   3. Persist to config.toml
+	*
+	* Used by root-level /.actions/mount action.
+	*/
+	loadProvider;
 	constructor(options = {}) {
-		super();
 		this.options = options;
 		for (const module of options?.modules ?? []) this.mount(module, (0, ufo.joinURL)(MODULES_ROOT_DIR, module.name));
 	}
@@ -69,17 +111,62 @@ var AFS = class extends strict_event_emitter.Emitter {
 	* Check if write operations are allowed for the given module.
 	* Throws AFSReadonlyError if not allowed.
 	*/
+	/** Fire-and-forget change notification */
+	notifyChange(record) {
+		try {
+			this.options.onChange?.(record);
+		} catch {}
+	}
 	checkWritePermission(module, operation, path) {
 		if (module.accessMode !== "readwrite") throw new require_error.AFSReadonlyError(`Module '${module.name}' is readonly, cannot perform ${operation} to ${path}`);
 	}
 	/**
+	* Check provider availability on mount.
+	* Validates that the provider can successfully respond to stat/read
+	* and list (if childrenCount indicates children exist).
+	*
+	* @throws AFSMountError if validation fails
+	*/
+	async checkProviderOnMount(provider) {
+		const timeout = getTimeout(provider);
+		const name = provider.name;
+		let rootData;
+		if (provider.stat) try {
+			rootData = (await withTimeout(provider.stat("/"), timeout)).data;
+		} catch (err) {
+			throw new require_error.AFSMountError(name, "stat", getMountErrorMessage(err, timeout));
+		}
+		else if (provider.read) try {
+			const result = await withTimeout(provider.read("/"), timeout);
+			if (result.data) rootData = {
+				path: result.data.path,
+				meta: result.data.meta ?? void 0
+			};
+		} catch (err) {
+			throw new require_error.AFSMountError(name, "read", getMountErrorMessage(err, timeout));
+		}
+		else throw new require_error.AFSMountError(name, "read", "Provider has no stat or read method");
+		if (!rootData) throw new require_error.AFSMountError(name, provider.stat ? "stat" : "read", "Root path returned undefined data");
+		const childrenCount = rootData.meta?.childrenCount;
+		if (childrenCount === -1 || typeof childrenCount === "number" && childrenCount > 0) {
+			if (!provider.list) throw new require_error.AFSMountError(name, "list", "Provider has childrenCount but no list method");
+			try {
+				const listResult = await withTimeout(provider.list("/"), timeout);
+				if (!listResult.data || listResult.data.length === 0) throw new require_error.AFSMountError(name, "list", "childrenCount indicates children but list returned empty");
+			} catch (err) {
+				if (err instanceof require_error.AFSMountError) throw err;
+				throw new require_error.AFSMountError(name, "list", getMountErrorMessage(err, timeout));
+			}
+		}
+	}
+	/**
 	* Mount a module at a path in a namespace
 	*
 	* @param module - The module to mount
 	* @param path - The path to mount at (optional, defaults to /modules/{module.name} for backward compatibility)
 	* @param options - Mount options (namespace, replace)
 	*/
-	mount(module, path, options) {
+	async mount(module, path, options) {
 		require_path.validateModuleName(module.name);
 		const normalizedPath = require_path.validatePath(path ?? (0, ufo.joinURL)(MODULES_ROOT_DIR, module.name));
 		const namespace = options?.namespace === void 0 ? null : options.namespace;
@@ -97,12 +184,20 @@ var AFS = class extends strict_event_emitter.Emitter {
 			if (existingPath.startsWith(normalizedPath) && (existingPath === normalizedPath || existingPath.length === normalizedPath.length || existingPath[normalizedPath.length] === "/")) throw new Error(`Mount conflict: path '${normalizedPath}' conflicts with existing mount '${existingPath}' in namespace '${namespace ?? "default"}'`);
 			if (normalizedPath.startsWith(existingPath) && (normalizedPath === existingPath || normalizedPath.length === existingPath.length || normalizedPath[existingPath.length] === "/")) throw new Error(`Mount conflict: path '${normalizedPath}' conflicts with existing mount '${existingPath}' in namespace '${namespace ?? "default"}'`);
 		}
+		await this.checkProviderOnMount(module);
 		this.mounts.set(key, {
 			namespace,
 			path: normalizedPath,
 			module
 		});
 		module.onMount?.(this);
+		this.notifyChange({
+			kind: "mount",
+			path: normalizedPath,
+			moduleName: module.name,
+			namespace,
+			timestamp: Date.now()
+		});
 		return this;
 	}
 	/**
@@ -138,8 +233,16 @@ var AFS = class extends strict_event_emitter.Emitter {
 		const normalizedPath = require_path.validatePath(path);
 		const ns = namespace === void 0 ? null : namespace;
 		const key = this.makeKey(ns, normalizedPath);
-		if (this.mounts.has(key)) {
+		const entry = this.mounts.get(key);
+		if (entry) {
 			this.mounts.delete(key);
+			this.notifyChange({
+				kind: "unmount",
+				path: normalizedPath,
+				moduleName: entry.module.name,
+				namespace: entry.namespace,
+				timestamp: Date.now()
+			});
 			return true;
 		}
 		return false;
@@ -197,11 +300,13 @@ var AFS = class extends strict_event_emitter.Emitter {
 			let newMaxDepth;
 			let subpath;
 			let remainedModulePath;
-			if (!options?.exactMatch && modulePath.startsWith(path)) {
+			const moduleUnderPath = !options?.exactMatch && modulePath.startsWith(path) && (modulePath === path || path === "/" || modulePath[path.length] === "/");
+			const pathUnderModule = path.startsWith(modulePath) && (path === modulePath || modulePath === "/" || path[modulePath.length] === "/");
+			if (moduleUnderPath) {
 				newMaxDepth = Math.max(0, maxDepth - (modulePathSegments.length - pathSegments.length));
 				subpath = "/";
 				remainedModulePath = (0, ufo.joinURL)("/", ...modulePathSegments.slice(pathSegments.length).slice(0, maxDepth));
-			} else if (path.startsWith(modulePath)) {
+			} else if (pathUnderModule) {
 				newMaxDepth = maxDepth;
 				subpath = (0, ufo.joinURL)("/", ...pathSegments.slice(modulePathSegments.length));
 				remainedModulePath = "/";
@@ -219,27 +324,22 @@ var AFS = class extends strict_event_emitter.Emitter {
 	}
 	async list(path, options = {}) {
 		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
-		let preset;
-		if (options.preset) {
-			preset = this.options?.context?.list?.presets?.[options.preset];
-			if (!preset) throw new Error(`Preset not found: ${options.preset}`);
-		}
-		return await this.processWithPreset(normalizedPath, void 0, preset, {
-			...options,
-			defaultSelect: () => this._list(normalizedPath, namespace, options)
-		});
+		return await this._list(normalizedPath, namespace, options);
 	}
 	async _list(path, namespace, options = {}) {
+		if (options?.maxDepth === 0) return { data: [] };
 		const results = [];
 		const hasModulesMounts = namespace === null && [...this.mounts.values()].some((m) => m.namespace === null && m.path.startsWith(`${MODULES_ROOT_DIR}/`));
 		if (path === "/" && hasModulesMounts) {
 			const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
+			let moduleCount = 0;
+			for (const entry of this.mounts.values()) if (entry.namespace === namespace) moduleCount++;
 			results.push({
 				id: "modules",
 				path: MODULES_ROOT_DIR,
 				summary: "All mounted modules",
-				metadata: {
-					type: "directory",
+				meta: {
+					childrenCount: moduleCount,
 					description: "All mounted modules"
 				}
 			});
@@ -259,48 +359,191 @@ var AFS = class extends strict_event_emitter.Emitter {
 					id: matched.module.name,
 					path: matched.modulePath,
 					summary: matched.module.description,
-					metadata: {
-						type: "module",
+					meta: {
+						childrenCount: -1,
 						description: matched.module.description
 					}
 				};
 				results.push(moduleEntry);
 				continue;
 			}
-			if (!matched.module.list) continue;
+			if (!matched.module.list) {
+				if (matched.module.read) try {
+					const childrenCount = (await matched.module.read(matched.subpath)).data?.meta?.childrenCount;
+					if (childrenCount === void 0 || childrenCount === 0) continue;
+					throw new Error(`Provider '${matched.module.name}' has childrenCount=${childrenCount} but does not implement list(). Providers with children must implement the list() method.`);
+				} catch (error) {
+					if (error instanceof Error && error.message.includes("does not implement list")) throw error;
+					continue;
+				}
+				continue;
+			}
 			try {
-				const { data } = await matched.module.list(matched.subpath, {
+				const result = await matched.module.list(matched.subpath, {
 					...options,
 					maxDepth: matched.maxDepth
 				});
-				const children = data.map((entry) => ({
+				const children = result.data.map((entry) => ({
 					...entry,
 					path: (0, ufo.joinURL)(matched.modulePath, entry.path)
 				}));
 				results.push(...children);
+				if (result.message && children.length === 0) return {
+					data: results,
+					message: result.message
+				};
 			} catch (error) {
 				throw new Error(`Error listing from module at ${matched.modulePath}: ${error.message}`);
 			}
 		}
 		return { data: results };
 	}
+	/**
+	* Check if a path should skip auto-enrichment.
+	* Paths ending with /.meta or /.actions should not be enriched
+	* to avoid recursive fetches, but their children (e.g., /.meta/kinds)
+	* can still be enriched.
+	*/
+	shouldSkipEnrich(path) {
+		return path.endsWith("/.meta") || path.endsWith("/.actions");
+	}
+	/**
+	* Fetch actions for a path by listing path/.actions.
+	* Returns ActionSummary[] on success, [] on failure.
+	*/
+	async fetchActions(module, subpath) {
+		try {
+			const actionsPath = (0, ufo.joinURL)(subpath, ".actions");
+			const result = await module.list?.(actionsPath);
+			if (!result?.data) return [];
+			return result.data.filter((entry) => entry.meta?.kind === "afs:executable").map((entry) => ({
+				name: entry.id,
+				description: entry.meta?.description,
+				inputSchema: entry.meta?.inputSchema
+			}));
+		} catch {
+			return [];
+		}
+	}
+	/**
+	* Fetch meta for a path by reading path/.meta.
+	* Returns the meta content on success, null on failure.
+	*/
+	async fetchMeta(module, subpath) {
+		try {
+			const metaPath = (0, ufo.joinURL)(subpath, ".meta");
+			const result = await module.read?.(metaPath);
+			if (!result?.data?.content) return null;
+			const content = result.data.content;
+			if (typeof content === "object" && content !== null && !Array.isArray(content)) return content;
+			return null;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Type for data that can be enriched (has path, optional actions, optional meta)
+	*/
+	async enrichData(data, module, subpath) {
+		if (this.shouldSkipEnrich(subpath)) return data;
+		const result = { ...data };
+		const enrichPromises = [];
+		if (result.actions === void 0) enrichPromises.push(this.fetchActions(module, subpath).then((actions) => {
+			result.actions = actions;
+		}));
+		if (result.meta?.kind === void 0) enrichPromises.push(this.fetchMeta(module, subpath).then((meta) => {
+			if (meta) result.meta = {
+				...result.meta,
+				...meta
+			};
+		}));
+		await Promise.all(enrichPromises);
+		return result;
+	}
 	async read(path, _options) {
 		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
+		if (normalizedPath === "/.meta/.capabilities") return { data: {
+			id: ".capabilities",
+			path: "/.meta/.capabilities",
+			content: await this.aggregateCapabilities(namespace),
+			meta: { kind: "afs:capabilities" }
+		} };
 		const modules = this.findModulesInNamespace(normalizedPath, namespace, { exactMatch: true });
 		for (const { module, modulePath, subpath } of modules) {
 			const res = await module.read?.(subpath);
-			if (res?.data) return {
-				...res,
-				data: {
-					...res.data,
-					path: (0, ufo.joinURL)(modulePath, res.data.path)
-				}
-			};
+			if (res?.data) {
+				const enrichedData = await this.enrichData(res.data, module, subpath);
+				return {
+					...res,
+					data: {
+						...enrichedData,
+						path: (0, ufo.joinURL)(modulePath, res.data.path)
+					}
+				};
+			}
 		}
-		return {
-			data: void 0,
-			message: "File not found"
+		throw new require_error.AFSNotFoundError(path);
+	}
+	/**
+	* Aggregate capabilities from all mounted providers.
+	*
+	* For each provider:
+	* - Read /.meta/.capabilities
+	* - Merge tools with provider prefix and mount path prefix
+	* - Merge actions with mount path prefix on discovery.pathTemplate
+	* - Silently skip providers that fail or don't implement capabilities
+	*/
+	async aggregateCapabilities(namespace) {
+		const allTools = [];
+		const allActions = [];
+		const skipped = [];
+		const allOperations = [];
+		const mounts = this.getMounts(namespace);
+		for (const mount of mounts) {
+			const { path: mountPath, module: provider } = mount;
+			try {
+				const content = (await provider.read?.("/.meta/.capabilities"))?.data?.content;
+				if (!content) continue;
+				const manifest = content;
+				for (const tool of manifest.tools ?? []) allTools.push({
+					...tool,
+					name: `${manifest.provider}.${tool.name}`,
+					path: (0, ufo.joinURL)(mountPath, tool.path)
+				});
+				for (const actionCatalog of manifest.actions ?? []) allActions.push({
+					...actionCatalog,
+					discovery: {
+						...actionCatalog.discovery,
+						pathTemplate: (0, ufo.joinURL)(mountPath, actionCatalog.discovery.pathTemplate)
+					}
+				});
+				if (manifest.operations) allOperations.push(manifest.operations);
+			} catch {
+				skipped.push(mountPath);
+			}
+		}
+		const result = {
+			schemaVersion: 1,
+			provider: "afs",
+			description: "AFS aggregated capabilities",
+			tools: allTools,
+			actions: allActions
+		};
+		if (allOperations.length > 0) result.operations = {
+			read: allOperations.some((o) => o.read),
+			list: allOperations.some((o) => o.list),
+			write: allOperations.some((o) => o.write),
+			delete: allOperations.some((o) => o.delete),
+			search: allOperations.some((o) => o.search),
+			exec: allOperations.some((o) => o.exec),
+			stat: allOperations.some((o) => o.stat),
+			explain: allOperations.some((o) => o.explain)
 		};
+		if (skipped.length > 0) {
+			result.partial = true;
+			result.skipped = skipped;
+		}
+		return result;
 	}
 	async write(path, content, options) {
 		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
@@ -308,20 +551,34 @@ var AFS = class extends strict_event_emitter.Emitter {
 		if (!module?.module.write) throw new Error(`No module found for path: ${normalizedPath} in namespace '${namespace ?? "default"}'`);
 		this.checkWritePermission(module.module, "write", path);
 		const res = await module.module.write(module.subpath, content, options);
-		return {
+		const result = {
 			...res,
 			data: {
 				...res.data,
 				path: (0, ufo.joinURL)(module.modulePath, res.data.path)
 			}
 		};
+		this.notifyChange({
+			kind: "write",
+			path: result.data.path,
+			moduleName: module.module.name,
+			timestamp: Date.now()
+		});
+		return result;
 	}
 	async delete(path, options) {
 		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
 		const module = this.findModulesInNamespace(normalizedPath, namespace, { exactMatch: true })[0];
 		if (!module?.module.delete) throw new Error(`No module found for path: ${normalizedPath} in namespace '${namespace ?? "default"}'`);
 		this.checkWritePermission(module.module, "delete", path);
-		return await module.module.delete(module.subpath, options);
+		const result = await module.module.delete(module.subpath, options);
+		this.notifyChange({
+			kind: "delete",
+			path: (0, ufo.joinURL)(module.modulePath, module.subpath),
+			moduleName: module.module.name,
+			timestamp: Date.now()
+		});
+		return result;
 	}
 	async rename(oldPath, newPath, options) {
 		const { namespace: oldNamespace, path: normalizedOldPath } = this.parsePathWithNamespace(oldPath);
@@ -332,43 +589,20 @@ var AFS = class extends strict_event_emitter.Emitter {
 		if (!oldModule || !newModule || oldModule.modulePath !== newModule.modulePath) throw new Error(`Cannot rename across different modules. Both paths must be in the same module.`);
 		if (!oldModule.module.rename) throw new Error(`Module does not support rename operation: ${oldModule.modulePath}`);
 		this.checkWritePermission(oldModule.module, "rename", oldPath);
-		return await oldModule.module.rename(oldModule.subpath, newModule.subpath, options);
+		const result = await oldModule.module.rename(oldModule.subpath, newModule.subpath, options);
+		this.notifyChange({
+			kind: "rename",
+			path: (0, ufo.joinURL)(oldModule.modulePath, oldModule.subpath),
+			moduleName: oldModule.module.name,
+			namespace: oldNamespace,
+			meta: { newPath: (0, ufo.joinURL)(newModule.modulePath, newModule.subpath) },
+			timestamp: Date.now()
+		});
+		return result;
 	}
 	async search(path, query, options = {}) {
 		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
-		let preset;
-		if (options.preset) {
-			preset = this.options?.context?.search?.presets?.[options.preset];
-			if (!preset) throw new Error(`Preset not found: ${options.preset}`);
-		}
-		return await this.processWithPreset(normalizedPath, query, preset, {
-			...options,
-			defaultSelect: () => this._search(normalizedPath, namespace, query, options)
-		});
-	}
-	async processWithPreset(path, query, preset, options) {
-		const select = options.select || preset?.select;
-		const per = options.per || preset?.per;
-		const dedupe = options.dedupe || preset?.dedupe;
-		const format = options.format || preset?.format;
-		const entries = select ? (await this._select(path, query, select, options)).data : (await options.defaultSelect()).data;
-		const mapped = per ? await Promise.all(entries.map((data) => per.invoke({ data }, options).then((res) => res.data))) : entries;
-		const deduped = dedupe ? await dedupe.invoke({ data: mapped }, options).then((res) => res.data) : mapped;
-		let formatted = deduped;
-		if (format === "simple-list" || format === "tree") {
-			const valid = zod.z.array(require_type.afsEntrySchema).safeParse(deduped);
-			if (!valid.data) throw new Error("Tree format requires entries to be AFSEntry objects");
-			if (format === "tree") formatted = this.buildTreeView(valid.data);
-			else if (format === "simple-list") formatted = this.buildSimpleListView(valid.data);
-		} else if (typeof format === "object" && typeof format.invoke === "function") formatted = await format.invoke({ data: deduped }, options).then((res) => res.data);
-		return { data: formatted };
-	}
-	async _select(path, query, select, options) {
-		const { data } = await select.invoke({
-			path,
-			query
-		}, options);
-		return { data: (await Promise.all(data.map((p) => this.read(p).then((res) => res.data)))).filter((i) => !!i) };
+		return await this._search(normalizedPath, namespace, query, options);
 	}
 	async _search(path, namespace, query, options) {
 		const results = [];
@@ -391,50 +625,169 @@ var AFS = class extends strict_event_emitter.Emitter {
 			message: messages.join("; ")
 		};
 	}
-	async exec(path, args, options) {
+	async exec(path, args, options = {}) {
 		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
+		if (normalizedPath.startsWith("/.actions/")) return await this.execRootAction(normalizedPath, args);
 		const module = this.findModulesInNamespace(normalizedPath, namespace)[0];
 		if (!module?.module.exec) throw new Error(`No module found for path: ${normalizedPath} in namespace '${namespace ?? "default"}'`);
-		return await module.module.exec(module.subpath, args, options);
-	}
-	buildSimpleListView(entries) {
-		return entries.map((entry) => `${entry.path}${this.buildMetadataSuffix(entry)}`);
-	}
-	buildTreeView(entries) {
-		const tree = {};
-		const entryMap = /* @__PURE__ */ new Map();
-		for (const entry of entries) {
-			entryMap.set(entry.path, entry);
-			const parts = entry.path.split("/").filter(Boolean);
-			let current = tree;
-			for (const part of parts) {
-				if (!current[part]) current[part] = {};
-				current = current[part];
+		this.checkWritePermission(module.module, "exec", path);
+		await this.validateExecInput(module.module, module.subpath, args);
+		const enhancedOptions = {
+			...options,
+			context: {
+				...options?.context,
+				afs: this
+			}
+		};
+		return await module.module.exec(module.subpath, args, enhancedOptions);
+	}
+	/**
+	* Handle root-level action execution (/.actions/*).
+	* Currently supports:
+	* - /.actions/mount: Load and mount a provider via loadProvider
+	*/
+	async execRootAction(path, args) {
+		const actionName = path.slice(10);
+		if (actionName === "mount") return await this.execRootMountAction(args);
+		throw new require_error.AFSNotFoundError(path, `Root action not found: ${actionName}`);
+	}
+	/**
+	* Execute root-level mount action.
+	* Validates input and delegates to loadProvider.
+	*/
+	async execRootMountAction(args) {
+		if (typeof args.uri !== "string" || args.uri === "") throw new require_error.AFSValidationError("Input validation failed: uri: must be a non-empty string");
+		if (typeof args.path !== "string" || args.path === "") throw new require_error.AFSValidationError("Input validation failed: path: must be a non-empty string");
+		if (!this.loadProvider) throw new Error("loadProvider not configured");
+		await this.loadProvider(args.uri, args.path);
+		return {
+			success: true,
+			data: {
+				uri: args.uri,
+				path: args.path
 			}
-		}
-		const renderTree = (node, prefix = "", currentPath = "") => {
-			let result = "";
-			const keys = Object.keys(node);
-			keys.forEach((key, index) => {
-				const isLast = index === keys.length - 1;
-				const fullPath = currentPath ? `${currentPath}/${key}` : `/${key}`;
-				const entry = entryMap.get(fullPath);
-				result += `${prefix}${isLast ? "└── " : "├── "}${key}${entry ? this.buildMetadataSuffix(entry) : ""}`;
-				result += `\n`;
-				result += renderTree(node[key], `${prefix}${isLast ? "    " : "│   "}`, fullPath);
-			});
-			return result;
 		};
-		return renderTree(tree);
-	}
-	buildMetadataSuffix(entry) {
-		const metadataParts = [];
-		const childrenCount = entry?.metadata?.childrenCount;
-		if (typeof childrenCount === "number") metadataParts.push(`${childrenCount} items`);
-		if (entry?.metadata?.childrenTruncated) metadataParts.push("truncated");
-		if (entry?.metadata?.gitignored) metadataParts.push("gitignored");
-		if (entry?.metadata?.execute) metadataParts.push("executable");
-		return metadataParts.length > 0 ? ` [${metadataParts.join(", ")}]` : "";
+	}
+	/**
+	* Validate exec input args against inputSchema.
+	* Throws AFSValidationError if validation fails.
+	* Uses zod-from-json-schema for full JSON Schema validation.
+	*/
+	async validateExecInput(module, subpath, args) {
+		let inputSchema;
+		if (module.read) try {
+			inputSchema = (await module.read(subpath)).data?.meta?.inputSchema;
+		} catch {
+			return;
+		}
+		if (!inputSchema) return;
+		try {
+			const { convertJsonSchemaToZod } = await import("zod-from-json-schema");
+			convertJsonSchemaToZod(inputSchema).parse(args);
+		} catch (error) {
+			if (error instanceof Error && error.name === "ZodError") throw new require_error.AFSValidationError(`Input validation failed: ${error.issues.map((issue) => {
+				const path = issue.path.join(".");
+				return path ? `${path}: ${issue.message}` : issue.message;
+			}).join("; ")}`);
+		}
+	}
+	/**
+	* Get stat information for a path
+	*
+	* Resolution order:
+	* 1. Provider's stat() method (if implemented)
+	* 2. Fallback to read() - extracts stat data from AFSEntry
+	*
+	* This allows providers to implement only read() while stat() still works.
+	*/
+	async stat(path, options) {
+		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
+		const module = this.findModulesInNamespace(normalizedPath, namespace)[0];
+		if (!module) throw new require_error.AFSNotFoundError(path);
+		if (module.module.stat) try {
+			const result = await module.module.stat(module.subpath, options);
+			if (result.data) {
+				const enrichedData = await this.enrichData(result.data, module.module, module.subpath);
+				return {
+					...result,
+					data: enrichedData
+				};
+			}
+			throw new require_error.AFSNotFoundError(path);
+		} catch (error) {
+			if (error instanceof require_error.AFSNotFoundError) throw error;
+		}
+		if (module.module.read) {
+			const readResult = await module.module.read(module.subpath, options);
+			if (readResult.data) {
+				const { content: _content, ...statData } = readResult.data;
+				return { data: await this.enrichData(statData, module.module, module.subpath) };
+			}
+		}
+		throw new require_error.AFSNotFoundError(path);
+	}
+	/**
+	* Get human-readable explanation for a path
+	*
+	* Resolution order:
+	* 1. Provider's explain() method (if implemented)
+	* 2. Fallback to stat() - builds explanation from metadata
+	*
+	* This allows providers to skip implementing explain() while it still works.
+	*/
+	async explain(path, options) {
+		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
+		const module = this.findModulesInNamespace(normalizedPath, namespace)[0];
+		if (!module) throw new require_error.AFSNotFoundError(path);
+		if (module.module.explain) try {
+			return await module.module.explain(module.subpath, options);
+		} catch (error) {
+			if (error instanceof require_error.AFSNotFoundError) throw error;
+		}
+		const data = (await this.stat(path, options)).data;
+		if (data) {
+			const lines = [];
+			lines.push(`# ${normalizedPath}`);
+			lines.push("");
+			const meta = data.meta || {};
+			if (meta.size !== void 0) lines.push(`- **Size**: ${this.formatBytes(meta.size)}`);
+			if (meta.childrenCount !== void 0) lines.push(`- **Children**: ${meta.childrenCount} items`);
+			if (data.updatedAt) lines.push(`- **Modified**: ${data.updatedAt.toISOString()}`);
+			if (meta.description) {
+				lines.push("");
+				lines.push("## Description");
+				lines.push(String(meta.description));
+			}
+			if (meta.provider) lines.push(`- **Provider**: ${meta.provider}`);
+			if (meta.kind) lines.push(`- **Kind**: ${meta.kind}`);
+			if (meta.kinds && Array.isArray(meta.kinds)) lines.push(`- **Kinds**: ${meta.kinds.join(", ")}`);
+			if (data.actions && data.actions.length > 0) {
+				lines.push("");
+				lines.push("## Actions");
+				for (const action of data.actions) lines.push(`- **${action.name}**${action.description ? `: ${action.description}` : ""}`);
+			}
+			return {
+				format: "markdown",
+				content: lines.join("\n")
+			};
+		}
+		throw new Error(`No explain or stat handler for path: ${normalizedPath} in namespace '${namespace ?? "default"}'`);
+	}
+	/**
+	* Format bytes to human-readable string
+	*/
+	formatBytes(bytes) {
+		if (bytes === 0) return "0 B";
+		const k = 1024;
+		const sizes = [
+			"B",
+			"KB",
+			"MB",
+			"GB",
+			"TB"
+		];
+		const i = Math.floor(Math.log(bytes) / Math.log(k));
+		return `${Number.parseFloat((bytes / k ** i).toFixed(2))} ${sizes[i]}`;
 	}
 	physicalPath;
 	async initializePhysicalPath() {