@nextclaw/kernel 0.6.28 → 0.7.0

package/dist/index.js

@@ -10,7 +10,7 @@ import { catchError, filter, from, lastValueFrom, tap } from "rxjs";
 import { appendFileSync, chmodSync, constants, createReadStream, existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import path, { basename, delimiter, dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { access, appendFile, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
-import { AppHomeService, AppInstallationService, AppManifestService, AppRegistryService, isAppComponentManifestBundle } from "@nextclaw/app-runtime";
+import { AppHomeService, AppInstallationService, AppInstanceStorageService, AppManifestService, AppRegistryService, isAppComponentManifestBundle } from "@nextclaw/app-runtime";
 import { execFileSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { BUILTIN_PROVIDER_PLUGINS } from "@nextclaw/runtime";
@@ -2686,6 +2686,52 @@ var AppPackageOperationManager = class {
 	isMissingFileError = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 };
 //#endregion
+//#region src/services/app-package-presentation.service.ts
+var AppPackagePresentationService = class {
+	readManifest = async (manifestPath) => {
+		const candidate = JSON.parse(await readFile(manifestPath, "utf8"));
+		const rawIcon = typeof candidate.icon === "string" ? candidate.icon : void 0;
+		return {
+			...typeof candidate.title === "string" ? { title: candidate.title } : {},
+			...typeof candidate.description === "string" ? { description: candidate.description } : {},
+			...rawIcon ? { icon: await this.resolveIcon(manifestPath, rawIcon) } : {},
+			...this.readLocalizedField(candidate, "nameI18n"),
+			...this.readLocalizedField(candidate, "titleI18n"),
+			...this.readLocalizedField(candidate, "descriptionI18n")
+		};
+	};
+	readLocalizedField = (candidate, field) => {
+		const value = candidate[field];
+		if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+		const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+		return entries.length > 0 ? { [field]: Object.fromEntries(entries) } : {};
+	};
+	resolveIcon = async (manifestPath, icon) => {
+		if (this.isDirectIconReference(icon)) return icon;
+		const manifestDirectory = path.dirname(manifestPath);
+		const iconPath = path.resolve(manifestDirectory, icon);
+		const relative = path.relative(manifestDirectory, iconPath);
+		if (relative.startsWith("..") || path.isAbsolute(relative)) return icon;
+		const mimeType = this.iconMimeType(path.extname(iconPath));
+		if (!mimeType) return icon;
+		const bytes = await readFile(iconPath);
+		if (bytes.byteLength > 256 * 1024) return icon;
+		return `data:${mimeType};base64,${bytes.toString("base64")}`;
+	};
+	isDirectIconReference = (icon) => icon.startsWith("data:") || icon.startsWith("http://") || icon.startsWith("https://") || icon.startsWith("/") || !icon.includes("/") && !icon.includes(".") && [...icon].length <= 8;
+	iconMimeType = (extension) => {
+		switch (extension.toLowerCase()) {
+			case ".svg": return "image/svg+xml";
+			case ".png": return "image/png";
+			case ".jpg":
+			case ".jpeg": return "image/jpeg";
+			case ".webp": return "image/webp";
+			case ".gif": return "image/gif";
+			default: return;
+		}
+	};
+};
+//#endregion
 //#region src/types/app-package.types.ts
 var AppPackageError = class extends Error {
 	constructor(code, message) {
@@ -2812,6 +2858,7 @@ var AppPackageManager = class {
 	installationService;
 	manifestService = new AppManifestService();
 	operationManager;
+	presentationService = new AppPackagePresentationService();
 	registryService;
 	runtimeHooks = EMPTY_RUNTIME_HOOKS;
 	builtInBootstrapPromise;
@@ -2845,7 +2892,9 @@ var AppPackageManager = class {
 	};
 	listActiveComponentSources = async () => {
 		await this.ensureBuiltInPackages();
-		return (await this.registryService.listApps()).filter((record) => record.enabled).flatMap((record) => {
+		const records = await this.registryService.listApps();
+		return (await Promise.all(records.filter((record) => record.enabled).map(async (record) => {
+			await this.installationService.assertVersionIntegrity(record.appId, record.activeVersion);
 			const version = record.installedVersions[record.activeVersion];
 			if (!version || version.manifestSchemaVersion !== 2) return [];
 			return (version.components ?? []).map((component) => ({
@@ -2855,9 +2904,12 @@ var AppPackageManager = class {
 				packageVersion: record.activeVersion,
 				sourcePath: component.componentDirectory,
 				manifestPath: component.manifestPath,
-				dataDirectory: record.dataDirectory
+				dataDirectory: record.dataDirectory,
+				instanceId: record.defaultInstance.id,
+				storage: record.defaultInstance.storage,
+				...this.resolveSecurity(version, record.appId)
 			}));
-		});
+		}))).flat();
 	};
 	listOperations = async () => await this.operationManager.list();
 	startOperation = async (input) => {
@@ -2873,66 +2925,115 @@ var AppPackageManager = class {
 		return await this.getPackage(result.appId);
 	};
 	enable = async (appId) => {
-		const app = await this.getPackage(appId);
-		if (app.enabled) return app;
-		await this.assertEngineCompatibility(appId);
-		const sources = this.toComponentSources(app);
-		await this.runtimeHooks.assertCanActivate(sources);
-		await this.installationService.setEnabled(appId, true);
-		return await this.getPackage(appId);
+		return await this.installationService.withAppOperation(appId, async () => {
+			const app = await this.getPackage(appId);
+			await this.installationService.assertVersionIntegrity(appId, app.activeVersion);
+			if (app.enabled) return app;
+			await this.assertEngineCompatibility(appId);
+			const sources = this.toComponentSources(app);
+			await this.runtimeHooks.assertCanActivate(sources);
+			await this.installationService.setEnabled(appId, true);
+			return await this.getPackage(appId);
+		});
 	};
 	disable = async (appId) => {
-		const app = await this.getPackage(appId);
-		if (!app.enabled) return app;
-		await this.runtimeHooks.beforeDeactivate(this.toComponentSources(app));
-		await this.installationService.setEnabled(appId, false);
-		return await this.getPackage(appId);
+		return await this.installationService.withAppOperation(appId, async () => {
+			const app = await this.getPackage(appId);
+			if (!app.enabled) return app;
+			await this.runtimeHooks.beforeDeactivate(this.toComponentSources(app));
+			await this.installationService.setEnabled(appId, false);
+			return await this.getPackage(appId);
+		});
 	};
 	update = async (appId, options = {}) => {
-		const current = await this.getPackage(appId);
-		if (current.enabled) await this.runtimeHooks.beforeDeactivate(this.toComponentSources(current));
-		const result = await this.installationService.update(appId, options);
-		try {
-			await this.assertEngineCompatibility(appId);
-			const updated = await this.getPackage(appId);
-			if (updated.enabled) await this.runtimeHooks.assertCanActivate(this.toComponentSources(updated));
-			return {
-				package: updated,
+		return await this.installationService.withAppOperation(appId, async () => {
+			const current = await this.getPackage(appId);
+			const result = await this.installationService.update(appId, {
+				...options,
+				activate: false
+			});
+			if (!result.updated) return {
+				package: current,
 				result
 			};
-		} catch (error) {
-			if (result.updated) await this.installationService.rollback(appId, result.previousVersion);
-			throw error;
-		}
+			let activated = false;
+			let deactivated = false;
+			try {
+				await this.assertEngineCompatibility(appId, result.version);
+				const candidate = await this.toPackageView(await this.installationService.info(appId), result.version);
+				if (current.enabled) {
+					await this.runtimeHooks.beforeDeactivate(this.toComponentSources(current));
+					deactivated = true;
+					await this.runtimeHooks.assertCanActivate(this.toComponentSources(candidate));
+				}
+				activated = (await this.installationService.rollback(appId, result.version)).rolledBack;
+				return {
+					package: await this.getPackage(appId),
+					result
+				};
+			} catch (error) {
+				if (activated) await this.installationService.rollback(appId, result.previousVersion);
+				if (deactivated) try {
+					await this.runtimeHooks.assertCanActivate(this.toComponentSources(current));
+				} catch (recoveryError) {
+					throw new AggregateError([error, recoveryError], `应用 ${appId} 更新失败，且旧 runtime 恢复探测失败。`);
+				}
+				throw error;
+			}
+		});
 	};
 	rollback = async (appId, version) => {
-		const current = await this.getPackage(appId);
-		if (current.enabled) await this.runtimeHooks.beforeDeactivate(this.toComponentSources(current));
-		const result = await this.installationService.rollback(appId, version);
-		try {
-			await this.assertEngineCompatibility(appId);
-			const rolledBack = await this.getPackage(appId);
-			if (rolledBack.enabled) await this.runtimeHooks.assertCanActivate(this.toComponentSources(rolledBack));
-			return {
-				package: rolledBack,
-				result
+		return await this.installationService.withAppOperation(appId, async () => {
+			const current = await this.getPackage(appId);
+			if (current.activeVersion === version) return {
+				package: current,
+				result: {
+					appId,
+					activeVersion: version,
+					previousVersion: version,
+					enabled: current.enabled,
+					rolledBack: false
+				}
 			};
-		} catch (error) {
-			if (result.rolledBack) await this.installationService.rollback(appId, result.previousVersion);
-			throw error;
-		}
+			await this.assertEngineCompatibility(appId, version);
+			const candidate = await this.toPackageView(await this.installationService.info(appId), version);
+			let deactivated = false;
+			let result;
+			try {
+				if (current.enabled) {
+					await this.runtimeHooks.beforeDeactivate(this.toComponentSources(current));
+					deactivated = true;
+					await this.runtimeHooks.assertCanActivate(this.toComponentSources(candidate));
+				}
+				result = await this.installationService.rollback(appId, version);
+				return {
+					package: await this.getPackage(appId),
+					result
+				};
+			} catch (error) {
+				if (result?.rolledBack) await this.installationService.rollback(appId, result.previousVersion);
+				if (deactivated) try {
+					await this.runtimeHooks.assertCanActivate(this.toComponentSources(current));
+				} catch (recoveryError) {
+					throw new AggregateError([error, recoveryError], `应用 ${appId} 回滚失败，且旧 runtime 恢复探测失败。`);
+				}
+				throw error;
+			}
+		});
 	};
 	uninstall = async (appId, purgeData) => {
-		const current = await this.getPackage(appId);
-		if (current.builtIn) await this.registryService.setBuiltInSuppressed(appId, true);
-		try {
-			if (current.enabled) await this.runtimeHooks.beforeDeactivate(this.toComponentSources(current));
-			await this.runtimeHooks.beforeUninstall(this.toComponentSources(current));
-			return await this.installationService.uninstall(appId, purgeData);
-		} catch (error) {
-			if (current.builtIn) await this.registryService.setBuiltInSuppressed(appId, false);
-			throw error;
-		}
+		return await this.installationService.withAppOperation(appId, async () => {
+			const current = await this.getPackage(appId);
+			if (current.builtIn) await this.registryService.setBuiltInSuppressed(appId, true);
+			try {
+				if (current.enabled) await this.runtimeHooks.beforeDeactivate(this.toComponentSources(current));
+				await this.runtimeHooks.beforeUninstall(this.toComponentSources(current));
+				return await this.installationService.uninstall(appId, purgeData);
+			} catch (error) {
+				if (current.builtIn) await this.registryService.setBuiltInSuppressed(appId, false);
+				throw error;
+			}
+		});
 	};
 	ensureBuiltInPackages = async () => {
 		this.builtInBootstrapPromise ??= this.installBuiltInPackages();
@@ -2944,13 +3045,22 @@ var AppPackageManager = class {
 			if (!isAppComponentManifestBundle(manifest)) continue;
 			if (await this.registryService.isBuiltInSuppressed(manifest.manifest.id)) continue;
 			if ((await this.registryService.getApp(manifest.manifest.id))?.installedVersions[manifest.manifest.version]) continue;
-			await this.installationService.install(appDirectory);
+			await this.installationService.install(appDirectory, { trustedPublisher: {
+				id: "nextclaw",
+				name: "NextClaw",
+				url: "https://nextclaw.io"
+			} });
 		}
 	};
-	toPackageView = async (info) => {
-		const activeVersion = info.installedVersions.find((version) => version.version === info.activeVersion);
-		if (!activeVersion) throw new AppPackageError("APP_PACKAGE_OPERATION_FAILED", `应用 ${info.appId} 缺少激活版本 ${info.activeVersion}。`);
-		const packagePresentation = await this.readManifestPresentation(path.join(activeVersion.installDirectory, "manifest.json"));
+	toPackageView = async (info, selectedVersion = info.activeVersion) => {
+		const activeVersion = info.installedVersions.find((version) => version.version === selectedVersion);
+		if (!activeVersion) throw new AppPackageError("APP_PACKAGE_OPERATION_FAILED", `应用 ${info.appId} 缺少版本 ${selectedVersion}。`);
+		const packagePresentation = await this.presentationService.readManifest(path.join(activeVersion.installDirectory, "manifest.json"));
+		const manifestBundle = await this.manifestService.load(activeVersion.installDirectory);
+		const security = manifestBundle.manifest.schemaVersion === 2 ? this.manifestService.resolvePlatformSecurity(manifestBundle.manifest) : {
+			runtimeProfile: "wasi",
+			isolation: manifestBundle.manifest.main.kind === "wasi-http-component" ? "host-mediated" : "sandboxed"
+		};
 		return {
 			id: info.appId,
 			name: info.name,
@@ -2958,7 +3068,7 @@ var AppPackageManager = class {
 			icon: packagePresentation.icon,
 			nameI18n: packagePresentation.nameI18n,
 			descriptionI18n: packagePresentation.descriptionI18n,
-			activeVersion: info.activeVersion,
+			activeVersion: selectedVersion,
 			installedVersions: info.installedVersions.map((version) => version.version),
 			enabled: info.enabled,
 			builtIn: await this.isBuiltInAppId(info.appId),
@@ -2967,43 +3077,50 @@ var AppPackageManager = class {
 				kind: component.kind,
 				id: component.id,
 				packageId: info.appId,
-				packageVersion: info.activeVersion,
+				packageVersion: selectedVersion,
 				sourcePath: component.componentDirectory,
 				manifestPath: component.manifestPath,
 				dataDirectory: info.dataDirectory,
-				...await this.readManifestPresentation(component.manifestPath)
+				instanceId: info.instance.id,
+				storage: info.storage,
+				runtimeProfile: security.runtimeProfile,
+				isolation: security.isolation,
+				...await this.presentationService.readManifest(component.manifestPath)
 			}))),
-			dataDirectory: info.dataDirectory
-		};
-	};
-	readManifestPresentation = async (manifestPath) => {
-		const candidate = JSON.parse(await readFile(manifestPath, "utf8"));
-		const rawIcon = typeof candidate.icon === "string" ? candidate.icon : void 0;
-		return {
-			...typeof candidate.title === "string" ? { title: candidate.title } : {},
-			...typeof candidate.description === "string" ? { description: candidate.description } : {},
-			...rawIcon ? { icon: await this.resolvePresentationIcon(manifestPath, rawIcon) } : {},
-			...this.readLocalizedField(candidate, "nameI18n"),
-			...this.readLocalizedField(candidate, "titleI18n"),
-			...this.readLocalizedField(candidate, "descriptionI18n")
+			dataDirectory: info.dataDirectory,
+			instanceId: info.instance.id,
+			storage: info.storage,
+			storageUsage: info.storageUsage,
+			runtimeProfile: security.runtimeProfile,
+			isolation: security.isolation
+		};
+	};
+	resolveSecurity = (version, appId) => {
+		if (version.security) return {
+			runtimeProfile: version.security.runtimeProfile,
+			isolation: version.security.isolation
+		};
+		const hasService = version.components?.some((component) => component.kind === "service") ?? false;
+		if (version.manifestSchemaVersion !== 2) throw new AppPackageError("APP_PACKAGE_INCOMPATIBLE", `应用 ${appId} 仍使用 legacy schema，不能投影组件。`);
+		return hasService ? {
+			runtimeProfile: "native-process",
+			isolation: "full-user"
+		} : {
+			runtimeProfile: "panel-only",
+			isolation: "sandboxed"
 		};
 	};
-	readLocalizedField = (candidate, field) => {
-		const value = candidate[field];
-		if (!value || typeof value !== "object" || Array.isArray(value)) return {};
-		const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
-		return entries.length > 0 ? { [field]: Object.fromEntries(entries) } : {};
-	};
 	toComponentSources = (app) => app.components.map((component) => ({ ...component }));
-	assertEngineCompatibility = async (appId) => {
+	assertEngineCompatibility = async (appId, selectedVersion) => {
 		const productVersion = this.params.productVersion?.trim();
 		if (!productVersion) return;
 		const info = await this.installationService.info(appId);
-		const activeVersion = info.installedVersions.find((version) => version.version === info.activeVersion);
-		if (!activeVersion) throw new AppPackageError("APP_PACKAGE_OPERATION_FAILED", `应用 ${appId} 缺少激活版本 ${info.activeVersion}。`);
+		const targetVersion = selectedVersion ?? info.activeVersion;
+		const activeVersion = info.installedVersions.find((version) => version.version === targetVersion);
+		if (!activeVersion) throw new AppPackageError("APP_PACKAGE_OPERATION_FAILED", `应用 ${appId} 缺少版本 ${targetVersion}。`);
 		const manifestBundle = await this.manifestService.load(activeVersion.installDirectory);
 		const engineRange = manifestBundle.manifest.schemaVersion === 2 ? manifestBundle.manifest.engines?.nextclaw?.trim() : void 0;
-		if (engineRange && !satisfiesAppEngineVersion(productVersion, engineRange)) throw new AppPackageError("APP_PACKAGE_INCOMPATIBLE", `应用 ${appId}@${info.activeVersion} 要求 NextClaw ${engineRange}，当前版本为 ${productVersion}。`);
+		if (engineRange && !satisfiesAppEngineVersion(productVersion, engineRange)) throw new AppPackageError("APP_PACKAGE_INCOMPATIBLE", `应用 ${appId}@${targetVersion} 要求 NextClaw ${engineRange}，当前版本为 ${productVersion}。`);
 	};
 	listBuiltInDefinitions = async () => {
 		if (!this.params.builtInAppsDirectory) return [];
@@ -3027,29 +3144,6 @@ var AppPackageManager = class {
 		return await this.builtInDefinitionsPromise;
 	};
 	isBuiltInAppId = async (appId) => (await this.listBuiltInDefinitions()).some(({ manifest }) => manifest.manifest.id === appId);
-	resolvePresentationIcon = async (manifestPath, icon) => {
-		if (icon.startsWith("data:") || icon.startsWith("http://") || icon.startsWith("https://") || icon.startsWith("/") || !icon.includes("/") && !icon.includes(".") && [...icon].length <= 8) return icon;
-		const manifestDirectory = path.dirname(manifestPath);
-		const iconPath = path.resolve(manifestDirectory, icon);
-		const relative = path.relative(manifestDirectory, iconPath);
-		if (relative.startsWith("..") || path.isAbsolute(relative)) return icon;
-		const mimeType = this.iconMimeType(path.extname(iconPath));
-		if (!mimeType) return icon;
-		const bytes = await readFile(iconPath);
-		if (bytes.byteLength > 256 * 1024) return icon;
-		return `data:${mimeType};base64,${bytes.toString("base64")}`;
-	};
-	iconMimeType = (extension) => {
-		switch (extension.toLowerCase()) {
-			case ".svg": return "image/svg+xml";
-			case ".png": return "image/png";
-			case ".jpg":
-			case ".jpeg": return "image/jpeg";
-			case ".webp": return "image/webp";
-			case ".gif": return "image/gif";
-			default: return;
-		}
-	};
 	executeOperation = async (input, report) => {
 		if (input.action === "install") {
 			const installed = await this.install(input.source, input.registryUrl, async (phase) => await report(phase));
@@ -9731,7 +9825,7 @@ var McpServiceAppRuntimeService = class {
 	toMcpServerRecord = (app, manifest) => ({
 		name: app.id,
 		definition: {
-			enabled: manifest.enabled,
+			enabled: app.enabled,
 			transport: {
 				type: "stdio",
 				command: manifest.command,
@@ -9752,7 +9846,16 @@ var McpServiceAppRuntimeService = class {
 	});
 	createAppRuntimeEnv = (app) => {
 		const env = {};
-		if (app.dataDirectory) env.NEXTCLAW_APP_DATA_DIR = app.dataDirectory;
+		if (app.storage) {
+			env.NEXTCLAW_APP_INSTANCE_ID = app.storage.instanceId;
+			env.NEXTCLAW_APP_COMPONENT_ID = app.id;
+			env.NEXTCLAW_APP_DATA_DIR = app.storage.dataDirectory;
+			env.NEXTCLAW_APP_CONFIG_DIR = app.storage.configDirectory;
+			env.NEXTCLAW_APP_STATE_DIR = app.storage.stateDirectory;
+			env.NEXTCLAW_APP_CACHE_DIR = app.storage.cacheDirectory;
+			env.NEXTCLAW_APP_TMP_DIR = app.storage.temporaryDirectory;
+			env.NEXTCLAW_APP_LOG_DIR = app.storage.logsDirectory;
+		} else if (app.dataDirectory) env.NEXTCLAW_APP_DATA_DIR = app.dataDirectory;
 		if (app.sourceKind !== "package" || !app.packageId || !app.packageVersion || !app.packageDirectory) return env;
 		env.NEXTCLAW_APP_ID = app.packageId;
 		env.NEXTCLAW_APP_VERSION = app.packageVersion;
@@ -9775,6 +9878,182 @@ var McpServiceAppRuntimeService = class {
 	};
 };
 //#endregion
+//#region src/utils/service-app-manifest.utils.ts
+const SERVICE_APP_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SERVICE_ACTION_RISKS = new Set([
+	"read",
+	"write",
+	"external",
+	"dangerous"
+]);
+const SERVICE_APP_MANIFEST_FILE_NAME = "service-app.json";
+function getServiceAppManifestPath(dirPath) {
+	return join(dirPath, SERVICE_APP_MANIFEST_FILE_NAME);
+}
+async function readServiceAppManifest(dirPath) {
+	return parseServiceAppManifest(await readFile(getServiceAppManifestPath(dirPath), "utf8"));
+}
+function parseServiceAppManifest(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		throw new Error(`service-app.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!isRecord$9(parsed)) throw new Error("service-app.json must contain an object.");
+	const id = readRequiredString$6(parsed, "id");
+	if (!SERVICE_APP_ID_PATTERN.test(id)) throw new Error("service app id must be kebab-case.");
+	const protocol = readOptionalString$7(parsed, "protocol") ?? "mcp";
+	if (protocol !== "mcp") throw new Error("service app protocol must be mcp.");
+	return {
+		id,
+		title: readRequiredString$6(parsed, "title"),
+		description: readOptionalString$7(parsed, "description"),
+		enabled: readOptionalBoolean$1(parsed, "enabled") ?? true,
+		protocol,
+		command: readRequiredString$6(parsed, "command"),
+		args: readStringArray(parsed.args, "args"),
+		actions: readManifestActions(parsed.actions)
+	};
+}
+function readManifestActions(value) {
+	if (value === void 0) throw new Error("service app actions are required.");
+	if (!isRecord$9(value)) throw new Error("service app actions must be an object.");
+	if (Object.keys(value).length === 0) throw new Error("service app actions cannot be empty.");
+	const actions = {};
+	for (const [name, action] of Object.entries(value)) {
+		if (!name.trim()) throw new Error("service app action name cannot be empty.");
+		if (!isRecord$9(action)) throw new Error(`service app action ${name} must be an object.`);
+		const risk = readOptionalString$7(action, "risk");
+		if (risk !== void 0 && !SERVICE_ACTION_RISKS.has(risk)) throw new Error(`service app action ${name} has invalid risk.`);
+		const inputSchema = action.inputSchema;
+		if (inputSchema !== void 0 && !isRecord$9(inputSchema)) throw new Error(`service app action ${name} inputSchema must be an object.`);
+		actions[name] = {
+			risk,
+			title: readOptionalString$7(action, "title"),
+			description: readOptionalString$7(action, "description"),
+			inputSchema
+		};
+	}
+	return actions;
+}
+function readRequiredString$6(record, key) {
+	const value = readOptionalString$7(record, key);
+	if (!value) throw new Error(`service app ${key} is required.`);
+	return value;
+}
+function readOptionalString$7(record, key) {
+	return typeof record[key] === "string" && record[key].trim() ? record[key].trim() : void 0;
+}
+function readOptionalBoolean$1(record, key) {
+	if (record[key] === void 0) return;
+	if (typeof record[key] !== "boolean") throw new Error(`service app ${key} must be boolean.`);
+	return record[key];
+}
+function readStringArray(value, key) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) throw new Error(`service app ${key} must be a string array.`);
+	return value;
+}
+function isRecord$9(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+//#region src/services/service-app-record.service.ts
+var ServiceAppRecordService = class {
+	instanceStorageService = new AppInstanceStorageService();
+	constructor(params) {
+		this.params = params;
+	}
+	buildWorkspaceRecord = async (serviceAppsPath, dirName) => {
+		const dirPath = join(serviceAppsPath, dirName);
+		try {
+			const manifest = await readServiceAppManifest(dirPath);
+			return this.fromManifest(dirPath, manifest, void 0, await this.materializeWorkspaceStorage(manifest.id));
+		} catch (error) {
+			if (this.isMissingFileError(error)) return null;
+			return this.failedWorkspaceRecord(dirName, dirPath, error);
+		}
+	};
+	buildPackageRecord = async (source) => {
+		try {
+			const manifest = await readServiceAppManifest(source.sourcePath);
+			if (manifest.id !== source.id) throw new Error(`service component id mismatch: ${source.id}`);
+			return this.fromManifest(source.sourcePath, manifest, source, source.storage);
+		} catch (error) {
+			return this.failedPackageRecord(source, error);
+		}
+	};
+	materializeWorkspaceStorage = async (serviceId) => {
+		const instanceDirectory = join(this.params.getWorkspacePath(), ".nextclaw", "app-instances", serviceId, "default");
+		return (await this.instanceStorageService.materialize({
+			appId: serviceId,
+			instanceId: "default",
+			instanceDirectory
+		})).storage;
+	};
+	fromManifest = (dirPath, manifest, packageSource, storage) => {
+		const runtimeStatus = this.params.runtimeService.getStatus(manifest.id);
+		return {
+			id: manifest.id,
+			title: manifest.title,
+			description: manifest.description,
+			dirPath,
+			manifestPath: getServiceAppManifestPath(dirPath),
+			command: manifest.command,
+			args: manifest.args,
+			cwd: dirPath,
+			enabled: packageSource ? true : manifest.enabled,
+			protocol: manifest.protocol,
+			status: packageSource || manifest.enabled ? runtimeStatus.status : "stopped",
+			lastError: runtimeStatus.lastError,
+			lastStartedAt: runtimeStatus.lastStartedAt,
+			lastReadyAt: runtimeStatus.lastReadyAt,
+			lastFailedAt: runtimeStatus.lastFailedAt,
+			sourceKind: packageSource ? "package" : "workspace",
+			packageId: packageSource?.packageId,
+			packageVersion: packageSource?.packageVersion,
+			packageDirectory: packageSource ? join(packageSource.sourcePath, "..", "..") : void 0,
+			dataDirectory: storage?.dataDirectory,
+			instanceId: packageSource?.instanceId ?? storage?.instanceId,
+			storage,
+			isolation: packageSource?.isolation ?? "full-user"
+		};
+	};
+	failedWorkspaceRecord = (id, dirPath, error) => ({
+		id,
+		title: this.toTitle(id),
+		dirPath,
+		manifestPath: getServiceAppManifestPath(dirPath),
+		cwd: dirPath,
+		enabled: false,
+		protocol: "mcp",
+		status: "failed",
+		lastError: error instanceof Error ? error.message : String(error)
+	});
+	failedPackageRecord = (source, error) => ({
+		id: source.id,
+		title: this.toTitle(source.id),
+		dirPath: source.sourcePath,
+		manifestPath: source.manifestPath,
+		cwd: source.sourcePath,
+		enabled: false,
+		protocol: "mcp",
+		status: "failed",
+		lastError: error instanceof Error ? error.message : String(error),
+		sourceKind: "package",
+		packageId: source.packageId,
+		packageVersion: source.packageVersion,
+		packageDirectory: join(source.sourcePath, "..", ".."),
+		dataDirectory: source.dataDirectory,
+		instanceId: source.instanceId,
+		storage: source.storage,
+		isolation: source.isolation
+	});
+	toTitle = (value) => basename(value).replace(/[-_]+/g, " ").trim() || value;
+	isMissingFileError = (error) => typeof error === "object" && error !== null && error.code === "ENOENT";
+};
+//#endregion
 //#region src/stores/service-action-grant.store.ts
 const EMPTY_GRANTS = {
 	version: 1,
@@ -9784,9 +10063,9 @@ var ServiceActionGrantStore = class {
 	constructor(storePath) {
 		this.storePath = storePath;
 	}
-	isGranted = async (caller, actionId) => {
-		const data = await this.load();
-		return Boolean(data.grants[getServiceActionCallerKey(caller)]?.actions[actionId]);
+	isGranted = async (caller, actionId, currentRisk) => {
+		const grant = (await this.load()).grants[getServiceActionCallerKey(caller)]?.actions[actionId];
+		return Boolean(grant && (currentRisk === void 0 || grant.risk === currentRisk));
 	};
 	grant = async ({ actionId, caller, grantedAt, risk }) => {
 		const data = await this.load();
@@ -9853,12 +10132,12 @@ var ServiceActionGrantStore = class {
 	};
 };
 function normalizeStoreData(value) {
-	if (!isRecord$9(value) || value.version !== 1 || !isRecord$9(value.grants)) return structuredClone(EMPTY_GRANTS);
+	if (!isRecord$8(value) || value.version !== 1 || !isRecord$8(value.grants)) return structuredClone(EMPTY_GRANTS);
 	const grants = {};
 	for (const [callerKey, callerValue] of Object.entries(value.grants)) {
-		if (!isRecord$9(callerValue) || !isRecord$9(callerValue.actions)) continue;
+		if (!isRecord$8(callerValue) || !isRecord$8(callerValue.actions)) continue;
 		const actions = {};
-		for (const [actionId, actionValue] of Object.entries(callerValue.actions)) if (isRecord$9(actionValue) && typeof actionValue.grantedAt === "string" && isServiceActionRisk(actionValue.risk)) actions[actionId] = {
+		for (const [actionId, actionValue] of Object.entries(callerValue.actions)) if (isRecord$8(actionValue) && typeof actionValue.grantedAt === "string" && isServiceActionRisk(actionValue.risk)) actions[actionId] = {
 			grantedAt: actionValue.grantedAt,
 			risk: actionValue.risk
 		};
@@ -9872,92 +10151,11 @@ function normalizeStoreData(value) {
 function isServiceActionRisk(value) {
 	return value === "read" || value === "write" || value === "external" || value === "dangerous";
 }
-function isRecord$9(value) {
+function isRecord$8(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function isMissingFileError(error) {
-	return isRecord$9(error) && error.code === "ENOENT";
-}
-//#endregion
-//#region src/utils/service-app-manifest.utils.ts
-const SERVICE_APP_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const SERVICE_ACTION_RISKS = new Set([
-	"read",
-	"write",
-	"external",
-	"dangerous"
-]);
-const SERVICE_APP_MANIFEST_FILE_NAME = "service-app.json";
-function getServiceAppManifestPath(dirPath) {
-	return join(dirPath, SERVICE_APP_MANIFEST_FILE_NAME);
-}
-async function readServiceAppManifest(dirPath) {
-	return parseServiceAppManifest(await readFile(getServiceAppManifestPath(dirPath), "utf8"));
-}
-function parseServiceAppManifest(raw) {
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (error) {
-		throw new Error(`service-app.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	if (!isRecord$8(parsed)) throw new Error("service-app.json must contain an object.");
-	const id = readRequiredString$6(parsed, "id");
-	if (!SERVICE_APP_ID_PATTERN.test(id)) throw new Error("service app id must be kebab-case.");
-	const protocol = readOptionalString$7(parsed, "protocol") ?? "mcp";
-	if (protocol !== "mcp") throw new Error("service app protocol must be mcp.");
-	return {
-		id,
-		title: readRequiredString$6(parsed, "title"),
-		description: readOptionalString$7(parsed, "description"),
-		enabled: readOptionalBoolean$1(parsed, "enabled") ?? true,
-		protocol,
-		command: readRequiredString$6(parsed, "command"),
-		args: readStringArray(parsed.args, "args"),
-		actions: readManifestActions(parsed.actions)
-	};
-}
-function readManifestActions(value) {
-	if (value === void 0) throw new Error("service app actions are required.");
-	if (!isRecord$8(value)) throw new Error("service app actions must be an object.");
-	if (Object.keys(value).length === 0) throw new Error("service app actions cannot be empty.");
-	const actions = {};
-	for (const [name, action] of Object.entries(value)) {
-		if (!name.trim()) throw new Error("service app action name cannot be empty.");
-		if (!isRecord$8(action)) throw new Error(`service app action ${name} must be an object.`);
-		const risk = readOptionalString$7(action, "risk");
-		if (risk !== void 0 && !SERVICE_ACTION_RISKS.has(risk)) throw new Error(`service app action ${name} has invalid risk.`);
-		const inputSchema = action.inputSchema;
-		if (inputSchema !== void 0 && !isRecord$8(inputSchema)) throw new Error(`service app action ${name} inputSchema must be an object.`);
-		actions[name] = {
-			risk,
-			title: readOptionalString$7(action, "title"),
-			description: readOptionalString$7(action, "description"),
-			inputSchema
-		};
-	}
-	return actions;
-}
-function readRequiredString$6(record, key) {
-	const value = readOptionalString$7(record, key);
-	if (!value) throw new Error(`service app ${key} is required.`);
-	return value;
-}
-function readOptionalString$7(record, key) {
-	return typeof record[key] === "string" && record[key].trim() ? record[key].trim() : void 0;
-}
-function readOptionalBoolean$1(record, key) {
-	if (record[key] === void 0) return;
-	if (typeof record[key] !== "boolean") throw new Error(`service app ${key} must be boolean.`);
-	return record[key];
-}
-function readStringArray(value, key) {
-	if (value === void 0) return [];
-	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) throw new Error(`service app ${key} must be a string array.`);
-	return value;
-}
-function isRecord$8(value) {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+	return isRecord$8(error) && error.code === "ENOENT";
 }
 //#endregion
 //#region src/utils/service-app-runtime-action.utils.ts
@@ -10006,17 +10204,22 @@ function isServiceAppError(error) {
 }
 var ServiceAppManager = class {
 	runtimeService;
+	recordService;
 	constructor(params) {
 		this.params = params;
 		this.runtimeService = params.runtimeService ?? new McpServiceAppRuntimeService({ getConfig: () => params.configManager.config });
+		this.recordService = new ServiceAppRecordService({
+			getWorkspacePath: this.getWorkspacePath,
+			runtimeService: this.runtimeService
+		});
 	}
 	listServiceApps = async () => {
 		const workspacePath = this.getWorkspacePath();
 		const serviceAppsPath = this.getServiceAppsPath(workspacePath);
 		const dirNames = await this.listServiceAppDirNames(serviceAppsPath);
-		const workspaceEntries = await Promise.all(dirNames.map((dirName) => this.buildServiceAppRecord(serviceAppsPath, dirName)));
+		const workspaceEntries = await Promise.all(dirNames.map((dirName) => this.recordService.buildWorkspaceRecord(serviceAppsPath, dirName)));
 		const packageSources = (await this.listPackageComponentSources()).filter((component) => component.kind === "service");
-		const packageEntries = await Promise.all(packageSources.map((source) => this.buildServiceAppRecordFromPackage(source)));
+		const packageEntries = await Promise.all(packageSources.map((source) => this.recordService.buildPackageRecord(source)));
 		return {
 			workspacePath,
 			serviceAppsPath,
@@ -10048,7 +10251,8 @@ var ServiceAppManager = class {
 		const { manifest, record } = await this.requireServiceAppForAction(actionId);
 		const actionName = getServiceActionName(actionId, record.id);
 		if (!Object.hasOwn(manifest.actions, actionName)) throw new ServiceAppError("SERVICE_APP_ACTION_NOT_FOUND", "service action not found");
-		if (!await this.createGrantStore().isGranted(request.caller, actionId)) throw new ServiceAppError("AUTHORIZATION_REQUIRED", `This panel app needs permission to call ${actionId}.`);
+		const declaredRisk = manifest.actions[actionName]?.risk ?? "dangerous";
+		if (!await this.createGrantStore().isGranted(request.caller, actionId, declaredRisk)) throw new ServiceAppError("AUTHORIZATION_REQUIRED", `This panel app needs permission to call ${actionId}.`);
 		return {
 			actionId,
 			result: await this.runtimeService.invokeAction({
@@ -10125,6 +10329,31 @@ var ServiceAppManager = class {
 			const conflictsWithPackage = activePackageSources.some((active) => active.kind === "service" && active.id === component.id && active.packageId !== component.packageId);
 			if (workspaceIds.has(component.id) || conflictsWithPackage) throw new AppPackageError("APP_PACKAGE_CONFLICT", `Service component id 冲突：${component.id}`);
 		}
+		for (const component of serviceComponents) {
+			let manifest;
+			try {
+				manifest = await readServiceAppManifest(component.sourcePath);
+			} catch (error) {
+				throw new AppPackageError("APP_PACKAGE_OPERATION_FAILED", `Service component ${component.id} manifest 无效：${error instanceof Error ? error.message : String(error)}`);
+			}
+			try {
+				const record = this.recordService.fromManifest(component.sourcePath, manifest, component, component.storage);
+				const runtimeActions = await this.runtimeService.listActions({
+					app: record,
+					manifest
+				});
+				const runtimeStatus = this.runtimeService.getStatus(component.id);
+				if (runtimeStatus.status === "failed") throw new AppPackageError("APP_PACKAGE_OPERATION_FAILED", `Service component ${component.id} 启动探测失败：${runtimeStatus.lastError ?? "unknown error"}`);
+				const invalidAction = mergeServiceAppRuntimeActions({
+					record,
+					manifest,
+					runtimeActions
+				}).find((action) => action.runtimeState === "missing" || action.runtimeState === "undeclared");
+				if (invalidAction) throw new AppPackageError("APP_PACKAGE_OPERATION_FAILED", `Service component ${component.id} action 合同不一致：${invalidAction.id} (${invalidAction.runtimeState})`);
+			} finally {
+				await this.runtimeService.restart(component.id);
+			}
+		}
 	};
 	deactivatePackageComponents = async (components) => {
 		const serviceIds = components.filter((component) => component.kind === "service").map((component) => component.id);
@@ -10137,7 +10366,7 @@ var ServiceAppManager = class {
 	};
 	withGrantState = async (action, params) => {
 		if (!params.caller) return action;
-		const granted = await this.createGrantStore().isGranted(params.caller, action.id);
+		const granted = await this.createGrantStore().isGranted(params.caller, action.id, action.risk);
 		return {
 			...action,
 			grantState: resolveServiceActionGrantState({
@@ -10175,7 +10404,7 @@ var ServiceAppManager = class {
 			if (manifest.id !== appId) throw new ServiceAppError("SERVICE_APP_INVALID_MANIFEST", "service app manifest id must match directory name");
 			return {
 				manifest,
-				record: this.toServiceAppRecord(dirPath, manifest, packageSource)
+				record: this.recordService.fromManifest(dirPath, manifest, packageSource, packageSource?.storage ?? await this.recordService.materializeWorkspaceStorage(manifest.id))
 			};
 		} catch (error) {
 			if (isServiceAppError(error)) throw error;
@@ -10193,7 +10422,7 @@ var ServiceAppManager = class {
 				const manifest = await readServiceAppManifest(dirPath);
 				return {
 					manifest,
-					record: this.toServiceAppRecord(dirPath, manifest)
+					record: this.recordService.fromManifest(dirPath, manifest, void 0, await this.recordService.materializeWorkspaceStorage(manifest.id))
 				};
 			} catch {
 				return null;
@@ -10204,7 +10433,7 @@ var ServiceAppManager = class {
 				const manifest = await readServiceAppManifest(component.sourcePath);
 				return {
 					manifest,
-					record: this.toServiceAppRecord(component.sourcePath, manifest, component)
+					record: this.recordService.fromManifest(component.sourcePath, manifest, component, component.storage)
 				};
 			} catch {
 				return null;
@@ -10212,51 +10441,6 @@ var ServiceAppManager = class {
 		}));
 		return [...workspaceEntries, ...packageEntries].filter((entry) => Boolean(entry));
 	};
-	buildServiceAppRecord = async (serviceAppsPath, dirName) => {
-		const dirPath = join(serviceAppsPath, dirName);
-		try {
-			const manifest = await readServiceAppManifest(dirPath);
-			return this.toServiceAppRecord(dirPath, manifest);
-		} catch (error) {
-			if (this.isMissingFileError(error)) return null;
-			return {
-				id: dirName,
-				title: toTitle(dirName),
-				dirPath,
-				manifestPath: getServiceAppManifestPath(dirPath),
-				cwd: dirPath,
-				enabled: false,
-				protocol: "mcp",
-				status: "failed",
-				lastError: error instanceof Error ? error.message : String(error)
-			};
-		}
-	};
-	toServiceAppRecord = (dirPath, manifest, packageSource) => {
-		const runtimeStatus = this.runtimeService.getStatus(manifest.id);
-		return {
-			id: manifest.id,
-			title: manifest.title,
-			description: manifest.description,
-			dirPath,
-			manifestPath: getServiceAppManifestPath(dirPath),
-			command: manifest.command,
-			args: manifest.args,
-			cwd: dirPath,
-			enabled: manifest.enabled,
-			protocol: manifest.protocol,
-			status: manifest.enabled ? runtimeStatus.status : "stopped",
-			lastError: runtimeStatus.lastError,
-			lastStartedAt: runtimeStatus.lastStartedAt,
-			lastReadyAt: runtimeStatus.lastReadyAt,
-			lastFailedAt: runtimeStatus.lastFailedAt,
-			sourceKind: packageSource ? "package" : "workspace",
-			packageId: packageSource?.packageId,
-			packageVersion: packageSource?.packageVersion,
-			packageDirectory: packageSource ? join(packageSource.sourcePath, "..", "..") : void 0,
-			dataDirectory: packageSource?.dataDirectory
-		};
-	};
 	assertCaller = (caller) => {
 		if (caller.surface !== "panel-app" || !caller.appId.trim()) throw new ServiceAppError("SERVICE_APP_INVALID_CALLER", "service action caller is invalid");
 	};
@@ -10268,30 +10452,6 @@ var ServiceAppManager = class {
 	getServiceAppsPath = (workspacePath) => join(workspacePath, DEFAULT_SERVICE_APPS_DIR);
 	createGrantStore = () => new ServiceActionGrantStore(join(this.getServiceAppsPath(this.getWorkspacePath()), SERVICE_ACTION_GRANTS_FILE_NAME));
 	listPackageComponentSources = async () => await this.params.listPackageComponentSources?.() ?? [];
-	buildServiceAppRecordFromPackage = async (source) => {
-		try {
-			const manifest = await readServiceAppManifest(source.sourcePath);
-			if (manifest.id !== source.id) throw new Error(`service component id mismatch: ${source.id}`);
-			return this.toServiceAppRecord(source.sourcePath, manifest, source);
-		} catch (error) {
-			return {
-				id: source.id,
-				title: toTitle(source.id),
-				dirPath: source.sourcePath,
-				manifestPath: source.manifestPath,
-				cwd: source.sourcePath,
-				enabled: false,
-				protocol: "mcp",
-				status: "failed",
-				lastError: error instanceof Error ? error.message : String(error),
-				sourceKind: "package",
-				packageId: source.packageId,
-				packageVersion: source.packageVersion,
-				packageDirectory: join(source.sourcePath, "..", ".."),
-				dataDirectory: source.dataDirectory
-			};
-		}
-	};
 	listServiceAppDirNames = async (serviceAppsPath) => {
 		try {
 			return (await readdir(serviceAppsPath, { withFileTypes: true })).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name);
@@ -10302,9 +10462,6 @@ var ServiceAppManager = class {
 	};
 	isMissingFileError = (error) => typeof error === "object" && error !== null && error.code === "ENOENT";
 };
-function toTitle(value) {
-	return basename(value).replace(/[-_]+/g, " ").trim() || value;
-}
 //#endregion
 //#region src/managers/session-run.manager.ts
 var MessageInbox = class {