@nextclaw/server 0.12.5 → 0.12.7

package/dist/index.d.ts

@@ -349,6 +349,37 @@ declare class UiAuthService {
   };
 }
 //#endregion
+//#region src/ui/runtime-control.types.d.ts
+type RuntimeControlEnvironment = "desktop-embedded" | "managed-local-service" | "self-hosted-web" | "shared-web";
+type RuntimeLifecycleState = "healthy" | "starting-service" | "restarting-service" | "stopping-service" | "restarting-app" | "recovering" | "unavailable" | "failed";
+type RuntimeActionImpact = "none" | "brief-ui-disconnect" | "full-app-relaunch";
+type RuntimeActionCapability = {
+  available: boolean;
+  requiresConfirmation: boolean;
+  impact: RuntimeActionImpact;
+  reasonIfUnavailable?: string;
+};
+type RuntimeServiceState = "running" | "stopped" | "starting" | "stopping" | "restarting" | "unknown";
+type RuntimeControlView = {
+  environment: RuntimeControlEnvironment;
+  lifecycle: RuntimeLifecycleState;
+  serviceState: RuntimeServiceState;
+  canStartService: RuntimeActionCapability;
+  canRestartService: RuntimeActionCapability;
+  canStopService: RuntimeActionCapability;
+  canRestartApp: RuntimeActionCapability;
+  ownerLabel?: string;
+  managementHint?: string;
+  message?: string;
+};
+type RuntimeControlAction = "start-service" | "restart-service" | "stop-service" | "restart-app";
+type RuntimeControlActionResult = {
+  accepted: boolean;
+  action: RuntimeControlAction;
+  lifecycle: RuntimeLifecycleState;
+  message: string;
+};
+//#endregion
 //#region src/ui/ui-routes/types.d.ts
 type UiRouterOptions = {
   configPath: string;
@@ -362,6 +393,7 @@ type UiRouterOptions = {
   ncpSessionService?: UiNcpSessionService;
   authService?: UiAuthService;
   remoteAccess?: UiRemoteAccessHost;
+  runtimeControl?: UiRuntimeControlHost;
   getBootstrapStatus?: () => BootstrapStatusView;
   getPluginChannelBindings?: () => PluginChannelBinding[];
   getPluginUiMetadata?: () => PluginUiMetadata[];
@@ -377,6 +409,12 @@ type UiRemoteAccessHost = {
   runDoctor: () => Promise<RemoteDoctorView>;
   controlService: (action: RemoteServiceAction) => Promise<RemoteServiceActionResult>;
 };
+type UiRuntimeControlHost = {
+  getControl: () => Promise<RuntimeControlView> | RuntimeControlView;
+  startService: () => Promise<RuntimeControlActionResult> | RuntimeControlActionResult;
+  restartService: () => Promise<RuntimeControlActionResult> | RuntimeControlActionResult;
+  stopService: () => Promise<RuntimeControlActionResult> | RuntimeControlActionResult;
+};
 //#endregion
 //#region src/ui/chat-session-type.types.d.ts
 type ChatSessionTypeCtaView = {
@@ -760,6 +798,12 @@ type AgentBindingView = {
 type SessionConfigView = {
   dmScope?: "main" | "per-peer" | "per-channel-peer" | "per-account-channel-peer";
 };
+type RuntimeEntryView = {
+  enabled?: boolean;
+  label?: string;
+  type: string;
+  config?: Record<string, unknown>;
+};
 type SessionEntryView = {
   key: string;
   createdAt: string;
@@ -808,6 +852,7 @@ type SessionPatchUpdate = {
   preferredThinking?: ThinkingLevel | null;
   sessionType?: string | null;
   projectRoot?: string | null;
+  uiReadAt?: string | null;
   clearHistory?: boolean;
 };
 type SessionSkillEntryView = {
@@ -843,6 +888,15 @@ type ServerPathBrowseView = {
   breadcrumbs: ServerPathBreadcrumbView[];
   entries: ServerPathEntryView[];
 };
+type ServerPathReadView = {
+  requestedPath: string;
+  resolvedPath: string;
+  kind: "text" | "markdown" | "binary";
+  sizeBytes: number;
+  truncated: boolean;
+  text?: string;
+  languageHint?: string | null;
+};
 type CronScheduleView = {
   kind: "at";
   atMs?: number | null;
@@ -913,6 +967,9 @@ type RuntimeConfigUpdate = {
       engine?: string;
       engineConfig?: Record<string, unknown>;
     };
+    runtimes?: {
+      entries?: Record<string, RuntimeEntryView> | null;
+    };
     list?: AgentProfileView[];
   };
   bindings?: AgentBindingView[];
@@ -1001,6 +1058,9 @@ type ConfigView = {
       contextTokens?: number;
       maxToolIterations?: number;
     };
+    runtimes?: {
+      entries?: Record<string, RuntimeEntryView>;
+    };
     list?: AgentProfileView[];
     context?: {
       bootstrap?: {
@@ -1208,6 +1268,7 @@ type UiServerOptions = {
   ncpAgent?: UiNcpAgent;
   ncpSessionService?: UiNcpSessionService;
   remoteAccess?: UiRemoteAccessHost;
+  runtimeControl?: UiRuntimeControlHost;
   getBootstrapStatus?: () => BootstrapStatusView;
   getPluginChannelBindings?: () => PluginChannelBinding[];
   getPluginUiMetadata?: () => PluginUiMetadata[];
@@ -1287,4 +1348,4 @@ declare function getUiBridgeSecretPath(): string;
 declare function readUiBridgeSecret(): string | null;
 declare function ensureUiBridgeSecret(): string;
 //#endregion
-export { AgentBindingView, AgentCreateRequest, AgentDeleteResult, AgentProfileView, AgentUpdateRequest, ApiError, ApiResponse, AppMetaView, AuthEnabledUpdateRequest, AuthLoginRequest, AuthPasswordUpdateRequest, AuthSetupRequest, AuthStatusView, BindingPeerView, BochaFreshnessValue, BootstrapPhase, BootstrapRemoteState, BootstrapStageState, BootstrapStatusView, ChannelAuthPollRequest, ChannelAuthPollResult, ChannelAuthStartRequest, ChannelAuthStartResult, ChannelSpecView, type ChatSessionTypeCtaView, type ChatSessionTypeOptionView, type ChatSessionTypesView, ConfigActionExecuteRequest, ConfigActionExecuteResult, ConfigActionManifest, ConfigActionType, ConfigMetaView, ConfigSchemaResponse, ConfigUiHint, ConfigUiHints, ConfigView, CronActionResult, CronCreateRequest, CronCreateResult, CronEnableRequest, CronJobStateView, CronJobView, CronListView, CronPayloadView, CronRunRequest, CronScheduleView, DEFAULT_SESSION_TYPE, MarketplaceApiConfig, MarketplaceInstallKind, MarketplaceInstallSkillParams, MarketplaceInstallSpec, MarketplaceInstalledRecord, MarketplaceInstalledView, MarketplaceInstaller, MarketplaceItemSummary, MarketplaceItemType, MarketplaceItemView, MarketplaceListView, MarketplaceLocalizedTextMap, MarketplaceMcpContentView, MarketplaceMcpDoctorResult, MarketplaceMcpInstallKind, MarketplaceMcpInstallRequest, MarketplaceMcpInstallResult, MarketplaceMcpInstallSpec, MarketplaceMcpManageAction, MarketplaceMcpManageRequest, MarketplaceMcpManageResult, MarketplaceMcpTemplateInput, MarketplacePluginContentView, MarketplacePluginInstallKind, MarketplacePluginInstallRequest, MarketplacePluginInstallResult, MarketplacePluginManageAction, MarketplacePluginManageRequest, MarketplacePluginManageResult, MarketplaceRecommendationView, MarketplaceSkillContentView, MarketplaceSkillInstallKind, MarketplaceSkillInstallRequest, MarketplaceSkillInstallResult, MarketplaceSkillManageAction, MarketplaceSkillManageRequest, MarketplaceSkillManageResult, MarketplaceSort, NcpSessionSkillsView, ProviderAuthImportResult, ProviderAuthPollRequest, ProviderAuthPollResult, ProviderAuthStartRequest, ProviderAuthStartResult, ProviderConfigUpdate, ProviderConfigView, ProviderConnectionTestRequest, ProviderConnectionTestResult, ProviderCreateRequest, ProviderCreateResult, ProviderDeleteResult, ProviderSpecView, RemoteAccessView, RemoteAccountProfileUpdateRequest, RemoteAccountView, RemoteBrowserAuthPollRequest, RemoteBrowserAuthPollResult, RemoteBrowserAuthStartRequest, RemoteBrowserAuthStartResult, RemoteDoctorCheckView, RemoteDoctorView, RemoteLoginRequest, RemoteRuntimeView, RemoteServiceAction, RemoteServiceActionResult, RemoteServiceView, RemoteSettingsUpdateRequest, RemoteSettingsView, RuntimeConfigUpdate, SearchConfigUpdate, SearchConfigView, SearchProviderConfigView, SearchProviderName, SearchProviderSpecView, SecretProviderEnvView, SecretProviderExecView, SecretProviderFileView, SecretProviderView, SecretRefView, SecretSourceView, SecretsConfigUpdate, SecretsView, ServerPathBreadcrumbView, ServerPathBrowseView, ServerPathEntryView, SessionConfigView, SessionEntryView, SessionEventView, SessionHistoryView, SessionMessageView, SessionPatchUpdate, SessionPatchValidationError, SessionSkillEntryView, SessionTypeDescribeParams, SessionsListView, TavilySearchDepthValue, UiNcpAgent, UiNcpAssetPutView, UiNcpAssetView, UiNcpSessionListView, UiNcpSessionMessagesView, UiNcpSessionService, UiNcpStoredAssetRecord, type UiRemoteAccessHost, UiServerEvent, UiServerHandle, UiServerOptions, buildConfigMeta, buildConfigSchemaView, buildConfigView, createCustomProvider, createUiRouter, deleteCustomProvider, deleteSession, ensureUiBridgeSecret, executeConfigAction, getSessionHistory, getUiBridgeSecretPath, listSessions, loadConfigOrDefault, patchSession, readUiBridgeSecret, startUiServer, testProviderConnection, updateChannel, updateModel, updateProvider, updateRuntime, updateSearch, updateSecrets };
+export { AgentBindingView, AgentCreateRequest, AgentDeleteResult, AgentProfileView, AgentUpdateRequest, ApiError, ApiResponse, AppMetaView, AuthEnabledUpdateRequest, AuthLoginRequest, AuthPasswordUpdateRequest, AuthSetupRequest, AuthStatusView, BindingPeerView, BochaFreshnessValue, BootstrapPhase, BootstrapRemoteState, BootstrapStageState, BootstrapStatusView, ChannelAuthPollRequest, ChannelAuthPollResult, ChannelAuthStartRequest, ChannelAuthStartResult, ChannelSpecView, type ChatSessionTypeCtaView, type ChatSessionTypeOptionView, type ChatSessionTypesView, ConfigActionExecuteRequest, ConfigActionExecuteResult, ConfigActionManifest, ConfigActionType, ConfigMetaView, ConfigSchemaResponse, ConfigUiHint, ConfigUiHints, ConfigView, CronActionResult, CronCreateRequest, CronCreateResult, CronEnableRequest, CronJobStateView, CronJobView, CronListView, CronPayloadView, CronRunRequest, CronScheduleView, DEFAULT_SESSION_TYPE, MarketplaceApiConfig, MarketplaceInstallKind, MarketplaceInstallSkillParams, MarketplaceInstallSpec, MarketplaceInstalledRecord, MarketplaceInstalledView, MarketplaceInstaller, MarketplaceItemSummary, MarketplaceItemType, MarketplaceItemView, MarketplaceListView, MarketplaceLocalizedTextMap, MarketplaceMcpContentView, MarketplaceMcpDoctorResult, MarketplaceMcpInstallKind, MarketplaceMcpInstallRequest, MarketplaceMcpInstallResult, MarketplaceMcpInstallSpec, MarketplaceMcpManageAction, MarketplaceMcpManageRequest, MarketplaceMcpManageResult, MarketplaceMcpTemplateInput, MarketplacePluginContentView, MarketplacePluginInstallKind, MarketplacePluginInstallRequest, MarketplacePluginInstallResult, MarketplacePluginManageAction, MarketplacePluginManageRequest, MarketplacePluginManageResult, MarketplaceRecommendationView, MarketplaceSkillContentView, MarketplaceSkillInstallKind, MarketplaceSkillInstallRequest, MarketplaceSkillInstallResult, MarketplaceSkillManageAction, MarketplaceSkillManageRequest, MarketplaceSkillManageResult, MarketplaceSort, NcpSessionSkillsView, ProviderAuthImportResult, ProviderAuthPollRequest, ProviderAuthPollResult, ProviderAuthStartRequest, ProviderAuthStartResult, ProviderConfigUpdate, ProviderConfigView, ProviderConnectionTestRequest, ProviderConnectionTestResult, ProviderCreateRequest, ProviderCreateResult, ProviderDeleteResult, ProviderSpecView, RemoteAccessView, RemoteAccountProfileUpdateRequest, RemoteAccountView, RemoteBrowserAuthPollRequest, RemoteBrowserAuthPollResult, RemoteBrowserAuthStartRequest, RemoteBrowserAuthStartResult, RemoteDoctorCheckView, RemoteDoctorView, RemoteLoginRequest, RemoteRuntimeView, RemoteServiceAction, RemoteServiceActionResult, RemoteServiceView, RemoteSettingsUpdateRequest, RemoteSettingsView, RuntimeActionCapability, RuntimeActionImpact, RuntimeConfigUpdate, RuntimeControlAction, RuntimeControlActionResult, RuntimeControlEnvironment, RuntimeControlView, RuntimeEntryView, RuntimeLifecycleState, RuntimeServiceState, SearchConfigUpdate, SearchConfigView, SearchProviderConfigView, SearchProviderName, SearchProviderSpecView, SecretProviderEnvView, SecretProviderExecView, SecretProviderFileView, SecretProviderView, SecretRefView, SecretSourceView, SecretsConfigUpdate, SecretsView, ServerPathBreadcrumbView, ServerPathBrowseView, ServerPathEntryView, ServerPathReadView, SessionConfigView, SessionEntryView, SessionEventView, SessionHistoryView, SessionMessageView, SessionPatchUpdate, SessionPatchValidationError, SessionSkillEntryView, SessionTypeDescribeParams, SessionsListView, TavilySearchDepthValue, UiNcpAgent, UiNcpAssetPutView, UiNcpAssetView, UiNcpSessionListView, UiNcpSessionMessagesView, UiNcpSessionService, UiNcpStoredAssetRecord, type UiRemoteAccessHost, type UiRuntimeControlHost, UiServerEvent, UiServerHandle, UiServerOptions, buildConfigMeta, buildConfigSchemaView, buildConfigView, createCustomProvider, createUiRouter, deleteCustomProvider, deleteSession, ensureUiBridgeSecret, executeConfigAction, getSessionHistory, getUiBridgeSecretPath, listSessions, loadConfigOrDefault, patchSession, readUiBridgeSecret, startUiServer, testProviderConnection, updateChannel, updateModel, updateProvider, updateRuntime, updateSearch, updateSecrets };

package/dist/index.js

@@ -3,8 +3,8 @@ import { compress } from "hono/compress";
 import { serve } from "@hono/node-server";
 import { WebSocket, WebSocketServer } from "ws";
 import fs, { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { readFile, readdir, realpath, stat } from "node:fs/promises";
-import path, { dirname, isAbsolute, join, parse, resolve } from "node:path";
+import { open, readFile, readdir, realpath, stat } from "node:fs/promises";
+import path, { dirname, extname, isAbsolute, join, parse, resolve } from "node:path";
 import * as NextclawCore from "@nextclaw/core";
 import { ConfigSchema, DEFAULT_WORKSPACE_PATH, LiteLLMProvider, SessionManager, buildConfigSchema, createAgentProfile, expandHome, findEffectiveAgentProfile, getDataDir, getPackageVersion, getProviderName, getWorkspacePathFromConfig, hasSecretRef, isSensitiveConfigPath, loadConfig, normalizeThinkingLevels, parseThinkingLevel, probeFeishu, readAgentAvatarContent, removeAgentProfile, resolveEffectiveAgentProfiles, saveConfig, updateAgentProfile } from "@nextclaw/core";
 import { createHash, randomBytes, randomUUID, scryptSync, timingSafeEqual } from "node:crypto";
@@ -1331,7 +1331,7 @@ function buildConfigView(config, options) {
 	const providers = {};
 	for (const [name, provider] of Object.entries(config.providers)) providers[name] = toProviderView(config, provider, name, uiHints, findServerBuiltinProviderByName(name));
 	return {
-		agents: config.agents,
+		agents: sanitizePublicConfigValue(config.agents, "agents", uiHints),
 		providers,
 		search: buildSearchView(config),
 		channels: sanitizePublicConfigValue(projectedChannels, "channels", uiHints),
@@ -1348,6 +1348,40 @@ function buildConfigView(config, options) {
 		}
 	};
 }
+function normalizeRuntimeEntries(entries) {
+	if (!entries || typeof entries !== "object" || Array.isArray(entries)) return {};
+	const normalized = {};
+	for (const [rawId, rawEntry] of Object.entries(entries)) {
+		const id = rawId.trim();
+		if (!id || !rawEntry || typeof rawEntry !== "object" || Array.isArray(rawEntry)) continue;
+		const entry = rawEntry;
+		const type = normalizeOptionalString(entry.type);
+		if (!type) continue;
+		normalized[id] = {
+			enabled: typeof entry.enabled === "boolean" ? entry.enabled : true,
+			...normalizeOptionalString(entry.label) ? { label: normalizeOptionalString(entry.label) ?? void 0 } : {},
+			type,
+			config: normalizeRuntimeEntryConfig(type, entry.config && typeof entry.config === "object" && !Array.isArray(entry.config) ? entry.config : {})
+		};
+	}
+	return normalized;
+}
+function normalizeRuntimeEntryConfig(type, config) {
+	if (type !== "narp-stdio") return { ...config };
+	const command = normalizeOptionalString(config.command);
+	const cwd = normalizeOptionalString(config.cwd);
+	return {
+		wireDialect: normalizeOptionalString(config.wireDialect) ?? "acp",
+		processScope: normalizeOptionalString(config.processScope) ?? "per-session",
+		...command ? { command } : {},
+		...normalizeStringArray(config.args) ? { args: normalizeStringArray(config.args) } : {},
+		env: normalizeUnknownStringRecord(config.env) ?? {},
+		...cwd ? { cwd } : {},
+		startupTimeoutMs: normalizePositiveInteger(config.startupTimeoutMs) ?? 8e3,
+		probeTimeoutMs: normalizePositiveInteger(config.probeTimeoutMs) ?? 3e3,
+		requestTimeoutMs: normalizePositiveInteger(config.requestTimeoutMs) ?? 12e4
+	};
+}
 function clearSecretRef(config, path) {
 	if (config.secrets.refs[path]) delete config.secrets.refs[path];
 }
@@ -1545,6 +1579,22 @@ function normalizeOptionalString(value) {
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : null;
 }
+function normalizePositiveInteger(value) {
+	const parsed = typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : NaN;
+	if (!Number.isFinite(parsed)) return null;
+	const normalized = Math.trunc(parsed);
+	return normalized > 0 ? normalized : null;
+}
+function normalizeStringArray(value) {
+	if (!Array.isArray(value)) return null;
+	const entries = value.map((entry) => normalizeOptionalString(entry)).filter((entry) => Boolean(entry));
+	return entries.length > 0 ? entries : null;
+}
+function normalizeUnknownStringRecord(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const entries = Object.entries(value).map(([key, entryValue]) => [key.trim(), normalizeOptionalString(entryValue)]).filter(([key, entryValue]) => key.length > 0 && Boolean(entryValue));
+	return entries.length > 0 ? Object.fromEntries(entries) : null;
+}
 function normalizeHeaders(input) {
 	if (!input) return null;
 	const entries = Object.entries(input).map(([key, value]) => [key.trim(), String(value ?? "").trim()]).filter(([key, value]) => key.length > 0 && value.length > 0);
@@ -1858,6 +1908,7 @@ function updateRuntime(configPath, patch) {
 			...hasEngineConfig ? { engineConfig: { ...entry.engineConfig } } : {}
 		};
 	});
+	if (patch.agents?.runtimes && Object.prototype.hasOwnProperty.call(patch.agents.runtimes, "entries")) config.agents.runtimes.entries = normalizeRuntimeEntries(patch.agents.runtimes.entries);
 	if (Object.prototype.hasOwnProperty.call(patch, "bindings")) config.bindings = patch.bindings ?? [];
 	if (patch.session) config.session = {
 		...config.session,
@@ -2591,6 +2642,7 @@ var ConfigRoutesController = class {
 		if (body.data.agents?.defaults && Object.prototype.hasOwnProperty.call(body.data.agents.defaults, "contextTokens")) changedPaths.push("agents.defaults.contextTokens");
 		if (body.data.agents?.defaults && Object.prototype.hasOwnProperty.call(body.data.agents.defaults, "engine")) changedPaths.push("agents.defaults.engine");
 		if (body.data.agents?.defaults && Object.prototype.hasOwnProperty.call(body.data.agents.defaults, "engineConfig")) changedPaths.push("agents.defaults.engineConfig");
+		if (body.data.agents?.runtimes && Object.prototype.hasOwnProperty.call(body.data.agents.runtimes, "entries")) changedPaths.push("agents.runtimes.entries");
 		changedPaths.push("agents.list", "bindings", "session");
 		await this.publishConfigUpdates(changedPaths);
 		return c.json(ok(result));
@@ -2988,6 +3040,16 @@ function applySessionTypePatch(metadata, patch) {
 	delete metadata.session_type;
 	delete metadata.sessionType;
 }
+function applyUiReadAtPatch(metadata, patch) {
+	if (!Object.prototype.hasOwnProperty.call(patch, "uiReadAt")) return metadata;
+	const uiReadAt = typeof patch.uiReadAt === "string" ? patch.uiReadAt.trim() : "";
+	if (uiReadAt) return {
+		...metadata,
+		ui_last_read_at: uiReadAt
+	};
+	const { ui_last_read_at: _removed, ...nextMetadata } = metadata;
+	return nextMetadata;
+}
 async function applyProjectRootPatch(metadata, patch) {
 	if (!Object.prototype.hasOwnProperty.call(patch, "projectRoot")) return;
 	const projectRoot = await normalizeSessionProjectRoot(patch.projectRoot);
@@ -3000,14 +3062,16 @@ async function applyProjectRootPatch(metadata, patch) {
 	delete metadata.projectRoot;
 }
 async function buildPatchedSessionMetadata(params) {
+	const { metadata, patch } = params;
 	const nextMetadata = applySessionPreferencePatch({
-		metadata: structuredClone(params.metadata),
-		patch: params.patch,
+		metadata: structuredClone(metadata),
+		patch,
 		createInvalidThinkingError: () => /* @__PURE__ */ new Error("PREFERRED_THINKING_INVALID")
 	});
-	applySessionTypePatch(nextMetadata, params.patch);
-	await applyProjectRootPatch(nextMetadata, params.patch);
-	return nextMetadata;
+	applySessionTypePatch(nextMetadata, patch);
+	const nextMetadataWithReadAt = applyUiReadAtPatch(nextMetadata, patch);
+	await applyProjectRootPatch(nextMetadataWithReadAt, patch);
+	return nextMetadataWithReadAt;
 }
 var NcpSessionRoutesController = class {
 	sessionSkillsViewBuilder;
@@ -4343,6 +4407,41 @@ var RemoteRoutesController = class {
 	};
 };
 //#endregion
+//#region src/ui/ui-routes/runtime-control.controller.ts
+var RuntimeControlRoutesController = class {
+	constructor(host) {
+		this.host = host;
+	}
+	getControl = async (c) => {
+		try {
+			return c.json(ok(await this.host.getControl()));
+		} catch (error) {
+			return c.json(err("RUNTIME_CONTROL_FAILED", formatUserFacingError(error)), 500);
+		}
+	};
+	restartService = async (c) => {
+		try {
+			return c.json(ok(await this.host.restartService()));
+		} catch (error) {
+			return c.json(err("RUNTIME_RESTART_FAILED", formatUserFacingError(error)), 400);
+		}
+	};
+	startService = async (c) => {
+		try {
+			return c.json(ok(await this.host.startService()));
+		} catch (error) {
+			return c.json(err("RUNTIME_START_FAILED", formatUserFacingError(error)), 400);
+		}
+	};
+	stopService = async (c) => {
+		try {
+			return c.json(ok(await this.host.stopService()));
+		} catch (error) {
+			return c.json(err("RUNTIME_STOP_FAILED", formatUserFacingError(error)), 400);
+		}
+	};
+};
+//#endregion
 //#region src/ui/server-path/server-path-browse.utils.ts
 var ServerPathBrowseError = class extends Error {
 	constructor(code, message) {
@@ -4429,6 +4528,139 @@ function isServerPathBrowseError(error) {
 	return error instanceof ServerPathBrowseError;
 }
 //#endregion
+//#region src/ui/server-path/server-path-read.utils.ts
+const DEFAULT_PREVIEW_MAX_BYTES = 2e5;
+const MARKDOWN_EXTENSIONS = new Set([
+	".md",
+	".mdx",
+	".markdown"
+]);
+const TEXT_EXTENSIONS = new Set([
+	".c",
+	".cc",
+	".conf",
+	".cpp",
+	".css",
+	".csv",
+	".env",
+	".go",
+	".graphql",
+	".h",
+	".hpp",
+	".html",
+	".ini",
+	".java",
+	".js",
+	".json",
+	".jsx",
+	".log",
+	".mjs",
+	".py",
+	".rb",
+	".rs",
+	".sh",
+	".sql",
+	".svg",
+	".toml",
+	".ts",
+	".tsx",
+	".txt",
+	".xml",
+	".yaml",
+	".yml"
+]);
+var ServerPathReadError = class extends Error {
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "ServerPathReadError";
+	}
+};
+function normalizeReadPath(params) {
+	const { basePath, path } = params;
+	const rawPath = typeof path === "string" ? path.trim() : "";
+	const normalizedBasePath = typeof basePath === "string" ? basePath.trim() : "";
+	if (!rawPath) return resolve(expandHome(normalizedBasePath || homedir()));
+	const expandedPath = expandHome(rawPath);
+	if (expandedPath.startsWith("/")) return resolve(expandedPath);
+	if (!normalizedBasePath) throw new ServerPathReadError("SERVER_PATH_BASE_REQUIRED", "relative server path requires a base path");
+	return resolve(expandHome(normalizedBasePath), expandedPath);
+}
+function inferPreviewKind(path) {
+	const extension = extname(path).toLowerCase();
+	if (MARKDOWN_EXTENSIONS.has(extension)) return "markdown";
+	if (TEXT_EXTENSIONS.has(extension)) return "text";
+	return "binary";
+}
+function isLikelyTextBuffer(buffer) {
+	for (const byte of buffer) if (byte === 0) return false;
+	return true;
+}
+function readLanguageHint(path) {
+	const extension = extname(path).toLowerCase();
+	if (!extension) return null;
+	if (MARKDOWN_EXTENSIONS.has(extension)) return "markdown";
+	return extension.slice(1) || null;
+}
+async function readFilePreviewBytes(params) {
+	const { maxBytes, resolvedPath, sizeBytes } = params;
+	const bytesToRead = Math.min(sizeBytes, maxBytes);
+	const fileHandle = await open(resolvedPath, "r");
+	try {
+		const buffer = Buffer.alloc(bytesToRead);
+		const { bytesRead } = await fileHandle.read(buffer, 0, bytesToRead, 0);
+		return {
+			buffer: buffer.subarray(0, bytesRead),
+			truncated: sizeBytes > maxBytes
+		};
+	} finally {
+		await fileHandle.close();
+	}
+}
+async function readServerPath(options = {}) {
+	const requestedPath = typeof options.path === "string" ? options.path.trim() : "";
+	const resolvedPath = normalizeReadPath(options);
+	let resolvedStats;
+	try {
+		resolvedStats = await stat(resolvedPath);
+	} catch {
+		throw new ServerPathReadError("SERVER_PATH_NOT_FOUND", "server path does not exist");
+	}
+	if (!resolvedStats.isFile()) throw new ServerPathReadError("SERVER_PATH_NOT_FILE", "server path must point to a file");
+	let previewBytes;
+	try {
+		previewBytes = await readFilePreviewBytes({
+			resolvedPath,
+			sizeBytes: resolvedStats.size,
+			maxBytes: options.maxBytes ?? DEFAULT_PREVIEW_MAX_BYTES
+		});
+	} catch {
+		throw new ServerPathReadError("SERVER_PATH_NOT_READABLE", "server path is not readable");
+	}
+	const inferredKind = inferPreviewKind(resolvedPath);
+	const resolvedKind = inferredKind === "binary" && isLikelyTextBuffer(previewBytes.buffer) ? "text" : inferredKind;
+	if (resolvedKind === "binary") return {
+		requestedPath: requestedPath || resolvedPath,
+		resolvedPath,
+		kind: "binary",
+		sizeBytes: resolvedStats.size,
+		truncated: previewBytes.truncated,
+		languageHint: readLanguageHint(resolvedPath)
+	};
+	return {
+		requestedPath: requestedPath || resolvedPath,
+		resolvedPath,
+		kind: resolvedKind,
+		sizeBytes: resolvedStats.size,
+		truncated: previewBytes.truncated,
+		text: previewBytes.buffer.toString("utf8"),
+		languageHint: readLanguageHint(resolvedPath)
+	};
+}
+function isServerPathReadError(error) {
+	return error instanceof ServerPathReadError;
+}
+//#endregion
 //#region src/ui/ui-routes/server-path.controller.ts
 function readIncludeFilesFlag(value) {
 	return value === "1" || value === "true";
@@ -4446,6 +4678,18 @@ var ServerPathRoutesController = class {
 			throw error;
 		}
 	};
+	read = async (c) => {
+		try {
+			const payload = await readServerPath({
+				path: c.req.query("path"),
+				basePath: c.req.query("basePath")
+			});
+			return c.json(ok(payload));
+		} catch (error) {
+			if (isServerPathReadError(error)) return c.json(err(error.code, error.message), 400);
+			throw error;
+		}
+	};
 };
 //#endregion
 //#region src/ui/router.ts
@@ -4496,6 +4740,7 @@ function registerNcpSessionRoutes(app, ncpSessionController) {
 }
 function registerServerPathRoutes(app, serverPathController) {
 	app.get("/api/server-paths/browse", serverPathController.browse);
+	app.get("/api/server-paths/read", serverPathController.read);
 }
 function registerNcpRuntimeRoutes(app, options, ncpAssetController) {
 	if (!options.ncpAgent) return;
@@ -4526,22 +4771,35 @@ function registerRemoteRoutes(app, remoteController) {
 	app.put("/api/remote/settings", remoteController.updateSettings);
 	app.post("/api/remote/service/:action", remoteController.controlService);
 }
+function registerRuntimeControlRoutes(app, runtimeControlController) {
+	if (!runtimeControlController) return;
+	app.get("/api/runtime/control", runtimeControlController.getControl);
+	app.post("/api/runtime/control/start-service", runtimeControlController.startService);
+	app.post("/api/runtime/control/restart-service", runtimeControlController.restartService);
+	app.post("/api/runtime/control/stop-service", runtimeControlController.stopService);
+}
+function createUiRouteControllers(options, authService, marketplaceBaseUrl) {
+	return {
+		app: new AppRoutesController(options),
+		agents: new AgentsRoutesController(options),
+		auth: new AuthRoutesController(authService),
+		config: new ConfigRoutesController(options),
+		cron: new CronRoutesController(options),
+		ncpSession: new NcpSessionRoutesController(options),
+		ncpAsset: new NcpAssetRoutesController(options),
+		serverPath: new ServerPathRoutesController(),
+		remote: options.remoteAccess ? new RemoteRoutesController(options.remoteAccess) : null,
+		runtimeControl: options.runtimeControl ? new RuntimeControlRoutesController(options.runtimeControl) : null,
+		pluginMarketplace: new PluginMarketplaceController(options, marketplaceBaseUrl),
+		skillMarketplace: new SkillMarketplaceController(options, marketplaceBaseUrl),
+		mcpMarketplace: new McpMarketplaceController(options, marketplaceBaseUrl)
+	};
+}
 function createUiRouter(options) {
 	const app = new Hono();
 	const marketplaceBaseUrl = normalizeMarketplaceBaseUrl(options);
 	const authService = options.authService ?? new UiAuthService(options.configPath);
-	const appController = new AppRoutesController(options);
-	const agentsController = new AgentsRoutesController(options);
-	const authController = new AuthRoutesController(authService);
-	const configController = new ConfigRoutesController(options);
-	const cronController = new CronRoutesController(options);
-	const ncpSessionController = new NcpSessionRoutesController(options);
-	const ncpAssetController = new NcpAssetRoutesController(options);
-	const serverPathController = new ServerPathRoutesController();
-	const remoteController = options.remoteAccess ? new RemoteRoutesController(options.remoteAccess) : null;
-	const pluginMarketplaceController = new PluginMarketplaceController(options, marketplaceBaseUrl);
-	const skillMarketplaceController = new SkillMarketplaceController(options, marketplaceBaseUrl);
-	const mcpMarketplaceController = new McpMarketplaceController(options, marketplaceBaseUrl);
+	const controllers = createUiRouteControllers(options, authService, marketplaceBaseUrl);
 	app.notFound((c) => c.json(err("NOT_FOUND", "endpoint not found"), 404));
 	app.use("/api/*", async (c, next) => {
 		const path = c.req.path;
@@ -4556,21 +4814,22 @@ function createUiRouter(options) {
 		c.status(401);
 		return c.json(err("UNAUTHORIZED", "Authentication required."), 401);
 	});
-	app.get("/api/health", appController.health);
-	app.get("/api/app/meta", appController.appMeta);
-	app.get("/api/runtime/bootstrap-status", appController.bootstrapStatus);
-	registerAuthRoutes(app, authController);
-	registerAgentRoutes(app, agentsController);
-	registerConfigRoutes(app, configController);
-	registerNcpSessionRoutes(app, ncpSessionController);
-	registerServerPathRoutes(app, serverPathController);
-	registerNcpRuntimeRoutes(app, options, ncpAssetController);
-	registerCronRoutes(app, cronController);
-	registerRemoteRoutes(app, remoteController);
+	app.get("/api/health", controllers.app.health);
+	app.get("/api/app/meta", controllers.app.appMeta);
+	app.get("/api/runtime/bootstrap-status", controllers.app.bootstrapStatus);
+	registerAuthRoutes(app, controllers.auth);
+	registerAgentRoutes(app, controllers.agents);
+	registerConfigRoutes(app, controllers.config);
+	registerNcpSessionRoutes(app, controllers.ncpSession);
+	registerServerPathRoutes(app, controllers.serverPath);
+	registerNcpRuntimeRoutes(app, options, controllers.ncpAsset);
+	registerCronRoutes(app, controllers.cron);
+	registerRemoteRoutes(app, controllers.remote);
+	registerRuntimeControlRoutes(app, controllers.runtimeControl);
 	mountMarketplaceRoutes(app, {
-		plugin: pluginMarketplaceController,
-		skill: skillMarketplaceController,
-		mcp: mcpMarketplaceController
+		plugin: controllers.pluginMarketplace,
+		skill: controllers.skillMarketplace,
+		mcp: controllers.mcpMarketplace
 	});
 	return app;
 }
@@ -4656,6 +4915,7 @@ function startUiServer(options) {
 		ncpSessionService: options.ncpSessionService,
 		authService,
 		remoteAccess: options.remoteAccess,
+		runtimeControl: options.runtimeControl,
 		getBootstrapStatus: options.getBootstrapStatus,
 		getPluginChannelBindings: options.getPluginChannelBindings,
 		getPluginUiMetadata: options.getPluginUiMetadata

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/server",
-  "version": "0.12.5",
+  "version": "0.12.7",
   "private": false,
   "description": "Nextclaw UI/API server.",
   "type": "module",
@@ -18,12 +18,12 @@
     "@hono/node-server": "^1.13.3",
     "hono": "^4.6.2",
     "ws": "^8.18.0",
-    "@nextclaw/core": "0.12.5",
-    "@nextclaw/mcp": "0.1.70",
-    "@nextclaw/ncp-http-agent-server": "0.3.12",
-    "@nextclaw/ncp": "0.5.0",
-    "@nextclaw/openclaw-compat": "1.0.5",
-    "@nextclaw/runtime": "0.2.37"
+    "@nextclaw/core": "0.12.7",
+    "@nextclaw/openclaw-compat": "1.0.7",
+    "@nextclaw/ncp": "0.5.2",
+    "@nextclaw/ncp-http-agent-server": "0.3.14",
+    "@nextclaw/mcp": "0.1.72",
+    "@nextclaw/runtime": "0.2.39"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",