@nextclaw/service 0.1.1

package/dist/shared/controllers/gateway.controller.js

@@ -0,0 +1,318 @@
+import { getPackageVersion as getPackageVersion$1 } from "../utils/package/package-manifest.utils.js";
+import "../utils/cli.utils.js";
+import { NpmRuntimeUpdateCommandService } from "../../launcher/npm-runtime-update-command.service.js";
+import { parseSessionKey, writeRestartSentinel } from "../services/restart/restart-sentinel.service.js";
+import { ConfigSchema, buildConfigSchema, buildReloadPlan, diffConfigPaths, normalizeInlineSecretRefs, redactConfigObject } from "@nextclaw/core";
+import { existsSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+//#region src/shared/controllers/gateway.controller.ts
+const hashRaw = (raw) => createHash("sha256").update(raw).digest("hex");
+const readConfigSnapshot = (getConfigPath) => {
+	const path = getConfigPath();
+	let raw = "";
+	let parsed = {};
+	if (existsSync(path)) {
+		raw = readFileSync(path, "utf-8");
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			parsed = {};
+		}
+	}
+	let config;
+	let valid = true;
+	try {
+		config = ConfigSchema.parse(normalizeInlineSecretRefs(parsed));
+	} catch {
+		config = ConfigSchema.parse({});
+		valid = false;
+	}
+	if (!raw) raw = JSON.stringify(config, null, 2);
+	const hash = hashRaw(raw);
+	const schema = buildConfigSchema({ version: getPackageVersion$1() });
+	const redacted = redactConfigObject(config, schema.uiHints);
+	return {
+		raw: valid ? JSON.stringify(redacted, null, 2) : null,
+		hash: valid ? hash : null,
+		config,
+		redacted,
+		valid
+	};
+};
+const redactValue = (value) => {
+	return redactConfigObject(value, buildConfigSchema({ version: getPackageVersion$1() }).uiHints);
+};
+const mergeDeep = (base, patch) => {
+	const next = { ...base };
+	for (const [key, value] of Object.entries(patch)) if (value && typeof value === "object" && !Array.isArray(value)) {
+		const baseVal = base[key];
+		if (baseVal && typeof baseVal === "object" && !Array.isArray(baseVal)) next[key] = mergeDeep(baseVal, value);
+		else next[key] = mergeDeep({}, value);
+	} else next[key] = value;
+	return next;
+};
+const buildPendingRestartMessage = (paths) => {
+	if (paths.length === 0) return "Config saved. Restart manually to apply changes.";
+	return `Config saved. Restart manually to apply: ${paths.join(", ")}.`;
+};
+var GatewayControllerImpl = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	normalizeOptionalString = (value) => {
+		if (typeof value !== "string") return;
+		return value.trim() || void 0;
+	};
+	resolveDeliveryContext = (sessionKey) => {
+		const normalizedSessionKey = this.normalizeOptionalString(sessionKey);
+		const keyTarget = parseSessionKey(normalizedSessionKey);
+		const keyRoute = keyTarget && keyTarget.channel !== "agent" ? keyTarget : null;
+		const metadata = (normalizedSessionKey ? this.deps.sessionManager?.getIfExists(normalizedSessionKey) : null)?.metadata ?? {};
+		const rawContext = metadata.last_delivery_context;
+		const cachedContext = rawContext && typeof rawContext === "object" && !Array.isArray(rawContext) ? rawContext : null;
+		const cachedMetadataRaw = cachedContext?.metadata;
+		const cachedMetadata = cachedMetadataRaw && typeof cachedMetadataRaw === "object" && !Array.isArray(cachedMetadataRaw) ? { ...cachedMetadataRaw } : {};
+		const channel = this.normalizeOptionalString(cachedContext?.channel) ?? keyRoute?.channel;
+		const chatId = this.normalizeOptionalString(cachedContext?.chatId) ?? this.normalizeOptionalString(metadata.last_to) ?? keyRoute?.chatId;
+		const replyTo = this.normalizeOptionalString(cachedContext?.replyTo) ?? this.normalizeOptionalString(metadata.last_message_id);
+		const accountId = this.normalizeOptionalString(cachedContext?.accountId) ?? this.normalizeOptionalString(metadata.last_account_id);
+		if (!channel || !chatId) return;
+		if (accountId && !this.normalizeOptionalString(cachedMetadata.accountId)) cachedMetadata.accountId = accountId;
+		return {
+			channel,
+			chatId,
+			...replyTo ? { replyTo } : {},
+			...accountId ? { accountId } : {},
+			...Object.keys(cachedMetadata).length > 0 ? { metadata: cachedMetadata } : {}
+		};
+	};
+	writeRestartSentinelPayload = async (params) => {
+		const sessionKey = this.normalizeOptionalString(params.sessionKey);
+		const deliveryContext = this.resolveDeliveryContext(sessionKey);
+		try {
+			return await writeRestartSentinel({
+				kind: params.kind,
+				status: params.status,
+				ts: Date.now(),
+				sessionKey,
+				deliveryContext,
+				message: params.note ?? null,
+				stats: {
+					reason: params.reason ?? null,
+					strategy: params.strategy ?? null
+				}
+			});
+		} catch {
+			return null;
+		}
+	};
+	requestRestart = async (options) => {
+		if (this.deps.requestRestart) {
+			await this.deps.requestRestart(options);
+			return;
+		}
+		const delay = typeof options?.delayMs === "number" && Number.isFinite(options.delayMs) ? Math.max(0, options.delayMs) : 100;
+		console.log(`Gateway restart requested via tool${options?.reason ? ` (${options.reason})` : ""}.`);
+		setTimeout(() => {
+			process.exit(0);
+		}, delay);
+	};
+	createConfigMutationResult = (params) => {
+		const pendingRestart = params.plan.restartRequired.length > 0 ? {
+			required: true,
+			automatic: false,
+			changedPaths: [...params.plan.restartRequired],
+			message: buildPendingRestartMessage(params.plan.restartRequired)
+		} : null;
+		const message = params.changedPaths.length === 0 ? "Config already matched the requested state." : pendingRestart ? params.changedPaths.length > params.plan.restartRequired.length ? "Config saved. Supported changes were applied immediately; restart manually to apply the rest." : "Config saved. Restart manually to apply changes." : "Config saved and applied.";
+		return {
+			ok: true,
+			note: params.note ?? null,
+			path: this.deps.getConfigPath(),
+			config: redactValue(params.config),
+			changedPaths: [...params.changedPaths],
+			message,
+			pendingRestart
+		};
+	};
+	applyConfigChange = async (params) => {
+		const { nextConfig, note } = params;
+		const changedPaths = diffConfigPaths(readConfigSnapshot(this.deps.getConfigPath).config, nextConfig);
+		const plan = buildReloadPlan(changedPaths);
+		if (changedPaths.length === 0) return this.createConfigMutationResult({
+			changedPaths,
+			config: nextConfig,
+			note,
+			plan
+		});
+		this.deps.saveConfig(nextConfig);
+		await this.deps.configManager.applyReloadPlan(nextConfig);
+		return this.createConfigMutationResult({
+			changedPaths,
+			config: nextConfig,
+			note,
+			plan
+		});
+	};
+	status = () => {
+		return {
+			channels: this.deps.channels.enabledChannels,
+			cron: this.deps.cron.status(),
+			configPath: this.deps.getConfigPath()
+		};
+	};
+	reloadConfig = async (reason) => {
+		return this.deps.configManager.reloadConfig(reason);
+	};
+	restart = async (options) => {
+		await this.writeRestartSentinelPayload({
+			kind: "restart",
+			status: "ok",
+			sessionKey: options?.sessionKey,
+			reason: options?.reason ?? "gateway.restart"
+		});
+		await this.requestRestart(options);
+		return "Restart scheduled";
+	};
+	getConfig = async () => {
+		const snapshot = readConfigSnapshot(this.deps.getConfigPath);
+		return {
+			raw: snapshot.raw,
+			hash: snapshot.hash,
+			path: this.deps.getConfigPath(),
+			config: snapshot.redacted,
+			parsed: snapshot.redacted,
+			resolved: snapshot.redacted,
+			valid: snapshot.valid
+		};
+	};
+	getConfigSchema = async () => {
+		return buildConfigSchema({ version: getPackageVersion$1() });
+	};
+	applyConfig = async (params) => {
+		const snapshot = readConfigSnapshot(this.deps.getConfigPath);
+		if (!params.baseHash) return {
+			ok: false,
+			error: "config base hash required; re-run config.get and retry"
+		};
+		if (!snapshot.valid || !snapshot.hash) return {
+			ok: false,
+			error: "config base hash unavailable; re-run config.get and retry"
+		};
+		if (params.baseHash !== snapshot.hash) return {
+			ok: false,
+			error: "config changed since last load; re-run config.get and retry"
+		};
+		let parsedRaw;
+		try {
+			parsedRaw = JSON.parse(params.raw);
+		} catch {
+			return {
+				ok: false,
+				error: "invalid JSON in raw config"
+			};
+		}
+		let validated;
+		try {
+			validated = ConfigSchema.parse(normalizeInlineSecretRefs(parsedRaw));
+		} catch (err) {
+			return {
+				ok: false,
+				error: `invalid config: ${String(err)}`
+			};
+		}
+		return this.applyConfigChange({
+			kind: "config.apply",
+			nextConfig: validated,
+			note: params.note
+		});
+	};
+	patchConfig = async (params) => {
+		const snapshot = readConfigSnapshot(this.deps.getConfigPath);
+		if (!params.baseHash) return {
+			ok: false,
+			error: "config base hash required; re-run config.get and retry"
+		};
+		if (!snapshot.valid || !snapshot.hash) return {
+			ok: false,
+			error: "config base hash unavailable; re-run config.get and retry"
+		};
+		if (params.baseHash !== snapshot.hash) return {
+			ok: false,
+			error: "config changed since last load; re-run config.get and retry"
+		};
+		let patch;
+		try {
+			patch = JSON.parse(params.raw);
+		} catch {
+			return {
+				ok: false,
+				error: "invalid JSON in raw config"
+			};
+		}
+		const merged = mergeDeep(snapshot.config, patch);
+		let validated;
+		try {
+			validated = ConfigSchema.parse(normalizeInlineSecretRefs(merged));
+		} catch (err) {
+			return {
+				ok: false,
+				error: `invalid config: ${String(err)}`
+			};
+		}
+		return this.applyConfigChange({
+			kind: "config.patch",
+			nextConfig: validated,
+			note: params.note
+		});
+	};
+	updateRun = async (params) => {
+		const versionBefore = getPackageVersion$1();
+		params.timeoutMs;
+		const updateCommand = new NpmRuntimeUpdateCommandService();
+		const downloadedSnapshot = await updateCommand.runManaged({ download: true });
+		const snapshot = downloadedSnapshot.status === "downloaded" ? await updateCommand.runManaged({ apply: true }) : downloadedSnapshot;
+		if (snapshot.status === "blocked" || snapshot.status === "failed") return {
+			ok: false,
+			error: snapshot.errorMessage ?? snapshot.blockReason ?? "update failed",
+			snapshot,
+			version: {
+				before: versionBefore,
+				after: getPackageVersion$1(),
+				changed: false
+			}
+		};
+		const versionAfter = getPackageVersion$1();
+		const delayMs = params.restartDelayMs ?? 0;
+		const sentinelPath = await this.writeRestartSentinelPayload({
+			kind: "update.run",
+			status: "ok",
+			sessionKey: params.sessionKey,
+			note: params.note,
+			reason: "update.run",
+			strategy: "runtime-bundle"
+		});
+		await this.requestRestart({
+			delayMs,
+			reason: "update.run"
+		});
+		return {
+			ok: true,
+			note: params.note ?? null,
+			restart: {
+				scheduled: true,
+				delayMs
+			},
+			strategy: "runtime-bundle",
+			snapshot,
+			version: {
+				before: versionBefore,
+				after: versionAfter,
+				changed: versionBefore !== versionAfter
+			},
+			sentinel: sentinelPath ? { path: sentinelPath } : null
+		};
+	};
+};
+//#endregion
+export { GatewayControllerImpl };

package/dist/shared/services/extensions/extension-lifecycle.service.d.ts

@@ -0,0 +1,56 @@
+import { ChildProcess, spawn } from "node:child_process";
+
+//#region src/shared/services/extensions/extension-lifecycle.service.d.ts
+type ExtensionServerConfig = {
+  type: "stdio";
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+};
+type ExtensionManifest = {
+  id: string;
+  name?: string;
+  version?: string;
+  rootDir: string;
+  server: ExtensionServerConfig;
+  contributes?: {
+    channels?: Array<{
+      id: string;
+      name?: string;
+      description?: string;
+      meta?: Record<string, unknown>;
+      configSchema?: Record<string, unknown>;
+      configUiHints?: Record<string, Record<string, unknown>>;
+      auth?: boolean | Record<string, unknown>;
+    }>;
+  };
+};
+type RunningExtensionProcess = {
+  manifest: ExtensionManifest;
+  process: ChildProcess;
+};
+type ExtensionLifecycleServiceOptions = {
+  endpoint: string;
+  token: string;
+  spawnProcess?: typeof spawn;
+  logger?: Pick<Console, "warn">;
+};
+declare class ExtensionManifestDiscoveryService {
+  readonly discover: (roots: string[]) => Promise<ExtensionManifest[]>;
+  private readonly discoverRoot;
+  private readonly readManifestIfExists;
+}
+declare class ExtensionLifecycleService {
+  private readonly options;
+  private readonly processes;
+  private readonly spawnProcess;
+  private readonly logger;
+  constructor(options: ExtensionLifecycleServiceOptions);
+  readonly startAll: (manifests: ExtensionManifest[]) => Promise<RunningExtensionProcess[]>;
+  readonly start: (manifest: ExtensionManifest) => RunningExtensionProcess;
+  readonly stopAll: () => Promise<void>;
+  readonly list: () => RunningExtensionProcess[];
+  private readonly stopProcess;
+}
+//#endregion
+export { ExtensionLifecycleService, ExtensionLifecycleServiceOptions, ExtensionManifest, ExtensionManifestDiscoveryService, ExtensionServerConfig, RunningExtensionProcess };

package/dist/shared/services/extensions/extension-lifecycle.service.js

@@ -0,0 +1,143 @@
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { readFile, readdir } from "node:fs/promises";
+//#region src/shared/services/extensions/extension-lifecycle.service.ts
+const EXTENSION_MANIFEST_FILE = "nextclaw.extension.json";
+function readString(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function readStringArray(value) {
+	if (!Array.isArray(value)) return;
+	return value.every((item) => typeof item === "string") ? value : void 0;
+}
+function readStringRecord(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return;
+	const entries = Object.entries(value);
+	if (!entries.every(([, item]) => typeof item === "string")) return;
+	return Object.fromEntries(entries);
+}
+function sanitizeExtensionNodeOptions(value) {
+	if (!value?.trim()) return;
+	const tokens = value.split(/\s+/).filter(Boolean);
+	const sanitized = [];
+	for (let index = 0; index < tokens.length; index += 1) {
+		const token = tokens[index];
+		if (token === "--conditions=development" || token === "-C=development") continue;
+		if ((token === "--conditions" || token === "-C") && tokens[index + 1] === "development") {
+			index += 1;
+			continue;
+		}
+		sanitized.push(token);
+	}
+	return sanitized.length > 0 ? sanitized.join(" ") : void 0;
+}
+function toManifest(value, rootDir) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("extension manifest must be an object");
+	const record = value;
+	const server = record.server;
+	if (!server || typeof server !== "object" || Array.isArray(server)) throw new Error("extension manifest server is required");
+	const serverRecord = server;
+	const id = readString(record.id);
+	const command = readString(serverRecord.command);
+	if (!id) throw new Error("extension manifest id is required");
+	if (serverRecord.type !== "stdio") throw new Error("extension server.type must be stdio");
+	if (!command) throw new Error("extension server.command is required");
+	return {
+		id,
+		rootDir,
+		...readString(record.name) ? { name: readString(record.name) } : {},
+		...readString(record.version) ? { version: readString(record.version) } : {},
+		server: {
+			type: "stdio",
+			command,
+			...readStringArray(serverRecord.args) ? { args: readStringArray(serverRecord.args) } : {},
+			...readStringRecord(serverRecord.env) ? { env: readStringRecord(serverRecord.env) } : {}
+		},
+		...record.contributes && typeof record.contributes === "object" && !Array.isArray(record.contributes) ? { contributes: record.contributes } : {}
+	};
+}
+var ExtensionManifestDiscoveryService = class {
+	discover = async (roots) => {
+		const manifests = [];
+		for (const root of roots) manifests.push(...await this.discoverRoot(root));
+		return manifests;
+	};
+	discoverRoot = async (root) => {
+		const directManifest = await this.readManifestIfExists(join(root, EXTENSION_MANIFEST_FILE));
+		if (directManifest) return [directManifest];
+		const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+		return (await Promise.all(entries.filter((entry) => entry.isDirectory()).map((entry) => this.readManifestIfExists(join(root, entry.name, EXTENSION_MANIFEST_FILE))))).filter((manifest) => Boolean(manifest));
+	};
+	readManifestIfExists = async (path) => {
+		try {
+			return toManifest(JSON.parse(await readFile(path, "utf-8")), dirname(path));
+		} catch (error) {
+			if (error.code === "ENOENT") return null;
+			throw error;
+		}
+	};
+};
+var ExtensionLifecycleService = class {
+	processes = /* @__PURE__ */ new Map();
+	spawnProcess;
+	logger;
+	constructor(options) {
+		this.options = options;
+		this.spawnProcess = options.spawnProcess ?? spawn;
+		this.logger = options.logger ?? console;
+	}
+	startAll = async (manifests) => {
+		const started = [];
+		for (const manifest of manifests) started.push(this.start(manifest));
+		return started;
+	};
+	start = (manifest) => {
+		const existing = this.processes.get(manifest.id);
+		if (existing) return existing;
+		const child = this.spawnProcess(manifest.server.command, manifest.server.args ?? [], {
+			cwd: manifest.rootDir,
+			env: {
+				...process.env,
+				NODE_OPTIONS: sanitizeExtensionNodeOptions(process.env.NODE_OPTIONS),
+				...manifest.server.env,
+				NEXTCLAW_EXTENSION_ID: manifest.id,
+				NEXTCLAW_EXTENSION_ENDPOINT: this.options.endpoint,
+				NEXTCLAW_EXTENSION_TOKEN: this.options.token
+			},
+			stdio: [
+				"ignore",
+				"ignore",
+				"inherit"
+			]
+		});
+		const running = {
+			manifest,
+			process: child
+		};
+		this.processes.set(manifest.id, running);
+		child.once("exit", () => {
+			if (this.processes.get(manifest.id)?.process === child) this.processes.delete(manifest.id);
+			this.logger.warn(`Extension ${manifest.id} exited.`);
+		});
+		child.once("error", (error) => {
+			this.logger.warn(`Extension ${manifest.id} failed: ${error.message}`);
+		});
+		return running;
+	};
+	stopAll = async () => {
+		const running = Array.from(this.processes.values());
+		this.processes.clear();
+		await Promise.all(running.map((entry) => this.stopProcess(entry.process)));
+	};
+	list = () => Array.from(this.processes.values());
+	stopProcess = async (child) => {
+		if (child.exitCode !== null || child.signalCode !== null) return;
+		await new Promise((resolve) => {
+			child.once("exit", () => resolve());
+			child.kill();
+			setTimeout(resolve, 1e3).unref();
+		});
+	};
+};
+//#endregion
+export { ExtensionLifecycleService, ExtensionManifestDiscoveryService };

package/dist/shared/services/extensions/service-extension-runtime.service.d.ts

@@ -0,0 +1,51 @@
+import { ExtensionLifecycleService, ExtensionManifestDiscoveryService, RunningExtensionProcess } from "./extension-lifecycle.service.js";
+import { NextclawGatewayRuntime } from "../gateway/nextclaw-gateway-runtime.service.js";
+import * as NextclawCore from "@nextclaw/core";
+import { Ingress } from "@nextclaw/shared";
+import { PluginChannelBinding, PluginUiMetadata } from "@nextclaw/openclaw-compat";
+
+//#region src/shared/services/extensions/service-extension-runtime.service.d.ts
+type Config$1 = NextclawCore.Config;
+type ExtensionRuntimeContributions = {
+  channelBindings: PluginChannelBinding[];
+  uiMetadata: PluginUiMetadata[];
+};
+declare function resolveBuiltinExtensionManifestRoots(): string[];
+declare function resolveExtensionManifestRoots(params: {
+  config: Config$1;
+  workspace: string;
+}): string[];
+declare function startDiscoveredExtensions(params: {
+  config: Config$1;
+  workspace: string;
+  endpoint: string;
+  token: string;
+  discovery?: ExtensionManifestDiscoveryService;
+  lifecycle?: ExtensionLifecycleService;
+}): Promise<{
+  lifecycle: ExtensionLifecycleService;
+  running: RunningExtensionProcess[];
+}>;
+declare class ServiceExtensionRuntime {
+  private readonly gateway;
+  readonly token: `${string}-${string}-${string}-${string}-${string}`;
+  private lifecycle;
+  private manifests;
+  private readonly pendingRequests;
+  constructor(gateway: NextclawGatewayRuntime);
+  readonly registerIngressHandlers: (ingress: Ingress) => void;
+  readonly loadContributions: () => Promise<ExtensionRuntimeContributions>;
+  readonly start: () => Promise<void>;
+  readonly stop: () => Promise<void>;
+  private readonly handleChannelConfigGet;
+  private readonly handleChannelMessageSubmit;
+  private readonly handleExtensionResponse;
+  private readonly discoverManifests;
+  private readonly toContributions;
+  private readonly readConfigUiHints;
+  private readonly createChannelAuth;
+  private readonly requestExtension;
+  private readonly assertAuthorized;
+}
+//#endregion
+export { ServiceExtensionRuntime, resolveBuiltinExtensionManifestRoots, resolveExtensionManifestRoots, startDiscoveredExtensions };