@nextclaw/service 0.1.1

package/dist/shared/services/runtime/service-managed-startup.service.js

@@ -0,0 +1,426 @@
+import { isProcessRunning, openBrowser, resolveServiceLogPath, resolveUiApiBase, resolveUiConfig, resolveUiStaticDir, waitForExit } from "../../utils/cli.utils.js";
+import { localUiRuntimeStore } from "../../stores/local-ui-runtime.store.js";
+import { managedServiceStateStore } from "../../stores/managed-service-state.store.js";
+import { probeHealthEndpoint } from "../../utils/service-port-probe.utils.js";
+import { resolveCliSubcommandLaunch } from "../../utils/marketplace/cli-subcommand-launch.utils.js";
+import { createTopLevelNextclawCommandEnv } from "../../utils/top-level-nextclaw-command-env.utils.js";
+import { writeInitialManagedServiceState, writeReadyManagedServiceState } from "./service-remote-runtime.service.js";
+import { spawn } from "node:child_process";
+import { dirname } from "node:path";
+import * as NextclawCore from "@nextclaw/core";
+import { FileLogSink } from "@nextclaw/core";
+import { mkdirSync } from "node:fs";
+//#region src/shared/services/runtime/service-managed-startup.service.ts
+const { APP_NAME: APP_NAME$1, loadConfig: loadConfig$1 } = NextclawCore;
+function resolveManagedServiceReadySnapshot(params) {
+	const { snapshot, readLocalUiRuntimeState, isProcessRunningFn: providedIsProcessRunningFn } = params;
+	const localUiRuntimeState = (readLocalUiRuntimeState ?? localUiRuntimeStore.read)();
+	const isProcessRunningFn = providedIsProcessRunningFn ?? isProcessRunning;
+	if (!localUiRuntimeState || typeof localUiRuntimeState.pid !== "number" || !Number.isFinite(localUiRuntimeState.pid) || localUiRuntimeState.uiPort !== snapshot.uiPort || !isProcessRunningFn(localUiRuntimeState.pid)) return snapshot;
+	return {
+		...snapshot,
+		pid: localUiRuntimeState.pid,
+		uiUrl: localUiRuntimeState.uiUrl,
+		apiUrl: localUiRuntimeState.apiUrl,
+		uiHost: localUiRuntimeState.uiHost ?? snapshot.uiHost,
+		uiPort: localUiRuntimeState.uiPort ?? snapshot.uiPort
+	};
+}
+function toObjectRecord(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	return value;
+}
+function hasSessionRoutingMetadata(params) {
+	const context = toObjectRecord(params.metadata.last_delivery_context) ?? {};
+	const hasPrimaryRoute = Boolean(params.normalizeOptionalString(context.channel)) && Boolean(params.normalizeOptionalString(context.chatId));
+	const hasFallbackRoute = Boolean(params.normalizeOptionalString(params.metadata.last_channel)) && Boolean(params.normalizeOptionalString(params.metadata.last_to));
+	return hasPrimaryRoute || hasFallbackRoute;
+}
+function resolveManagedServiceUiBinding(state) {
+	try {
+		const parsed = new URL(state.uiUrl);
+		const parsedPort = Number(parsed.port || 80);
+		return {
+			host: state.uiHost ?? parsed.hostname,
+			port: Number.isFinite(parsedPort) ? parsedPort : state.uiPort ?? 55667
+		};
+	} catch {
+		return {
+			host: state.uiHost ?? "127.0.0.1",
+			port: state.uiPort ?? 55667
+		};
+	}
+}
+function resolveSessionRouteCandidate(params) {
+	const sessionRecord = toObjectRecord(params.session);
+	const key = params.normalizeOptionalString(sessionRecord?.key);
+	if (!key || key.startsWith("cli:")) return null;
+	if (!hasSessionRoutingMetadata({
+		metadata: toObjectRecord(sessionRecord?.metadata) ?? {},
+		normalizeOptionalString: params.normalizeOptionalString
+	})) return null;
+	const updatedAtRaw = params.normalizeOptionalString(sessionRecord?.updated_at);
+	const updatedAt = updatedAtRaw ? Date.parse(updatedAtRaw) : NaN;
+	return {
+		key,
+		updatedAt: Number.isFinite(updatedAt) ? updatedAt : 0
+	};
+}
+function spawnManagedService(params) {
+	const { appName, config, uiConfig, uiUrl, apiUrl, healthUrl, startupTimeoutMs, resolveStartupTimeoutMs, appendStartupStage, printStartupFailureDiagnostics, resolveServiceLogPath } = params;
+	const logPath = resolveServiceLogPath();
+	new FileLogSink({ serviceLogPath: logPath }).ensureReady();
+	mkdirSync(dirname(logPath), { recursive: true });
+	const readinessTimeoutMs = resolveStartupTimeoutMs(startupTimeoutMs);
+	const quickPhaseTimeoutMs = Math.min(8e3, readinessTimeoutMs);
+	const extendedPhaseTimeoutMs = Math.max(0, readinessTimeoutMs - quickPhaseTimeoutMs);
+	appendStartupStage(logPath, `start requested: ui=${uiConfig.host}:${uiConfig.port}, readinessTimeoutMs=${readinessTimeoutMs}`);
+	console.log(`Starting ${appName} background service (readiness timeout ${Math.ceil(readinessTimeoutMs / 1e3)}s)...`);
+	const cliLaunch = resolveCliSubcommandLaunch({
+		argvEntry: process.argv[1],
+		importMetaUrl: import.meta.url,
+		cliArgs: [
+			"serve",
+			"--ui-port",
+			String(uiConfig.port)
+		],
+		nodePath: process.execPath
+	});
+	const childArgs = [...process.execArgv, ...cliLaunch.args];
+	appendStartupStage(logPath, `spawning background process: ${cliLaunch.command} ${childArgs.join(" ")}`);
+	const child = spawn(cliLaunch.command, childArgs, {
+		env: createTopLevelNextclawCommandEnv(process.env),
+		stdio: "ignore",
+		detached: true
+	});
+	appendStartupStage(logPath, `spawned background process pid=${child.pid ?? "unknown"}`);
+	if (!child.pid) {
+		appendStartupStage(logPath, "spawn failed: child pid missing");
+		console.error("Error: Failed to start background service.");
+		printStartupFailureDiagnostics({
+			uiUrl,
+			apiUrl,
+			healthUrl,
+			logPath,
+			lastProbeError: null
+		});
+		return null;
+	}
+	const snapshot = {
+		pid: child.pid,
+		uiUrl,
+		apiUrl,
+		uiHost: uiConfig.host,
+		uiPort: uiConfig.port,
+		logPath
+	};
+	writeInitialManagedServiceState({
+		config,
+		readinessTimeoutMs,
+		snapshot
+	});
+	return {
+		child,
+		logPath,
+		readinessTimeoutMs,
+		quickPhaseTimeoutMs,
+		extendedPhaseTimeoutMs,
+		snapshot
+	};
+}
+async function waitForManagedServiceReadiness(params) {
+	params.appendStartupStage(params.logPath, `health probe started: ${params.healthUrl} (phase=quick, timeoutMs=${params.quickPhaseTimeoutMs})`);
+	let readiness = await params.waitForBackgroundServiceReady({
+		pid: params.childPid,
+		healthUrl: params.healthUrl,
+		timeoutMs: params.quickPhaseTimeoutMs
+	});
+	if (!readiness.ready && params.isProcessRunning(params.childPid) && params.extendedPhaseTimeoutMs > 0) {
+		console.warn(`Warning: Background service is still running but not ready after ${Math.ceil(params.quickPhaseTimeoutMs / 1e3)}s; waiting up to ${Math.ceil(params.extendedPhaseTimeoutMs / 1e3)}s more.`);
+		params.appendStartupStage(params.logPath, `health probe entering extended phase (timeoutMs=${params.extendedPhaseTimeoutMs}, lastError=${readiness.lastProbeError ?? "none"})`);
+		readiness = await params.waitForBackgroundServiceReady({
+			pid: params.childPid,
+			healthUrl: params.healthUrl,
+			timeoutMs: params.extendedPhaseTimeoutMs
+		});
+	}
+	if (!readiness.ready && params.isProcessRunning(params.childPid)) params.appendStartupStage(params.logPath, `startup degraded: process alive but health probe timed out after ${params.readinessTimeoutMs}ms (lastError=${readiness.lastProbeError ?? "none"})`);
+	return readiness;
+}
+async function reportManagedServiceStart(params) {
+	if (!params.readiness.ready) {
+		const hint = params.readiness.lastProbeError ? ` Last probe error: ${params.readiness.lastProbeError}` : "";
+		console.warn(`Warning: ${params.appName} is running (PID ${params.state.pid}) but not healthy yet after ${Math.ceil(params.readinessTimeoutMs / 1e3)}s. Marked as degraded.${hint}`);
+		console.warn(`Tip: Run "${params.appName} status --json" and check logs: ${params.state.logPath}`);
+	} else console.log(`✓ ${params.appName} started in background (PID ${params.state.pid})`);
+	console.log(`UI: ${params.uiUrl}`);
+	console.log(`API: ${params.apiUrl}`);
+	await params.printPublicUiUrls(params.uiConfig.host, params.uiConfig.port);
+	console.log(`Logs: ${params.state.logPath}`);
+	params.printServiceControlHints();
+}
+var ManagedServiceCommandService = class {
+	loggingRuntime = NextclawCore.getLoggingRuntime();
+	serviceLogger = this.loggingRuntime.getLogger("service");
+	constructor(deps) {
+		this.deps = deps;
+	}
+	runForeground = async (options) => {
+		const uiConfig = resolveUiConfig(loadConfig$1(), options.uiOverrides);
+		const uiUrl = resolveUiApiBase(uiConfig.host, uiConfig.port);
+		if (options.open) openBrowser(uiUrl);
+		await this.deps.startGateway({
+			uiOverrides: options.uiOverrides,
+			uiStaticDir: resolveUiStaticDir()
+		});
+	};
+	startService = async (options) => {
+		this.loggingRuntime.ensureReady();
+		const { open, startupTimeoutMs, uiOverrides } = options;
+		const config = loadConfig$1();
+		const uiConfig = resolveUiConfig(config, uiOverrides);
+		const uiUrl = resolveUiApiBase(uiConfig.host, uiConfig.port);
+		const apiUrl = `${uiUrl}/api`;
+		const staticDir = resolveUiStaticDir();
+		const existing = managedServiceStateStore.read();
+		if (existing && isProcessRunning(existing.pid)) {
+			await this.handleExistingManagedService({
+				existing,
+				uiConfig,
+				options
+			});
+			return;
+		}
+		if (existing) managedServiceStateStore.clear();
+		if (!staticDir) {
+			process.exitCode = 1, console.error(`Error: ${APP_NAME$1} UI frontend bundle not found. Reinstall or rebuild ${APP_NAME$1}. For dev-only overrides, set NEXTCLAW_UI_STATIC_DIR to a built frontend directory.`);
+			return;
+		}
+		const healthUrl = `${apiUrl}/health`;
+		const portPreflight = await this.deps.checkUiPortPreflight({
+			host: uiConfig.host,
+			port: uiConfig.port,
+			healthUrl
+		});
+		if (!portPreflight.ok) {
+			process.exitCode = 1, console.error(`Error: Cannot start ${APP_NAME$1} because UI port ${uiConfig.port} is already occupied.`), console.error(portPreflight.message);
+			return;
+		}
+		if (portPreflight.reusedExistingHealthyTarget) {
+			await this.reuseExistingHealthyStartTarget({
+				uiConfig,
+				uiUrl,
+				apiUrl,
+				open
+			});
+			return;
+		}
+		await this.startNewManagedServiceTarget({
+			config,
+			uiConfig,
+			uiUrl,
+			apiUrl,
+			healthUrl,
+			startupTimeoutMs
+		});
+		if (open) openBrowser(uiUrl);
+	};
+	stopService = async () => {
+		const state = managedServiceStateStore.read();
+		if (!state) {
+			console.log("No running background service found.");
+			return;
+		}
+		if (!isProcessRunning(state.pid)) {
+			console.log("Service is not running. Cleaning up state.");
+			managedServiceStateStore.clear();
+			return;
+		}
+		console.log(`Stopping ${APP_NAME$1} (PID ${state.pid})...`);
+		try {
+			process.kill(state.pid, "SIGTERM");
+		} catch (error) {
+			console.error(`Failed to stop service: ${String(error)}`);
+			return;
+		}
+		if (!await waitForExit(state.pid, 3e3)) {
+			try {
+				process.kill(state.pid, "SIGKILL");
+			} catch (error) {
+				console.error(`Failed to force stop service: ${String(error)}`);
+				return;
+			}
+			await waitForExit(state.pid, 2e3);
+		}
+		managedServiceStateStore.clear();
+		localUiRuntimeStore.clearIfOwnedByProcess(state.pid);
+		console.log(`✓ ${APP_NAME$1} stopped`);
+	};
+	handleExistingManagedService = async (params) => {
+		const { existing, options, uiConfig } = params;
+		console.log(`✓ ${APP_NAME$1} is already running (PID ${existing.pid})`);
+		console.log(`UI: ${existing.uiUrl}`);
+		console.log(`API: ${existing.apiUrl}`);
+		const binding = resolveManagedServiceUiBinding(existing);
+		if (binding.host !== uiConfig.host || binding.port !== uiConfig.port) {
+			console.log(`Detected running service UI bind (${binding.host}:${binding.port}); enforcing (${uiConfig.host}:${uiConfig.port})...`);
+			await this.stopService();
+			const stateAfterStop = managedServiceStateStore.read();
+			if (stateAfterStop && isProcessRunning(stateAfterStop.pid)) {
+				process.exitCode = 1;
+				console.error("Error: Failed to stop running service while enforcing public UI exposure.");
+				return true;
+			}
+			await this.startService(options);
+			return true;
+		}
+		await this.deps.printPublicUiUrls(binding.host, binding.port);
+		console.log(`Logs: ${existing.logPath}`);
+		this.deps.printServiceControlHints();
+		return true;
+	};
+	reuseExistingHealthyStartTarget = async (params) => {
+		const { apiUrl, open, uiConfig, uiUrl } = params;
+		console.log(`✓ ${APP_NAME$1} is already serving the target UI/API port`);
+		console.log(`UI: ${uiUrl}`);
+		console.log(`API: ${apiUrl}`);
+		console.warn([
+			`Warning: The healthy listener on ${uiConfig.port} is not tracked by ${managedServiceStateStore.path}.`,
+			"This start call reused the existing runtime instead of spawning another one.",
+			"Use the owning process or port-level tools to stop it; managed stop/restart will not control it automatically."
+		].join(" "));
+		await this.deps.printPublicUiUrls(uiConfig.host, uiConfig.port);
+		if (open) openBrowser(uiUrl);
+	};
+	startNewManagedServiceTarget = async (params) => {
+		const { apiUrl, config, healthUrl, startupTimeoutMs, uiConfig, uiUrl } = params;
+		const startup = spawnManagedService({
+			appName: APP_NAME$1,
+			config,
+			uiConfig,
+			uiUrl,
+			apiUrl,
+			healthUrl,
+			startupTimeoutMs,
+			resolveStartupTimeoutMs: this.resolveStartupTimeoutMs,
+			appendStartupStage: this.appendStartupStage,
+			printStartupFailureDiagnostics: this.printStartupFailureDiagnostics,
+			resolveServiceLogPath
+		});
+		if (!startup) {
+			this.serviceLogger.fatal("managed service startup aborted", { reason: "child_process_not_created" });
+			process.exitCode = 1;
+			return;
+		}
+		const readiness = await waitForManagedServiceReadiness({
+			appName: APP_NAME$1,
+			childPid: startup.snapshot.pid,
+			healthUrl,
+			logPath: startup.logPath,
+			readinessTimeoutMs: startup.readinessTimeoutMs,
+			quickPhaseTimeoutMs: startup.quickPhaseTimeoutMs,
+			extendedPhaseTimeoutMs: startup.extendedPhaseTimeoutMs,
+			appendStartupStage: this.appendStartupStage,
+			waitForBackgroundServiceReady: this.waitForBackgroundServiceReady,
+			isProcessRunning
+		});
+		if (!readiness.ready && !isProcessRunning(startup.snapshot.pid)) {
+			process.exitCode = 1;
+			managedServiceStateStore.clear();
+			const hint = readiness.lastProbeError ? ` Last probe error: ${readiness.lastProbeError}` : "";
+			this.appendStartupStage(startup.logPath, `startup failed: process exited before ready.${hint}`);
+			this.serviceLogger.fatal("managed service exited before readiness completed", {
+				uiUrl,
+				apiUrl,
+				healthUrl,
+				logPath: startup.logPath,
+				...readiness.lastProbeError ? { lastProbeError: readiness.lastProbeError } : {}
+			});
+			console.error(`Error: Failed to start background service. Check logs: ${startup.logPath}.${hint}`);
+			this.printStartupFailureDiagnostics({
+				uiUrl,
+				apiUrl,
+				healthUrl,
+				logPath: startup.logPath,
+				lastProbeError: readiness.lastProbeError
+			});
+			return;
+		}
+		startup.child.unref();
+		const readySnapshot = resolveManagedServiceReadySnapshot({ snapshot: startup.snapshot });
+		await reportManagedServiceStart({
+			appName: APP_NAME$1,
+			state: writeReadyManagedServiceState({
+				readinessTimeoutMs: startup.readinessTimeoutMs,
+				readiness,
+				snapshot: readySnapshot
+			}),
+			uiConfig,
+			uiUrl,
+			apiUrl,
+			readinessTimeoutMs: startup.readinessTimeoutMs,
+			readiness,
+			printPublicUiUrls: this.deps.printPublicUiUrls,
+			printServiceControlHints: this.deps.printServiceControlHints
+		});
+	};
+	waitForBackgroundServiceReady = async (params) => {
+		const { pid, healthUrl, timeoutMs } = params;
+		const startedAt = Date.now();
+		let lastProbeError = null;
+		while (Date.now() - startedAt < timeoutMs) {
+			if (!isProcessRunning(pid)) return {
+				ready: false,
+				lastProbeError
+			};
+			const probe = await probeHealthEndpoint(healthUrl);
+			if (!probe.healthy) {
+				lastProbeError = probe.error;
+				await new Promise((resolvePromise) => setTimeout(resolvePromise, 200));
+				continue;
+			}
+			await new Promise((resolvePromise) => setTimeout(resolvePromise, 300));
+			if (isProcessRunning(pid)) return {
+				ready: true,
+				lastProbeError: null
+			};
+			await new Promise((resolvePromise) => setTimeout(resolvePromise, 200));
+		}
+		return {
+			ready: false,
+			lastProbeError
+		};
+	};
+	resolveStartupTimeoutMs = (overrideTimeoutMs) => {
+		const fallback = process.platform === "win32" ? 28e3 : 33e3;
+		const envRaw = process.env.NEXTCLAW_START_TIMEOUT_MS?.trim();
+		const envValue = envRaw ? Number(envRaw) : NaN;
+		const fromEnv = Number.isFinite(envValue) && envValue > 0 ? Math.floor(envValue) : null;
+		const resolved = (Number.isFinite(overrideTimeoutMs) && Number(overrideTimeoutMs) > 0 ? Math.floor(Number(overrideTimeoutMs)) : null) ?? fromEnv ?? fallback;
+		return Math.max(3e3, resolved);
+	};
+	appendStartupStage = (logPath, message) => {
+		try {
+			this.serviceLogger.child("startup").info(message, { logPath });
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			console.error(`Warning: failed to write startup diagnostics log (${logPath}): ${detail}`);
+		}
+	};
+	printStartupFailureDiagnostics = (params) => {
+		const { apiUrl, healthUrl, lastProbeError, logPath, uiUrl } = params;
+		const statePath = managedServiceStateStore.path;
+		const lines = [
+			"Startup diagnostics:",
+			`- UI URL: ${uiUrl}`,
+			`- API URL: ${apiUrl}`,
+			`- Health probe: ${healthUrl}`,
+			`- Service state path: ${statePath}`,
+			`- Startup log path: ${logPath}`
+		];
+		if (lastProbeError) lines.push(`- Last probe detail: ${lastProbeError}`);
+		console.error(lines.join("\n"));
+	};
+};
+//#endregion
+export { ManagedServiceCommandService, reportManagedServiceStart, resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate, spawnManagedService, waitForManagedServiceReadiness };

package/dist/shared/services/runtime/service-remote-runtime.service.d.ts

@@ -0,0 +1,53 @@
+import { ManagedServiceState } from "../../stores/managed-service-state.store.js";
+import { Config } from "@nextclaw/core";
+import { RemoteServiceModule } from "@nextclaw/remote";
+
+//#region src/shared/services/runtime/service-remote-runtime.service.d.ts
+type ManagedServiceSnapshot = {
+  pid: number;
+  uiUrl: string;
+  apiUrl: string;
+  uiHost: string;
+  uiPort: number;
+  logPath: string;
+};
+type RemoteRuntimeOwnershipClaim = {
+  ok: true;
+  release: () => void;
+} | {
+  ok: false;
+  error: string;
+};
+declare function claimManagedRemoteRuntimeOwnership(params: {
+  localOrigin: string;
+  lockPath?: string;
+  currentPid?: number;
+  now?: () => string;
+  isProcessRunningFn?: (pid: number) => boolean;
+  readServiceStateFn?: () => ManagedServiceState | null;
+}): RemoteRuntimeOwnershipClaim;
+declare function createManagedRemoteModule(params: {
+  loadConfig: () => Config;
+  uiEnabled: boolean;
+  localOrigin: string;
+}): RemoteServiceModule | null;
+declare function createManagedRemoteModuleForUi(params: {
+  loadConfig: () => Config;
+  uiConfig: Pick<Config["ui"], "enabled" | "host" | "port">;
+  localOriginOverride?: string;
+}): RemoteServiceModule | null;
+declare function writeInitialManagedServiceState(params: {
+  config: Config;
+  readinessTimeoutMs: number;
+  snapshot: ManagedServiceSnapshot;
+}): void;
+declare function writeReadyManagedServiceState(params: {
+  readinessTimeoutMs: number;
+  readiness: {
+    ready: boolean;
+    lastProbeError: string | null;
+  };
+  snapshot: ManagedServiceSnapshot;
+}): ManagedServiceState;
+//#endregion
+export { claimManagedRemoteRuntimeOwnership, createManagedRemoteModule, createManagedRemoteModuleForUi, writeInitialManagedServiceState, writeReadyManagedServiceState };

package/dist/shared/services/runtime/service-remote-runtime.service.js

@@ -0,0 +1,173 @@
+import { isProcessRunning, resolveUiApiBase } from "../../utils/cli.utils.js";
+import { managedServiceStateStore } from "../../stores/managed-service-state.store.js";
+import { buildNextclawConfiguredRemoteState, createNextclawRemoteConnector, createNextclawRemoteStatusStore } from "../../../commands/remote/services/remote-runtime-support.service.js";
+import { dirname, resolve } from "node:path";
+import { getDataDir } from "@nextclaw/core";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { RemoteServiceModule } from "@nextclaw/remote";
+//#region src/shared/services/runtime/service-remote-runtime.service.ts
+function resolveRemoteOwnershipLockPath() {
+	return resolve(getDataDir(), "run", "remote-owner.lock.json");
+}
+function readRemoteOwnershipRecord(lockPath) {
+	try {
+		const raw = JSON.parse(readFileSync(lockPath, "utf-8"));
+		if (typeof raw.pid !== "number" || !Number.isFinite(raw.pid)) return null;
+		return {
+			pid: raw.pid,
+			localOrigin: typeof raw.localOrigin === "string" ? raw.localOrigin : "",
+			claimedAt: typeof raw.claimedAt === "string" ? raw.claimedAt : ""
+		};
+	} catch {
+		return null;
+	}
+}
+function removeRemoteOwnershipLock(lockPath) {
+	if (!existsSync(lockPath)) return;
+	try {
+		unlinkSync(lockPath);
+	} catch {
+		try {
+			rmSync(lockPath, { force: true });
+		} catch {}
+	}
+}
+function buildManagedServiceOwnershipError(params) {
+	return `Remote access is already owned by running NextClaw service PID ${params.pid}${params.ownerOrigin ? ` (${params.ownerOrigin})` : ""}. Stop that service or disable remote there before starting another process with the same NEXTCLAW_HOME.`;
+}
+function buildLocalProcessOwnershipError(record) {
+	const originText = record.localOrigin ? ` (${record.localOrigin})` : "";
+	return `Remote access is already owned by local NextClaw process PID ${record.pid}${originText}. Stop that process or use a different NEXTCLAW_HOME before starting another remote-enabled process.`;
+}
+function createRemoteOwnershipRelease(params) {
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		const current = readRemoteOwnershipRecord(params.lockPath);
+		if (!current || current.pid === params.claim.pid && current.claimedAt === params.claim.claimedAt) removeRemoteOwnershipLock(params.lockPath);
+	};
+}
+function detectManagedRemoteOwnershipConflict(params) {
+	const runningService = params.readServiceStateFn();
+	if (!runningService || runningService.pid === params.currentPid || !params.isProcessRunningFn(runningService.pid) || !runningService.remote?.enabled) return null;
+	return buildManagedServiceOwnershipError({
+		pid: runningService.pid,
+		ownerOrigin: runningService.remote.localOrigin ?? runningService.uiUrl
+	});
+}
+function tryClaimRemoteOwnershipLock(params) {
+	for (let attempt = 0; attempt < 2; attempt += 1) try {
+		const fd = openSync(params.lockPath, "wx");
+		writeFileSync(fd, `${JSON.stringify(params.claim, null, 2)}\n`, "utf-8");
+		closeSync(fd);
+		return {
+			ok: true,
+			release: createRemoteOwnershipRelease({
+				lockPath: params.lockPath,
+				claim: params.claim
+			})
+		};
+	} catch (error) {
+		if ((typeof error === "object" && error && "code" in error ? String(error.code) : "") !== "EEXIST") return {
+			ok: false,
+			error: `Failed to claim local remote runtime ownership: ${error instanceof Error ? error.message : String(error)}`
+		};
+		const existing = readRemoteOwnershipRecord(params.lockPath);
+		if (existing && existing.pid !== params.currentPid && params.isProcessRunningFn(existing.pid)) return {
+			ok: false,
+			error: buildLocalProcessOwnershipError(existing)
+		};
+		removeRemoteOwnershipLock(params.lockPath);
+	}
+	return {
+		ok: false,
+		error: "Failed to claim local remote runtime ownership after clearing a stale lock."
+	};
+}
+function claimManagedRemoteRuntimeOwnership(params) {
+	const lockPath = params.lockPath ?? resolveRemoteOwnershipLockPath();
+	const currentPid = params.currentPid ?? process.pid;
+	const now = params.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+	const isProcessRunningFn = params.isProcessRunningFn ?? isProcessRunning;
+	const managedConflict = detectManagedRemoteOwnershipConflict({
+		currentPid,
+		isProcessRunningFn,
+		readServiceStateFn: params.readServiceStateFn ?? managedServiceStateStore.read
+	});
+	if (managedConflict) return {
+		ok: false,
+		error: managedConflict
+	};
+	mkdirSync(dirname(lockPath), { recursive: true });
+	return tryClaimRemoteOwnershipLock({
+		lockPath,
+		claim: {
+			pid: currentPid,
+			localOrigin: params.localOrigin,
+			claimedAt: now()
+		},
+		currentPid,
+		isProcessRunningFn
+	});
+}
+function createManagedRemoteModule(params) {
+	if (!params.uiEnabled) return null;
+	return new RemoteServiceModule({
+		loadConfig: params.loadConfig,
+		uiEnabled: params.uiEnabled,
+		localOrigin: params.localOrigin,
+		statusStore: createNextclawRemoteStatusStore("service"),
+		createConnector: (logger) => createNextclawRemoteConnector({ logger }),
+		claimOwnership: () => claimManagedRemoteRuntimeOwnership({ localOrigin: params.localOrigin }),
+		logger: {
+			info: (message) => console.log(`[remote] ${message}`),
+			warn: (message) => console.warn(`[remote] ${message}`),
+			error: (message) => console.error(`[remote] ${message}`)
+		}
+	});
+}
+function createManagedRemoteModuleForUi(params) {
+	const explicitLocalOrigin = params.localOriginOverride?.trim() ?? process.env.NEXTCLAW_REMOTE_LOCAL_ORIGIN?.trim();
+	return createManagedRemoteModule({
+		loadConfig: params.loadConfig,
+		uiEnabled: params.uiConfig.enabled,
+		localOrigin: explicitLocalOrigin && explicitLocalOrigin.length > 0 ? explicitLocalOrigin.replace(/\/+$/, "") : resolveUiApiBase(params.uiConfig.host, params.uiConfig.port)
+	});
+}
+function writeInitialManagedServiceState(params) {
+	managedServiceStateStore.write({
+		pid: params.snapshot.pid,
+		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		uiUrl: params.snapshot.uiUrl,
+		apiUrl: params.snapshot.apiUrl,
+		uiHost: params.snapshot.uiHost,
+		uiPort: params.snapshot.uiPort,
+		logPath: params.snapshot.logPath,
+		startupLastProbeError: null,
+		startupTimeoutMs: params.readinessTimeoutMs,
+		startupCheckedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		...params.config.remote.enabled ? { remote: buildNextclawConfiguredRemoteState(params.config) } : {}
+	});
+}
+function writeReadyManagedServiceState(params) {
+	const currentState = managedServiceStateStore.read();
+	const state = {
+		pid: params.snapshot.pid,
+		startedAt: currentState?.startedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		uiUrl: params.snapshot.uiUrl,
+		apiUrl: params.snapshot.apiUrl,
+		uiHost: params.snapshot.uiHost,
+		uiPort: params.snapshot.uiPort,
+		logPath: params.snapshot.logPath,
+		startupState: params.readiness.ready ? "ready" : "degraded",
+		startupLastProbeError: params.readiness.lastProbeError,
+		startupTimeoutMs: params.readinessTimeoutMs,
+		startupCheckedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		...currentState?.remote ? { remote: currentState.remote } : {}
+	};
+	managedServiceStateStore.write(state);
+	return state;
+}
+//#endregion
+export { claimManagedRemoteRuntimeOwnership, createManagedRemoteModule, createManagedRemoteModuleForUi, writeInitialManagedServiceState, writeReadyManagedServiceState };

package/dist/shared/services/runtime/utils/skills-loader.utils.d.ts

@@ -0,0 +1,12 @@
+//#region src/shared/services/runtime/utils/skills-loader.utils.d.ts
+type SkillInfo = {
+  name: string;
+  path: string;
+  source: "workspace" | "builtin";
+};
+type SkillsLoaderInstance = {
+  listSkills: (filterUnavailable?: boolean) => SkillInfo[];
+};
+declare function createSkillsLoader(workspace: string): SkillsLoaderInstance | null;
+//#endregion
+export { createSkillsLoader };

package/dist/shared/services/runtime/utils/skills-loader.utils.js

@@ -0,0 +1,9 @@
+import * as NextclawCore from "@nextclaw/core";
+//#region src/shared/services/runtime/utils/skills-loader.utils.ts
+function createSkillsLoader(workspace) {
+	const ctor = NextclawCore.SkillsLoader;
+	if (!ctor) return null;
+	return new ctor(workspace);
+}
+//#endregion
+export { createSkillsLoader };

package/dist/shared/services/session/service-deferred-ncp-agent.service.d.ts

@@ -0,0 +1,14 @@
+import { UiNcpAgent } from "@nextclaw/server";
+import { AgentRuntimeHandle } from "@nextclaw/kernel";
+
+//#region src/shared/services/session/service-deferred-ncp-agent.service.d.ts
+type DeferredUiNcpAgentController = {
+  agent: UiNcpAgent;
+  activate: (agent: AgentRuntimeHandle) => void;
+  clear: () => void;
+  close: () => Promise<void>;
+  isReady: () => boolean;
+};
+declare function createDeferredUiNcpAgent(basePath?: string): DeferredUiNcpAgentController;
+//#endregion
+export { DeferredUiNcpAgentController, createDeferredUiNcpAgent };