@nextclaw/service 0.1.1

package/dist/shared/services/marketplace/service-marketplace-installer.service.d.ts

@@ -0,0 +1,31 @@
+import { MarketplaceInstaller } from "@nextclaw/server";
+
+//#region src/shared/services/marketplace/service-marketplace-installer.service.d.ts
+type UserFacingResult = {
+  message: string;
+  output?: string;
+};
+type BuiltinSkillInstallResult = UserFacingResult | null;
+declare class ServiceMarketplaceInstaller {
+  private readonly deps;
+  constructor(deps: {
+    applyLiveConfigReload?: () => Promise<void>;
+    runCliSubcommand: (args: string[]) => Promise<string>;
+    installBuiltinSkill: (slug: string, force?: boolean) => BuiltinSkillInstallResult;
+  });
+  createInstaller(): MarketplaceInstaller;
+  private installPlugin;
+  private installSkill;
+  private installMcp;
+  private enablePlugin;
+  private disablePlugin;
+  private uninstallPlugin;
+  private uninstallSkill;
+  private enableMcp;
+  private disableMcp;
+  private removeMcp;
+  private doctorMcp;
+  private createMcpMarketplaceOps;
+}
+//#endregion
+export { ServiceMarketplaceInstaller };

package/dist/shared/services/marketplace/service-marketplace-installer.service.js

@@ -0,0 +1,99 @@
+import { buildMarketplaceSkillInstallArgs, pickUserFacingCommandSummary } from "../../utils/marketplace/service-marketplace-helpers.utils.js";
+import { disablePluginMutation, enablePluginMutation, installPluginMutation, uninstallPluginMutation } from "../../../commands/plugin/plugin-mutation-actions.js";
+import { ServiceMcpMarketplaceOps } from "./service-mcp-marketplace-ops.js";
+import { join } from "node:path";
+import { getWorkspacePath, loadConfig } from "@nextclaw/core";
+import { existsSync, rmSync } from "node:fs";
+//#region src/shared/services/marketplace/service-marketplace-installer.service.ts
+var ServiceMarketplaceInstaller = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	createInstaller() {
+		return {
+			installPlugin: (spec) => this.installPlugin(spec),
+			installSkill: (params) => this.installSkill(params),
+			installMcp: (params) => this.installMcp(params),
+			enablePlugin: (id) => this.enablePlugin(id),
+			disablePlugin: (id) => this.disablePlugin(id),
+			uninstallPlugin: (id) => this.uninstallPlugin(id),
+			uninstallSkill: (slug) => this.uninstallSkill(slug),
+			enableMcp: (name) => this.enableMcp(name),
+			disableMcp: (name) => this.disableMcp(name),
+			removeMcp: (name) => this.removeMcp(name),
+			doctorMcp: (name) => this.doctorMcp(name)
+		};
+	}
+	async installPlugin(spec) {
+		const result = await installPluginMutation(spec);
+		await this.deps.applyLiveConfigReload?.();
+		return { message: result.message };
+	}
+	async installSkill(params) {
+		if (params.kind === "builtin") {
+			const result = this.deps.installBuiltinSkill(params.slug, params.force);
+			if (!result) throw new Error(`Builtin skill not found: ${params.slug}`);
+			return result;
+		}
+		if (params.kind && params.kind !== "marketplace") throw new Error(`Unsupported marketplace skill kind: ${params.kind}`);
+		const workspace = getWorkspacePath(loadConfig().agents.defaults.workspace);
+		const args = buildMarketplaceSkillInstallArgs({
+			slug: params.slug,
+			workspace,
+			force: params.force
+		});
+		try {
+			return { message: pickUserFacingCommandSummary(await this.deps.runCliSubcommand(args), `Installed skill: ${params.slug}`) };
+		} catch (error) {
+			const fallback = this.deps.installBuiltinSkill(params.slug, params.force);
+			if (!fallback) throw error;
+			return fallback;
+		}
+	}
+	async installMcp(params) {
+		return await this.createMcpMarketplaceOps().install(params);
+	}
+	async enablePlugin(id) {
+		const result = await enablePluginMutation(id);
+		await this.deps.applyLiveConfigReload?.();
+		return { message: result.message };
+	}
+	async disablePlugin(id) {
+		const result = await disablePluginMutation(id);
+		await this.deps.applyLiveConfigReload?.();
+		return { message: result.message };
+	}
+	async uninstallPlugin(id) {
+		await disablePluginMutation(id);
+		await this.deps.applyLiveConfigReload?.();
+		const result = await uninstallPluginMutation(id, { force: true });
+		await this.deps.applyLiveConfigReload?.();
+		return { message: result.message };
+	}
+	async uninstallSkill(slug) {
+		const targetDir = join(getWorkspacePath(loadConfig().agents.defaults.workspace), "skills", slug);
+		if (!existsSync(targetDir)) throw new Error(`Skill not installed in workspace: ${slug}`);
+		rmSync(targetDir, {
+			recursive: true,
+			force: true
+		});
+		return { message: `Uninstalled skill: ${slug}` };
+	}
+	async enableMcp(name) {
+		return await this.createMcpMarketplaceOps().enable(name);
+	}
+	async disableMcp(name) {
+		return await this.createMcpMarketplaceOps().disable(name);
+	}
+	async removeMcp(name) {
+		return await this.createMcpMarketplaceOps().remove(name);
+	}
+	async doctorMcp(name) {
+		return await this.createMcpMarketplaceOps().doctor(name);
+	}
+	createMcpMarketplaceOps() {
+		return new ServiceMcpMarketplaceOps({ applyLiveConfigReload: this.deps.applyLiveConfigReload });
+	}
+};
+//#endregion
+export { ServiceMarketplaceInstaller };

package/dist/shared/services/marketplace/service-mcp-marketplace-ops.d.ts

@@ -0,0 +1,39 @@
+import * as _$_nextclaw_mcp0 from "@nextclaw/mcp";
+
+//#region src/shared/services/marketplace/service-mcp-marketplace-ops.d.ts
+declare class ServiceMcpMarketplaceOps {
+  private readonly options;
+  constructor(options: {
+    applyLiveConfigReload?: () => Promise<void>;
+  });
+  install(params: {
+    spec: string;
+    name?: string;
+    enabled?: boolean;
+    allAgents?: boolean;
+    agents?: string[];
+    inputs?: Record<string, string>;
+    template?: unknown;
+  }): Promise<{
+    name: string;
+    message: string;
+    output?: string;
+  }>;
+  enable(name: string): Promise<{
+    message: string;
+    output?: string;
+  }>;
+  disable(name: string): Promise<{
+    message: string;
+    output?: string;
+  }>;
+  remove(name: string): Promise<{
+    message: string;
+    output?: string;
+  }>;
+  doctor(name: string): Promise<_$_nextclaw_mcp0.McpDoctorReport>;
+  private createMutationService;
+  private createDoctorFacade;
+}
+//#endregion
+export { ServiceMcpMarketplaceOps };

package/dist/shared/services/marketplace/service-mcp-marketplace-ops.js

@@ -0,0 +1,67 @@
+import { loadConfig, saveConfig } from "@nextclaw/core";
+import { McpDoctorFacade, McpMutationService } from "@nextclaw/mcp";
+//#region src/shared/services/marketplace/service-mcp-marketplace-ops.ts
+var ServiceMcpMarketplaceOps = class {
+	constructor(options) {
+		this.options = options;
+	}
+	async install(params) {
+		if (!params.template) throw new Error(`Missing MCP marketplace template for ${params.spec}`);
+		const template = params.template;
+		const result = this.createMutationService().installFromTemplate({
+			template,
+			name: params.name,
+			enabled: params.enabled,
+			scope: {
+				allAgents: params.allAgents ?? true,
+				agents: params.allAgents === false ? params.agents ?? [] : []
+			},
+			inputs: params.inputs,
+			metadata: {
+				source: "marketplace",
+				catalogSlug: params.spec,
+				displayName: template.defaultName
+			}
+		});
+		if (!result.changed) throw new Error(result.message);
+		await this.options.applyLiveConfigReload?.();
+		return {
+			name: result.name,
+			message: result.message
+		};
+	}
+	async enable(name) {
+		const result = this.createMutationService().toggleEnabled(name, true);
+		if (!result.changed) throw new Error(result.message);
+		await this.options.applyLiveConfigReload?.();
+		return { message: result.message };
+	}
+	async disable(name) {
+		const result = this.createMutationService().toggleEnabled(name, false);
+		if (!result.changed) throw new Error(result.message);
+		await this.options.applyLiveConfigReload?.();
+		return { message: result.message };
+	}
+	async remove(name) {
+		const result = this.createMutationService().removeServer(name);
+		if (!result.changed) throw new Error(result.message);
+		await this.options.applyLiveConfigReload?.();
+		return { message: result.message };
+	}
+	async doctor(name) {
+		const report = await this.createDoctorFacade().inspectOne(name);
+		if (!report) throw new Error(`Unknown MCP server: ${name}`);
+		return report;
+	}
+	createMutationService() {
+		return new McpMutationService({
+			getConfig: () => loadConfig(),
+			saveConfig: (config) => saveConfig(config)
+		});
+	}
+	createDoctorFacade() {
+		return new McpDoctorFacade({ getConfig: () => loadConfig() });
+	}
+};
+//#endregion
+export { ServiceMcpMarketplaceOps };

package/dist/shared/services/plugin/utils/plugin-dev-hot-reload.utils.d.ts

@@ -0,0 +1,24 @@
+import { ServiceFileWatcherRegistry } from "../../gateway/service-startup-support.service.js";
+
+//#region src/shared/services/plugin/utils/plugin-dev-hot-reload.utils.d.ts
+declare const DEV_PLUGIN_HOT_RELOAD_TARGETS_ENV = "NEXTCLAW_DEV_PLUGIN_HOT_RELOAD_TARGETS";
+type DevPluginHotReloadTarget = {
+  pluginId: string;
+  pluginPath: string;
+  watchPaths: string[];
+};
+declare function resolveDevPluginHotReloadTargets(rawValue?: string | undefined): DevPluginHotReloadTarget[];
+declare function startDevPluginHotReloadWatcher(params: {
+  watcherRegistry: ServiceFileWatcherRegistry;
+  reloadPlugins: (pluginIds: string[]) => Promise<void>;
+  targets?: DevPluginHotReloadTarget[];
+}): void;
+declare function wrapStartChannelsWithDevPluginHotReload(params: {
+  startChannels: () => Promise<void>;
+  watcherRegistry: ServiceFileWatcherRegistry;
+  isRuntimeActive: () => boolean;
+  reloadPlugins: (pluginIds: string[]) => Promise<void>;
+  startupSettleMs: number;
+}): () => Promise<void>;
+//#endregion
+export { DEV_PLUGIN_HOT_RELOAD_TARGETS_ENV, DevPluginHotReloadTarget, resolveDevPluginHotReloadTargets, startDevPluginHotReloadWatcher, wrapStartChannelsWithDevPluginHotReload };

package/dist/shared/services/plugin/utils/plugin-dev-hot-reload.utils.js

@@ -0,0 +1,117 @@
+import { resolve, sep } from "node:path";
+import chokidar from "chokidar";
+//#region src/shared/services/plugin/utils/plugin-dev-hot-reload.utils.ts
+const DEV_PLUGIN_HOT_RELOAD_TARGETS_ENV = "NEXTCLAW_DEV_PLUGIN_HOT_RELOAD_TARGETS";
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readOptionalString(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
+function normalizeWatchPaths(value) {
+	if (!Array.isArray(value)) return [];
+	const watchPaths = [];
+	for (const entry of value) {
+		const normalized = readOptionalString(entry);
+		if (!normalized) continue;
+		const resolvedPath = resolve(normalized);
+		if (!watchPaths.includes(resolvedPath)) watchPaths.push(resolvedPath);
+	}
+	return watchPaths;
+}
+function resolveDevPluginHotReloadTargets(rawValue = process.env[DEV_PLUGIN_HOT_RELOAD_TARGETS_ENV]) {
+	if (typeof rawValue !== "string" || rawValue.trim().length === 0) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(rawValue);
+	} catch (error) {
+		throw new Error(`[dev-plugin-hot-reload] failed to parse ${DEV_PLUGIN_HOT_RELOAD_TARGETS_ENV}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!Array.isArray(parsed)) throw new Error(`[dev-plugin-hot-reload] ${DEV_PLUGIN_HOT_RELOAD_TARGETS_ENV} must be a JSON array`);
+	const seenPluginIds = /* @__PURE__ */ new Set();
+	const targets = [];
+	for (const entry of parsed) {
+		if (!isRecord(entry)) continue;
+		const pluginId = readOptionalString(entry.pluginId);
+		const pluginPath = readOptionalString(entry.pluginPath);
+		const watchPaths = normalizeWatchPaths(entry.watchPaths);
+		if (!pluginId || !pluginPath || watchPaths.length === 0) continue;
+		if (seenPluginIds.has(pluginId)) throw new Error(`[dev-plugin-hot-reload] duplicate plugin target for "${pluginId}"`);
+		seenPluginIds.add(pluginId);
+		targets.push({
+			pluginId,
+			pluginPath: resolve(pluginPath),
+			watchPaths
+		});
+	}
+	return targets;
+}
+function startDevPluginHotReloadWatcher(params) {
+	const targets = params.targets ?? resolveDevPluginHotReloadTargets();
+	if (targets.length === 0) return;
+	const pendingPluginIds = /* @__PURE__ */ new Set();
+	let flushTimer = null;
+	let reloadRunning = false;
+	let reloadPending = false;
+	const flushReload = async () => {
+		if (reloadRunning) {
+			reloadPending = true;
+			return;
+		}
+		const pluginIds = [...pendingPluginIds];
+		pendingPluginIds.clear();
+		if (pluginIds.length === 0) return;
+		reloadRunning = true;
+		try {
+			console.log(`[dev] Plugin dist updated: ${pluginIds.join(", ")}`);
+			await params.reloadPlugins(pluginIds);
+			console.log(`[dev] Plugin hot reload applied: ${pluginIds.join(", ")}`);
+		} catch (error) {
+			console.error(`[dev] Plugin hot reload failed: ${error instanceof Error ? error.message : String(error)}`);
+		} finally {
+			reloadRunning = false;
+			if (reloadPending || pendingPluginIds.size > 0) {
+				reloadPending = false;
+				await flushReload();
+			}
+		}
+	};
+	const scheduleReload = (pluginId) => {
+		pendingPluginIds.add(pluginId);
+		if (flushTimer) clearTimeout(flushTimer);
+		flushTimer = setTimeout(() => {
+			flushTimer = null;
+			flushReload();
+		}, 150);
+	};
+	const watcher = chokidar.watch(targets.flatMap((entry) => entry.watchPaths), {
+		ignoreInitial: true,
+		awaitWriteFinish: {
+			stabilityThreshold: 200,
+			pollInterval: 50
+		}
+	});
+	params.watcherRegistry.remember(watcher);
+	watcher.on("all", (_event, changedPath) => {
+		const normalizedChangedPath = resolve(changedPath);
+		for (const target of targets) if (target.watchPaths.some((watchPath) => normalizedChangedPath === watchPath || normalizedChangedPath.startsWith(`${watchPath}${sep}`))) scheduleReload(target.pluginId);
+	});
+	console.log(`[dev] Plugin hot reload watcher: ${targets.map((entry) => entry.pluginId).join(", ")}`);
+}
+function wrapStartChannelsWithDevPluginHotReload(params) {
+	return async () => {
+		await params.startChannels();
+		console.log(`[dev] Plugin hot reload watcher will arm after ${params.startupSettleMs}ms startup settle window.`);
+		setTimeout(() => {
+			if (!params.isRuntimeActive()) return;
+			startDevPluginHotReloadWatcher({
+				watcherRegistry: params.watcherRegistry,
+				reloadPlugins: params.reloadPlugins
+			});
+		}, params.startupSettleMs).unref?.();
+	};
+}
+//#endregion
+export { DEV_PLUGIN_HOT_RELOAD_TARGETS_ENV, resolveDevPluginHotReloadTargets, startDevPluginHotReloadWatcher, wrapStartChannelsWithDevPluginHotReload };

package/dist/shared/services/plugin/utils/plugin-runtime-bridge.utils.d.ts

@@ -0,0 +1,6 @@
+import { NextclawGatewayRuntime } from "../../gateway/nextclaw-gateway-runtime.service.js";
+
+//#region src/shared/services/plugin/utils/plugin-runtime-bridge.utils.d.ts
+declare function installPluginRuntimeBridge(gateway: NextclawGatewayRuntime): void;
+//#endregion
+export { installPluginRuntimeBridge };

package/dist/shared/services/plugin/utils/plugin-runtime-bridge.utils.js

@@ -0,0 +1,96 @@
+import { loadConfig, saveConfig } from "@nextclaw/core";
+import { setPluginRuntimeBridge } from "@nextclaw/openclaw-compat";
+import { dispatchPromptOverNcp } from "@nextclaw/kernel";
+//#region src/shared/services/plugin/utils/plugin-runtime-bridge.utils.ts
+function installPluginRuntimeBridge(gateway) {
+	setPluginRuntimeBridge({
+		loadConfig: () => gateway.kernel.extensions.toConfigView(gateway.configManager.loadConfig()),
+		writeConfigFile: async (nextConfigView) => {
+			if (!nextConfigView || typeof nextConfigView !== "object" || Array.isArray(nextConfigView)) throw new Error("plugin runtime writeConfigFile expects an object config");
+			const current = loadConfig();
+			saveConfig(gateway.kernel.extensions.mergeConfigView(current, nextConfigView));
+		},
+		dispatchReplyWithBufferedBlockDispatcher: async ({ ctx, dispatcherOptions }) => {
+			const request = resolvePluginRuntimeRequest(ctx);
+			if (!request) return;
+			try {
+				await dispatcherOptions.onReplyStart?.();
+				const response = await dispatchPromptOverNcp({
+					config: gateway.configManager.loadConfig(),
+					sessionManager: gateway.sessionManager,
+					resolveNcpAgent: () => gateway.liveAgentRuntime,
+					...request
+				});
+				const replyText = typeof response === "string" ? response : String(response ?? "");
+				if (replyText.trim()) await dispatcherOptions.deliver({ text: replyText }, { kind: "final" });
+			} catch (error) {
+				dispatcherOptions.onError?.(error);
+				throw error;
+			}
+		}
+	});
+}
+function resolvePluginRuntimeRequest(ctx) {
+	const bodyForAgent = typeof ctx.BodyForAgent === "string" ? ctx.BodyForAgent : "";
+	const body = typeof ctx.Body === "string" ? ctx.Body : "";
+	const content = (bodyForAgent || body).trim();
+	const attachments = resolvePluginRuntimeAttachments(ctx);
+	if (!content && attachments.length === 0) return null;
+	const sessionKey = typeof ctx.SessionKey === "string" && ctx.SessionKey.trim().length > 0 ? ctx.SessionKey : void 0;
+	const channel = typeof ctx.OriginatingChannel === "string" && ctx.OriginatingChannel.trim().length > 0 ? ctx.OriginatingChannel : "cli";
+	const chatId = typeof ctx.OriginatingTo === "string" && ctx.OriginatingTo.trim().length > 0 ? ctx.OriginatingTo : typeof ctx.SenderId === "string" && ctx.SenderId.trim().length > 0 ? ctx.SenderId : "direct";
+	const agentId = typeof ctx.AgentId === "string" ? ctx.AgentId : void 0;
+	const modelOverride = resolveModelOverride(ctx);
+	const accountId = typeof ctx.AccountId === "string" && ctx.AccountId.trim().length > 0 ? ctx.AccountId : void 0;
+	return {
+		content,
+		sessionKey,
+		channel,
+		chatId,
+		agentId,
+		attachments,
+		metadata: {
+			...accountId ? { account_id: accountId } : {},
+			...modelOverride ? { model: modelOverride } : {}
+		}
+	};
+}
+function resolveModelOverride(ctx) {
+	if (typeof ctx.Model === "string" && ctx.Model.trim().length > 0) return ctx.Model.trim();
+	if (typeof ctx.AgentModel === "string" && ctx.AgentModel.trim().length > 0) return ctx.AgentModel.trim();
+}
+function readStringList(value) {
+	if (!Array.isArray(value)) return [];
+	return value.map((entry) => typeof entry === "string" ? entry.trim() : "").filter(Boolean);
+}
+function readOptionalString(value) {
+	if (typeof value !== "string") return;
+	return value.trim() || void 0;
+}
+function resolvePluginRuntimeAttachments(ctx) {
+	const mediaPaths = readStringList(ctx.MediaPaths);
+	const mediaUrls = readStringList(ctx.MediaUrls);
+	const fallbackPath = readOptionalString(ctx.MediaPath);
+	const fallbackUrl = readOptionalString(ctx.MediaUrl);
+	const mediaTypes = readStringList(ctx.MediaTypes);
+	const fallbackType = readOptionalString(ctx.MediaType);
+	const entryCount = Math.max(mediaPaths.length, mediaUrls.length, fallbackPath ? 1 : 0, fallbackUrl ? 1 : 0);
+	const attachments = [];
+	for (let index = 0; index < entryCount; index += 1) {
+		const path = mediaPaths[index] ?? (index === 0 ? fallbackPath : void 0);
+		const rawUrl = mediaUrls[index] ?? (index === 0 ? fallbackUrl : void 0);
+		const url = rawUrl && rawUrl !== path ? rawUrl : void 0;
+		const mimeType = mediaTypes[index] ?? fallbackType;
+		if (!path && !url) continue;
+		attachments.push({
+			path,
+			url,
+			mimeType,
+			source: "plugin-runtime",
+			status: path ? "ready" : "remote-only"
+		});
+	}
+	return attachments;
+}
+//#endregion
+export { installPluginRuntimeBridge };

package/dist/shared/services/restart/restart-coordinator.service.d.ts

@@ -0,0 +1,30 @@
+import { ManagedServiceState } from "../../stores/managed-service-state.store.js";
+
+//#region src/shared/services/restart/restart-coordinator.service.d.ts
+type RestartStrategy = "background-service-or-manual" | "background-service-or-exit" | "exit-process";
+type RestartRequest = {
+  reason: string;
+  strategy?: RestartStrategy;
+  delayMs?: number;
+  manualMessage?: string;
+};
+type RestartResult = {
+  status: "service-restarted" | "restart-in-progress" | "exit-scheduled" | "manual-required";
+  message: string;
+};
+type RestartCoordinatorDeps = {
+  readServiceState: () => ManagedServiceState | null;
+  isProcessRunning: (pid: number) => boolean;
+  currentPid: () => number;
+  restartBackgroundService: (reason: string) => Promise<boolean>;
+  scheduleProcessExit: (delayMs: number, reason: string) => void;
+};
+declare class RestartCoordinator {
+  private deps;
+  private restartingService;
+  private exitScheduled;
+  constructor(deps: RestartCoordinatorDeps);
+  readonly requestRestart: (request: RestartRequest) => Promise<RestartResult>;
+}
+//#endregion
+export { RestartCoordinator, RestartRequest, RestartResult, RestartStrategy };

package/dist/shared/services/restart/restart-coordinator.service.js

@@ -0,0 +1,51 @@
+//#region src/shared/services/restart/restart-coordinator.service.ts
+var RestartCoordinator = class {
+	restartingService = false;
+	exitScheduled = false;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	requestRestart = async (request) => {
+		const reason = request.reason.trim() || "config changed";
+		const strategy = request.strategy ?? "background-service-or-manual";
+		if (strategy !== "exit-process") {
+			const state = this.deps.readServiceState();
+			const serviceRunning = Boolean(state && this.deps.isProcessRunning(state.pid));
+			const managedByCurrentProcess = Boolean(state && state.pid === this.deps.currentPid());
+			if (serviceRunning && !managedByCurrentProcess) {
+				if (this.restartingService) return {
+					status: "restart-in-progress",
+					message: "Restart already in progress; skipping duplicate request."
+				};
+				this.restartingService = true;
+				try {
+					if (await this.deps.restartBackgroundService(reason)) return {
+						status: "service-restarted",
+						message: `Restarted background service to apply changes (${reason}).`
+					};
+				} finally {
+					this.restartingService = false;
+				}
+			}
+		}
+		if (strategy === "background-service-or-exit" || strategy === "exit-process") {
+			if (this.exitScheduled) return {
+				status: "exit-scheduled",
+				message: "Restart already scheduled; skipping duplicate request."
+			};
+			const delay = typeof request.delayMs === "number" && Number.isFinite(request.delayMs) ? Math.max(0, Math.floor(request.delayMs)) : 100;
+			this.exitScheduled = true;
+			this.deps.scheduleProcessExit(delay, reason);
+			return {
+				status: "exit-scheduled",
+				message: `Restart scheduled (${reason}).`
+			};
+		}
+		return {
+			status: "manual-required",
+			message: request.manualMessage ?? "Restart the gateway to apply changes."
+		};
+	};
+};
+//#endregion
+export { RestartCoordinator };

package/dist/shared/services/restart/restart-sentinel.service.d.ts

@@ -0,0 +1,39 @@
+import { SessionManager } from "@nextclaw/core";
+
+//#region src/shared/services/restart/restart-sentinel.service.d.ts
+type RestartSentinelDeliveryContext = {
+  channel?: string;
+  chatId?: string;
+  replyTo?: string | null;
+  accountId?: string | null;
+  metadata?: Record<string, unknown>;
+};
+type RestartSentinelPayload = {
+  kind: "config.apply" | "config.patch" | "update.run" | "restart";
+  status: "ok" | "error" | "skipped";
+  ts: number;
+  sessionKey?: string;
+  deliveryContext?: RestartSentinelDeliveryContext;
+  message?: string | null;
+  stats?: {
+    reason?: string | null;
+    strategy?: string | null;
+    durationMs?: number | null;
+  };
+};
+type RestartSentinelFile = {
+  version: 1;
+  payload: RestartSentinelPayload;
+};
+declare function resolveRestartSentinelPath(): string;
+declare function writeRestartSentinel(payload: RestartSentinelPayload): Promise<string>;
+declare function consumeRestartSentinel(): Promise<RestartSentinelFile | null>;
+declare function summarizeRestartSentinel(payload: RestartSentinelPayload): string;
+declare function formatRestartSentinelMessage(payload: RestartSentinelPayload): string;
+declare function parseSessionKey(sessionKey?: string): {
+  channel: string;
+  chatId: string;
+} | null;
+declare function enqueuePendingSystemEvent(sessionManager: SessionManager, sessionKey: string, message: string): void;
+//#endregion
+export { RestartSentinelDeliveryContext, RestartSentinelPayload, consumeRestartSentinel, enqueuePendingSystemEvent, formatRestartSentinelMessage, parseSessionKey, resolveRestartSentinelPath, summarizeRestartSentinel, writeRestartSentinel };