@nextclaw/kernel 0.11.0 → 0.12.0

package/dist/index.js

@@ -8,7 +8,7 @@ import { CHAT_CONTINUATION_TARGET_MESSAGE_METADATA_KEY, CHAT_CONVERSATION_EXCERP
 import { createHash, createHmac, randomBytes, randomUUID, scryptSync, timingSafeEqual } from "node:crypto";
 import { catchError, filter, from, lastValueFrom, tap } from "rxjs";
 import { DefaultNcpAgentConversationStateManager, insertMessageByTimeline, mergeToolExecutionTiming } from "@nextclaw/ncp-toolkit";
-import { appendFileSync, chmodSync, constants, createReadStream, existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { accessSync, 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, AppInstanceInventoryService, AppInstanceStorageService, AppManifestService, AppPlatformTargetService, AppRegistryService, AppServiceLaunchService, FileLockService, isAppComponentManifestBundle } from "@nextclaw/app-runtime";
@@ -3592,6 +3592,30 @@ var AppPackagePresentationService = class {
 	};
 };
 //#endregion
+//#region src/services/app-package-runtime-activation.service.ts
+const EMPTY_APP_PACKAGE_RUNTIME_HOOKS = {
+	assertCanActivate: async () => void 0,
+	afterActivate: async () => void 0,
+	beforeDeactivate: async () => void 0,
+	beforeUninstall: async () => void 0
+};
+var AppPackageRuntimeActivationService = class {
+	recoverFailedActivation = async (params) => {
+		const recoveryErrors = [];
+		try {
+			await params.beforeDeactivate(params.sources);
+		} catch (recoveryError) {
+			recoveryErrors.push(recoveryError);
+		}
+		try {
+			await params.disable();
+		} catch (recoveryError) {
+			recoveryErrors.push(recoveryError);
+		}
+		if (recoveryErrors.length > 0) throw new AggregateError([params.error, ...recoveryErrors], `应用 ${params.appId} 启用失败，且 runtime 状态恢复未完整完成。`);
+	};
+};
+//#endregion
 //#region src/types/app-package.types.ts
 var AppPackageError = class extends Error {
 	constructor(code, message) {
@@ -3708,11 +3732,6 @@ function compareVersions(left, right) {
 }
 //#endregion
 //#region src/managers/app-package.manager.ts
-const EMPTY_RUNTIME_HOOKS = {
-	assertCanActivate: async () => void 0,
-	beforeDeactivate: async () => void 0,
-	beforeUninstall: async () => void 0
-};
 var AppPackageManager = class {
 	appHomeService;
 	installationService;
@@ -3720,8 +3739,9 @@ var AppPackageManager = class {
 	operationManager;
 	platformTargetService = new AppPlatformTargetService();
 	presentationService = new AppPackagePresentationService();
+	runtimeActivationService = new AppPackageRuntimeActivationService();
 	registryService;
-	runtimeHooks = EMPTY_RUNTIME_HOOKS;
+	runtimeHooks = EMPTY_APP_PACKAGE_RUNTIME_HOOKS;
 	builtInBootstrapPromise;
 	builtInDefinitionsPromise;
 	constructor(params) {
@@ -3827,6 +3847,20 @@ var AppPackageManager = class {
 			const sources = this.toComponentSources(app);
 			await this.runtimeHooks.assertCanActivate(sources);
 			await this.installationService.setEnabled(appId, true);
+			try {
+				await this.runtimeHooks.afterActivate(sources);
+			} catch (error) {
+				await this.runtimeActivationService.recoverFailedActivation({
+					appId,
+					error,
+					sources,
+					beforeDeactivate: this.runtimeHooks.beforeDeactivate,
+					disable: async () => {
+						await this.installationService.setEnabled(appId, false);
+					}
+				});
+				throw error;
+			}
 			return await this.getPackage(appId);
 		});
 	};
@@ -3861,6 +3895,7 @@ var AppPackageManager = class {
 					await this.runtimeHooks.assertCanActivate(this.toComponentSources(candidate));
 				}
 				activated = (await this.installationService.rollback(appId, result.version)).rolledBack;
+				if (current.enabled) await this.runtimeHooks.afterActivate(this.toComponentSources(candidate));
 				return {
 					package: await this.getPackage(appId),
 					result
@@ -3869,6 +3904,7 @@ var AppPackageManager = class {
 				if (activated) await this.installationService.rollback(appId, result.previousVersion);
 				if (deactivated) try {
 					await this.runtimeHooks.assertCanActivate(this.toComponentSources(current));
+					await this.runtimeHooks.afterActivate(this.toComponentSources(current));
 				} catch (recoveryError) {
 					throw new AggregateError([error, recoveryError], `应用 ${appId} 更新失败，且旧 runtime 恢复探测失败。`);
 				}
@@ -3900,6 +3936,7 @@ var AppPackageManager = class {
 					await this.runtimeHooks.assertCanActivate(this.toComponentSources(candidate));
 				}
 				result = await this.installationService.rollback(appId, version);
+				if (current.enabled) await this.runtimeHooks.afterActivate(this.toComponentSources(candidate));
 				return {
 					package: await this.getPackage(appId),
 					result
@@ -3908,6 +3945,7 @@ var AppPackageManager = class {
 				if (result?.rolledBack) await this.installationService.rollback(appId, result.previousVersion);
 				if (deactivated) try {
 					await this.runtimeHooks.assertCanActivate(this.toComponentSources(current));
+					await this.runtimeHooks.afterActivate(this.toComponentSources(current));
 				} catch (recoveryError) {
 					throw new AggregateError([error, recoveryError], `应用 ${appId} 回滚失败，且旧 runtime 恢复探测失败。`);
 				}
@@ -3965,7 +4003,8 @@ var AppPackageManager = class {
 		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"
+			isolation: manifestBundle.manifest.main.kind === "wasi-http-component" ? "host-mediated" : "sandboxed",
+			permissions: manifestBundle.manifest.permissions ?? {}
 		};
 		return {
 			id: info.appId,
@@ -3991,6 +4030,7 @@ var AppPackageManager = class {
 				storage: info.storage,
 				runtimeProfile: security.runtimeProfile,
 				isolation: security.isolation,
+				permissions: security.permissions,
 				...await this.presentationService.readManifest(component.manifestPath)
 			}))),
 			dataDirectory: info.dataDirectory,
@@ -4004,16 +4044,19 @@ var AppPackageManager = class {
 	resolveSecurity = (version, appId) => {
 		if (version.security) return {
 			runtimeProfile: version.security.runtimeProfile,
-			isolation: version.security.isolation
+			isolation: version.security.isolation,
+			permissions: version.security.permissions
 		};
 		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"
+			isolation: "full-user",
+			permissions: {}
 		} : {
 			runtimeProfile: "panel-only",
-			isolation: "sandboxed"
+			isolation: "sandboxed",
+			permissions: {}
 		};
 	};
 	toComponentSources = (app) => app.components.map((component) => ({ ...component }));
@@ -4954,7 +4997,7 @@ function readRequiredString$8(value, name) {
 	if (!trimmed) throw new Error(`${name} is required`);
 	return trimmed;
 }
-function readOptionalNumber(value) {
+function readOptionalNumber$1(value) {
 	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
 function readTextContent(value) {
@@ -4971,7 +5014,7 @@ function readInboundAttachments(value) {
 		...readString$8(entry.url) ? { url: readString$8(entry.url) } : {},
 		...readString$8(entry.assetUri) ? { assetUri: readString$8(entry.assetUri) } : {},
 		...readString$8(entry.mimeType) ? { mimeType: readString$8(entry.mimeType) } : {},
-		...readOptionalNumber(entry.size) !== void 0 ? { size: readOptionalNumber(entry.size) } : {},
+		...readOptionalNumber$1(entry.size) !== void 0 ? { size: readOptionalNumber$1(entry.size) } : {},
 		...readString$8(entry.source) ? { source: readString$8(entry.source) } : {},
 		...entry.status === "ready" || entry.status === "remote-only" ? { status: entry.status } : {},
 		...readString$8(entry.errorCode) ? { errorCode: readString$8(entry.errorCode) } : {}
@@ -5007,7 +5050,7 @@ function normalizeAuthPollResult(value) {
 		channel: readRequiredString$8(record.channel, "channel"),
 		status: record.status,
 		message: readString$8(record.message),
-		nextPollMs: readOptionalNumber(record.nextPollMs),
+		nextPollMs: readOptionalNumber$1(record.nextPollMs),
 		accountId: typeof record.accountId === "string" ? record.accountId : null,
 		notes: Array.isArray(record.notes) ? record.notes.filter((note) => typeof note === "string") : [],
 		channelConfig: normalizeChannelConfigResult(record)
@@ -5044,8 +5087,8 @@ var ExtensionIngressDiagnosticsService = class {
 			parentCorrelationId: readString$8(payload.parentCorrelationId),
 			reasonCode: readString$8(payload.reasonCode),
 			providerCode: readString$8(payload.providerCode),
-			durationMs: readOptionalNumber(payload.durationMs),
-			attempt: readOptionalNumber(payload.attempt),
+			durationMs: readOptionalNumber$1(payload.durationMs),
+			attempt: readOptionalNumber$1(payload.attempt),
 			facts: {
 				...readRecord$2(payload.facts),
 				extensionId: credential.extensionId,
@@ -5674,6 +5717,70 @@ function isRecord$15(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 //#endregion
+//#region src/utils/service-app-error.utils.ts
+const SERVICE_APP_ERROR_CODES = new Set([
+	"AUTHORIZATION_REQUIRED",
+	"SERVICE_APP_ACTION_NOT_DECLARED",
+	"SERVICE_APP_ACTION_NOT_FOUND",
+	"SERVICE_APP_INVALID_ACTION",
+	"SERVICE_APP_INVALID_CALLER",
+	"SERVICE_APP_INVALID_MANIFEST",
+	"SERVICE_APP_MANAGED_SOURCE",
+	"SERVICE_APP_NOT_FOUND",
+	"SERVICE_APP_READ_FAILED",
+	"SERVICE_APP_RUNTIME_FAILED"
+]);
+var ServiceAppError = class extends Error {
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "ServiceAppError";
+	}
+};
+const isServiceAppError = (error) => error instanceof ServiceAppError || typeof error === "object" && error !== null && error.name === "ServiceAppError" && typeof error.message === "string" && SERVICE_APP_ERROR_CODES.has(error.code);
+//#endregion
+//#region src/utils/service-action.utils.ts
+const DEFAULT_SERVICE_ACTION_RISK = "dangerous";
+function buildServiceActionId(appId, actionName) {
+	return `${appId}.${actionName}`;
+}
+function getServiceActionName(actionId, appId) {
+	const prefix = `${appId}.`;
+	if (!actionId.startsWith(prefix)) throw new Error("service action does not belong to service app.");
+	const name = actionId.slice(prefix.length).trim();
+	if (!name) throw new Error("service action name is required.");
+	return name;
+}
+function parseServiceActionCallerKey(key) {
+	const [surface, callerId, ...rest] = key.split(":");
+	if (!callerId || rest.length > 0) return null;
+	if (surface === "panel-app") return {
+		surface,
+		appId: callerId
+	};
+	if (surface === "agent") return {
+		surface,
+		agentId: callerId
+	};
+	return null;
+}
+function getServiceActionCallerId(caller) {
+	return caller.surface === "panel-app" ? caller.appId : caller.agentId;
+}
+function assertServiceActionCaller(caller, hasAgent) {
+	if (caller.surface === "panel-app" && caller.appId.trim()) return;
+	if (caller.surface === "agent" && caller.agentId.trim() && (hasAgent?.(caller.agentId) ?? true)) return;
+	throw new ServiceAppError("SERVICE_APP_INVALID_CALLER", "service action caller is invalid");
+}
+function assertServiceActionDeclared(caller, actionId, declaredActions) {
+	if (caller.surface === "agent") return;
+	if (!declaredActions?.includes(actionId)) throw new ServiceAppError("SERVICE_APP_ACTION_NOT_DECLARED", "panel app did not declare this service action");
+}
+function resolveServiceActionGrantState({ actionId, declaredActions, granted }) {
+	if (declaredActions && !declaredActions.includes(actionId)) return "not-declared";
+	return granted ? "granted" : "not-granted";
+}
+//#endregion
 //#region src/features/capability-grants/utils/capability-grant-resource.utils.ts
 function createPanelAppClientGrantRequest(appId) {
 	return {
@@ -5693,7 +5800,7 @@ function createPanelAppAgentGrantRequest(caller, capability) {
 	return {
 		subject: {
 			type: caller.surface,
-			id: caller.appId
+			id: getServiceActionCallerId(caller)
 		},
 		resource: {
 			type: "agent.capability",
@@ -5707,7 +5814,7 @@ function createServiceActionGrantRequest(caller, action) {
 	return {
 		subject: {
 			type: caller.surface,
-			id: caller.appId
+			id: getServiceActionCallerId(caller)
 		},
 		resource: {
 			type: "service.action",
@@ -5742,31 +5849,6 @@ function isPanelAppAgentCapability(value) {
 	return PANEL_APP_AGENT_CAPABILITIES.includes(value);
 }
 //#endregion
-//#region src/utils/service-action.utils.ts
-const DEFAULT_SERVICE_ACTION_RISK = "dangerous";
-function buildServiceActionId(appId, actionName) {
-	return `${appId}.${actionName}`;
-}
-function getServiceActionName(actionId, appId) {
-	const prefix = `${appId}.`;
-	if (!actionId.startsWith(prefix)) throw new Error("service action does not belong to service app.");
-	const name = actionId.slice(prefix.length).trim();
-	if (!name) throw new Error("service action name is required.");
-	return name;
-}
-function parseServiceActionCallerKey(key) {
-	const [surface, appId, ...rest] = key.split(":");
-	if (surface !== "panel-app" || !appId || rest.length > 0) return null;
-	return {
-		surface,
-		appId
-	};
-}
-function resolveServiceActionGrantState({ actionId, declaredActions, granted }) {
-	if (declaredActions && !declaredActions.includes(actionId)) return "not-declared";
-	return granted ? "granted" : "not-granted";
-}
-//#endregion
 //#region src/features/capability-grants/services/capability-grant-legacy-migration.service.ts
 const PANEL_AGENT_GRANTS_FILE_NAME = ".panel-app-capability-grants.json";
 const PANEL_CLIENT_GRANTS_FILE_NAME = ".panel-app-client-grants.json";
@@ -5905,7 +5987,7 @@ function parseServiceActionGrants(value) {
 			return {
 				subject: {
 					type: caller.surface,
-					id: caller.appId
+					id: caller.surface === "panel-app" ? caller.appId : caller.agentId
 				},
 				resource: {
 					type: "service.action",
@@ -7502,7 +7584,7 @@ var ExtensionRuntimeService = class {
 		const credential = this.assertAuthorized(envelope, context);
 		const payload = readRecord$2(envelope.payload);
 		const generation = readRequiredString$8(payload.generation, "generation");
-		const pid = readOptionalNumber(payload.pid);
+		const pid = readOptionalNumber$1(payload.pid);
 		if (generation !== credential.generation || pid === void 0 || !Number.isInteger(pid) || pid <= 0) throw new Error("Invalid extension runtime ready payload");
 		this.lifecycle.markReady({
 			extensionId: credential.extensionId,
@@ -13419,6 +13501,7 @@ var McpServiceAppRuntimeService = class {
 		this.states.clear();
 	};
 	toMcpServerRecord = (app, manifest) => {
+		if (!manifest.command || !manifest.args) throw new Error(`MCP Service App ${app.id} is missing its launch command.`);
 		const launch = resolveRuntimeCommandLaunch(manifest.command);
 		return {
 			name: app.id,
@@ -13480,6 +13563,462 @@ var McpServiceAppRuntimeService = class {
 	};
 };
 //#endregion
+//#region src/services/portable-service-runner-client.service.ts
+const PORTABLE_RUNNER_PROTOCOL_VERSION = "0.1.0";
+var PortableServiceRunnerError = class extends Error {
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "PortableServiceRunnerError";
+	}
+};
+var PortableServiceRunnerClientService = class {
+	child;
+	pending = /* @__PURE__ */ new Map();
+	stderrTail = [];
+	constructor(params = {}) {
+		this.params = params;
+	}
+	listActions = async (app) => this.request({
+		operation: "list-actions",
+		app
+	}, 7e3);
+	invoke = async (app, actionName, input, timeoutMs = 7e3) => this.request({
+		operation: "invoke",
+		app,
+		actionName,
+		input
+	}, timeoutMs);
+	startResident = async (app, config) => this.request({
+		operation: "start-resident",
+		app,
+		input: config
+	}, 7e3);
+	startProvider = async (app, config) => this.request({
+		operation: "start-provider",
+		app,
+		input: config
+	}, 7e3);
+	deliverEvent = async (app, event) => this.request({
+		operation: "deliver-event",
+		app,
+		input: event
+	}, 7e3);
+	stats = async () => this.request({ operation: "stats" }, 2e3);
+	stop = async (app) => {
+		await this.request({
+			operation: "stop",
+			app,
+			input: {
+				stoppedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				reason: "host-stop"
+			}
+		}, 2e3);
+	};
+	dispose = async () => {
+		const child = this.child;
+		this.child = void 0;
+		if (!child) return;
+		child.stdin.end();
+		await new Promise((resolve) => {
+			const timeout = setTimeout(() => {
+				child.kill("SIGKILL");
+				resolve();
+			}, 1e3);
+			timeout.unref();
+			child.once("exit", () => {
+				clearTimeout(timeout);
+				resolve();
+			});
+		});
+	};
+	request = async (request, timeoutMs) => {
+		const child = this.ensureChild();
+		const requestId = randomUUID();
+		const payload = {
+			...request,
+			requestId,
+			app: request.app ? this.toRunnerApp(request.app) : void 0
+		};
+		return await new Promise((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				const error = new PortableServiceRunnerError("PORTABLE_RUNTIME_TIMEOUT", `Portable component exceeded its ${timeoutMs}ms execution budget.`);
+				this.failAll(error);
+				this.child?.kill("SIGKILL");
+				this.child = void 0;
+			}, timeoutMs);
+			timeout.unref();
+			this.pending.set(requestId, {
+				resolve: (value) => resolve(value),
+				reject,
+				timeout
+			});
+			child.stdin.write(`${JSON.stringify(payload)}\n`, (error) => {
+				if (!error) return;
+				const pending = this.pending.get(requestId);
+				if (!pending) return;
+				clearTimeout(pending.timeout);
+				this.pending.delete(requestId);
+				reject(error);
+			});
+		});
+	};
+	ensureChild = () => {
+		if (this.child && this.child.exitCode === null) return this.child;
+		const child = spawn(this.resolveRunnerPath(), [], { stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		] });
+		this.child = child;
+		this.stderrTail = [];
+		createInterface({ input: child.stdout }).on("line", this.handleLine);
+		child.stderr.on("data", (chunk) => {
+			const message = chunk.toString("utf8").trim();
+			if (!message) return;
+			this.stderrTail = [...this.stderrTail, message].slice(-20);
+			process.stderr.write(`${message}\n`);
+		});
+		child.once("error", (error) => {
+			if (this.child === child) this.handleChildFailure(error);
+		});
+		child.once("exit", (code, signal) => {
+			if (this.child !== child) return;
+			this.child = void 0;
+			const error = new PortableServiceRunnerError("PORTABLE_RUNNER_EXITED", `Portable runner exited (${signal ?? code ?? "unknown"}). ${this.stderrTail.join(" ")}`.trim());
+			this.failAll(error);
+			this.params.onUnexpectedExit?.(error);
+		});
+		return child;
+	};
+	handleLine = (line) => {
+		let response;
+		try {
+			response = JSON.parse(line);
+		} catch {
+			this.handleChildFailure(/* @__PURE__ */ new Error(`Portable runner returned invalid JSON: ${line}`));
+			return;
+		}
+		if (response.protocolVersion !== PORTABLE_RUNNER_PROTOCOL_VERSION) {
+			const error = new PortableServiceRunnerError("PORTABLE_RUNNER_PROTOCOL_MISMATCH", `Portable runner protocol mismatch: expected ${PORTABLE_RUNNER_PROTOCOL_VERSION}, received ${response.protocolVersion ?? "missing"}.`);
+			const child = this.child;
+			this.handleChildFailure(error);
+			child?.kill("SIGKILL");
+			return;
+		}
+		const pending = this.pending.get(response.requestId);
+		if (!pending) return;
+		clearTimeout(pending.timeout);
+		this.pending.delete(response.requestId);
+		if (response.ok) {
+			pending.resolve(response.result);
+			return;
+		}
+		pending.reject(new PortableServiceRunnerError(response.error?.code ?? "PORTABLE_RUNTIME_FAILED", response.error?.message ?? "Portable runner request failed."));
+	};
+	handleChildFailure = (error) => {
+		this.failAll(error);
+		this.child = void 0;
+	};
+	failAll = (error) => {
+		for (const pending of this.pending.values()) {
+			clearTimeout(pending.timeout);
+			pending.reject(error);
+		}
+		this.pending.clear();
+	};
+	toRunnerApp = (app) => ({
+		id: app.id,
+		componentPath: app.componentPath,
+		dataDirectory: app.dataDirectory,
+		allowedDomains: app.permissions.allowedDomains ?? [],
+		allowedProviderIds: app.providerIds ?? [],
+		storageEnabled: Boolean(app.permissions.storage)
+	});
+	resolveRunnerPath = () => {
+		const runnerPath = (this.params.env ?? process.env).NEXTCLAW_WASMTIME_RUNNER_PATH?.trim() || this.params.runnerPath?.trim();
+		if (!runnerPath) throw new PortableServiceRunnerError("PORTABLE_RUNNER_UNAVAILABLE", "Portable runner is not part of this NextClaw distribution. Build the product runtime resource; runner developers may set NEXTCLAW_WASMTIME_RUNNER_PATH explicitly.");
+		try {
+			accessSync(runnerPath, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+		} catch {
+			throw new PortableServiceRunnerError("PORTABLE_RUNNER_UNAVAILABLE", `Portable runner is missing or not executable: ${runnerPath}`);
+		}
+		return runnerPath;
+	};
+};
+//#endregion
+//#region src/services/portable-service-app-runtime.service.ts
+var PortableServiceAppRuntimeService = class {
+	runner;
+	states = /* @__PURE__ */ new Map();
+	apps = /* @__PURE__ */ new Map();
+	providers = /* @__PURE__ */ new Set();
+	persistentRegistrations = /* @__PURE__ */ new Map();
+	residentTimers = /* @__PURE__ */ new Map();
+	residentDeliveries = /* @__PURE__ */ new Map();
+	recoveryPromise;
+	constructor(params = {}) {
+		this.runner = new PortableServiceRunnerClientService({
+			runnerPath: params.runnerPath,
+			onUnexpectedExit: (error) => {
+				this.recoverPersistentComponentsIfNeeded(error);
+			}
+		});
+	}
+	getStatus = (appId) => this.states.get(appId) ?? { status: "idle" };
+	start = async ({ app, manifest }) => {
+		if (!app.enabled || !manifest.lifecycle || manifest.lifecycle.mode === "action") return;
+		this.persistentRegistrations.set(app.id, {
+			app,
+			manifest
+		});
+		const runnerApp = this.toRunnerApp(app, manifest.providerIds);
+		this.apps.set(app.id, runnerApp);
+		if (manifest.lifecycle.mode === "provider") {
+			if (this.providers.has(app.id)) return;
+			const lastStartedAt = (/* @__PURE__ */ new Date()).toISOString();
+			this.states.set(app.id, {
+				status: "starting",
+				lastStartedAt
+			});
+			try {
+				await this.runner.startProvider(runnerApp, {
+					mode: "provider",
+					startedAt: lastStartedAt
+				});
+				this.providers.add(app.id);
+				this.states.set(app.id, {
+					status: "running",
+					lastStartedAt,
+					lastReadyAt: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			} catch (error) {
+				this.markFailed(app.id, lastStartedAt, error);
+				throw error;
+			}
+			return;
+		}
+		if (this.residentTimers.has(app.id)) return;
+		const lastStartedAt = (/* @__PURE__ */ new Date()).toISOString();
+		this.states.set(app.id, {
+			status: "starting",
+			lastStartedAt
+		});
+		try {
+			await this.runner.startResident(runnerApp, {
+				eventIntervalMs: manifest.lifecycle.eventIntervalMs,
+				startedAt: lastStartedAt
+			});
+			const timer = setInterval(() => {
+				this.scheduleResidentEvent({
+					appId: app.id,
+					eventIntervalMs: manifest.lifecycle?.mode === "resident" ? manifest.lifecycle.eventIntervalMs : 0
+				});
+			}, manifest.lifecycle.eventIntervalMs);
+			timer.unref();
+			this.residentTimers.set(app.id, timer);
+			this.states.set(app.id, {
+				status: "running",
+				lastStartedAt,
+				lastReadyAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		} catch (error) {
+			this.markFailed(app.id, lastStartedAt, error);
+			throw error;
+		}
+	};
+	listActions = async ({ app, manifest }) => {
+		if (!app.enabled) return [];
+		const runnerApp = this.toRunnerApp(app, manifest.providerIds);
+		this.apps.set(app.id, runnerApp);
+		const persistent = manifest.lifecycle?.mode === "resident" || manifest.lifecycle?.mode === "provider";
+		const lastStartedAt = persistent ? this.states.get(app.id)?.lastStartedAt ?? (/* @__PURE__ */ new Date()).toISOString() : (/* @__PURE__ */ new Date()).toISOString();
+		if (!persistent) this.states.set(app.id, {
+			status: "starting",
+			lastStartedAt
+		});
+		try {
+			const actions = await this.runner.listActions(runnerApp);
+			if (!persistent) this.states.set(app.id, {
+				status: "running",
+				lastStartedAt,
+				lastReadyAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			return actions.map((action) => {
+				const declared = manifest.actions[action.name];
+				return {
+					id: buildServiceActionId(app.id, action.name),
+					appId: app.id,
+					name: action.name,
+					title: declared?.title ?? action.title,
+					description: declared?.description ?? action.description,
+					inputSchema: declared?.inputSchema,
+					risk: declared?.risk ?? "dangerous"
+				};
+			});
+		} catch (error) {
+			this.markFailed(app.id, lastStartedAt, error);
+			await this.recoverPersistentComponentsIfNeeded(error);
+			throw error;
+		}
+	};
+	invokeAction = async ({ app, manifest, actionName, input }) => {
+		await this.start({
+			app,
+			manifest
+		});
+		const runnerApp = this.toRunnerApp(app, manifest.providerIds);
+		this.apps.set(app.id, runnerApp);
+		if (manifest.lifecycle?.mode === "resident") try {
+			return await this.runner.invoke(runnerApp, actionName, input, manifest.actions[actionName]?.timeoutMs ?? 7e3);
+		} catch (error) {
+			this.markFailed(app.id, this.states.get(app.id)?.lastStartedAt ?? (/* @__PURE__ */ new Date()).toISOString(), error);
+			await this.recoverPersistentComponentsIfNeeded(error);
+			throw error;
+		}
+		const lastStartedAt = (/* @__PURE__ */ new Date()).toISOString();
+		this.states.set(app.id, {
+			status: "starting",
+			lastStartedAt
+		});
+		try {
+			const result = await this.runner.invoke(runnerApp, actionName, input, manifest.actions[actionName]?.timeoutMs ?? 7e3);
+			this.states.set(app.id, {
+				status: "running",
+				lastStartedAt,
+				lastReadyAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			return result;
+		} catch (error) {
+			this.markFailed(app.id, lastStartedAt, error);
+			await this.recoverPersistentComponentsIfNeeded(error);
+			throw error;
+		}
+	};
+	stop = async (appId) => {
+		this.clearResidentTimer(appId);
+		this.providers.delete(appId);
+		this.persistentRegistrations.delete(appId);
+		const app = this.apps.get(appId);
+		this.apps.delete(appId);
+		if (app) await this.runner.stop(app);
+		this.states.set(appId, { status: "idle" });
+	};
+	restart = async (appId) => await this.stop(appId);
+	dispose = async () => {
+		if (this.recoveryPromise) await this.recoveryPromise;
+		for (const appId of this.residentTimers.keys()) this.clearResidentTimer(appId);
+		await Promise.allSettled(this.residentDeliveries.values());
+		await this.runner.dispose();
+		this.states.clear();
+		this.apps.clear();
+		this.providers.clear();
+		this.persistentRegistrations.clear();
+		this.residentDeliveries.clear();
+	};
+	scheduleResidentEvent = (params) => {
+		if (this.residentDeliveries.has(params.appId)) return;
+		const delivery = this.deliverResidentEvent(params).finally(() => {
+			this.residentDeliveries.delete(params.appId);
+		});
+		this.residentDeliveries.set(params.appId, delivery);
+	};
+	deliverResidentEvent = async (params) => {
+		const app = this.apps.get(params.appId);
+		if (!app) return;
+		const triggeredAt = (/* @__PURE__ */ new Date()).toISOString();
+		try {
+			await this.runner.deliverEvent(app, {
+				eventId: `timer-${triggeredAt}`,
+				kind: "timer",
+				triggeredAt,
+				eventIntervalMs: params.eventIntervalMs
+			});
+		} catch (error) {
+			this.clearResidentTimer(params.appId);
+			this.markFailed(params.appId, this.states.get(params.appId)?.lastStartedAt ?? triggeredAt, error);
+			await this.recoverPersistentComponentsIfNeeded(error);
+		}
+	};
+	clearResidentTimer = (appId) => {
+		const timer = this.residentTimers.get(appId);
+		if (timer) clearInterval(timer);
+		this.residentTimers.delete(appId);
+	};
+	recoverPersistentComponentsIfNeeded = async (error) => {
+		if (!(error instanceof PortableServiceRunnerError) || !["PORTABLE_RUNTIME_TIMEOUT", "PORTABLE_RUNNER_EXITED"].includes(error.code)) return;
+		if (this.recoveryPromise) return await this.recoveryPromise;
+		const registrations = Array.from(this.persistentRegistrations.values());
+		if (registrations.length === 0) return;
+		this.recoveryPromise = (async () => {
+			for (const appId of this.residentTimers.keys()) this.clearResidentTimer(appId);
+			this.providers.clear();
+			const ordered = [...registrations.filter(({ manifest }) => manifest.lifecycle?.mode === "provider"), ...registrations.filter(({ manifest }) => manifest.lifecycle?.mode === "resident")];
+			for (const registration of ordered) try {
+				await this.start(registration);
+			} catch {}
+		})().finally(() => {
+			this.recoveryPromise = void 0;
+		});
+		await this.recoveryPromise;
+	};
+	toRunnerApp = (app, providerIds) => {
+		if (!app.componentPath || !app.dataDirectory) throw new Error(`Portable Service App ${app.id} is missing component or data storage.`);
+		return {
+			id: app.id,
+			componentPath: app.componentPath,
+			dataDirectory: app.dataDirectory,
+			permissions: app.permissions ?? {},
+			providerIds
+		};
+	};
+	markFailed = (appId, lastStartedAt, error) => {
+		this.states.set(appId, {
+			status: "failed",
+			lastError: error instanceof Error ? error.message : String(error),
+			lastStartedAt,
+			lastFailedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	};
+};
+//#endregion
+//#region src/services/service-app-runtime.service.ts
+var ServiceAppRuntimeService = class {
+	mcp;
+	portable;
+	protocols = /* @__PURE__ */ new Map();
+	constructor(params) {
+		this.mcp = new McpServiceAppRuntimeService(params);
+		this.portable = new PortableServiceAppRuntimeService({ runnerPath: params.portableServiceRunnerPath });
+	}
+	getStatus = (appId) => {
+		return this.protocols.get(appId) === "wasi-component" ? this.portable.getStatus(appId) : this.mcp.getStatus(appId);
+	};
+	start = async (call) => {
+		this.protocols.set(call.app.id, call.manifest.protocol);
+		if (call.manifest.protocol === "wasi-component") await this.portable.start(call);
+	};
+	listActions = async (call) => {
+		this.protocols.set(call.app.id, call.manifest.protocol);
+		return call.manifest.protocol === "wasi-component" ? await this.portable.listActions(call) : await this.mcp.listActions(call);
+	};
+	invokeAction = async (call) => {
+		this.protocols.set(call.app.id, call.manifest.protocol);
+		return call.manifest.protocol === "wasi-component" ? await this.portable.invokeAction(call) : await this.mcp.invokeAction(call);
+	};
+	stop = async (appId) => {
+		const protocol = this.protocols.get(appId);
+		if (protocol === "wasi-component") await this.portable.stop(appId);
+		else if (protocol === "mcp") await this.mcp.stop(appId);
+		else await Promise.all([this.mcp.stop(appId), this.portable.stop(appId)]);
+	};
+	restart = async (appId) => await this.stop(appId);
+	dispose = async () => {
+		await Promise.all([this.mcp.dispose(), this.portable.dispose()]);
+		this.protocols.clear();
+	};
+};
+//#endregion
 //#region src/utils/service-app-manifest.utils.ts
 const SERVICE_APP_ID_PATTERN$1 = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const SERVICE_ACTION_RISKS = new Set([
@@ -13506,19 +14045,56 @@ function parseServiceAppManifest(raw, options = {}) {
 	const id = readRequiredString$6(parsed, "id");
 	if (!SERVICE_APP_ID_PATTERN$1.test(id)) throw new Error("service app id must be kebab-case.");
 	const protocol = readOptionalString$8(parsed, "protocol") ?? "mcp";
-	if (protocol !== "mcp") throw new Error("service app protocol must be mcp.");
-	const launch = new AppServiceLaunchService(options.platformTargetService).resolve(parsed, options.target);
+	if (protocol !== "mcp" && protocol !== "wasi-component") throw new Error("service app protocol must be mcp or wasi-component.");
+	const launch = protocol === "mcp" ? new AppServiceLaunchService(options.platformTargetService).resolve(parsed, options.target) : void 0;
+	const componentEntry = protocol === "wasi-component" ? readPortableComponentEntry(parsed) : void 0;
+	const lifecycle = readServiceAppLifecycle(parsed.lifecycle);
+	if (lifecycle.mode !== "action" && protocol !== "wasi-component") throw new Error(`${lifecycle.mode} service app lifecycle requires wasi-component protocol.`);
 	return {
 		id,
 		title: readRequiredString$6(parsed, "title"),
 		description: readOptionalString$8(parsed, "description"),
 		enabled: readOptionalBoolean$1(parsed, "enabled") ?? true,
 		protocol,
-		command: launch.command,
-		args: launch.args,
+		command: launch?.command,
+		args: launch?.args,
+		componentEntry,
+		providerIds: readProviderIds(parsed.providers),
+		lifecycle,
 		actions: readManifestActions(parsed.actions)
 	};
 }
+function readServiceAppLifecycle(value) {
+	if (value === void 0) return { mode: "action" };
+	if (!isRecord$7(value)) throw new Error("service app lifecycle must be an object.");
+	const mode = readOptionalString$8(value, "mode") ?? "action";
+	if (mode === "action") return { mode };
+	if (mode === "provider") return { mode };
+	if (mode !== "resident") throw new Error("service app lifecycle.mode must be action, resident or provider.");
+	const eventIntervalMs = readOptionalNumber(value, "eventIntervalMs");
+	if (eventIntervalMs === void 0 || !Number.isInteger(eventIntervalMs) || eventIntervalMs < 250 || eventIntervalMs > 6e4) throw new Error("resident service app lifecycle.eventIntervalMs must be an integer between 250 and 60000.");
+	return {
+		mode,
+		eventIntervalMs
+	};
+}
+function readProviderIds(value) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value)) throw new Error("service app providers must be an array.");
+	const providerIds = value.map((entry) => {
+		if (typeof entry !== "string" || !SERVICE_APP_ID_PATTERN$1.test(entry.trim())) throw new Error("service app providers must contain kebab-case service app ids.");
+		return entry.trim();
+	});
+	return Array.from(new Set(providerIds));
+}
+function readPortableComponentEntry(record) {
+	const component = record.component;
+	if (!isRecord$7(component)) throw new Error("service app component is required for wasi-component.");
+	const entry = readRequiredString$6(component, "entry").replace(/\\/g, "/");
+	if (path.isAbsolute(entry) || entry.includes("\0") || entry.split("/").includes("..")) throw new Error("service app component.entry must be a package-relative path.");
+	if (!entry.endsWith(".wasm")) throw new Error("service app component.entry must reference a .wasm file.");
+	return entry;
+}
 function readManifestActions(value) {
 	if (value === void 0) throw new Error("service app actions are required.");
 	if (!isRecord$7(value)) throw new Error("service app actions must be an object.");
@@ -13531,11 +14107,14 @@ function readManifestActions(value) {
 		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$7(inputSchema)) throw new Error(`service app action ${name} inputSchema must be an object.`);
+		const timeoutMs = readOptionalNumber(action, "timeoutMs");
+		if (timeoutMs !== void 0 && (!Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 3e5)) throw new Error(`service app action ${name} timeoutMs must be an integer between 100 and 300000.`);
 		actions[name] = {
 			risk,
 			title: readOptionalString$8(action, "title"),
 			description: readOptionalString$8(action, "description"),
-			inputSchema
+			inputSchema,
+			timeoutMs
 		};
 	}
 	return actions;
@@ -13553,10 +14132,49 @@ function readOptionalBoolean$1(record, key) {
 	if (typeof record[key] !== "boolean") throw new Error(`service app ${key} must be boolean.`);
 	return record[key];
 }
+function readOptionalNumber(record, key) {
+	if (record[key] === void 0) return;
+	if (typeof record[key] !== "number") throw new Error(`service app ${key} must be number.`);
+	return record[key];
+}
 function isRecord$7(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 //#endregion
+//#region src/services/service-app-lifecycle.service.ts
+var ServiceAppLifecycleService = class {
+	constructor(params) {
+		this.params = params;
+	}
+	startDiscovered = async (registrations) => {
+		const active = registrations.filter(({ manifest, record }) => record.enabled && manifest.lifecycle && manifest.lifecycle.mode !== "action");
+		await Promise.allSettled(this.order(active).map(async ({ manifest, record }) => await this.params.runtimeService.start?.({
+			app: record,
+			manifest
+		})));
+	};
+	activatePackageComponents = async (components) => {
+		const registrations = [];
+		for (const component of components.filter((entry) => entry.kind === "service")) {
+			const manifest = await readServiceAppManifest(component.sourcePath);
+			if (!manifest.lifecycle || manifest.lifecycle.mode === "action") continue;
+			registrations.push({
+				manifest,
+				record: this.params.recordService.fromManifest(component.sourcePath, manifest, component, component.storage)
+			});
+		}
+		for (const { manifest, record } of this.order(registrations)) await this.params.runtimeService.start?.({
+			app: record,
+			manifest
+		});
+	};
+	deactivatePackageComponents = async (components) => {
+		const serviceIds = components.filter((component) => component.kind === "service").map((component) => component.id);
+		await Promise.all(serviceIds.map(async (serviceId) => await this.params.runtimeService.stop(serviceId)));
+	};
+	order = (registrations) => [...registrations.filter(({ manifest }) => manifest.lifecycle?.mode === "provider"), ...registrations.filter(({ manifest }) => manifest.lifecycle?.mode === "resident")];
+};
+//#endregion
 //#region src/services/service-app-record.service.ts
 var ServiceAppRecordService = class {
 	instanceStorageService = new AppInstanceStorageService();
@@ -13638,7 +14256,12 @@ var ServiceAppRecordService = class {
 			dataDirectory: storage?.dataDirectory,
 			instanceId: packageSource?.instanceId ?? storage?.instanceId,
 			storage,
-			isolation: packageSource?.isolation ?? "full-user"
+			isolation: packageSource?.isolation ?? "full-user",
+			runtimeProfile: packageSource?.runtimeProfile ?? "native-process",
+			permissions: packageSource?.permissions ?? {},
+			componentPath: manifest.componentEntry ? join(dirPath, manifest.componentEntry) : void 0,
+			providerIds: manifest.providerIds,
+			lifecycle: manifest.lifecycle
 		};
 	};
 	failedWorkspaceRecord = (id, dirPath, error) => ({
@@ -13669,7 +14292,9 @@ var ServiceAppRecordService = class {
 		dataDirectory: source.dataDirectory,
 		instanceId: source.instanceId,
 		storage: source.storage,
-		isolation: source.isolation
+		isolation: source.isolation,
+		runtimeProfile: source.runtimeProfile,
+		permissions: source.permissions
 	});
 	toTitle = (value) => basename(value).replace(/[-_]+/g, " ").trim() || value;
 	getWorkspaceInstanceDirectory = (serviceId) => join(this.params.getWorkspacePath(), ".nextclaw", "app-instances", serviceId, "default");
@@ -13838,13 +14463,16 @@ var ServiceActionGrantService = class {
 		const results = [];
 		for (const grant of grants) {
 			const actionId = readServiceActionTargetId(grant.resource.target);
-			if (!actionId || grant.subject.type !== "panel-app") continue;
+			if (!actionId || grant.subject.type !== "panel-app" && grant.subject.type !== "agent") continue;
 			try {
 				const action = await this.params.resolveAction(actionId);
 				results.push({
-					caller: {
+					caller: grant.subject.type === "panel-app" ? {
 						surface: "panel-app",
 						appId: grant.subject.id
+					} : {
+						surface: "agent",
+						agentId: grant.subject.id
 					},
 					actionId,
 					risk: action.risk,
@@ -13860,7 +14488,7 @@ var ServiceActionGrantService = class {
 		await this.params.capabilityGrantManager.revoke({
 			subject: {
 				type: caller.surface,
-				id: caller.appId
+				id: getServiceActionCallerId(caller)
 			},
 			resourceType: "service.action",
 			target: { actionId }
@@ -13961,28 +14589,6 @@ function mergeServiceAppRuntimeActions({ record, manifest, runtimeActions }) {
 	return [...declared, ...undeclared].sort((left, right) => left.id.localeCompare(right.id));
 }
 //#endregion
-//#region src/utils/service-app-error.utils.ts
-const SERVICE_APP_ERROR_CODES = new Set([
-	"AUTHORIZATION_REQUIRED",
-	"SERVICE_APP_ACTION_NOT_DECLARED",
-	"SERVICE_APP_ACTION_NOT_FOUND",
-	"SERVICE_APP_INVALID_ACTION",
-	"SERVICE_APP_INVALID_CALLER",
-	"SERVICE_APP_INVALID_MANIFEST",
-	"SERVICE_APP_MANAGED_SOURCE",
-	"SERVICE_APP_NOT_FOUND",
-	"SERVICE_APP_READ_FAILED",
-	"SERVICE_APP_RUNTIME_FAILED"
-]);
-var ServiceAppError = class extends Error {
-	constructor(code, message) {
-		super(message);
-		this.code = code;
-		this.name = "ServiceAppError";
-	}
-};
-const isServiceAppError = (error) => error instanceof ServiceAppError || typeof error === "object" && error !== null && error.name === "ServiceAppError" && typeof error.message === "string" && SERVICE_APP_ERROR_CODES.has(error.code);
-//#endregion
 //#region src/managers/service-app.manager.ts
 const SERVICE_APP_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 var ServiceAppManager = class {
@@ -13991,14 +14597,22 @@ var ServiceAppManager = class {
 	recordService;
 	actionGrants;
 	packageRuntime;
+	lifecycleService;
 	reconciliationDiagnostics = [];
 	constructor(params) {
 		this.params = params;
-		this.runtimeService = params.runtimeService ?? new McpServiceAppRuntimeService({ getConfig: () => params.configManager.config });
+		this.runtimeService = params.runtimeService ?? new ServiceAppRuntimeService({
+			getConfig: () => params.configManager.config,
+			portableServiceRunnerPath: params.portableServiceRunnerPath
+		});
 		this.recordService = new ServiceAppRecordService({
 			getWorkspacePath: this.getWorkspacePath,
 			runtimeService: this.runtimeService
 		});
+		this.lifecycleService = new ServiceAppLifecycleService({
+			recordService: this.recordService,
+			runtimeService: this.runtimeService
+		});
 		this.actionGrants = new ServiceActionGrantService({
 			capabilityGrantManager: params.capabilityGrantManager,
 			resolveAction: this.requireServiceAction
@@ -14017,6 +14631,7 @@ var ServiceAppManager = class {
 			lockPathForAppId: (appId) => this.getServiceAppLockPath(this.getWorkspacePath(), appId),
 			serviceAppsPath: this.getServiceAppsPath(this.getWorkspacePath())
 		});
+		await this.lifecycleService.startDiscovered(await this.listValidServiceApps());
 	};
 	listServiceApps = async () => {
 		const workspacePath = this.getWorkspacePath();
@@ -14052,8 +14667,8 @@ var ServiceAppManager = class {
 		});
 	};
 	invokeServiceAction = async (actionId, request) => {
-		this.assertCaller(request.caller);
-		this.assertDeclaredAction(actionId, request.declaredActions);
+		assertServiceActionCaller(request.caller, this.params.hasAgent);
+		assertServiceActionDeclared(request.caller, actionId, request.declaredActions);
 		const { manifest, record } = await this.requireServiceAppForAction(actionId, true);
 		const actionName = getServiceActionName(actionId, record.id);
 		if (!Object.hasOwn(manifest.actions, actionName)) throw new ServiceAppError("SERVICE_APP_ACTION_NOT_FOUND", "service action not found");
@@ -14080,30 +14695,33 @@ var ServiceAppManager = class {
 		return grant;
 	};
 	grantServiceActions = async (actionIds, request) => {
-		this.assertCaller(request.caller);
+		assertServiceActionCaller(request.caller, this.params.hasAgent);
 		const normalizedActionIds = this.normalizeActionIds(actionIds);
 		if (normalizedActionIds.length === 0) throw new ServiceAppError("SERVICE_APP_INVALID_ACTION", "service action id is invalid");
 		const actions = [];
 		for (const actionId of normalizedActionIds) {
-			this.assertDeclaredAction(actionId, request.declaredActions);
+			assertServiceActionDeclared(request.caller, actionId, request.declaredActions);
 			actions.push(await this.requireServiceAction(actionId));
 		}
 		return await this.actionGrants.grant(request.caller, actions);
 	};
 	listServiceActionGrants = async () => await this.actionGrants.list();
 	revokeServiceAction = async (caller, actionId) => {
-		this.assertCaller(caller);
+		assertServiceActionCaller(caller, this.params.hasAgent);
 		await this.actionGrants.revoke(caller, actionId);
 	};
 	matchesCapabilityGrant = async (grant) => {
-		if (grant.subject.type !== "panel-app" || grant.resource.type !== "service.action") return false;
+		if (grant.subject.type !== "panel-app" && grant.subject.type !== "agent" || grant.resource.type !== "service.action") return false;
 		const actionId = readServiceActionTargetId(grant.resource.target);
 		if (!actionId) return false;
 		try {
 			const action = await this.requireServiceAction(actionId);
-			return getCapabilityGrantKey(grant) === getCapabilityGrantKey(createServiceActionGrantRequest({
+			return getCapabilityGrantKey(grant) === getCapabilityGrantKey(createServiceActionGrantRequest(grant.subject.type === "panel-app" ? {
 				surface: "panel-app",
 				appId: grant.subject.id
+			} : {
+				surface: "agent",
+				agentId: grant.subject.id
 			}, action));
 		} catch {
 			return false;
@@ -14183,10 +14801,8 @@ var ServiceAppManager = class {
 			}
 		}
 	};
-	deactivatePackageComponents = async (components) => {
-		const serviceIds = components.filter((component) => component.kind === "service").map((component) => component.id);
-		await Promise.all(serviceIds.map(async (serviceId) => await this.runtimeService.stop(serviceId)));
-	};
+	activatePackageComponents = async (components) => await this.lifecycleService.activatePackageComponents(components);
+	deactivatePackageComponents = async (components) => await this.lifecycleService.deactivatePackageComponents(components);
 	preparePackageComponentDeactivation = async (components) => await this.packageRuntime.prepareDeactivation(components);
 	removePackageComponentGrants = async (components) => await this.actionGrants.removePackageGrants(new Set(components.filter((component) => component.kind === "service").map((component) => component.id)));
 	withGrantState = async (action, params) => {
@@ -14267,12 +14883,6 @@ var ServiceAppManager = class {
 		}));
 		return [...workspaceEntries, ...packageEntries].filter((entry) => Boolean(entry));
 	};
-	assertCaller = (caller) => {
-		if (caller.surface !== "panel-app" || !caller.appId.trim()) throw new ServiceAppError("SERVICE_APP_INVALID_CALLER", "service action caller is invalid");
-	};
-	assertDeclaredAction = (actionId, declaredActions) => {
-		if (!declaredActions.includes(actionId)) throw new ServiceAppError("SERVICE_APP_ACTION_NOT_DECLARED", "panel app did not declare this service action");
-	};
 	normalizeActionIds = (actionIds) => Array.from(new Set(actionIds.map((actionId) => actionId.trim()).filter((actionId) => actionId.length > 0)));
 	getWorkspacePath = () => getWorkspacePathFromConfig(this.params.configManager.config);
 	getServiceAppsPath = (workspacePath) => join(workspacePath, DEFAULT_SERVICE_APPS_DIR);
@@ -21248,6 +21858,57 @@ function readOptionalString$1(value) {
 	return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
 //#endregion
+//#region src/utils/service-action-tool.utils.ts
+const MAX_TOOL_NAME_LENGTH = 64;
+const HASH_LENGTH = 8;
+const TOOL_PREFIX = "service__";
+function buildServiceActionToolName(actionId) {
+	const readable = actionId.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "action";
+	const suffix = `__${createHash("sha256").update(actionId).digest("hex").slice(0, HASH_LENGTH)}`;
+	const available = MAX_TOOL_NAME_LENGTH - 9 - suffix.length;
+	return `${TOOL_PREFIX}${readable.slice(0, available)}${suffix}`;
+}
+//#endregion
+//#region src/contributions/tool-provider/providers/service-action-tool.provider.ts
+const EMPTY_OBJECT_SCHEMA = {
+	type: "object",
+	properties: {},
+	additionalProperties: false
+};
+var ServiceActionToolProvider = class {
+	constructor(runContextService, serviceAppManager) {
+		this.runContextService = runContextService;
+		this.serviceAppManager = serviceAppManager;
+	}
+	provide = async (request) => {
+		const { toolRunContext } = await this.runContextService.resolve(request);
+		const caller = {
+			surface: "agent",
+			agentId: toolRunContext.agentId
+		};
+		return (await this.serviceAppManager.listServiceActions({ caller })).filter((action) => action.grantState === "granted").map((action) => this.toTool(caller, action));
+	};
+	toTool = (caller, action) => ({
+		name: buildServiceActionToolName(action.id),
+		description: [
+			action.title ?? action.name,
+			action.description,
+			`NextClaw Service Action: ${action.id}`
+		].filter(Boolean).join("\n"),
+		parameters: action.inputSchema ?? EMPTY_OBJECT_SCHEMA,
+		supportsParallelToolCalls: action.risk === "read",
+		execute: async (args) => await this.serviceAppManager.invokeServiceAction(action.id, {
+			caller,
+			input: readInput(args)
+		})
+	});
+};
+function readInput(value) {
+	if (value === void 0) return {};
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Service Action tool input must be an object.");
+	return value;
+}
+//#endregion
 //#region src/contributions/tool-provider/services/tool-provider-run-context.service.ts
 var ToolProviderRunContextService = class {
 	constructor(sessionManager, agentManager, configManager) {
@@ -21304,6 +21965,7 @@ var ToolProviderContribution = class extends Contribution$1 {
 			new ProjectToolProvider(this.kernel.projectManager),
 			new SessionToolProvider(runContextService, this.kernel.sessionManager, this.kernel.sessionRequests, this.kernel.sessionSearch),
 			new AssetToolProvider(this.kernel.assetStore),
+			new ServiceActionToolProvider(runContextService, this.kernel.serviceAppManager),
 			new McpToolProvider(runContextService, this.kernel.mcpManager)
 		];
 	};
@@ -21332,11 +21994,13 @@ function createKernelOperationalManagers(params) {
 	};
 }
 function createKernelServiceAppManagers(params) {
-	const { appHomeDirectory, appPackageManager, capabilityGrantManager, configManager } = params;
+	const { appHomeDirectory, appPackageManager, capabilityGrantManager, configManager, hasAgent, portableServiceRunnerPath } = params;
 	const serviceAppManager = new ServiceAppManager({
 		configManager,
 		listPackageComponentSources: appPackageManager.listActiveComponentSources,
-		capabilityGrantManager
+		capabilityGrantManager,
+		hasAgent,
+		portableServiceRunnerPath
 	});
 	return {
 		serviceAppManager,
@@ -21405,6 +22069,9 @@ function installKernelAppPackageRuntimeHooks(params) {
 			await panelAppManager.assertCanActivatePackageComponents(sources);
 			await serviceAppManager.assertCanActivatePackageComponents(sources);
 		},
+		afterActivate: async (sources) => {
+			await serviceAppManager.activatePackageComponents(sources);
+		},
 		beforeDeactivate: async (sources) => {
 			panelAppManager.deactivatePackageComponents(sources);
 			await serviceAppManager.deactivatePackageComponents(sources);
@@ -21548,7 +22215,9 @@ var NextclawKernel = class {
 			appHomeDirectory: resolveKernelAppHomeDirectory(options),
 			appPackageManager: this.appPackageManager,
 			configManager: this.configManager,
-			capabilityGrantManager: this.capabilityGrants
+			capabilityGrantManager: this.capabilityGrants,
+			hasAgent: (agentId) => this.agents.getAgent(agentId) !== null,
+			portableServiceRunnerPath: options.portableServiceRunnerPath
 		}));
 		installKernelAppPackageRuntimeHooks({
 			appPackageManager: this.appPackageManager,
@@ -22776,6 +23445,6 @@ function resolveLegacyEventType(message) {
 	return `message.${role || "other"}`;
 }
 //#endregion
-export { AUTOMATIC_UPDATE_CHECK_INTERVAL_MS, AccessManager, AgentManager, AgentRunClient, AppDataError, AppDataManager, AppPackageError, AppPackageManager, AutomationManager, BuiltinNarpRuntimeProviderService, CONTEXT_COMPACTION_CONTINUATION_TEXT, CONTEXT_COMPACTION_PROJECTION_KIND, CONTEXT_COMPACTION_PROJECTION_METADATA_KEY, CONTEXT_COMPACTION_SYSTEM_PREAMBLE, CONTEXT_COMPACTION_TIMELINE_KIND, CapabilityGrantLegacyMigrationService, CapabilityGrantManager, CapabilityGrantStore, ChannelManager, CommandRegistry, ConfigManager, ContextCompactionJournalRecoveryService, ContextCompactionPreflightService, Contribution, DEFAULT_AGENT_RUNTIME_ENTRY_ID, DEFAULT_SERVICE_ACTION_RISK, DESKTOP_HOST_ACCESS, DESKTOP_HOST_PROTOCOL_VERSION, DesktopHostCapabilityManager, DesktopNodeReplService, DesktopSessionStateService, EventBus, ExtensionManager, FeatureControlsService, GatewayInboundProcessor, InboxDeliveryError, InboxDeliveryManager, Ingress, LlmProviderManager, LlmUsageManager, LlmUsageStore, MAX_INBOX_DELIVERY_CONTENT_LENGTH, McpManager, McpServiceAppRuntimeService, NARP_HTTP_RUNTIME_KIND, NARP_STDIO_RUNTIME_KIND, NEXTCLAW_TIMELINE_KIND_METADATA_KEY, NcpAgentSessionJournalStore, NextclawHarness, NextclawHarnessError, NextclawKernel, ObservationManager, PANEL_APP_AGENT_CAPABILITIES, PROJECT_TEMPLATE_IDS, PROVIDER_MODEL_CATALOG_REFRESH_INTERVAL_MS, PanelAppAssetTokenService, PanelAppError, PanelAppManager, PreferenceError, PreferenceManager, ProjectError, ProjectManager, ProviderManagerNcpLLMApi, ProviderModelCatalogManager, SERVICE_APP_MANIFEST_FILE_NAME, ServiceAppError, ServiceAppManager, SessionContextCompactionError, SessionContextCompactionManager, SessionManager, SessionMessageCursorError, SessionRequestManager, SessionSettingsError, SkillManager, SystemObjectReferenceError, SystemObjectReferenceManager, UnavailableDesktopHost, UpdateManifestReader, assertObservationJsonValue, assertObservationPredicate, buildAgentRunSendPayload, buildContextCompactionModelProjection, buildContextCompactionTimelineNcpMessage, buildLlmUsageSummary, buildLocalizedTextMap, buildNextclawNcpRunContext, buildObservationEventModelMessage, buildServiceActionId, capabilityGrantCovers, createAgentRuntimeSessionRequestDispatcher, createAssetTools, createCapabilityDeclarationFingerprint, createContextCompactionMessageId, createContextWindowSignature, createCronJobSystemObjectProvider, createDesktopHostError, createInboxDeliverySystemObjectProvider, createLlmUsageRecord, createPanelAppAgentGrantRequest, createPanelAppClientGrantRequest, createServiceActionGrantRequest, createTypedKey, describeAgentRuntimeSessionTypes, dispatchAgentRuntimeSessionRequest, dispatchChannelReplyRoute, dispatchPromptOverNcp, dispatchPromptOverNcpResult, evaluateObservationEventAdmission, eventKeys, getAutomaticUpdateCheckDelay, getCapabilityGrantKey, getServiceActionName, getServiceAppManifestPath, getUiContentParamsBootstrapScript, getUnsignedUpdateManifest, hasLlmUsageTelemetry, ingressKeys, injectUiContentParamsBootstrap, isAppDataError, isAppPackageError, isContextCompactionProjectionMessage, isContextCompactionTimelineMessage, isContextWindowSnapshot, isInboxDeliveryError, isPanelAppAgentCapability, isPanelAppError, isPreferenceError, isProjectError, isReplyCapableChannel, isServiceAppError, isSessionContextCompactionError, isSessionMessageCursorError, isSessionSettingsError, isSystemObjectReferenceError, listExtensionChannelIds, listServiceAppManifestActions, matchesCapabilityGrantFilter, matchesObservationPredicate, mergeServiceAppRuntimeActions, normalizeAgentRuntimeSessionTypeIcon, normalizeCapabilityGrantRequest, normalizeLlmUsageModel, normalizeOptionalString, parseObservationDuration, parseServiceAppManifest, parseSkillFrontmatter, readContextCompactionCheckpoint, readContextWindowEventSessionId, readJsonPointer, readLatestContextCompactionCheckpoint, readLearningLoopRuntimeConfig, readMetadataModel, readMetadataThinking, readServiceActionTargetId, readServiceAppManifest, resolveAgentRuntimeEntries, resolveAutomaticUpdateCheckIntervalMs, resolveChannelReplyRoute, resolveEffectiveModel, resolveLegacyEventType, resolveSessionChannelContext, runGatewayInboundLoop, runNextclawTask, sanitizeLlmUsage, serializeContextTail, serializeUnsignedUpdateManifest, shouldRefreshContextWindowDuringStream, shouldRefreshContextWindowImmediately, startPromptOverNcpExecution, stripSkillFrontmatter, syncSessionThinkingPreference, toBoundedJson, toNcpMessages, waitForAgentRuntimeSessionReply };
+export { AUTOMATIC_UPDATE_CHECK_INTERVAL_MS, AccessManager, AgentManager, AgentRunClient, AppDataError, AppDataManager, AppPackageError, AppPackageManager, AutomationManager, BuiltinNarpRuntimeProviderService, CONTEXT_COMPACTION_CONTINUATION_TEXT, CONTEXT_COMPACTION_PROJECTION_KIND, CONTEXT_COMPACTION_PROJECTION_METADATA_KEY, CONTEXT_COMPACTION_SYSTEM_PREAMBLE, CONTEXT_COMPACTION_TIMELINE_KIND, CapabilityGrantLegacyMigrationService, CapabilityGrantManager, CapabilityGrantStore, ChannelManager, CommandRegistry, ConfigManager, ContextCompactionJournalRecoveryService, ContextCompactionPreflightService, Contribution, DEFAULT_AGENT_RUNTIME_ENTRY_ID, DEFAULT_SERVICE_ACTION_RISK, DESKTOP_HOST_ACCESS, DESKTOP_HOST_PROTOCOL_VERSION, DesktopHostCapabilityManager, DesktopNodeReplService, DesktopSessionStateService, EventBus, ExtensionManager, FeatureControlsService, GatewayInboundProcessor, InboxDeliveryError, InboxDeliveryManager, Ingress, LlmProviderManager, LlmUsageManager, LlmUsageStore, MAX_INBOX_DELIVERY_CONTENT_LENGTH, McpManager, McpServiceAppRuntimeService, NARP_HTTP_RUNTIME_KIND, NARP_STDIO_RUNTIME_KIND, NEXTCLAW_TIMELINE_KIND_METADATA_KEY, NcpAgentSessionJournalStore, NextclawHarness, NextclawHarnessError, NextclawKernel, ObservationManager, PANEL_APP_AGENT_CAPABILITIES, PROJECT_TEMPLATE_IDS, PROVIDER_MODEL_CATALOG_REFRESH_INTERVAL_MS, PanelAppAssetTokenService, PanelAppError, PanelAppManager, PreferenceError, PreferenceManager, ProjectError, ProjectManager, ProviderManagerNcpLLMApi, ProviderModelCatalogManager, SERVICE_APP_MANIFEST_FILE_NAME, ServiceAppError, ServiceAppManager, ServiceAppRuntimeService, SessionContextCompactionError, SessionContextCompactionManager, SessionManager, SessionMessageCursorError, SessionRequestManager, SessionSettingsError, SkillManager, SystemObjectReferenceError, SystemObjectReferenceManager, UnavailableDesktopHost, UpdateManifestReader, assertObservationJsonValue, assertObservationPredicate, buildAgentRunSendPayload, buildContextCompactionModelProjection, buildContextCompactionTimelineNcpMessage, buildLlmUsageSummary, buildLocalizedTextMap, buildNextclawNcpRunContext, buildObservationEventModelMessage, buildServiceActionId, capabilityGrantCovers, createAgentRuntimeSessionRequestDispatcher, createAssetTools, createCapabilityDeclarationFingerprint, createContextCompactionMessageId, createContextWindowSignature, createCronJobSystemObjectProvider, createDesktopHostError, createInboxDeliverySystemObjectProvider, createLlmUsageRecord, createPanelAppAgentGrantRequest, createPanelAppClientGrantRequest, createServiceActionGrantRequest, createTypedKey, describeAgentRuntimeSessionTypes, dispatchAgentRuntimeSessionRequest, dispatchChannelReplyRoute, dispatchPromptOverNcp, dispatchPromptOverNcpResult, evaluateObservationEventAdmission, eventKeys, getAutomaticUpdateCheckDelay, getCapabilityGrantKey, getServiceActionName, getServiceAppManifestPath, getUiContentParamsBootstrapScript, getUnsignedUpdateManifest, hasLlmUsageTelemetry, ingressKeys, injectUiContentParamsBootstrap, isAppDataError, isAppPackageError, isContextCompactionProjectionMessage, isContextCompactionTimelineMessage, isContextWindowSnapshot, isInboxDeliveryError, isPanelAppAgentCapability, isPanelAppError, isPreferenceError, isProjectError, isReplyCapableChannel, isServiceAppError, isSessionContextCompactionError, isSessionMessageCursorError, isSessionSettingsError, isSystemObjectReferenceError, listExtensionChannelIds, listServiceAppManifestActions, matchesCapabilityGrantFilter, matchesObservationPredicate, mergeServiceAppRuntimeActions, normalizeAgentRuntimeSessionTypeIcon, normalizeCapabilityGrantRequest, normalizeLlmUsageModel, normalizeOptionalString, parseObservationDuration, parseServiceAppManifest, parseSkillFrontmatter, readContextCompactionCheckpoint, readContextWindowEventSessionId, readJsonPointer, readLatestContextCompactionCheckpoint, readLearningLoopRuntimeConfig, readMetadataModel, readMetadataThinking, readServiceActionTargetId, readServiceAppManifest, resolveAgentRuntimeEntries, resolveAutomaticUpdateCheckIntervalMs, resolveChannelReplyRoute, resolveEffectiveModel, resolveLegacyEventType, resolveSessionChannelContext, runGatewayInboundLoop, runNextclawTask, sanitizeLlmUsage, serializeContextTail, serializeUnsignedUpdateManifest, shouldRefreshContextWindowDuringStream, shouldRefreshContextWindowImmediately, startPromptOverNcpExecution, stripSkillFrontmatter, syncSessionThinkingPreference, toBoundedJson, toNcpMessages, waitForAgentRuntimeSessionReply };
 
 //# sourceMappingURL=index.js.map