nextclaw 0.18.12-beta.1 → 0.18.12-beta.3

package/dist/cli/app/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { _ as waitForExit, a as findExecutableOnPath, c as isProcessRunning, d as prompt, f as resolvePublicIp, g as resolveUiStaticDir, h as resolveUiConfig, i as NpmRuntimeBundleLayoutStore, l as openBrowser, m as resolveUiApiBase, n as NpmRuntimeBundleService, o as getPackageVersion$1, p as resolveServiceLogPath, r as compareNpmRuntimeVersions, s as isLoopbackHost, t as NpmRuntimeUpdateStateStore, u as printAgentResponse } from "../../npm-runtime-update-state.store-DaF0iDY9.js";
+import { _ as waitForExit, a as findExecutableOnPath, c as isProcessRunning, d as prompt, f as resolvePublicIp, g as resolveUiStaticDir, h as resolveUiConfig, i as NpmRuntimeBundleLayoutStore, l as openBrowser, m as resolveUiApiBase, n as NpmRuntimeBundleService, o as getPackageVersion$1, p as resolveServiceLogPath, r as compareNpmRuntimeVersions, s as isLoopbackHost, t as NpmRuntimeUpdateStateStore, u as printAgentResponse } from "../../npm-runtime-update-state.store-CQ8tFzah.js";
 import { createRequire } from "node:module";
 import * as NextclawCore from "@nextclaw/core";
 import { APP_NAME, APP_TAGLINE, AgentRouteResolver, BUILTIN_MAIN_AGENT_ID, ChannelManager, CommandRegistry, ConfigSchema, ContextBuilder, CronService, CronTool, DEFAULT_WORKSPACE_DIR, DEFAULT_WORKSPACE_PATH, DisposableStore, EditFileTool, ExecTool, ExtensionToolAdapter, FileLogSink, GatewayTool, InputBudgetPruner, LLMProvider, ListDirTool, MemoryGetTool, MemorySearchTool, MessageBus, MessageTool, ProviderManager, ReadFileTool, RequestedSkillsMetadataReader, SessionManager, SessionsHistoryTool, SessionsListTool, SkillsLoader, Tool, ToolRegistry, WebFetchTool, WebSearchTool, WriteFileTool, buildConfigSchema, buildMinimalSystemExecutionPrompt, buildReloadPlan, buildToolCatalogEntries, createAgentProfile, createAssistantStreamDeltaControlMessage, createAssistantStreamResetControlMessage, createGlobalTypedEventBus, createTypedEventKey, createTypingStopControlMessage, diffConfigPaths, expandHome, findEffectiveAgentProfile, getAppLogger, getConfigPath, getDataDir, getDataPath, getLoggingRuntime, getWorkspacePath, hasSecretRef, loadConfig, normalizeInlineSecretRefs, parseAgentScopedSessionKey, parseThinkingLevel, readSessionProjectRoot, redactConfigObject, removeAgentProfile, resolveAppLogPath, resolveConfigSecrets, resolveDefaultAgentProfileId, resolveEffectiveAgentProfiles, resolveLocalUiBaseUrl, resolveProviderRuntime, resolveSessionWorkspacePath, resolveThinkingLevel, saveConfig, toDisposable, updateAgentProfile } from "@nextclaw/core";
@@ -5062,30 +5062,6 @@ function parseSessionKey(sessionKey) {
 	};
 }
 //#endregion
-//#region src/cli/shared/utils/runtime-helpers.ts
-function resolveSkillsInstallWorkdir(params) {
-	if (params.explicitWorkdir) return expandHome(params.explicitWorkdir);
-	return getWorkspacePath(params.configuredWorkspace);
-}
-function parseStartTimeoutMs(value) {
-	if (value === void 0) return;
-	const parsed = Number(value);
-	if (!Number.isFinite(parsed) || parsed <= 0) {
-		console.error("Invalid --start-timeout value. Provide milliseconds (e.g. 45000).");
-		process.exit(1);
-	}
-	return Math.floor(parsed);
-}
-function resolveManagedServiceUiOverrides(params) {
-	const uiOverrides = {
-		enabled: true,
-		host: params.forcedPublicHost,
-		open: false
-	};
-	if (params.uiPort) uiOverrides.port = Number(params.uiPort);
-	return uiOverrides;
-}
-//#endregion
 //#region src/cli/shared/utils/startup-trace.ts
 const STARTUP_TRACE_ENABLED = process.env.NEXTCLAW_STARTUP_TRACE === "1";
 const STARTUP_TRACE_ORIGIN_MS = Date.now();
@@ -14004,7 +13980,7 @@ var ServiceMarketplaceInstaller = class {
 };
 //#endregion
 //#region src/cli/shared/utils/marketplace/cli-subcommand-launch.utils.ts
-const require$2 = createRequire(import.meta.url);
+const require$3 = createRequire(import.meta.url);
 const TYPESCRIPT_EXTENSIONS$1 = new Set([
 	".ts",
 	".tsx",
@@ -14012,7 +13988,7 @@ const TYPESCRIPT_EXTENSIONS$1 = new Set([
 	".cts"
 ]);
 const isTypeScriptEntry = (entry) => TYPESCRIPT_EXTENSIONS$1.has(extname(entry).toLowerCase());
-const resolveTsxCliEntry = () => require$2.resolve("tsx/cli");
+const resolveTsxCliEntry = () => require$3.resolve("tsx/cli");
 const resolveCliAppEntryFromImportMeta$1 = (importMetaUrl) => {
 	const modulePath = fileURLToPath(importMetaUrl);
 	const cliRootIndex = modulePath.replace(/\\/g, "/").lastIndexOf("/cli/");
@@ -15199,6 +15175,169 @@ function createRemoteAccessHost(params) {
 	});
 }
 //#endregion
+//#region src/cli/shared/services/ui/npm-runtime-update-host.service.ts
+const INITIAL_DOWNLOAD_PROGRESS = {
+	downloadedBytes: 0,
+	totalBytes: null,
+	percent: null
+};
+var NpmRuntimeUpdateHost = class {
+	source = new NpmRuntimeUpdateSourceService();
+	layout = new NpmRuntimeBundleLayoutStore();
+	stateStore = new NpmRuntimeUpdateStateStore(this.layout.getStatePath());
+	launcherVersion = getPackageVersion$1();
+	bundleService = new NpmRuntimeBundleService({
+		layout: this.layout,
+		stateStore: this.stateStore,
+		launcherVersion: this.launcherVersion
+	});
+	updateService = new NpmRuntimeUpdateService({
+		layout: this.layout,
+		bundleService: this.bundleService,
+		launcherVersion: this.launcherVersion,
+		bundlePublicKey: this.source.resolveBundlePublicKey() ?? void 0
+	});
+	snapshot;
+	activeTask = null;
+	automaticSyncStarted = false;
+	constructor(deps) {
+		this.deps = deps;
+		this.snapshot = this.createManager().getSnapshot();
+		this.startAutomaticSync();
+	}
+	getState = async () => {
+		this.startAutomaticSync();
+		return this.snapshot;
+	};
+	checkForUpdates = async () => {
+		return this.startCheck({ autoDownload: false });
+	};
+	downloadUpdate = async () => {
+		return this.startDownload();
+	};
+	applyDownloadedUpdate = async () => {
+		if (this.activeTask) return this.snapshot;
+		this.snapshot = {
+			...this.snapshot,
+			status: "applying",
+			progress: null,
+			errorMessage: null
+		};
+		try {
+			this.snapshot = this.createManager().applyDownloadedUpdate();
+			await requestManagedServiceRestart(this.deps.requestRestart, {
+				reason: "runtime update apply",
+				uiPort: this.deps.uiConfig.port
+			});
+			return this.snapshot;
+		} catch (error) {
+			this.snapshot = this.toFailedSnapshot(error);
+			throw error;
+		}
+	};
+	updatePreferences = async (preferences) => {
+		const nextState = this.stateStore.update((current) => ({
+			...current,
+			updatePreferences: {
+				...current.updatePreferences,
+				...preferences
+			}
+		}));
+		this.snapshot = this.createManager(nextState.channel).getSnapshot();
+		if (nextState.updatePreferences.automaticChecks) this.startAutomaticSync({ force: true });
+		return this.snapshot;
+	};
+	updateChannel = async (channel) => {
+		const nextState = this.stateStore.update((current) => ({
+			...current,
+			channel
+		}));
+		this.snapshot = this.createManager(nextState.channel).getSnapshot();
+		if (nextState.updatePreferences.automaticChecks) return this.startCheck({ autoDownload: nextState.updatePreferences.autoDownload });
+		return this.snapshot;
+	};
+	startAutomaticSync = (options = {}) => {
+		if (this.activeTask) return;
+		if (this.automaticSyncStarted && !options.force) return;
+		this.automaticSyncStarted = true;
+		const state = this.stateStore.read();
+		if (!state.updatePreferences.automaticChecks || state.downloadedVersion) return;
+		this.startCheck({ autoDownload: state.updatePreferences.autoDownload });
+	};
+	startCheck = async (options) => {
+		if (this.activeTask) return this.snapshot;
+		this.snapshot = {
+			...this.createManager().getSnapshot(),
+			status: "checking",
+			progress: null,
+			errorMessage: null
+		};
+		this.activeTask = (async () => {
+			try {
+				const checkedSnapshot = await this.createManager().checkForUpdate();
+				this.snapshot = checkedSnapshot;
+				if (options.autoDownload && checkedSnapshot.status === "update-available") await this.runDownloadTask();
+			} catch (error) {
+				this.snapshot = this.toFailedSnapshot(error);
+			} finally {
+				this.activeTask = null;
+			}
+		})();
+		return this.snapshot;
+	};
+	startDownload = async () => {
+		if (this.activeTask) return this.snapshot;
+		this.snapshot = {
+			...this.createManager().getSnapshot(),
+			status: "downloading",
+			progress: INITIAL_DOWNLOAD_PROGRESS,
+			errorMessage: null
+		};
+		this.activeTask = (async () => {
+			try {
+				await this.runDownloadTask();
+			} catch (error) {
+				this.snapshot = this.toFailedSnapshot(error);
+			} finally {
+				this.activeTask = null;
+			}
+		})();
+		return this.snapshot;
+	};
+	runDownloadTask = async () => {
+		this.snapshot = await this.createManager().downloadUpdate((progress) => {
+			this.snapshot = {
+				...this.snapshot,
+				status: "downloading",
+				progress,
+				errorMessage: null
+			};
+		});
+	};
+	createManager = (channel = this.stateStore.read().channel) => {
+		return new NpmRuntimeUpdateManager({
+			layout: this.layout,
+			stateStore: this.stateStore,
+			bundleService: this.bundleService,
+			updateService: this.updateService,
+			resolveManifestUrl: (resolvedChannel) => this.source.resolveManifestUrl(resolvedChannel),
+			launcherVersion: this.launcherVersion,
+			channel
+		});
+	};
+	toFailedSnapshot = (error) => {
+		return {
+			...this.createManager().getSnapshot(),
+			status: "failed",
+			progress: null,
+			errorMessage: error instanceof Error ? error.message : String(error ?? "Unknown error")
+		};
+	};
+};
+function createNpmRuntimeUpdateHost(params) {
+	return new NpmRuntimeUpdateHost(params);
+}
+//#endregion
 //#region src/cli/shared/stores/pending-restart.store.ts
 const clonePendingRestartState = (state) => {
 	if (!state) return null;
@@ -15320,12 +15459,17 @@ function createRuntimeControlHost(params) {
 //#endregion
 //#region src/cli/shared/services/ui/service-ui-hosts.service.ts
 function createServiceUiHosts(params) {
+	const { requestRestart, serviceCommands, uiConfig } = params;
 	return {
 		remoteAccess: createRemoteAccessHost(params),
 		runtimeControl: createRuntimeControlHost({
-			serviceCommands: params.serviceCommands,
-			requestRestart: params.requestRestart,
-			uiConfig: params.uiConfig
+			serviceCommands,
+			requestRestart,
+			uiConfig
+		}),
+		runtimeUpdate: process.env.NEXTCLAW_DISABLE_RUNTIME_UPDATE_HOST === "1" ? void 0 : createNpmRuntimeUpdateHost({
+			requestRestart,
+			uiConfig
 		})
 	};
 }
@@ -15665,6 +15809,9 @@ var ConfigReloader = class {
 	setReloadMcp(callback) {
 		this.options.reloadMcp = callback;
 	}
+	setReloadCompanion(callback) {
+		this.options.reloadCompanion = callback;
+	}
 	async applyReloadPlan(nextConfig) {
 		const changedPaths = diffConfigPaths(this.currentConfig, nextConfig);
 		if (!changedPaths.length) return;
@@ -15686,6 +15833,13 @@ var ConfigReloader = class {
 			});
 			console.log("Config reload: MCP servers reloaded.");
 		}
+		if (plan.reloadCompanion) {
+			await this.reloadCompanion({
+				config: nextConfig,
+				changedPaths
+			});
+			console.log("Config reload: companion setting applied.");
+		}
 		if (plan.restartChannels || reloadPluginsResult?.restartChannels) {
 			await this.reloadChannels(nextConfig, { start: true });
 			console.log("Config reload: channels restarted.");
@@ -15781,6 +15935,10 @@ var ConfigReloader = class {
 		if (!this.options.reloadMcp) return;
 		await this.options.reloadMcp(params);
 	}
+	async reloadCompanion(params) {
+		if (!this.options.reloadCompanion) return;
+		await this.options.reloadCompanion(params);
+	}
 };
 //#endregion
 //#region src/cli/shared/services/gateway/cron-job-handler.service.ts
@@ -16161,7 +16319,7 @@ function createSystemSessionUpdatedPublisher(params) {
 }
 async function startUiShell(params) {
 	logStartupTrace("service.start_ui_shell.begin");
-	const { applyLiveConfigReload, configPath, cronService, getBootstrapStatus, getPluginChannelBindings, getPluginUiMetadata, initializeAgentHomeDirectory, marketplace, ncpSessionService, openBrowserWindow, productVersion, remoteAccess, runtimeControl, uiConfig, uiStaticDir } = params;
+	const { applyLiveConfigReload, configPath, cronService, getBootstrapStatus, getPluginChannelBindings, getPluginUiMetadata, initializeAgentHomeDirectory, marketplace, ncpSessionService, openBrowserWindow, productVersion, remoteAccess, runtimeControl, runtimeUpdate, uiConfig, uiStaticDir } = params;
 	if (!uiConfig.enabled) return null;
 	let publishUiEvent = null;
 	const deferredNcpAgent = createDeferredUiNcpAgent();
@@ -16177,6 +16335,7 @@ async function startUiShell(params) {
 		marketplace,
 		remoteAccess,
 		runtimeControl,
+		runtimeUpdate,
 		getBootstrapStatus,
 		getPluginChannelBindings,
 		getPluginUiMetadata,
@@ -16962,6 +17121,165 @@ async function cleanupGatewayRuntime(params) {
 	setPluginRuntimeBridge(null);
 }
 //#endregion
+//#region src/cli/shared/stores/companion-runtime.store.ts
+var CompanionRuntimeStore = class {
+	get path() {
+		return resolve(getDataDir(), "run", "companion.json");
+	}
+	read = () => {
+		if (!existsSync(this.path)) return null;
+		try {
+			return JSON.parse(readFileSync(this.path, "utf-8"));
+		} catch {
+			return null;
+		}
+	};
+	write = (state) => {
+		mkdirSync(resolve(this.path, ".."), { recursive: true });
+		writeFileSync(this.path, JSON.stringify(state, null, 2));
+	};
+	clear = () => {
+		if (existsSync(this.path)) rmSync(this.path, { force: true });
+	};
+};
+const companionRuntimeStore = new CompanionRuntimeStore();
+//#endregion
+//#region src/cli/shared/services/ui/companion-runtime.service.ts
+const require$2 = createRequire(import.meta.url);
+var CompanionRuntimeService = class {
+	constructor(runtimeStore = companionRuntimeStore, uiDiscoveryService = localUiDiscoveryService) {
+		this.runtimeStore = runtimeStore;
+		this.uiDiscoveryService = uiDiscoveryService;
+	}
+	getRunningState = () => {
+		const state = this.runtimeStore.read();
+		if (!state) return null;
+		if (!isProcessRunning(state.pid)) {
+			this.runtimeStore.clear();
+			return null;
+		}
+		return state;
+	};
+	resolveDiscoveredBaseUrl = () => {
+		return this.uiDiscoveryService.resolveApiBase();
+	};
+	applyConfig = async (config) => {
+		if (!config.companion.enabled) {
+			await this.ensureStopped();
+			return;
+		}
+		await this.ensureStarted({ baseUrl: this.uiDiscoveryService.resolveLocalOrigin(config) });
+	};
+	updateEnabled = async (enabled, options = {}) => {
+		const config = loadConfig(getConfigPath());
+		const next = {
+			...config,
+			companion: {
+				...config.companion,
+				enabled
+			}
+		};
+		saveConfig(next, getConfigPath());
+		if (enabled) {
+			const explicitBaseUrl = options.baseUrl?.trim();
+			if (explicitBaseUrl) {
+				await this.ensureStarted({ baseUrl: explicitBaseUrl });
+				return next;
+			}
+			const discoveredBaseUrl = this.uiDiscoveryService.resolveApiBase();
+			if (discoveredBaseUrl) await this.ensureStarted({ baseUrl: discoveredBaseUrl });
+			return next;
+		}
+		await this.ensureStopped();
+		return next;
+	};
+	ensureStarted = async (options) => {
+		const baseUrl = options.baseUrl.trim().replace(/\/+$/, "");
+		const runningState = this.getRunningState();
+		if (runningState?.baseUrl === baseUrl) return runningState;
+		if (runningState) {
+			this.killProcess(runningState.pid, false);
+			this.runtimeStore.clear();
+		}
+		const launchSpec = this.resolveLaunchSpec();
+		const child = spawn(launchSpec.command, [
+			...launchSpec.args,
+			"--base-url",
+			baseUrl
+		], {
+			detached: true,
+			stdio: "ignore",
+			env: {
+				...process.env,
+				NEXTCLAW_COMPANION_RUNTIME_STATE_PATH: this.runtimeStore.path
+			}
+		});
+		child.unref();
+		return await this.waitForRunningState(baseUrl, child.pid ?? -1);
+	};
+	ensureStopped = async (options = {}) => {
+		const state = this.runtimeStore.read();
+		if (!state) return false;
+		if (!isProcessRunning(state.pid)) {
+			this.runtimeStore.clear();
+			return false;
+		}
+		this.killProcess(state.pid, options.force === true);
+		this.runtimeStore.clear();
+		return true;
+	};
+	printStatus = (options = {}) => {
+		const runningState = this.getRunningState();
+		const config = loadConfig(getConfigPath());
+		const view = runningState ? {
+			configuredEnabled: config.companion.enabled,
+			running: true,
+			...runningState
+		} : {
+			configuredEnabled: config.companion.enabled,
+			running: false
+		};
+		if (options.json) {
+			console.log(JSON.stringify(view, null, 2));
+			return;
+		}
+		if (!runningState) {
+			console.log(config.companion.enabled ? "Companion is enabled in config but is not running." : "Companion is disabled and not running.");
+			return;
+		}
+		console.log(`Companion is running (pid ${runningState.pid}) at ${runningState.baseUrl}. Configured enabled: ${config.companion.enabled ? "yes" : "no"}.`);
+	};
+	printStarted = (state) => {
+		console.log(`Started ${APP_NAME} companion (pid ${state.pid}) using ${state.baseUrl}.`);
+	};
+	printStopped = (stopped) => {
+		console.log(stopped ? "Stopped companion process." : "Companion is not running.");
+	};
+	killProcess = (pid, force) => {
+		process.kill(pid, force ? "SIGKILL" : "SIGTERM");
+	};
+	resolveLaunchSpec = () => {
+		const packageJsonPath = require$2.resolve("@nextclaw/companion/package.json");
+		const packageRoot = dirname(packageJsonPath);
+		const mainPath = resolve(packageRoot, "dist", "src", "main.js");
+		if (!existsSync(mainPath)) throw new Error(`Companion app build is missing at ${mainPath}. Build @nextclaw/companion first.`);
+		return {
+			command: createRequire(packageJsonPath)("electron"),
+			args: [packageRoot]
+		};
+	};
+	waitForRunningState = async (baseUrl, fallbackPid) => {
+		const timeoutAt = Date.now() + 5e3;
+		while (Date.now() < timeoutAt) {
+			const state = this.getRunningState();
+			if (state?.baseUrl === baseUrl) return state;
+			await new Promise((resolvePromise) => setTimeout(resolvePromise, 100));
+		}
+		throw new Error(fallbackPid > 0 ? `Companion started but did not report a live runtime state (launcher pid ${fallbackPid}).` : "Companion started but did not report a live runtime state.");
+	};
+};
+const companionRuntimeService = new CompanionRuntimeService();
+//#endregion
 //#region src/cli/shared/services/runtime/runtime-command.service.ts
 const { getApiBase, getConfigPath: getConfigPath$1, getProvider, getProviderName, getWorkspacePath: getWorkspacePath$1, loadConfig: loadConfig$1, LiteLLMProvider, MessageBus: MessageBus$1, resolveConfigSecrets: resolveConfigSecrets$1, SessionManager: SessionManager$1, parseAgentScopedSessionKey: parseAgentScopedSessionKey$1 } = NextclawCore;
 function createSkillsLoader(workspace) {
@@ -17008,38 +17326,16 @@ var RuntimeCommandService = class {
 			runCliSubcommand: (args) => this.runCliSubcommand(args),
 			installBuiltinSkill: (slug, force) => this.installBuiltinMarketplaceSkill(slug, force)
 		}).createInstaller();
-		const { remoteAccess, runtimeControl } = createServiceUiHosts({
-			serviceCommands: this,
-			requestRestart: this.deps.requestRestart,
-			uiConfig: shellContext.uiConfig,
-			remoteModule: shellContext.remoteModule
-		});
-		const uiStartup = await measureStartupAsync("service.start_ui_shell", async () => await startUiShell({
-			uiConfig: shellContext.uiConfig,
-			uiStaticDir: shellContext.uiStaticDir,
-			cronService: shellContext.cron,
-			getConfig: getRuntimeConfig,
-			configPath: getConfigPath$1(),
-			productVersion: getPackageVersion$1(),
-			getPluginChannelBindings: () => runtimeState?.pluginChannelBindings ?? [],
-			getPluginUiMetadata: () => runtimeState?.pluginUiMetadata ?? [],
-			marketplace: {
-				apiBaseUrl: process.env.NEXTCLAW_MARKETPLACE_API_BASE,
-				installer: marketplaceInstaller
-			},
-			remoteAccess,
-			runtimeControl,
-			getBootstrapStatus: () => bootstrapStatus.getStatus(),
-			openBrowserWindow: shellContext.uiConfig.open,
+		const uiStartup = await this.startGatewayUiShell({
+			shellContext,
 			applyLiveConfigReload,
-			ncpSessionService: ncpSessionRealtimeBridge.sessionService,
-			initializeAgentHomeDirectory: this.deps.initializeAgentHomeDirectory
-		}));
-		finalizeLocalUiStartup({
-			uiStartup,
-			setUiEventPublisher: (publish) => ncpSessionRealtimeBridge.setUiEventPublisher(publish),
-			uiConfig: shellContext.uiConfig
+			bootstrapStatus,
+			marketplaceInstaller,
+			ncpSessionRealtimeBridge,
+			getRuntimeConfig,
+			getRuntimeState: () => runtimeState
 		});
+		await companionRuntimeService.applyConfig(shellContext.config);
 		bootstrapStatus.markShellReady();
 		await setImmediate$1();
 		const gateway = measureStartupSync("service.create_gateway_startup_context", () => createGatewayStartupContext({
@@ -17057,33 +17353,14 @@ var RuntimeCommandService = class {
 		const loadGatewayConfig = () => resolveConfigSecrets$1(loadConfig$1(), { configPath: gateway.runtimeConfigPath });
 		const gatewayRuntimeState = createGatewayRuntimeState(gateway);
 		runtimeState = gatewayRuntimeState;
-		uiStartup?.publish({
-			type: "config.updated",
-			payload: { path: "channels" }
+		gateway.reloader.setReloadCompanion(async ({ config: nextConfig }) => {
+			await companionRuntimeService.applyConfig(nextConfig);
 		});
-		uiStartup?.publish({
-			type: "config.updated",
-			payload: { path: "plugins" }
-		});
-		configureGatewayPluginRuntime({
+		await this.hydrateGatewayRuntime({
 			gateway,
-			state: gatewayRuntimeState,
-			getLiveUiNcpAgent: () => this.liveUiNcpAgent
+			gatewayRuntimeState,
+			uiStartup
 		});
-		console.log("✓ Capability hydration: scheduled in background");
-		await measureStartupAsync("service.start_gateway_support_services", async () => await startGatewayRuntimeSupport({
-			cronJobs: gateway.cron.status().jobs,
-			remoteModule: gateway.remoteModule,
-			watchConfigFile: () => watchServiceConfigFile({
-				configPath: resolve(getConfigPath$1()),
-				watcherRegistry: this.fileWatchers,
-				scheduleReload: (reason) => gateway.reloader.scheduleReload(reason)
-			}),
-			startCron: () => gateway.cron.start(),
-			cronStorePath: resolve(join(NextclawCore.getDataDir(), "cron", "jobs.json")),
-			reloadCronStore: () => gateway.cron.reloadFromStore(),
-			watcherRegistry: this.fileWatchers
-		}));
 		const deferredGatewayStartupHooks = createDeferredGatewayStartupHooks({
 			uiStartup,
 			gateway,
@@ -17125,14 +17402,84 @@ var RuntimeCommandService = class {
 					this.applyLiveConfigReload = null;
 					this.liveUiNcpAgent = null;
 				},
-				clearRealtimeBridge: () => ncpSessionRealtimeBridge.clear(),
+				clearRealtimeBridge: () => {
+					ncpSessionRealtimeBridge.clear();
+				},
 				uiStartup,
 				remoteModule: gateway.remoteModule,
 				runtimeState
 			})
 		});
+		await companionRuntimeService.ensureStopped();
 		logStartupTrace("service.start_gateway.end");
 	};
+	startGatewayUiShell = async (params) => {
+		const { applyLiveConfigReload, bootstrapStatus, getRuntimeConfig, getRuntimeState, marketplaceInstaller, ncpSessionRealtimeBridge, shellContext } = params;
+		const { remoteAccess, runtimeControl, runtimeUpdate } = createServiceUiHosts({
+			serviceCommands: this,
+			requestRestart: this.deps.requestRestart,
+			uiConfig: shellContext.uiConfig,
+			remoteModule: shellContext.remoteModule
+		});
+		const uiStartup = await measureStartupAsync("service.start_ui_shell", async () => await startUiShell({
+			uiConfig: shellContext.uiConfig,
+			uiStaticDir: shellContext.uiStaticDir,
+			cronService: shellContext.cron,
+			getConfig: getRuntimeConfig,
+			configPath: getConfigPath$1(),
+			productVersion: getPackageVersion$1(),
+			getPluginChannelBindings: () => getRuntimeState()?.pluginChannelBindings ?? [],
+			getPluginUiMetadata: () => getRuntimeState()?.pluginUiMetadata ?? [],
+			marketplace: {
+				apiBaseUrl: process.env.NEXTCLAW_MARKETPLACE_API_BASE,
+				installer: marketplaceInstaller
+			},
+			remoteAccess,
+			runtimeControl,
+			runtimeUpdate,
+			getBootstrapStatus: () => bootstrapStatus.getStatus(),
+			openBrowserWindow: shellContext.uiConfig.open,
+			applyLiveConfigReload,
+			ncpSessionService: ncpSessionRealtimeBridge.sessionService,
+			initializeAgentHomeDirectory: this.deps.initializeAgentHomeDirectory
+		}));
+		finalizeLocalUiStartup({
+			uiStartup,
+			setUiEventPublisher: (publish) => ncpSessionRealtimeBridge.setUiEventPublisher(publish),
+			uiConfig: shellContext.uiConfig
+		});
+		return uiStartup;
+	};
+	hydrateGatewayRuntime = async (params) => {
+		const { gateway, gatewayRuntimeState, uiStartup } = params;
+		uiStartup?.publish({
+			type: "config.updated",
+			payload: { path: "channels" }
+		});
+		uiStartup?.publish({
+			type: "config.updated",
+			payload: { path: "plugins" }
+		});
+		configureGatewayPluginRuntime({
+			gateway,
+			state: gatewayRuntimeState,
+			getLiveUiNcpAgent: () => this.liveUiNcpAgent
+		});
+		console.log("✓ Capability hydration: scheduled in background");
+		await measureStartupAsync("service.start_gateway_support_services", async () => await startGatewayRuntimeSupport({
+			cronJobs: gateway.cron.status().jobs,
+			remoteModule: gateway.remoteModule,
+			watchConfigFile: () => watchServiceConfigFile({
+				configPath: resolve(getConfigPath$1()),
+				watcherRegistry: this.fileWatchers,
+				scheduleReload: (reason) => gateway.reloader.scheduleReload(reason)
+			}),
+			startCron: () => gateway.cron.start(),
+			cronStorePath: resolve(join(NextclawCore.getDataDir(), "cron", "jobs.json")),
+			reloadCronStore: () => gateway.cron.reloadFromStore(),
+			watcherRegistry: this.fileWatchers
+		}));
+	};
 	normalizeOptionalString = (value) => {
 		if (typeof value !== "string") return;
 		return value.trim() || void 0;
@@ -19035,6 +19382,30 @@ var RuntimeRestartRequestService = class {
 	};
 };
 //#endregion
+//#region src/cli/shared/utils/runtime-helpers.ts
+function resolveSkillsInstallWorkdir(params) {
+	if (params.explicitWorkdir) return expandHome(params.explicitWorkdir);
+	return getWorkspacePath(params.configuredWorkspace);
+}
+function parseStartTimeoutMs(value) {
+	if (value === void 0) return;
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed <= 0) {
+		console.error("Invalid --start-timeout value. Provide milliseconds (e.g. 45000).");
+		process.exit(1);
+	}
+	return Math.floor(parsed);
+}
+function resolveManagedServiceUiOverrides(params) {
+	const uiOverrides = {
+		enabled: true,
+		host: params.forcedPublicHost,
+		open: false
+	};
+	if (params.uiPort) uiOverrides.port = Number(params.uiPort);
+	return uiOverrides;
+}
+//#endregion
 //#region src/cli/commands/skills/marketplace-command-options.utils.ts
 function buildMarketplacePublishOptions(options) {
 	const { apiBaseUrl, author, description, dir, homepage, meta, name, packageName, publishedAt, scope, slug, sourceRepo, summary, tag, token, updatedAt } = options;
@@ -20127,6 +20498,74 @@ var StopCommands = class {
 	};
 };
 //#endregion
+//#region src/cli/commands/companion/services/companion-process.service.ts
+var CompanionProcessService = class {
+	constructor(runtimeService = companionRuntimeService) {
+		this.runtimeService = runtimeService;
+	}
+	start = async (options = {}) => {
+		const state = await this.runtimeService.ensureStarted({ baseUrl: this.resolveBaseUrl(options) });
+		this.runtimeService.printStarted(state);
+	};
+	status = async (options = {}) => {
+		this.runtimeService.printStatus(options);
+	};
+	stop = async (options = {}) => {
+		const stopped = await this.runtimeService.ensureStopped(options);
+		this.runtimeService.printStopped(stopped);
+	};
+	enable = async (options = {}) => {
+		const nextConfig = await this.runtimeService.updateEnabled(true, options);
+		this.printConfigEnabled(nextConfig, options.baseUrl);
+	};
+	disable = async (_options = {}) => {
+		const nextConfig = await this.runtimeService.updateEnabled(false);
+		console.log(nextConfig.companion.enabled ? "Companion remains enabled." : "Companion feature disabled. It will stay off until you enable it again.");
+	};
+	resolveBaseUrl = (options) => {
+		const explicitBaseUrl = options.baseUrl?.trim();
+		if (explicitBaseUrl) return explicitBaseUrl.replace(/\/+$/, "");
+		const discoveredBaseUrl = this.runtimeService.resolveDiscoveredBaseUrl();
+		if (discoveredBaseUrl) return discoveredBaseUrl;
+		const runningState = this.runtimeService.getRunningState();
+		if (runningState) return runningState.baseUrl;
+		throw new Error("Cannot resolve NextClaw UI base URL. Start NextClaw first or pass --base-url.");
+	};
+	printConfigEnabled = (config, baseUrl) => {
+		if (this.runtimeService.getRunningState()) {
+			console.log("Companion feature enabled and companion started.");
+			return;
+		}
+		if (baseUrl?.trim()) {
+			console.log("Companion feature enabled.");
+			return;
+		}
+		console.log(config.companion.enabled ? "Companion feature enabled. It will auto-start the next time a local NextClaw runtime is available." : "Companion feature is not enabled.");
+	};
+};
+//#endregion
+//#region src/cli/commands/companion/index.ts
+var CompanionCommands = class {
+	constructor(companionProcessService = new CompanionProcessService()) {
+		this.companionProcessService = companionProcessService;
+	}
+	start = async (options = {}) => {
+		await this.companionProcessService.start(options);
+	};
+	enable = async (options = {}) => {
+		await this.companionProcessService.enable(options);
+	};
+	disable = async (options = {}) => {
+		await this.companionProcessService.disable(options);
+	};
+	status = async (options = {}) => {
+		await this.companionProcessService.status(options);
+	};
+	stop = async (options = {}) => {
+		await this.companionProcessService.stop(options);
+	};
+};
+//#endregion
 //#region src/cli/app/runtime.ts
 const LOGO = "🤖";
 const FORCED_PUBLIC_UI_HOST = "0.0.0.0";
@@ -20158,6 +20597,7 @@ var CliRuntime = class {
 	restartCommands;
 	serveCommands;
 	stopCommands;
+	companionCommands;
 	constructor(options = {}) {
 		logStartupTrace("cli.runtime.constructor.begin");
 		this.logo = options.logo ?? "🤖";
@@ -20190,6 +20630,7 @@ var CliRuntime = class {
 			forcedPublicHost: FORCED_PUBLIC_UI_HOST
 		}));
 		this.stopCommands = measureStartupSync("cli.runtime.stop_commands", () => new StopCommands({ runtimeCommandService: this.runtimeCommandService }));
+		this.companionCommands = measureStartupSync("cli.runtime.companion_commands", () => new CompanionCommands());
 		this.serviceCommands = measureStartupSync("cli.runtime.service_commands", () => new ServiceCommands());
 		this.configCommands = measureStartupSync("cli.runtime.config_commands", () => new ConfigCommands({ requestRestart: (params) => this.requestRestart(params) }));
 		this.mcpCommands = measureStartupSync("cli.runtime.mcp_commands", () => new McpCommands());
@@ -20422,6 +20863,21 @@ var CliRuntime = class {
 	stop = async () => {
 		await this.stopCommands.run();
 	};
+	companionStart = async (opts = {}) => {
+		await this.companionCommands.start(opts);
+	};
+	companionEnable = async (opts = {}) => {
+		await this.companionCommands.enable(opts);
+	};
+	companionDisable = async (opts = {}) => {
+		await this.companionCommands.disable(opts);
+	};
+	companionStatus = async (opts = {}) => {
+		await this.companionCommands.status(opts);
+	};
+	companionStop = async (opts = {}) => {
+		await this.companionCommands.stop(opts);
+	};
 	agent = async (opts) => {
 		const configPath = getConfigPath();
 		const config = resolveConfigSecrets(loadConfig(), { configPath });
@@ -20594,6 +21050,16 @@ function registerAgentsCommands(program, runtime) {
 	agents.command("remove <agentId>").description("Remove an agent").option("--json", "Output JSON", false).action(async (agentId, opts) => runtime.agentsRemove(agentId, opts));
 }
 //#endregion
+//#region src/cli/app/register-companion-commands.ts
+function registerCompanionCommands(program, runtime) {
+	const companion = program.command("companion").description("Manage the standalone NextClaw companion shell");
+	companion.command("start").description("Start the companion shell in the background").option("--base-url <url>", "Explicit NextClaw UI base URL").action(async (opts) => runtime.companionStart(opts));
+	companion.command("enable").description("Enable the companion feature and start it when a local runtime is available").option("--base-url <url>", "Explicit NextClaw UI base URL").action(async (opts) => runtime.companionEnable(opts));
+	companion.command("disable").description("Disable the companion feature and stop any running companion process").action(async (opts) => runtime.companionDisable(opts));
+	companion.command("status").description("Show companion process status").option("--json", "Output JSON", false).action(async (opts) => runtime.companionStatus(opts));
+	companion.command("stop").description("Stop the companion process").option("--force", "Force kill the companion process", false).action(async (opts) => runtime.companionStop(opts));
+}
+//#endregion
 //#region src/cli/app/service-command-registration.service.ts
 const registerServiceCommands = ({ program, getServiceCommands }) => {
 	const service = program.command("service").description("Manage host service integrations");
@@ -20649,6 +21115,7 @@ program.command("start").description(`Start the ${APP_NAME} gateway + UI in the
 program.command("restart").description(`Restart the ${APP_NAME} background service`).option("--ui-port <port>", "UI port").option("--start-timeout <ms>", "Maximum wait time for startup readiness in milliseconds").option("--open", "Open browser after restart", false).action(async (opts) => runtime.restart(opts));
 program.command("serve").description(`Run the ${APP_NAME} gateway + UI in the foreground`).option("--ui-port <port>", "UI port").option("--open", "Open browser after start", false).action(async (opts) => runtime.serve(opts));
 program.command("stop").description(`Stop the ${APP_NAME} background service`).action(async () => runtime.stop());
+registerCompanionCommands(program, runtime);
 registerServiceCommands({
 	program,
 	getServiceCommands
@@ -20699,6 +21166,6 @@ const logs = program.command("logs").description("Inspect local runtime logs");
 logs.command("path").description("Show local log file paths").action(() => runtime.logsPath());
 logs.command("tail").description("Show recent local log entries").option("--lines <n>", "Number of lines to show", "40").option("--crash", "Tail crash.log instead of service.log", false).action((opts) => runtime.logsTail(opts));
 program.command("usage").description("Show observed LLM usage snapshots, history, and prompt cache stats").option("--history", "Show recent usage history", false).option("--stats", "Show aggregated usage stats from local history", false).option("--limit <n>", "Maximum number of history records to show", "10").option("--json", "Output JSON", false).action(async (opts) => llmUsageCommands.show(opts));
-program.parseAsync(process.argv);
+await program.parseAsync(process.argv);
 //#endregion
 export {};