@nextclaw/service 0.1.1

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

@@ -0,0 +1,88 @@
+import { resolve } from "node:path";
+import { getDataDir } from "@nextclaw/core";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+//#region src/shared/services/restart/restart-sentinel.service.ts
+const RESTART_SENTINEL_FILENAME = "restart-sentinel.json";
+const PENDING_SYSTEM_EVENTS_KEY = "pending_system_events";
+const RESTART_REASON_MAX_CHARS = 240;
+const RESTART_NOTE_MAX_CHARS = 600;
+const RESTART_OUTBOUND_MAX_CHARS = 1200;
+function trimTo(value, maxChars) {
+	const text = value.trim();
+	if (!text) return "";
+	if (text.length <= maxChars) return text;
+	return `${text.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;
+}
+function normalizeLine(value, maxChars) {
+	const trimmed = trimTo(value, maxChars);
+	return trimmed ? trimmed : null;
+}
+function resolveRestartSentinelPath() {
+	return resolve(getDataDir(), "run", RESTART_SENTINEL_FILENAME);
+}
+async function writeRestartSentinel(payload) {
+	const path = resolveRestartSentinelPath();
+	mkdirSync(resolve(path, ".."), { recursive: true });
+	writeFileSync(path, `${JSON.stringify({
+		version: 1,
+		payload
+	}, null, 2)}\n`, "utf-8");
+	return path;
+}
+async function consumeRestartSentinel() {
+	const path = resolveRestartSentinelPath();
+	if (!existsSync(path)) return null;
+	try {
+		const raw = readFileSync(path, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (!parsed || parsed.version !== 1 || !parsed.payload) {
+			rmSync(path, { force: true });
+			return null;
+		}
+		rmSync(path, { force: true });
+		return parsed;
+	} catch {
+		rmSync(path, { force: true });
+		return null;
+	}
+}
+function summarizeRestartSentinel(payload) {
+	const reason = normalizeLine(payload.stats?.reason ?? "", RESTART_REASON_MAX_CHARS);
+	if (payload.kind === "update.run") return payload.status === "ok" ? "✅ NextClaw update completed and service restarted." : "⚠️ NextClaw update finished with issues.";
+	if (payload.kind === "config.apply" || payload.kind === "config.patch") return payload.status === "ok" ? "✅ Config applied and service restarted." : "⚠️ Config change restart finished with issues.";
+	if (reason) return `Gateway restart complete (${reason}).`;
+	return "Gateway restart complete.";
+}
+function formatRestartSentinelMessage(payload) {
+	const lines = [summarizeRestartSentinel(payload)];
+	const note = normalizeLine(payload.message ?? "", RESTART_NOTE_MAX_CHARS);
+	if (note) lines.push(note);
+	const reason = normalizeLine(payload.stats?.reason ?? "", RESTART_REASON_MAX_CHARS);
+	if (reason && !lines.some((line) => line.includes(reason))) lines.push(`Reason: ${reason}`);
+	return trimTo(lines.join("\n").trim(), RESTART_OUTBOUND_MAX_CHARS);
+}
+function parseSessionKey(sessionKey) {
+	const value = sessionKey?.trim();
+	if (!value) return null;
+	const separator = value.indexOf(":");
+	if (separator <= 0 || separator >= value.length - 1) return null;
+	return {
+		channel: value.slice(0, separator),
+		chatId: value.slice(separator + 1)
+	};
+}
+function enqueuePendingSystemEvent(sessionManager, sessionKey, message) {
+	const text = message.trim();
+	if (!text) return;
+	const session = sessionManager.getOrCreate(sessionKey);
+	const queueRaw = session.metadata[PENDING_SYSTEM_EVENTS_KEY];
+	const queue = Array.isArray(queueRaw) ? queueRaw.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean) : [];
+	if (queue.at(-1) === text) return;
+	queue.push(text);
+	if (queue.length > 20) queue.splice(0, queue.length - 20);
+	session.metadata[PENDING_SYSTEM_EVENTS_KEY] = queue;
+	session.updatedAt = /* @__PURE__ */ new Date();
+	sessionManager.save(session);
+}
+//#endregion
+export { consumeRestartSentinel, enqueuePendingSystemEvent, formatRestartSentinelMessage, parseSessionKey, resolveRestartSentinelPath, summarizeRestartSentinel, writeRestartSentinel };

package/dist/shared/services/restart/runtime-restart-request.service.d.ts

@@ -0,0 +1,24 @@
+import { RestartResult } from "./restart-coordinator.service.js";
+import { RequestRestartParams } from "../../types/cli.types.js";
+
+//#region src/shared/services/restart/runtime-restart-request.service.d.ts
+type RuntimeRestartRequestServiceDeps = {
+  armManagedServiceRelaunch: (params: {
+    delayMs?: number;
+    reason: string;
+    strategy?: RequestRestartParams["strategy"];
+  }) => void;
+  requestRestartFromCoordinator: (params: {
+    delayMs?: number;
+    manualMessage?: string;
+    reason: string;
+    strategy?: RequestRestartParams["strategy"];
+  }) => Promise<RestartResult>;
+};
+declare class RuntimeRestartRequestService {
+  private readonly deps;
+  constructor(deps: RuntimeRestartRequestServiceDeps);
+  readonly run: (params: RequestRestartParams) => Promise<void>;
+}
+//#endregion
+export { RuntimeRestartRequestService };

package/dist/shared/services/restart/runtime-restart-request.service.js

@@ -0,0 +1,42 @@
+import { pendingRestartStore } from "../../stores/pending-restart.store.js";
+//#region src/shared/services/restart/runtime-restart-request.service.ts
+var RuntimeRestartRequestService = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	run = async (params) => {
+		const { changedPaths, delayMs, manualMessage, mode, reason, silentOnServiceRestart, strategy } = params;
+		if (mode === "notify") {
+			pendingRestartStore.mark({
+				changedPaths,
+				manualMessage,
+				reason
+			});
+			console.warn(manualMessage);
+			return;
+		}
+		this.deps.armManagedServiceRelaunch({
+			reason,
+			strategy,
+			delayMs
+		});
+		const result = await this.deps.requestRestartFromCoordinator({
+			reason,
+			strategy,
+			delayMs,
+			manualMessage
+		});
+		if (result.status === "manual-required" || result.status === "restart-in-progress") {
+			console.log(result.message);
+			return;
+		}
+		pendingRestartStore.clear();
+		if (result.status === "service-restarted") {
+			if (!silentOnServiceRestart) console.log(result.message);
+			return;
+		}
+		console.warn(result.message);
+	};
+};
+//#endregion
+export { RuntimeRestartRequestService };

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

@@ -0,0 +1,37 @@
+import { RequestRestartParams } from "../../types/cli.types.js";
+import { StartServiceOptions } from "./service-managed-startup.service.js";
+import { describeUnmanagedHealthyTargetMessage } from "../../utils/service-port-probe.utils.js";
+import { buildMarketplaceSkillInstallArgs, pickUserFacingCommandSummary } from "../../utils/marketplace/service-marketplace-helpers.utils.js";
+import * as NextclawCore from "@nextclaw/core";
+
+//#region src/shared/services/runtime/runtime-command.service.d.ts
+type Config$1 = NextclawCore.Config;
+declare class RuntimeCommandService {
+  private deps;
+  private loggingInstalled;
+  private readonly managedServiceCommandService;
+  constructor(deps: {
+    requestRestart: (params: RequestRestartParams) => Promise<void>;
+    initializeAgentHomeDirectory: (homeDirectory: string) => void;
+  });
+  startGateway: (options?: {
+    uiOverrides?: Partial<Config$1["ui"]>;
+    uiStaticDir?: string | null;
+  }) => Promise<void>;
+  startService: (options: StartServiceOptions) => Promise<void>;
+  stopService: () => Promise<void>;
+  runForeground: (options: {
+    uiOverrides: Partial<Config$1["ui"]>;
+    open: boolean;
+  }) => Promise<void>;
+  private installBuiltinMarketplaceSkill;
+  private mergeCommandOutput;
+  private runCliSubcommand;
+  private runCommand;
+  private ensureRuntimeLoggingInstalled;
+  private checkUiPortPreflight;
+  private printPublicUiUrls;
+  private printServiceControlHints;
+}
+//#endregion
+export { RuntimeCommandService, buildMarketplaceSkillInstallArgs, describeUnmanagedHealthyTargetMessage, pickUserFacingCommandSummary };

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

@@ -0,0 +1,163 @@
+import { isLoopbackHost, resolvePublicIp } from "../../utils/cli.utils.js";
+import { describeUnmanagedHealthyTargetMessage, inspectUiTarget } from "../../utils/service-port-probe.utils.js";
+import { buildMarketplaceSkillInstallArgs, pickUserFacingCommandSummary } from "../../utils/marketplace/service-marketplace-helpers.utils.js";
+import { resolveCliSubcommandEntry } from "../../utils/marketplace/cli-subcommand-launch.utils.js";
+import { ManagedServiceCommandService } from "./service-managed-startup.service.js";
+import { NextclawGatewayRuntime } from "../gateway/nextclaw-gateway-runtime.service.js";
+import { createSkillsLoader } from "./utils/skills-loader.utils.js";
+import { spawn } from "node:child_process";
+import * as NextclawCore from "@nextclaw/core";
+//#region src/shared/services/runtime/runtime-command.service.ts
+const { getWorkspacePath: getWorkspacePath$1, loadConfig: loadConfig$1 } = NextclawCore;
+var RuntimeCommandService = class {
+	loggingInstalled = false;
+	managedServiceCommandService = new ManagedServiceCommandService({
+		startGateway: async (options) => await this.startGateway(options),
+		printPublicUiUrls: async (host, port) => await this.printPublicUiUrls(host, port),
+		printServiceControlHints: () => this.printServiceControlHints(),
+		checkUiPortPreflight: async (params) => await this.checkUiPortPreflight(params)
+	});
+	constructor(deps) {
+		this.deps = deps;
+	}
+	startGateway = async (options = {}) => {
+		this.ensureRuntimeLoggingInstalled();
+		await new NextclawGatewayRuntime({
+			requestRestart: this.deps.requestRestart,
+			initializeAgentHomeDirectory: this.deps.initializeAgentHomeDirectory,
+			startService: this.startService,
+			stopService: this.stopService,
+			runCliSubcommand: this.runCliSubcommand,
+			installBuiltinMarketplaceSkill: this.installBuiltinMarketplaceSkill
+		}, options).start();
+	};
+	startService = async (options) => {
+		await this.managedServiceCommandService.startService(options);
+	};
+	stopService = async () => {
+		await this.managedServiceCommandService.stopService();
+	};
+	runForeground = async (options) => {
+		await this.managedServiceCommandService.runForeground(options);
+	};
+	installBuiltinMarketplaceSkill = (slug, _force) => {
+		if (!(createSkillsLoader(getWorkspacePath$1(loadConfig$1().agents.defaults.workspace))?.listSkills(false) ?? []).find((skill) => skill.name === slug && skill.source === "builtin")) return null;
+		return { message: `${slug} is already available (built-in)` };
+	};
+	mergeCommandOutput = (stdout, stderr) => {
+		return `${stdout}\n${stderr}`.trim();
+	};
+	runCliSubcommand = (args, timeoutMs = 18e4) => {
+		const cliEntry = resolveCliSubcommandEntry({
+			argvEntry: process.argv[1],
+			importMetaUrl: import.meta.url
+		});
+		return this.runCommand(process.execPath, [
+			...process.execArgv,
+			cliEntry,
+			...args
+		], {
+			cwd: process.cwd(),
+			timeoutMs
+		}).then((result) => this.mergeCommandOutput(result.stdout, result.stderr));
+	};
+	runCommand = (command, args, options = {}) => {
+		const timeoutMs = options.timeoutMs ?? 18e4;
+		return new Promise((resolvePromise, rejectPromise) => {
+			const child = spawn(command, args, {
+				cwd: options.cwd ?? process.cwd(),
+				env: process.env,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			});
+			let stdout = "";
+			let stderr = "";
+			child.stdout?.setEncoding("utf-8");
+			child.stderr?.setEncoding("utf-8");
+			child.stdout?.on("data", (chunk) => {
+				stdout += chunk;
+			});
+			child.stderr?.on("data", (chunk) => {
+				stderr += chunk;
+			});
+			const timer = setTimeout(() => {
+				child.kill("SIGTERM");
+				rejectPromise(/* @__PURE__ */ new Error(`command timed out after ${timeoutMs}ms`));
+			}, timeoutMs);
+			child.on("error", (error) => {
+				clearTimeout(timer);
+				rejectPromise(/* @__PURE__ */ new Error(`failed to start command: ${String(error)}`));
+			});
+			child.on("close", (code) => {
+				clearTimeout(timer);
+				const output = this.mergeCommandOutput(stdout, stderr);
+				if (code === 0) {
+					resolvePromise({
+						stdout,
+						stderr
+					});
+					return;
+				}
+				rejectPromise(new Error(output || `command failed with code ${code ?? 1}`));
+			});
+		});
+	};
+	ensureRuntimeLoggingInstalled = () => {
+		if (this.loggingInstalled) return;
+		NextclawCore.configureAppLogging({
+			installConsoleMirror: true,
+			installProcessCrashMonitor: true
+		});
+		this.loggingInstalled = true;
+	};
+	checkUiPortPreflight = async (params) => {
+		const target = await inspectUiTarget(params);
+		if (target.state === "available") return {
+			ok: true,
+			reusedExistingHealthyTarget: false
+		};
+		if (target.state === "healthy-existing") return {
+			ok: true,
+			reusedExistingHealthyTarget: true
+		};
+		const lines = [`Port probe: ${target.availabilityDetail}`];
+		if (target.probeError) lines.push(`Health probe: ${target.probeError}`);
+		lines.push("The port is occupied by a process that does not answer as a healthy NextClaw HTTP server.");
+		lines.push(`Fix: free port ${params.port} or start NextClaw with another port via --ui-port <port>.`);
+		lines.push(`Inspect locally with: ss -ltnp | grep ${params.port} || lsof -iTCP:${params.port} -sTCP:LISTEN -n -P`);
+		return {
+			ok: false,
+			message: lines.join("\n")
+		};
+	};
+	printPublicUiUrls = async (host, port) => {
+		if (isLoopbackHost(host)) {
+			console.log("Public URL: disabled (UI host is loopback). Current release expects public exposure; run nextclaw restart.");
+			return;
+		}
+		const publicIp = await resolvePublicIp();
+		if (!publicIp) {
+			console.log("Public URL: UI is exposed, but automatic public IP detection failed.");
+			return;
+		}
+		const publicBase = `http://${publicIp}:${port}`;
+		console.log(`Public UI (if firewall/NAT allows): ${publicBase}`);
+		console.log(`Public API (if firewall/NAT allows): ${publicBase}/api`);
+		console.log(`Public deploy note: NextClaw serves plain HTTP on ${port}.`);
+		console.log(`For https:// or standard 80/443 access, terminate TLS in Nginx/Caddy and proxy to http://127.0.0.1:${port}.`);
+		console.log(`If a reverse proxy returns 502, verify its upstream is http://127.0.0.1:${port} (not https://, not a stale port, and not a stopped process).`);
+	};
+	printServiceControlHints = () => {
+		console.log("Service controls:");
+		console.log("  - Check status: NextClaw status");
+		console.log("  - If you need to stop the service, run: NextClaw stop");
+		console.log("  - View log paths: NextClaw logs path");
+		console.log("  - Tail recent logs: NextClaw logs tail");
+		console.log("  - Check autostart: NextClaw service autostart status --user");
+	};
+};
+//#endregion
+export { RuntimeCommandService, buildMarketplaceSkillInstallArgs, describeUnmanagedHealthyTargetMessage, pickUserFacingCommandSummary };

package/dist/shared/services/runtime/runtime-config-init.service.d.ts

@@ -0,0 +1,4 @@
+//#region src/shared/services/runtime/runtime-config-init.service.d.ts
+declare function initializeConfigIfMissing(configPath?: string): boolean;
+//#endregion
+export { initializeConfigIfMissing };

package/dist/shared/services/runtime/runtime-config-init.service.js

@@ -0,0 +1,10 @@
+import { getConfigPath, loadConfig } from "@nextclaw/core";
+import { existsSync } from "node:fs";
+//#region src/shared/services/runtime/runtime-config-init.service.ts
+function initializeConfigIfMissing(configPath = getConfigPath()) {
+	if (existsSync(configPath)) return false;
+	loadConfig(configPath);
+	return true;
+}
+//#endregion
+export { initializeConfigIfMissing };

package/dist/shared/services/runtime/service-managed-startup.service.d.ts

@@ -0,0 +1,146 @@
+import { ManagedServiceState } from "../../stores/managed-service-state.store.js";
+import { localUiRuntimeStore } from "../../stores/local-ui-runtime.store.js";
+import { spawn } from "node:child_process";
+import * as NextclawCore from "@nextclaw/core";
+
+//#region src/shared/services/runtime/service-managed-startup.service.d.ts
+type Config$1 = NextclawCore.Config;
+type StartServiceOptions = {
+  uiOverrides: Partial<Config$1["ui"]>;
+  open: boolean;
+  startupTimeoutMs?: number;
+};
+type ManagedServiceSnapshot = {
+  pid: number;
+  uiUrl: string;
+  apiUrl: string;
+  uiHost: string;
+  uiPort: number;
+  logPath: string;
+};
+declare function resolveManagedServiceReadySnapshot(params: {
+  snapshot: ManagedServiceSnapshot;
+  readLocalUiRuntimeState?: typeof localUiRuntimeStore.read;
+  isProcessRunningFn?: (pid: number) => boolean;
+}): ManagedServiceSnapshot;
+declare function resolveManagedServiceUiBinding(state: ManagedServiceState): {
+  host: string;
+  port: number;
+};
+declare function resolveSessionRouteCandidate(params: {
+  session: unknown;
+  normalizeOptionalString: (value: unknown) => string | undefined;
+}): {
+  key: string;
+  updatedAt: number;
+} | null;
+declare function spawnManagedService(params: {
+  appName: string;
+  config: NextclawCore.Config;
+  uiConfig: {
+    host: string;
+    port: number;
+  };
+  uiUrl: string;
+  apiUrl: string;
+  healthUrl: string;
+  startupTimeoutMs?: number;
+  resolveStartupTimeoutMs: (overrideTimeoutMs: number | undefined) => number;
+  appendStartupStage: (logPath: string, message: string) => void;
+  printStartupFailureDiagnostics: (params: {
+    uiUrl: string;
+    apiUrl: string;
+    healthUrl: string;
+    logPath: string;
+    lastProbeError: string | null;
+  }) => void;
+  resolveServiceLogPath: () => string;
+}): {
+  child: ReturnType<typeof spawn>;
+  logPath: string;
+  readinessTimeoutMs: number;
+  quickPhaseTimeoutMs: number;
+  extendedPhaseTimeoutMs: number;
+  snapshot: ManagedServiceSnapshot;
+} | null;
+declare function waitForManagedServiceReadiness(params: {
+  appName: string;
+  childPid: number;
+  healthUrl: string;
+  logPath: string;
+  readinessTimeoutMs: number;
+  quickPhaseTimeoutMs: number;
+  extendedPhaseTimeoutMs: number;
+  appendStartupStage: (logPath: string, message: string) => void;
+  waitForBackgroundServiceReady: (params: {
+    pid: number;
+    healthUrl: string;
+    timeoutMs: number;
+  }) => Promise<{
+    ready: boolean;
+    lastProbeError: string | null;
+  }>;
+  isProcessRunning: (pid: number) => boolean;
+}): Promise<{
+  ready: boolean;
+  lastProbeError: string | null;
+}>;
+declare function reportManagedServiceStart(params: {
+  appName: string;
+  state: {
+    pid: number;
+    logPath: string;
+  };
+  uiConfig: {
+    host: string;
+    port: number;
+  };
+  uiUrl: string;
+  apiUrl: string;
+  readinessTimeoutMs: number;
+  readiness: {
+    ready: boolean;
+    lastProbeError: string | null;
+  };
+  printPublicUiUrls: (host: string, port: number) => Promise<void>;
+  printServiceControlHints: () => void;
+}): Promise<void>;
+declare class ManagedServiceCommandService {
+  private readonly deps;
+  private readonly loggingRuntime;
+  private readonly serviceLogger;
+  constructor(deps: {
+    startGateway: (options: {
+      uiOverrides: Partial<Config$1["ui"]>;
+      uiStaticDir?: string | null;
+    }) => Promise<void>;
+    printPublicUiUrls: (host: string, port: number) => Promise<void>;
+    printServiceControlHints: () => void;
+    checkUiPortPreflight: (params: {
+      host: string;
+      port: number;
+      healthUrl: string;
+    }) => Promise<{
+      ok: true;
+      reusedExistingHealthyTarget: boolean;
+    } | {
+      ok: false;
+      message: string;
+    }>;
+  });
+  runForeground: (options: {
+    uiOverrides: Partial<Config$1["ui"]>;
+    open: boolean;
+  }) => Promise<void>;
+  startService: (options: StartServiceOptions) => Promise<void>;
+  stopService: () => Promise<void>;
+  private handleExistingManagedService;
+  private reuseExistingHealthyStartTarget;
+  private startNewManagedServiceTarget;
+  private waitForBackgroundServiceReady;
+  private resolveStartupTimeoutMs;
+  private appendStartupStage;
+  private printStartupFailureDiagnostics;
+}
+//#endregion
+export { ManagedServiceCommandService, ManagedServiceSnapshot, StartServiceOptions, reportManagedServiceStart, resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate, spawnManagedService, waitForManagedServiceReadiness };