@aigne/aos 0.2.0-beta

package/dist/system-mounts/install.mjs

@@ -0,0 +1,102 @@
+import { materializeProviderMount, redactError } from "../mount/materializer.mjs";
+import { aupResourceProjector } from "../projectors/aup-projector.mjs";
+import { SYSTEM_MOUNTS } from "./lists.mjs";
+import { validateDescriptor } from "./validate.mjs";
+import { time } from "@aigne/afs-timing";
+
+//#region src/system-mounts/install.ts
+function hasMount(afs, path) {
+	const getMounts = afs.getMounts;
+	if (typeof getMounts !== "function") return false;
+	return getMounts.call(afs).some((m) => m.path === path);
+}
+/**
+* Per-descriptor Server-Timing key so cold-start cost is attributable to a
+* single system device (`mnt.dev.chain`, `mnt.dev.ai`, …) instead of hiding
+* inside the aggregate `op.prov`. Slashes → dots to keep the metric name a
+* valid Server-Timing token. Diagnostic only — `time()` is a no-op when no
+* TimingCollector is active on the ALS.
+*/
+const mntKey = (path) => `mnt${path.replace(/\//g, ".")}`;
+/**
+* Install the system mounts described by `descriptors` (defaults to the
+* shared {@link SYSTEM_MOUNTS}) onto `afs`.
+*
+* Per descriptor, in `order`:
+*  1. {@link validateDescriptor} — invalid → skip + warning (path/`..`/proto
+*     pollution caught here, reusing the Phase 0 guard).
+*  2. `conditional(ctx) === false` → skip.
+*  3. `install` present → call it (composite hatch owns its own mounts +
+*     idempotency + degradation). A throw propagates — chain config errors
+*     stay fatal, matching the legacy daemon. Other hatches catch internally.
+*  4. else `registry[providerKey]` absent → skip (this is how CF gets a
+*     subset without a control-flow fork).
+*  5. else already mounted → skip (idempotent).
+*  6. else `materializeProviderMount` with the AUP projector. A materialize
+*     failure degrades to a warning (matches legacy ash/agent/index, which
+*     were individually non-fatal).
+*/
+async function installSystemMounts(afs, registry, ctx, descriptors = SYSTEM_MOUNTS) {
+	const mounted = [];
+	const skipped = [];
+	const warnings = [];
+	const ordered = [...descriptors].sort((a, b) => a.order - b.order);
+	for (const descriptor of ordered) {
+		const validation = validateDescriptor(descriptor);
+		if (!validation.ok) {
+			const label = descriptor?.path ?? "<unknown>";
+			warnings.push(`${label}: invalid descriptor — ${validation.errors.join("; ")}`);
+			skipped.push(String(label));
+			continue;
+		}
+		if (descriptor.install) {
+			const outcome = await time(mntKey(descriptor.path), () => descriptor.install(afs, ctx, registry));
+			mounted.push(...outcome.mounted);
+			warnings.push(...outcome.warnings);
+			continue;
+		}
+		const factory = registry[descriptor.providerKey];
+		if (!factory) {
+			skipped.push(descriptor.path);
+			continue;
+		}
+		if (descriptor.conditional && !descriptor.conditional(ctx)) {
+			skipped.push(descriptor.path);
+			continue;
+		}
+		if (hasMount(afs, descriptor.path)) {
+			skipped.push(descriptor.path);
+			continue;
+		}
+		const options = typeof descriptor.options === "function" ? descriptor.options(ctx) : descriptor.options;
+		try {
+			await time(mntKey(descriptor.path), () => materializeProviderMount({
+				afs,
+				mountPath: descriptor.path,
+				definition: {
+					uri: `${descriptor.providerKey}://system${descriptor.path}`,
+					type: descriptor.providerKey,
+					...options !== void 0 ? { options } : {}
+				},
+				factory,
+				projectors: [aupResourceProjector],
+				scope: "host",
+				...descriptor.mountOptions ? { mountOptions: descriptor.mountOptions } : {},
+				projectionFailure: descriptor.projectionFailure ?? "warn"
+			}));
+			mounted.push(descriptor.path);
+		} catch (err) {
+			warnings.push(`${descriptor.path}: mount failed — ${redactError(err)}`);
+			skipped.push(descriptor.path);
+		}
+	}
+	return {
+		mounted,
+		skipped,
+		warnings
+	};
+}
+
+//#endregion
+export { installSystemMounts };
+//# sourceMappingURL=install.mjs.map

package/dist/system-mounts/install.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.mjs","names":[],"sources":["../../src/system-mounts/install.ts"],"sourcesContent":["/**\n * `installSystemMounts` — the single shared driver every runtime calls to\n * install its host system mounts (axis A). Replaces the per-runtime\n * hand-written orchestration (Node's 7 `setupSystem*` functions, CF's inline\n * `if` blocks) with one ordered pass over {@link SYSTEM_MOUNTS}.\n *\n * Divergence between runtimes is expressed purely as data: a runtime passes\n * a `registry` (providerKey → factory) containing only the keys it can\n * build/run. A descriptor whose `providerKey` is absent (or whose `install`\n * hatch needs an absent key) is skipped — no control-flow fork.\n *\n * See `planning/system-mount-runtime-parity/design.md` §4 / §4.1.\n */\n\nimport type { AFS, AFSRoot } from \"@aigne/afs\";\nimport { time } from \"@aigne/afs-timing\";\nimport { materializeProviderMount, type ProviderFactory, redactError } from \"../mount/index.js\";\nimport { aupResourceProjector } from \"../projectors/index.js\";\nimport { SYSTEM_MOUNTS } from \"./lists.js\";\nimport type { SystemMountContext, SystemMountDescriptor } from \"./types.js\";\nimport { validateDescriptor } from \"./validate.js\";\n\n/** Aggregate result of an {@link installSystemMounts} run. */\nexport interface InstallSystemMountsResult {\n  /** Every path actually mounted (across default + install-hatch entries). */\n  mounted: string[];\n  /** Descriptor paths that were intentionally skipped (missing key, conditional, invalid). */\n  skipped: string[];\n  /** Non-fatal failures, prefixed with the offending path. */\n  warnings: string[];\n}\n\nfunction hasMount(afs: AFSRoot, path: string): boolean {\n  const getMounts = (afs as unknown as AFS).getMounts;\n  if (typeof getMounts !== \"function\") return false;\n  return getMounts.call(afs).some((m: { path: string }) => m.path === path);\n}\n\n/**\n * Per-descriptor Server-Timing key so cold-start cost is attributable to a\n * single system device (`mnt.dev.chain`, `mnt.dev.ai`, …) instead of hiding\n * inside the aggregate `op.prov`. Slashes → dots to keep the metric name a\n * valid Server-Timing token. Diagnostic only — `time()` is a no-op when no\n * TimingCollector is active on the ALS.\n */\nconst mntKey = (path: string): string => `mnt${path.replace(/\\//g, \".\")}`;\n\n/**\n * Install the system mounts described by `descriptors` (defaults to the\n * shared {@link SYSTEM_MOUNTS}) onto `afs`.\n *\n * Per descriptor, in `order`:\n *  1. {@link validateDescriptor} — invalid → skip + warning (path/`..`/proto\n *     pollution caught here, reusing the Phase 0 guard).\n *  2. `conditional(ctx) === false` → skip.\n *  3. `install` present → call it (composite hatch owns its own mounts +\n *     idempotency + degradation). A throw propagates — chain config errors\n *     stay fatal, matching the legacy daemon. Other hatches catch internally.\n *  4. else `registry[providerKey]` absent → skip (this is how CF gets a\n *     subset without a control-flow fork).\n *  5. else already mounted → skip (idempotent).\n *  6. else `materializeProviderMount` with the AUP projector. A materialize\n *     failure degrades to a warning (matches legacy ash/agent/index, which\n *     were individually non-fatal).\n */\nexport async function installSystemMounts(\n  afs: AFSRoot,\n  registry: Record<string, ProviderFactory>,\n  ctx: SystemMountContext,\n  descriptors: readonly SystemMountDescriptor[] = SYSTEM_MOUNTS,\n): Promise<InstallSystemMountsResult> {\n  const mounted: string[] = [];\n  const skipped: string[] = [];\n  const warnings: string[] = [];\n\n  // Copy before sort — never mutate the frozen shared list.\n  const ordered = [...descriptors].sort((a, b) => a.order - b.order);\n\n  for (const descriptor of ordered) {\n    const validation = validateDescriptor(descriptor);\n    if (!validation.ok) {\n      const label = (descriptor as Partial<SystemMountDescriptor>)?.path ?? \"<unknown>\";\n      warnings.push(`${label}: invalid descriptor — ${validation.errors.join(\"; \")}`);\n      skipped.push(String(label));\n      continue;\n    }\n\n    // Decision order mirrors design.md §4: install hatch → registry-miss →\n    // conditional → materialize. `install` takes precedence (composite hatch\n    // owns its own construction + idempotency + degradation); a throw is fatal\n    // by design (chain config validation), so we do NOT swallow it.\n    if (descriptor.install) {\n      const outcome = await time(mntKey(descriptor.path), () =>\n        descriptor.install!(afs, ctx, registry),\n      );\n      mounted.push(...outcome.mounted);\n      warnings.push(...outcome.warnings);\n      continue;\n    }\n\n    const factory = registry[descriptor.providerKey as string];\n    if (!factory) {\n      // Subset semantics: the runtime can't build this provider. Not an error.\n      skipped.push(descriptor.path);\n      continue;\n    }\n\n    if (descriptor.conditional && !descriptor.conditional(ctx)) {\n      skipped.push(descriptor.path);\n      continue;\n    }\n\n    if (hasMount(afs, descriptor.path)) {\n      skipped.push(descriptor.path);\n      continue;\n    }\n\n    const options =\n      typeof descriptor.options === \"function\" ? descriptor.options(ctx) : descriptor.options;\n\n    try {\n      await time(mntKey(descriptor.path), () =>\n        materializeProviderMount({\n          afs: afs as unknown as AFS,\n          mountPath: descriptor.path,\n          definition: {\n            // URI is informational (error messages); the factory constructs\n            // the provider from `options`.\n            uri: `${descriptor.providerKey}://system${descriptor.path}`,\n            type: descriptor.providerKey as string,\n            ...(options !== undefined ? { options } : {}),\n          },\n          factory,\n          projectors: [aupResourceProjector],\n          scope: \"host\",\n          ...(descriptor.mountOptions ? { mountOptions: descriptor.mountOptions } : {}),\n          projectionFailure: descriptor.projectionFailure ?? \"warn\",\n        }),\n      );\n      mounted.push(descriptor.path);\n    } catch (err) {\n      warnings.push(`${descriptor.path}: mount failed — ${redactError(err)}`);\n      skipped.push(descriptor.path);\n    }\n  }\n\n  return { mounted, skipped, warnings };\n}\n"],"mappings":";;;;;;;AAgCA,SAAS,SAAS,KAAc,MAAuB;CACrD,MAAM,YAAa,IAAuB;AAC1C,KAAI,OAAO,cAAc,WAAY,QAAO;AAC5C,QAAO,UAAU,KAAK,IAAI,CAAC,MAAM,MAAwB,EAAE,SAAS,KAAK;;;;;;;;;AAU3E,MAAM,UAAU,SAAyB,MAAM,KAAK,QAAQ,OAAO,IAAI;;;;;;;;;;;;;;;;;;;AAoBvE,eAAsB,oBACpB,KACA,UACA,KACA,cAAgD,eACZ;CACpC,MAAM,UAAoB,EAAE;CAC5B,MAAM,UAAoB,EAAE;CAC5B,MAAM,WAAqB,EAAE;CAG7B,MAAM,UAAU,CAAC,GAAG,YAAY,CAAC,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM;AAElE,MAAK,MAAM,cAAc,SAAS;EAChC,MAAM,aAAa,mBAAmB,WAAW;AACjD,MAAI,CAAC,WAAW,IAAI;GAClB,MAAM,QAAS,YAA+C,QAAQ;AACtE,YAAS,KAAK,GAAG,MAAM,yBAAyB,WAAW,OAAO,KAAK,KAAK,GAAG;AAC/E,WAAQ,KAAK,OAAO,MAAM,CAAC;AAC3B;;AAOF,MAAI,WAAW,SAAS;GACtB,MAAM,UAAU,MAAM,KAAK,OAAO,WAAW,KAAK,QAChD,WAAW,QAAS,KAAK,KAAK,SAAS,CACxC;AACD,WAAQ,KAAK,GAAG,QAAQ,QAAQ;AAChC,YAAS,KAAK,GAAG,QAAQ,SAAS;AAClC;;EAGF,MAAM,UAAU,SAAS,WAAW;AACpC,MAAI,CAAC,SAAS;AAEZ,WAAQ,KAAK,WAAW,KAAK;AAC7B;;AAGF,MAAI,WAAW,eAAe,CAAC,WAAW,YAAY,IAAI,EAAE;AAC1D,WAAQ,KAAK,WAAW,KAAK;AAC7B;;AAGF,MAAI,SAAS,KAAK,WAAW,KAAK,EAAE;AAClC,WAAQ,KAAK,WAAW,KAAK;AAC7B;;EAGF,MAAM,UACJ,OAAO,WAAW,YAAY,aAAa,WAAW,QAAQ,IAAI,GAAG,WAAW;AAElF,MAAI;AACF,SAAM,KAAK,OAAO,WAAW,KAAK,QAChC,yBAAyB;IAClB;IACL,WAAW,WAAW;IACtB,YAAY;KAGV,KAAK,GAAG,WAAW,YAAY,WAAW,WAAW;KACrD,MAAM,WAAW;KACjB,GAAI,YAAY,SAAY,EAAE,SAAS,GAAG,EAAE;KAC7C;IACD;IACA,YAAY,CAAC,qBAAqB;IAClC,OAAO;IACP,GAAI,WAAW,eAAe,EAAE,cAAc,WAAW,cAAc,GAAG,EAAE;IAC5E,mBAAmB,WAAW,qBAAqB;IACpD,CAAC,CACH;AACD,WAAQ,KAAK,WAAW,KAAK;WACtB,KAAK;AACZ,YAAS,KAAK,GAAG,WAAW,KAAK,mBAAmB,YAAY,IAAI,GAAG;AACvE,WAAQ,KAAK,WAAW,KAAK;;;AAIjC,QAAO;EAAE;EAAS;EAAS;EAAU"}

package/dist/system-mounts/installers.cjs

@@ -0,0 +1,247 @@
+const require_chain = require('../devices/chain.cjs');
+const require_materializer = require('../mount/materializer.cjs');
+const require_aup_projector = require('../projectors/aup-projector.cjs');
+let ufo = require("ufo");
+let _aigne_afs = require("@aigne/afs");
+let _aigne_afs_timing = require("@aigne/afs-timing");
+
+//#region src/system-mounts/installers.ts
+/**
+* Runtime-neutral `install` escape-hatch implementations for the composite
+* entries in {@link SYSTEM_MOUNTS} (design.md §4.1). These orchestrate
+* multi-step mounts that a single `path`+`providerKey` can't express:
+*
+*  - {@link aiInstall}            — `/dev/ai` device + legacy/compat projections
+*  - {@link chainInstall}         — `/dev/chain/<network>` per builtin/config network + AUP
+*  - {@link deviceInstall}        — `/dev/ui`, `/dev/web` projections (conditional on source)
+*  - {@link observabilityInstall} — `/dev/observability` (+ optional host-inbox)
+*  - {@link messagingInstall}     — `/proc/messaging/agents` + `/proc/messaging/tools`
+*
+* Crucial invariant: NONE of these import a runtime-specific module. All
+* provider *construction* is delegated to the `registry` factories the
+* runtime supplies (Node builds disk-backed providers + loads AUP from the
+* package dir; CF builds bundled providers + loads AUP over HTTP). Projection
+* uses `ProjectionProvider` from `@aigne/afs` (runtime-neutral) and AUP
+* companion resources flow through the factory's `resources` field + the
+* materializer's `aupResourceProjector`. So these hatches bundle cleanly into
+* the Cloudflare Worker even when CF's registry omits the keys (the hatch
+* skips that sub-mount).
+*/
+const PROJECTION_OVERLAY = { allowOverlay: true };
+function getMounts(afs) {
+	const fn = afs.getMounts;
+	return typeof fn === "function" ? fn.call(afs) : [];
+}
+function hasMount(afs, path) {
+	return getMounts(afs).some((m) => m.path === path);
+}
+/** Mount a `ProjectionProvider` alias `target → source`, idempotent + tolerant. */
+async function mountProjection(afs, target, source, name, out) {
+	if (hasMount(afs, target)) return;
+	try {
+		await afs.mount(new _aigne_afs.ProjectionProvider({
+			name,
+			globalAFS: afs,
+			sourcePath: source
+		}), target, PROJECTION_OVERLAY);
+		out.mounted.push(target);
+	} catch (err) {
+		out.warnings.push(`${target}: projection failed — ${require_materializer.redactError(err)}`);
+	}
+}
+const AI_DEVICE = "/dev/ai";
+const AI_HUBS_AIGNEHUB = "/dev/ai/hubs/aignehub";
+const AI_LOCAL_EMBEDDING = "/dev/ai/local/embedding";
+const LEGACY_AIGNEHUB = "/modules/aignehub";
+const LEGACY_EMBEDDING = "/modules/embedding";
+const COMPAT_HUB = "/dev/ai/hub";
+const COMPAT_DEFAULTS = "/dev/ai/defaults";
+const COMPAT_EMBEDDING = "/dev/ai/embedding";
+async function aiInstall(afs, _ctx, registry) {
+	const out = {
+		mounted: [],
+		warnings: []
+	};
+	if (!hasMount(afs, AI_HUBS_AIGNEHUB)) {
+		const legacy = hasMount(afs, LEGACY_AIGNEHUB) ? LEGACY_AIGNEHUB : hasMount(afs, COMPAT_HUB) ? COMPAT_HUB : null;
+		if (legacy) await mountProjection(afs, AI_HUBS_AIGNEHUB, legacy, "dev-ai-hubs-aignehub", out);
+	}
+	if (!hasMount(afs, AI_LOCAL_EMBEDDING) && hasMount(afs, LEGACY_EMBEDDING)) await mountProjection(afs, AI_LOCAL_EMBEDDING, LEGACY_EMBEDDING, "dev-ai-local-embedding", out);
+	if (hasMount(afs, AI_HUBS_AIGNEHUB)) {
+		await mountProjection(afs, COMPAT_HUB, AI_HUBS_AIGNEHUB, "dev-ai-hub-compat", out);
+		await mountProjection(afs, COMPAT_DEFAULTS, (0, ufo.joinURL)(AI_HUBS_AIGNEHUB, "defaults"), "dev-ai-defaults-compat", out);
+	}
+	if (hasMount(afs, AI_LOCAL_EMBEDDING)) await mountProjection(afs, COMPAT_EMBEDDING, AI_LOCAL_EMBEDDING, "dev-ai-embedding-compat", out);
+	if (!hasMount(afs, AI_DEVICE)) {
+		const factory = registry["ai-device"];
+		if (factory) try {
+			const options = { globalAFS: afs };
+			if (hasMount(afs, "/user")) options.userSpaceRoot = "/user";
+			const { provider } = await factory.create({
+				uri: `ai-device://system${AI_DEVICE}`,
+				type: "ai-device",
+				options
+			});
+			await afs.mount(provider, AI_DEVICE, PROJECTION_OVERLAY);
+			out.mounted.push(AI_DEVICE);
+		} catch (err) {
+			out.warnings.push(`${AI_DEVICE}: mount failed — ${require_materializer.redactError(err)}`);
+		}
+	}
+	return out;
+}
+async function chainInstall(afs, ctx, registry) {
+	const out = {
+		mounted: [],
+		warnings: []
+	};
+	const configs = ctx.chainConfigs;
+	const cfgs = [...configs && configs.length > 0 ? configs : require_chain.BUILTIN_CHAIN_NETWORKS];
+	require_chain.validateChainNetworks(cfgs);
+	const factory = registry["ocap"];
+	if (!factory) return out;
+	for (const cfg of cfgs) {
+		const path = require_chain.chainNetworkToMountEntry(cfg).path;
+		if (hasMount(afs, path)) continue;
+		try {
+			await (0, _aigne_afs_timing.time)(`mnt.dev.chain.${cfg.network}`, () => require_materializer.materializeProviderMount({
+				afs,
+				mountPath: path,
+				definition: {
+					uri: `ocap://system${path}`,
+					type: "ocap",
+					options: {
+						endpoint: cfg.endpoint,
+						description: `Chain network ${cfg.network} via ${safeEndpointLabel(cfg.endpoint)}`
+					}
+				},
+				factory,
+				projectors: [require_aup_projector.aupResourceProjector],
+				scope: "host",
+				mountOptions: PROJECTION_OVERLAY,
+				projectionFailure: "warn"
+			}));
+			out.mounted.push(path);
+		} catch (err) {
+			out.warnings.push(`${path}: mount failed — ${require_materializer.redactError(err)}`);
+		}
+	}
+	return out;
+}
+function safeEndpointLabel(endpoint) {
+	try {
+		const url = new URL(endpoint);
+		return `${url.protocol}//${url.host}`;
+	} catch {
+		return "<endpoint>";
+	}
+}
+async function deviceInstall(afs) {
+	const out = {
+		mounted: [],
+		warnings: []
+	};
+	for (const [target, source, name] of [[
+		"/dev/ui",
+		"/ui",
+		"dev-ui"
+	], [
+		"/dev/web",
+		"/web",
+		"dev-web"
+	]]) {
+		if (hasMount(afs, target)) continue;
+		if (!hasMount(afs, source)) continue;
+		await mountProjection(afs, target, source, name, out);
+	}
+	return out;
+}
+const OBS_PATH = "/dev/observability";
+const OBS_HOST_INBOX = "/dev/observability/.host-inbox";
+async function observabilityInstall(afs, _ctx, registry) {
+	const out = {
+		mounted: [],
+		warnings: []
+	};
+	if (hasMount(afs, OBS_PATH)) {
+		out.warnings.push(`${OBS_PATH}: already mounted — skipped`);
+		return out;
+	}
+	let hostInboxMounted = false;
+	const hostInboxFactory = registry["observability-host-inbox"];
+	if (hostInboxFactory) try {
+		const { provider } = await hostInboxFactory.create({
+			uri: `fs://system${OBS_HOST_INBOX}`,
+			type: "fs"
+		});
+		await afs.mount(provider, OBS_HOST_INBOX, { hidden: true });
+		hostInboxMounted = true;
+		out.mounted.push(OBS_HOST_INBOX);
+	} catch (err) {
+		out.warnings.push(`${OBS_HOST_INBOX}: mount failed — ${require_materializer.redactError(err)}`);
+	}
+	const factory = registry["observability"];
+	if (!factory) return out;
+	try {
+		await require_materializer.materializeProviderMount({
+			afs,
+			mountPath: OBS_PATH,
+			definition: {
+				uri: `observability://system${OBS_PATH}`,
+				type: "observability",
+				options: {
+					upstream: afs,
+					description: "AI agent observability — jsonl event log viewer",
+					...hostInboxMounted ? { hostInboxPath: OBS_HOST_INBOX } : {}
+				}
+			},
+			factory,
+			projectors: [require_aup_projector.aupResourceProjector],
+			scope: "host",
+			mountOptions: PROJECTION_OVERLAY,
+			projectionFailure: "warn"
+		});
+		out.mounted.push(OBS_PATH);
+	} catch (err) {
+		out.warnings.push(`${OBS_PATH}: mount failed — ${require_materializer.redactError(err)}`);
+	}
+	return out;
+}
+const MSG_AGENTS = "/proc/messaging/agents";
+const MSG_TOOLS = "/proc/messaging/tools";
+async function messagingInstall(afs, _ctx, registry) {
+	const out = {
+		mounted: [],
+		warnings: []
+	};
+	const agentsFactory = registry["messaging-agents"];
+	if (agentsFactory && !hasMount(afs, MSG_AGENTS)) try {
+		const { provider } = await agentsFactory.create({
+			uri: `fs://system${MSG_AGENTS}`,
+			type: "fs"
+		});
+		await afs.mount(provider, MSG_AGENTS, PROJECTION_OVERLAY);
+		out.mounted.push(MSG_AGENTS);
+	} catch (err) {
+		out.warnings.push(`${MSG_AGENTS}: mount failed — ${require_materializer.redactError(err)}`);
+	}
+	const toolsFactory = registry["messaging-tools"];
+	if (toolsFactory && !hasMount(afs, MSG_TOOLS)) try {
+		const { provider } = await toolsFactory.create({
+			uri: `messaging-tools://system${MSG_TOOLS}`,
+			type: "messaging-tools"
+		});
+		await afs.mount(provider, MSG_TOOLS, PROJECTION_OVERLAY);
+		out.mounted.push(MSG_TOOLS);
+	} catch (err) {
+		out.warnings.push(`${MSG_TOOLS}: mount failed — ${require_materializer.redactError(err)}`);
+	}
+	return out;
+}
+
+//#endregion
+exports.aiInstall = aiInstall;
+exports.chainInstall = chainInstall;
+exports.deviceInstall = deviceInstall;
+exports.messagingInstall = messagingInstall;
+exports.observabilityInstall = observabilityInstall;

package/dist/system-mounts/installers.d.cts

@@ -0,0 +1,13 @@
+import { ProviderFactory } from "../mount/types.cjs";
+import { InstallOutcome, SystemMountContext } from "./types.cjs";
+import { AFSRoot } from "@aigne/afs";
+
+//#region src/system-mounts/installers.d.ts
+declare function aiInstall(afs: AFSRoot, _ctx: SystemMountContext, registry: Record<string, ProviderFactory>): Promise<InstallOutcome>;
+declare function chainInstall(afs: AFSRoot, ctx: SystemMountContext, registry: Record<string, ProviderFactory>): Promise<InstallOutcome>;
+declare function deviceInstall(afs: AFSRoot): Promise<InstallOutcome>;
+declare function observabilityInstall(afs: AFSRoot, _ctx: SystemMountContext, registry: Record<string, ProviderFactory>): Promise<InstallOutcome>;
+declare function messagingInstall(afs: AFSRoot, _ctx: SystemMountContext, registry: Record<string, ProviderFactory>): Promise<InstallOutcome>;
+//#endregion
+export { aiInstall, chainInstall, deviceInstall, messagingInstall, observabilityInstall };
+//# sourceMappingURL=installers.d.cts.map

package/dist/system-mounts/installers.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installers.d.cts","names":[],"sources":["../../src/system-mounts/installers.ts"],"mappings":";;;;;iBAgFsB,SAAA,CACpB,GAAA,EAAK,OAAA,EACL,IAAA,EAAM,kBAAA,EACN,QAAA,EAAU,MAAA,SAAe,eAAA,IACxB,OAAA,CAAQ,cAAA;AAAA,iBAuEW,YAAA,CACpB,GAAA,EAAK,OAAA,EACL,GAAA,EAAK,kBAAA,EACL,QAAA,EAAU,MAAA,SAAe,eAAA,IACxB,OAAA,CAAQ,cAAA;AAAA,iBAiEW,aAAA,CAAc,GAAA,EAAK,OAAA,GAAU,OAAA,CAAQ,cAAA;AAAA,iBAuBrC,oBAAA,CACpB,GAAA,EAAK,OAAA,EACL,IAAA,EAAM,kBAAA,EACN,QAAA,EAAU,MAAA,SAAe,eAAA,IACxB,OAAA,CAAQ,cAAA;AAAA,iBAmEW,gBAAA,CACpB,GAAA,EAAK,OAAA,EACL,IAAA,EAAM,kBAAA,EACN,QAAA,EAAU,MAAA,SAAe,eAAA,IACxB,OAAA,CAAQ,cAAA"}

package/dist/system-mounts/installers.d.mts

@@ -0,0 +1,14 @@
+import { ProviderFactory } from "../mount/types.mjs";
+import "../mount/index.mjs";
+import { InstallOutcome, SystemMountContext } from "./types.mjs";
+import { AFSRoot } from "@aigne/afs";
+
+//#region src/system-mounts/installers.d.ts
+declare function aiInstall(afs: AFSRoot, _ctx: SystemMountContext, registry: Record<string, ProviderFactory>): Promise<InstallOutcome>;
+declare function chainInstall(afs: AFSRoot, ctx: SystemMountContext, registry: Record<string, ProviderFactory>): Promise<InstallOutcome>;
+declare function deviceInstall(afs: AFSRoot): Promise<InstallOutcome>;
+declare function observabilityInstall(afs: AFSRoot, _ctx: SystemMountContext, registry: Record<string, ProviderFactory>): Promise<InstallOutcome>;
+declare function messagingInstall(afs: AFSRoot, _ctx: SystemMountContext, registry: Record<string, ProviderFactory>): Promise<InstallOutcome>;
+//#endregion
+export { aiInstall, chainInstall, deviceInstall, messagingInstall, observabilityInstall };
+//# sourceMappingURL=installers.d.mts.map

package/dist/system-mounts/installers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installers.d.mts","names":[],"sources":["../../src/system-mounts/installers.ts"],"mappings":";;;;;;iBAgFsB,SAAA,CACpB,GAAA,EAAK,OAAA,EACL,IAAA,EAAM,kBAAA,EACN,QAAA,EAAU,MAAA,SAAe,eAAA,IACxB,OAAA,CAAQ,cAAA;AAAA,iBAuEW,YAAA,CACpB,GAAA,EAAK,OAAA,EACL,GAAA,EAAK,kBAAA,EACL,QAAA,EAAU,MAAA,SAAe,eAAA,IACxB,OAAA,CAAQ,cAAA;AAAA,iBAiEW,aAAA,CAAc,GAAA,EAAK,OAAA,GAAU,OAAA,CAAQ,cAAA;AAAA,iBAuBrC,oBAAA,CACpB,GAAA,EAAK,OAAA,EACL,IAAA,EAAM,kBAAA,EACN,QAAA,EAAU,MAAA,SAAe,eAAA,IACxB,OAAA,CAAQ,cAAA;AAAA,iBAmEW,gBAAA,CACpB,GAAA,EAAK,OAAA,EACL,IAAA,EAAM,kBAAA,EACN,QAAA,EAAU,MAAA,SAAe,eAAA,IACxB,OAAA,CAAQ,cAAA"}

package/dist/system-mounts/installers.mjs

@@ -0,0 +1,244 @@
+import { BUILTIN_CHAIN_NETWORKS, chainNetworkToMountEntry, validateChainNetworks } from "../devices/chain.mjs";
+import { materializeProviderMount, redactError } from "../mount/materializer.mjs";
+import { aupResourceProjector } from "../projectors/aup-projector.mjs";
+import { joinURL } from "ufo";
+import { ProjectionProvider } from "@aigne/afs";
+import { time } from "@aigne/afs-timing";
+
+//#region src/system-mounts/installers.ts
+/**
+* Runtime-neutral `install` escape-hatch implementations for the composite
+* entries in {@link SYSTEM_MOUNTS} (design.md §4.1). These orchestrate
+* multi-step mounts that a single `path`+`providerKey` can't express:
+*
+*  - {@link aiInstall}            — `/dev/ai` device + legacy/compat projections
+*  - {@link chainInstall}         — `/dev/chain/<network>` per builtin/config network + AUP
+*  - {@link deviceInstall}        — `/dev/ui`, `/dev/web` projections (conditional on source)
+*  - {@link observabilityInstall} — `/dev/observability` (+ optional host-inbox)
+*  - {@link messagingInstall}     — `/proc/messaging/agents` + `/proc/messaging/tools`
+*
+* Crucial invariant: NONE of these import a runtime-specific module. All
+* provider *construction* is delegated to the `registry` factories the
+* runtime supplies (Node builds disk-backed providers + loads AUP from the
+* package dir; CF builds bundled providers + loads AUP over HTTP). Projection
+* uses `ProjectionProvider` from `@aigne/afs` (runtime-neutral) and AUP
+* companion resources flow through the factory's `resources` field + the
+* materializer's `aupResourceProjector`. So these hatches bundle cleanly into
+* the Cloudflare Worker even when CF's registry omits the keys (the hatch
+* skips that sub-mount).
+*/
+const PROJECTION_OVERLAY = { allowOverlay: true };
+function getMounts(afs) {
+	const fn = afs.getMounts;
+	return typeof fn === "function" ? fn.call(afs) : [];
+}
+function hasMount(afs, path) {
+	return getMounts(afs).some((m) => m.path === path);
+}
+/** Mount a `ProjectionProvider` alias `target → source`, idempotent + tolerant. */
+async function mountProjection(afs, target, source, name, out) {
+	if (hasMount(afs, target)) return;
+	try {
+		await afs.mount(new ProjectionProvider({
+			name,
+			globalAFS: afs,
+			sourcePath: source
+		}), target, PROJECTION_OVERLAY);
+		out.mounted.push(target);
+	} catch (err) {
+		out.warnings.push(`${target}: projection failed — ${redactError(err)}`);
+	}
+}
+const AI_DEVICE = "/dev/ai";
+const AI_HUBS_AIGNEHUB = "/dev/ai/hubs/aignehub";
+const AI_LOCAL_EMBEDDING = "/dev/ai/local/embedding";
+const LEGACY_AIGNEHUB = "/modules/aignehub";
+const LEGACY_EMBEDDING = "/modules/embedding";
+const COMPAT_HUB = "/dev/ai/hub";
+const COMPAT_DEFAULTS = "/dev/ai/defaults";
+const COMPAT_EMBEDDING = "/dev/ai/embedding";
+async function aiInstall(afs, _ctx, registry) {
+	const out = {
+		mounted: [],
+		warnings: []
+	};
+	if (!hasMount(afs, AI_HUBS_AIGNEHUB)) {
+		const legacy = hasMount(afs, LEGACY_AIGNEHUB) ? LEGACY_AIGNEHUB : hasMount(afs, COMPAT_HUB) ? COMPAT_HUB : null;
+		if (legacy) await mountProjection(afs, AI_HUBS_AIGNEHUB, legacy, "dev-ai-hubs-aignehub", out);
+	}
+	if (!hasMount(afs, AI_LOCAL_EMBEDDING) && hasMount(afs, LEGACY_EMBEDDING)) await mountProjection(afs, AI_LOCAL_EMBEDDING, LEGACY_EMBEDDING, "dev-ai-local-embedding", out);
+	if (hasMount(afs, AI_HUBS_AIGNEHUB)) {
+		await mountProjection(afs, COMPAT_HUB, AI_HUBS_AIGNEHUB, "dev-ai-hub-compat", out);
+		await mountProjection(afs, COMPAT_DEFAULTS, joinURL(AI_HUBS_AIGNEHUB, "defaults"), "dev-ai-defaults-compat", out);
+	}
+	if (hasMount(afs, AI_LOCAL_EMBEDDING)) await mountProjection(afs, COMPAT_EMBEDDING, AI_LOCAL_EMBEDDING, "dev-ai-embedding-compat", out);
+	if (!hasMount(afs, AI_DEVICE)) {
+		const factory = registry["ai-device"];
+		if (factory) try {
+			const options = { globalAFS: afs };
+			if (hasMount(afs, "/user")) options.userSpaceRoot = "/user";
+			const { provider } = await factory.create({
+				uri: `ai-device://system${AI_DEVICE}`,
+				type: "ai-device",
+				options
+			});
+			await afs.mount(provider, AI_DEVICE, PROJECTION_OVERLAY);
+			out.mounted.push(AI_DEVICE);
+		} catch (err) {
+			out.warnings.push(`${AI_DEVICE}: mount failed — ${redactError(err)}`);
+		}
+	}
+	return out;
+}
+async function chainInstall(afs, ctx, registry) {
+	const out = {
+		mounted: [],
+		warnings: []
+	};
+	const configs = ctx.chainConfigs;
+	const cfgs = [...configs && configs.length > 0 ? configs : BUILTIN_CHAIN_NETWORKS];
+	validateChainNetworks(cfgs);
+	const factory = registry["ocap"];
+	if (!factory) return out;
+	for (const cfg of cfgs) {
+		const path = chainNetworkToMountEntry(cfg).path;
+		if (hasMount(afs, path)) continue;
+		try {
+			await time(`mnt.dev.chain.${cfg.network}`, () => materializeProviderMount({
+				afs,
+				mountPath: path,
+				definition: {
+					uri: `ocap://system${path}`,
+					type: "ocap",
+					options: {
+						endpoint: cfg.endpoint,
+						description: `Chain network ${cfg.network} via ${safeEndpointLabel(cfg.endpoint)}`
+					}
+				},
+				factory,
+				projectors: [aupResourceProjector],
+				scope: "host",
+				mountOptions: PROJECTION_OVERLAY,
+				projectionFailure: "warn"
+			}));
+			out.mounted.push(path);
+		} catch (err) {
+			out.warnings.push(`${path}: mount failed — ${redactError(err)}`);
+		}
+	}
+	return out;
+}
+function safeEndpointLabel(endpoint) {
+	try {
+		const url = new URL(endpoint);
+		return `${url.protocol}//${url.host}`;
+	} catch {
+		return "<endpoint>";
+	}
+}
+async function deviceInstall(afs) {
+	const out = {
+		mounted: [],
+		warnings: []
+	};
+	for (const [target, source, name] of [[
+		"/dev/ui",
+		"/ui",
+		"dev-ui"
+	], [
+		"/dev/web",
+		"/web",
+		"dev-web"
+	]]) {
+		if (hasMount(afs, target)) continue;
+		if (!hasMount(afs, source)) continue;
+		await mountProjection(afs, target, source, name, out);
+	}
+	return out;
+}
+const OBS_PATH = "/dev/observability";
+const OBS_HOST_INBOX = "/dev/observability/.host-inbox";
+async function observabilityInstall(afs, _ctx, registry) {
+	const out = {
+		mounted: [],
+		warnings: []
+	};
+	if (hasMount(afs, OBS_PATH)) {
+		out.warnings.push(`${OBS_PATH}: already mounted — skipped`);
+		return out;
+	}
+	let hostInboxMounted = false;
+	const hostInboxFactory = registry["observability-host-inbox"];
+	if (hostInboxFactory) try {
+		const { provider } = await hostInboxFactory.create({
+			uri: `fs://system${OBS_HOST_INBOX}`,
+			type: "fs"
+		});
+		await afs.mount(provider, OBS_HOST_INBOX, { hidden: true });
+		hostInboxMounted = true;
+		out.mounted.push(OBS_HOST_INBOX);
+	} catch (err) {
+		out.warnings.push(`${OBS_HOST_INBOX}: mount failed — ${redactError(err)}`);
+	}
+	const factory = registry["observability"];
+	if (!factory) return out;
+	try {
+		await materializeProviderMount({
+			afs,
+			mountPath: OBS_PATH,
+			definition: {
+				uri: `observability://system${OBS_PATH}`,
+				type: "observability",
+				options: {
+					upstream: afs,
+					description: "AI agent observability — jsonl event log viewer",
+					...hostInboxMounted ? { hostInboxPath: OBS_HOST_INBOX } : {}
+				}
+			},
+			factory,
+			projectors: [aupResourceProjector],
+			scope: "host",
+			mountOptions: PROJECTION_OVERLAY,
+			projectionFailure: "warn"
+		});
+		out.mounted.push(OBS_PATH);
+	} catch (err) {
+		out.warnings.push(`${OBS_PATH}: mount failed — ${redactError(err)}`);
+	}
+	return out;
+}
+const MSG_AGENTS = "/proc/messaging/agents";
+const MSG_TOOLS = "/proc/messaging/tools";
+async function messagingInstall(afs, _ctx, registry) {
+	const out = {
+		mounted: [],
+		warnings: []
+	};
+	const agentsFactory = registry["messaging-agents"];
+	if (agentsFactory && !hasMount(afs, MSG_AGENTS)) try {
+		const { provider } = await agentsFactory.create({
+			uri: `fs://system${MSG_AGENTS}`,
+			type: "fs"
+		});
+		await afs.mount(provider, MSG_AGENTS, PROJECTION_OVERLAY);
+		out.mounted.push(MSG_AGENTS);
+	} catch (err) {
+		out.warnings.push(`${MSG_AGENTS}: mount failed — ${redactError(err)}`);
+	}
+	const toolsFactory = registry["messaging-tools"];
+	if (toolsFactory && !hasMount(afs, MSG_TOOLS)) try {
+		const { provider } = await toolsFactory.create({
+			uri: `messaging-tools://system${MSG_TOOLS}`,
+			type: "messaging-tools"
+		});
+		await afs.mount(provider, MSG_TOOLS, PROJECTION_OVERLAY);
+		out.mounted.push(MSG_TOOLS);
+	} catch (err) {
+		out.warnings.push(`${MSG_TOOLS}: mount failed — ${redactError(err)}`);
+	}
+	return out;
+}
+
+//#endregion
+export { aiInstall, chainInstall, deviceInstall, messagingInstall, observabilityInstall };
+//# sourceMappingURL=installers.mjs.map