@nextclaw/service 0.2.13 → 0.2.14

package/dist/utils/restart-sentinel.utils.d.ts

@@ -0,0 +1,37 @@
+//#region src/utils/restart-sentinel.utils.d.ts
+type RestartSentinelDeliveryContext = {
+  channel?: string;
+  chatId?: string;
+  replyTo?: string | null;
+  accountId?: string | null;
+  metadata?: Record<string, unknown>;
+};
+type RestartSentinelPayload = {
+  kind: "config.apply" | "config.patch" | "update.run" | "restart";
+  status: "ok" | "error" | "skipped";
+  ts: number;
+  sessionKey?: string;
+  deliveryContext?: RestartSentinelDeliveryContext;
+  message?: string | null;
+  stats?: {
+    reason?: string | null;
+    strategy?: string | null;
+    durationMs?: number | null;
+  };
+};
+type RestartSentinelFile = {
+  version: 1;
+  payload: RestartSentinelPayload;
+};
+declare function resolveRestartSentinelPath(): string;
+declare function writeRestartSentinel(payload: RestartSentinelPayload): Promise<string>;
+declare function consumeRestartSentinel(): Promise<RestartSentinelFile | null>;
+declare function summarizeRestartSentinel(payload: RestartSentinelPayload): string;
+declare function formatRestartSentinelMessage(payload: RestartSentinelPayload): string;
+declare function parseSessionKey(sessionKey?: string): {
+  channel: string;
+  chatId: string;
+} | null;
+//#endregion
+export { RestartSentinelDeliveryContext, RestartSentinelPayload, consumeRestartSentinel, formatRestartSentinelMessage, parseSessionKey, resolveRestartSentinelPath, summarizeRestartSentinel, writeRestartSentinel };
+//# sourceMappingURL=restart-sentinel.utils.d.ts.map

package/dist/utils/restart-sentinel.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart-sentinel.utils.d.ts","names":[],"sources":["../../src/utils/restart-sentinel.utils.ts"],"mappings":";KAIY,8BAAA;EACV,OAAA;EACA,MAAA;EACA,OAAA;EACA,SAAA;EACA,QAAA,GAAW,MAAA;AAAA;AAAA,KAGD,sBAAA;EACV,IAAA;EACA,MAAA;EACA,EAAA;EACA,UAAA;EACA,eAAA,GAAkB,8BAAA;EAClB,OAAA;EACA,KAAA;IACE,MAAA;IACA,QAAA;IACA,UAAA;EAAA;AAAA;AAAA,KAIC,mBAAA;EACH,OAAA;EACA,OAAA,EAAS,sBAAA;AAAA;AAAA,iBAwBK,0BAAA,CAAA;AAAA,iBAIM,oBAAA,CAAqB,OAAA,EAAS,sBAAA,GAAyB,OAAA;AAAA,iBAWvD,sBAAA,CAAA,GAA0B,OAAA,CAAQ,mBAAA;AAAA,iBAoBxC,wBAAA,CAAyB,OAAA,EAAS,sBAAA;AAAA,iBAkBlC,4BAAA,CAA6B,OAAA,EAAS,sBAAA;AAAA,iBAetC,eAAA,CACd,UAAA;EACG,OAAA;EAAiB,MAAA;AAAA"}

package/dist/utils/restart-sentinel.utils.js

@@ -0,0 +1,76 @@
+import { getRunPath } from "@nextclaw/core";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+//#region src/utils/restart-sentinel.utils.ts
+const RESTART_SENTINEL_FILENAME = "restart-sentinel.json";
+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(getRunPath(), 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)
+	};
+}
+//#endregion
+export { consumeRestartSentinel, formatRestartSentinelMessage, parseSessionKey, resolveRestartSentinelPath, summarizeRestartSentinel, writeRestartSentinel };
+
+//# sourceMappingURL=restart-sentinel.utils.js.map

package/dist/utils/restart-sentinel.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart-sentinel.utils.js","names":[],"sources":["../../src/utils/restart-sentinel.utils.ts"],"sourcesContent":["import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { getRunPath } from \"@nextclaw/core\";\n\nexport type RestartSentinelDeliveryContext = {\n  channel?: string;\n  chatId?: string;\n  replyTo?: string | null;\n  accountId?: string | null;\n  metadata?: Record<string, unknown>;\n};\n\nexport type RestartSentinelPayload = {\n  kind: \"config.apply\" | \"config.patch\" | \"update.run\" | \"restart\";\n  status: \"ok\" | \"error\" | \"skipped\";\n  ts: number;\n  sessionKey?: string;\n  deliveryContext?: RestartSentinelDeliveryContext;\n  message?: string | null;\n  stats?: {\n    reason?: string | null;\n    strategy?: string | null;\n    durationMs?: number | null;\n  };\n};\n\ntype RestartSentinelFile = {\n  version: 1;\n  payload: RestartSentinelPayload;\n};\n\nconst RESTART_SENTINEL_FILENAME = \"restart-sentinel.json\";\nconst RESTART_REASON_MAX_CHARS = 240;\nconst RESTART_NOTE_MAX_CHARS = 600;\nconst RESTART_OUTBOUND_MAX_CHARS = 1200;\n\nfunction trimTo(value: string, maxChars: number): string {\n  const text = value.trim();\n  if (!text) {\n    return \"\";\n  }\n  if (text.length <= maxChars) {\n    return text;\n  }\n  return `${text.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;\n}\n\nfunction normalizeLine(value: string, maxChars: number): string | null {\n  const trimmed = trimTo(value, maxChars);\n  return trimmed ? trimmed : null;\n}\n\nexport function resolveRestartSentinelPath(): string {\n  return resolve(getRunPath(), RESTART_SENTINEL_FILENAME);\n}\n\nexport async function writeRestartSentinel(payload: RestartSentinelPayload): Promise<string> {\n  const path = resolveRestartSentinelPath();\n  mkdirSync(resolve(path, \"..\"), { recursive: true });\n  const file: RestartSentinelFile = {\n    version: 1,\n    payload\n  };\n  writeFileSync(path, `${JSON.stringify(file, null, 2)}\\n`, \"utf-8\");\n  return path;\n}\n\nexport async function consumeRestartSentinel(): Promise<RestartSentinelFile | null> {\n  const path = resolveRestartSentinelPath();\n  if (!existsSync(path)) {\n    return null;\n  }\n  try {\n    const raw = readFileSync(path, \"utf-8\");\n    const parsed = JSON.parse(raw) as RestartSentinelFile;\n    if (!parsed || parsed.version !== 1 || !parsed.payload) {\n      rmSync(path, { force: true });\n      return null;\n    }\n    rmSync(path, { force: true });\n    return parsed;\n  } catch {\n    rmSync(path, { force: true });\n    return null;\n  }\n}\n\nexport function summarizeRestartSentinel(payload: RestartSentinelPayload): string {\n  const reason = normalizeLine(payload.stats?.reason ?? \"\", RESTART_REASON_MAX_CHARS);\n  if (payload.kind === \"update.run\") {\n    return payload.status === \"ok\"\n      ? \"✅ NextClaw update completed and service restarted.\"\n      : \"⚠️ NextClaw update finished with issues.\";\n  }\n  if (payload.kind === \"config.apply\" || payload.kind === \"config.patch\") {\n    return payload.status === \"ok\"\n      ? \"✅ Config applied and service restarted.\"\n      : \"⚠️ Config change restart finished with issues.\";\n  }\n  if (reason) {\n    return `Gateway restart complete (${reason}).`;\n  }\n  return \"Gateway restart complete.\";\n}\n\nexport function formatRestartSentinelMessage(payload: RestartSentinelPayload): string {\n  const lines = [summarizeRestartSentinel(payload)];\n  const note = normalizeLine(payload.message ?? \"\", RESTART_NOTE_MAX_CHARS);\n  if (note) {\n    lines.push(note);\n  }\n  const reason = normalizeLine(payload.stats?.reason ?? \"\", RESTART_REASON_MAX_CHARS);\n  if (reason && !lines.some((line) => line.includes(reason))) {\n    lines.push(`Reason: ${reason}`);\n  }\n\n  const message = lines.join(\"\\n\").trim();\n  return trimTo(message, RESTART_OUTBOUND_MAX_CHARS);\n}\n\nexport function parseSessionKey(\n  sessionKey?: string\n): { channel: string; chatId: string } | null {\n  const value = sessionKey?.trim();\n  if (!value) {\n    return null;\n  }\n  const separator = value.indexOf(\":\");\n  if (separator <= 0 || separator >= value.length - 1) {\n    return null;\n  }\n  return {\n    channel: value.slice(0, separator),\n    chatId: value.slice(separator + 1)\n  };\n}\n"],"mappings":";;;;AA+BA,MAAM,4BAA4B;AAClC,MAAM,2BAA2B;AACjC,MAAM,yBAAyB;AAC/B,MAAM,6BAA6B;AAEnC,SAAS,OAAO,OAAe,UAA0B;CACvD,MAAM,OAAO,MAAM,MAAM;AACzB,KAAI,CAAC,KACH,QAAO;AAET,KAAI,KAAK,UAAU,SACjB,QAAO;AAET,QAAO,GAAG,KAAK,MAAM,GAAG,KAAK,IAAI,GAAG,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC;;AAG/D,SAAS,cAAc,OAAe,UAAiC;CACrE,MAAM,UAAU,OAAO,OAAO,SAAS;AACvC,QAAO,UAAU,UAAU;;AAG7B,SAAgB,6BAAqC;AACnD,QAAO,QAAQ,YAAY,EAAE,0BAA0B;;AAGzD,eAAsB,qBAAqB,SAAkD;CAC3F,MAAM,OAAO,4BAA4B;AACzC,WAAU,QAAQ,MAAM,KAAK,EAAE,EAAE,WAAW,MAAM,CAAC;AAKnD,eAAc,MAAM,GAAG,KAAK,UAJM;EAChC,SAAS;EACT;EACD,EAC2C,MAAM,EAAE,CAAC,KAAK,QAAQ;AAClE,QAAO;;AAGT,eAAsB,yBAA8D;CAClF,MAAM,OAAO,4BAA4B;AACzC,KAAI,CAAC,WAAW,KAAK,CACnB,QAAO;AAET,KAAI;EACF,MAAM,MAAM,aAAa,MAAM,QAAQ;EACvC,MAAM,SAAS,KAAK,MAAM,IAAI;AAC9B,MAAI,CAAC,UAAU,OAAO,YAAY,KAAK,CAAC,OAAO,SAAS;AACtD,UAAO,MAAM,EAAE,OAAO,MAAM,CAAC;AAC7B,UAAO;;AAET,SAAO,MAAM,EAAE,OAAO,MAAM,CAAC;AAC7B,SAAO;SACD;AACN,SAAO,MAAM,EAAE,OAAO,MAAM,CAAC;AAC7B,SAAO;;;AAIX,SAAgB,yBAAyB,SAAyC;CAChF,MAAM,SAAS,cAAc,QAAQ,OAAO,UAAU,IAAI,yBAAyB;AACnF,KAAI,QAAQ,SAAS,aACnB,QAAO,QAAQ,WAAW,OACtB,uDACA;AAEN,KAAI,QAAQ,SAAS,kBAAkB,QAAQ,SAAS,eACtD,QAAO,QAAQ,WAAW,OACtB,4CACA;AAEN,KAAI,OACF,QAAO,6BAA6B,OAAO;AAE7C,QAAO;;AAGT,SAAgB,6BAA6B,SAAyC;CACpF,MAAM,QAAQ,CAAC,yBAAyB,QAAQ,CAAC;CACjD,MAAM,OAAO,cAAc,QAAQ,WAAW,IAAI,uBAAuB;AACzE,KAAI,KACF,OAAM,KAAK,KAAK;CAElB,MAAM,SAAS,cAAc,QAAQ,OAAO,UAAU,IAAI,yBAAyB;AACnF,KAAI,UAAU,CAAC,MAAM,MAAM,SAAS,KAAK,SAAS,OAAO,CAAC,CACxD,OAAM,KAAK,WAAW,SAAS;AAIjC,QAAO,OADS,MAAM,KAAK,KAAK,CAAC,MAAM,EAChB,2BAA2B;;AAGpD,SAAgB,gBACd,YAC4C;CAC5C,MAAM,QAAQ,YAAY,MAAM;AAChC,KAAI,CAAC,MACH,QAAO;CAET,MAAM,YAAY,MAAM,QAAQ,IAAI;AACpC,KAAI,aAAa,KAAK,aAAa,MAAM,SAAS,EAChD,QAAO;AAET,QAAO;EACL,SAAS,MAAM,MAAM,GAAG,UAAU;EAClC,QAAQ,MAAM,MAAM,YAAY,EAAE;EACnC"}

package/dist/utils/runtime/managed-service-routing.utils.d.ts

@@ -0,0 +1,31 @@
+import { ManagedServiceState } from "../../stores/managed-service-state.store.js";
+import { localUiRuntimeStore } from "../../stores/local-ui-runtime.store.js";
+
+//#region src/utils/runtime/managed-service-routing.utils.d.ts
+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;
+//#endregion
+export { ManagedServiceSnapshot, resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate };
+//# sourceMappingURL=managed-service-routing.utils.d.ts.map

package/dist/utils/runtime/managed-service-routing.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-service-routing.utils.d.ts","names":[],"sources":["../../../src/utils/runtime/managed-service-routing.utils.ts"],"mappings":";;;;KAIY,sBAAA;EACV,GAAA;EACA,KAAA;EACA,MAAA;EACA,MAAA;EACA,MAAA;EACA,OAAA;AAAA;AAAA,iBAGc,kCAAA,CAAmC,MAAA;EACjD,QAAA,EAAU,sBAAA;EACV,uBAAA,UAAiC,mBAAA,CAAoB,IAAA;EACrD,kBAAA,IAAsB,GAAA;AAAA,IACpB,sBAAA;AAAA,iBA6CY,8BAAA,CAA+B,KAAA,EAAO,mBAAA;EACpD,IAAA;EACA,IAAA;AAAA;AAAA,iBAiBc,4BAAA,CAA6B,MAAA;EAC3C,OAAA;EACA,uBAAA,GAA0B,KAAA;AAAA;EACtB,GAAA;EAAa,SAAA;AAAA"}

package/dist/utils/runtime/managed-service-routing.utils.js

@@ -0,0 +1,64 @@
+import { isProcessRunning } from "../cli.utils.js";
+import { localUiRuntimeStore } from "../../stores/local-ui-runtime.store.js";
+import "../../stores/managed-service-state.store.js";
+//#region src/utils/runtime/managed-service-routing.utils.ts
+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 { metadata, normalizeOptionalString } = params;
+	const context = toObjectRecord(metadata.last_delivery_context) ?? {};
+	const hasPrimaryRoute = Boolean(normalizeOptionalString(context.channel)) && Boolean(normalizeOptionalString(context.chatId));
+	const hasFallbackRoute = Boolean(normalizeOptionalString(metadata.last_channel)) && Boolean(normalizeOptionalString(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 { session, normalizeOptionalString } = params;
+	const sessionRecord = toObjectRecord(session);
+	const key = normalizeOptionalString(sessionRecord?.key);
+	if (!key || key.startsWith("cli:")) return null;
+	if (!hasSessionRoutingMetadata({
+		metadata: toObjectRecord(sessionRecord?.metadata) ?? {},
+		normalizeOptionalString
+	})) return null;
+	const updatedAtRaw = normalizeOptionalString(sessionRecord?.updated_at);
+	const updatedAt = updatedAtRaw ? Date.parse(updatedAtRaw) : NaN;
+	return {
+		key,
+		updatedAt: Number.isFinite(updatedAt) ? updatedAt : 0
+	};
+}
+//#endregion
+export { resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate };
+
+//# sourceMappingURL=managed-service-routing.utils.js.map

package/dist/utils/runtime/managed-service-routing.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-service-routing.utils.js","names":[],"sources":["../../../src/utils/runtime/managed-service-routing.utils.ts"],"sourcesContent":["import { type ManagedServiceState } from \"@nextclaw-service/stores/managed-service-state.store.js\";\nimport { localUiRuntimeStore } from \"@nextclaw-service/stores/local-ui-runtime.store.js\";\nimport { isProcessRunning } from \"@nextclaw-service/utils/cli.utils.js\";\n\nexport type ManagedServiceSnapshot = {\n  pid: number;\n  uiUrl: string;\n  apiUrl: string;\n  uiHost: string;\n  uiPort: number;\n  logPath: string;\n};\n\nexport function resolveManagedServiceReadySnapshot(params: {\n  snapshot: ManagedServiceSnapshot;\n  readLocalUiRuntimeState?: typeof localUiRuntimeStore.read;\n  isProcessRunningFn?: (pid: number) => boolean;\n}): ManagedServiceSnapshot {\n  const { snapshot, readLocalUiRuntimeState, isProcessRunningFn: providedIsProcessRunningFn } = params;\n  const localUiRuntimeState = (readLocalUiRuntimeState ?? localUiRuntimeStore.read)();\n  const isProcessRunningFn = providedIsProcessRunningFn ?? isProcessRunning;\n  if (\n    !localUiRuntimeState\n    || typeof localUiRuntimeState.pid !== \"number\"\n    || !Number.isFinite(localUiRuntimeState.pid)\n    || localUiRuntimeState.uiPort !== snapshot.uiPort\n    || !isProcessRunningFn(localUiRuntimeState.pid)\n  ) {\n    return snapshot;\n  }\n  return {\n    ...snapshot,\n    pid: localUiRuntimeState.pid,\n    uiUrl: localUiRuntimeState.uiUrl,\n    apiUrl: localUiRuntimeState.apiUrl,\n    uiHost: localUiRuntimeState.uiHost ?? snapshot.uiHost,\n    uiPort: localUiRuntimeState.uiPort ?? snapshot.uiPort\n  };\n}\n\nfunction toObjectRecord(value: unknown): Record<string, unknown> | null {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) {\n    return null;\n  }\n  return value as Record<string, unknown>;\n}\n\nfunction hasSessionRoutingMetadata(params: {\n  metadata: Record<string, unknown>;\n  normalizeOptionalString: (value: unknown) => string | undefined;\n}): boolean {\n  const { metadata, normalizeOptionalString } = params;\n  const context = toObjectRecord(metadata.last_delivery_context) ?? {};\n  const hasPrimaryRoute =\n    Boolean(normalizeOptionalString(context.channel)) &&\n    Boolean(normalizeOptionalString(context.chatId));\n  const hasFallbackRoute =\n    Boolean(normalizeOptionalString(metadata.last_channel)) &&\n    Boolean(normalizeOptionalString(metadata.last_to));\n  return hasPrimaryRoute || hasFallbackRoute;\n}\n\nexport function resolveManagedServiceUiBinding(state: ManagedServiceState): {\n  host: string;\n  port: number;\n} {\n  try {\n    const parsed = new URL(state.uiUrl);\n    const parsedPort = Number(parsed.port || 80);\n    return {\n      host: state.uiHost ?? parsed.hostname,\n      port: Number.isFinite(parsedPort) ? parsedPort : state.uiPort ?? 55667\n    };\n  } catch {\n    return {\n      host: state.uiHost ?? \"127.0.0.1\",\n      port: state.uiPort ?? 55667\n    };\n  }\n}\n\nexport function resolveSessionRouteCandidate(params: {\n  session: unknown;\n  normalizeOptionalString: (value: unknown) => string | undefined;\n}): { key: string; updatedAt: number } | null {\n  const { session, normalizeOptionalString } = params;\n  const sessionRecord = toObjectRecord(session);\n  const key = normalizeOptionalString(sessionRecord?.key);\n  if (!key || key.startsWith(\"cli:\")) {\n    return null;\n  }\n  const metadata = toObjectRecord(sessionRecord?.metadata) ?? {};\n  if (!hasSessionRoutingMetadata({ metadata, normalizeOptionalString })) {\n    return null;\n  }\n  const updatedAtRaw = normalizeOptionalString(sessionRecord?.updated_at);\n  const updatedAt = updatedAtRaw ? Date.parse(updatedAtRaw) : Number.NaN;\n  return {\n    key,\n    updatedAt: Number.isFinite(updatedAt) ? updatedAt : 0\n  };\n}\n"],"mappings":";;;;AAaA,SAAgB,mCAAmC,QAIxB;CACzB,MAAM,EAAE,UAAU,yBAAyB,oBAAoB,+BAA+B;CAC9F,MAAM,uBAAuB,2BAA2B,oBAAoB,OAAO;CACnF,MAAM,qBAAqB,8BAA8B;AACzD,KACE,CAAC,uBACE,OAAO,oBAAoB,QAAQ,YACnC,CAAC,OAAO,SAAS,oBAAoB,IAAI,IACzC,oBAAoB,WAAW,SAAS,UACxC,CAAC,mBAAmB,oBAAoB,IAAI,CAE/C,QAAO;AAET,QAAO;EACL,GAAG;EACH,KAAK,oBAAoB;EACzB,OAAO,oBAAoB;EAC3B,QAAQ,oBAAoB;EAC5B,QAAQ,oBAAoB,UAAU,SAAS;EAC/C,QAAQ,oBAAoB,UAAU,SAAS;EAChD;;AAGH,SAAS,eAAe,OAAgD;AACtE,KAAI,CAAC,SAAS,OAAO,UAAU,YAAY,MAAM,QAAQ,MAAM,CAC7D,QAAO;AAET,QAAO;;AAGT,SAAS,0BAA0B,QAGvB;CACV,MAAM,EAAE,UAAU,4BAA4B;CAC9C,MAAM,UAAU,eAAe,SAAS,sBAAsB,IAAI,EAAE;CACpE,MAAM,kBACJ,QAAQ,wBAAwB,QAAQ,QAAQ,CAAC,IACjD,QAAQ,wBAAwB,QAAQ,OAAO,CAAC;CAClD,MAAM,mBACJ,QAAQ,wBAAwB,SAAS,aAAa,CAAC,IACvD,QAAQ,wBAAwB,SAAS,QAAQ,CAAC;AACpD,QAAO,mBAAmB;;AAG5B,SAAgB,+BAA+B,OAG7C;AACA,KAAI;EACF,MAAM,SAAS,IAAI,IAAI,MAAM,MAAM;EACnC,MAAM,aAAa,OAAO,OAAO,QAAQ,GAAG;AAC5C,SAAO;GACL,MAAM,MAAM,UAAU,OAAO;GAC7B,MAAM,OAAO,SAAS,WAAW,GAAG,aAAa,MAAM,UAAU;GAClE;SACK;AACN,SAAO;GACL,MAAM,MAAM,UAAU;GACtB,MAAM,MAAM,UAAU;GACvB;;;AAIL,SAAgB,6BAA6B,QAGC;CAC5C,MAAM,EAAE,SAAS,4BAA4B;CAC7C,MAAM,gBAAgB,eAAe,QAAQ;CAC7C,MAAM,MAAM,wBAAwB,eAAe,IAAI;AACvD,KAAI,CAAC,OAAO,IAAI,WAAW,OAAO,CAChC,QAAO;AAGT,KAAI,CAAC,0BAA0B;EAAE,UADhB,eAAe,eAAe,SAAS,IAAI,EAAE;EACnB;EAAyB,CAAC,CACnE,QAAO;CAET,MAAM,eAAe,wBAAwB,eAAe,WAAW;CACvE,MAAM,YAAY,eAAe,KAAK,MAAM,aAAa,GAAG;AAC5D,QAAO;EACL;EACA,WAAW,OAAO,SAAS,UAAU,GAAG,YAAY;EACrD"}

package/dist/utils/runtime/service-remote-runtime.utils.d.ts

@@ -0,0 +1,58 @@
+import { ManagedServiceLease, ManagedServiceState } from "../../stores/managed-service-state.store.js";
+import { Config } from "@nextclaw/core";
+import { RemoteRuntimeState, RemoteServiceModule } from "@nextclaw/remote";
+
+//#region src/utils/runtime/service-remote-runtime.utils.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;
+  onRemoteStateChange?: (state: RemoteRuntimeState) => void;
+}): RemoteServiceModule | null;
+declare function createManagedRemoteModuleForUi(params: {
+  loadConfig: () => Config;
+  uiConfig: Pick<Config["ui"], "enabled" | "host" | "port">;
+  localOriginOverride?: string;
+  onRemoteStateChange?: (state: RemoteRuntimeState) => void;
+}): RemoteServiceModule | null;
+declare function writeInitialManagedServiceState(params: {
+  config: Config;
+  lease?: ManagedServiceLease;
+  readinessTimeoutMs: number;
+  snapshot: ManagedServiceSnapshot;
+}): void;
+declare function writeReadyManagedServiceState(params: {
+  lease?: ManagedServiceLease;
+  readinessTimeoutMs: number;
+  readiness: {
+    ready: boolean;
+    lastProbeError: string | null;
+  };
+  snapshot: ManagedServiceSnapshot;
+}): ManagedServiceState;
+//#endregion
+export { claimManagedRemoteRuntimeOwnership, createManagedRemoteModule, createManagedRemoteModuleForUi, writeInitialManagedServiceState, writeReadyManagedServiceState };
+//# sourceMappingURL=service-remote-runtime.utils.d.ts.map

package/dist/utils/runtime/service-remote-runtime.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-remote-runtime.utils.d.ts","names":[],"sources":["../../../src/utils/runtime/service-remote-runtime.utils.ts"],"mappings":";;;;;KA0BK,sBAAA;EACH,GAAA;EACA,KAAA;EACA,MAAA;EACA,MAAA;EACA,MAAA;EACA,OAAA;AAAA;AAAA,KASG,2BAAA;EAAgC,EAAA;EAAU,OAAA;AAAA;EAA0B,EAAA;EAAW,KAAA;AAAA;AAAA,iBA4IpE,kCAAA,CAAmC,MAAA;EACjD,WAAA;EACA,QAAA;EACA,UAAA;EACA,GAAA;EACA,kBAAA,IAAsB,GAAA;EACtB,kBAAA,SAA2B,mBAAA;AAAA,IACzB,2BAAA;AAAA,iBAuCY,yBAAA,CAA0B,MAAA;EACxC,UAAA,QAAkB,MAAA;EAClB,SAAA;EACA,WAAA;EACA,mBAAA,IAAuB,KAAA,EAAO,kBAAA;AAAA,IAC5B,mBAAA;AAAA,iBAoBY,8BAAA,CAA+B,MAAA;EAC7C,UAAA,QAAkB,MAAA;EAClB,QAAA,EAAU,IAAA,CAAK,MAAA;EACf,mBAAA;EAA8B,mBAAA,IAAuB,KAAA,EAAO,kBAAA;AAAA,IAC1D,mBAAA;AAAA,iBAcY,+BAAA,CAAgC,MAAA;EAC9C,MAAA,EAAQ,MAAA;EACR,KAAA,GAAQ,mBAAA;EACR,kBAAA;EACA,QAAA,EAAU,sBAAA;AAAA;AAAA,iBAmBI,6BAAA,CAA8B,MAAA;EAC5C,KAAA,GAAQ,mBAAA;EACR,kBAAA;EACA,SAAA;IAAa,KAAA;IAAgB,cAAA;EAAA;EAC7B,QAAA,EAAU,sBAAA;AAAA,IACR,mBAAA"}

package/dist/utils/runtime/service-remote-runtime.utils.js

@@ -0,0 +1,184 @@
+import { isProcessRunning, resolveUiApiBase } from "../cli.utils.js";
+import { managedServiceStateStore } from "../../stores/managed-service-state.store.js";
+import { buildNextclawConfiguredRemoteState, createNextclawRemoteConnector, createNextclawRemoteStatusStore } from "../remote/remote-runtime-support.utils.js";
+import { getRunPath } from "@nextclaw/core";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { RemoteServiceModule } from "@nextclaw/remote";
+//#region src/utils/runtime/service-remote-runtime.utils.ts
+function resolveRemoteOwnershipLockPath() {
+	return resolve(getRunPath(), "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) {
+	const { claim, currentPid, isProcessRunningFn, lockPath } = params;
+	for (let attempt = 0; attempt < 2; attempt += 1) try {
+		const fd = openSync(lockPath, "wx");
+		writeFileSync(fd, `${JSON.stringify(claim, null, 2)}\n`, "utf-8");
+		closeSync(fd);
+		return {
+			ok: true,
+			release: createRemoteOwnershipRelease({
+				lockPath,
+				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(lockPath);
+		if (existing && existing.pid !== currentPid && isProcessRunningFn(existing.pid)) return {
+			ok: false,
+			error: buildLocalProcessOwnershipError(existing)
+		};
+		removeRemoteOwnershipLock(lockPath);
+	}
+	return {
+		ok: false,
+		error: "Failed to claim local remote runtime ownership after clearing a stale lock."
+	};
+}
+function claimManagedRemoteRuntimeOwnership(params) {
+	const { localOrigin, lockPath: lockPathOverride, currentPid: currentPidOverride, now: nowOverride, isProcessRunningFn: isProcessRunningOverride, readServiceStateFn: readServiceStateOverride } = params;
+	const lockPath = lockPathOverride ?? resolveRemoteOwnershipLockPath();
+	const currentPid = currentPidOverride ?? process.pid;
+	const now = nowOverride ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+	const isProcessRunningFn = isProcessRunningOverride ?? isProcessRunning;
+	const managedConflict = detectManagedRemoteOwnershipConflict({
+		currentPid,
+		isProcessRunningFn,
+		readServiceStateFn: readServiceStateOverride ?? managedServiceStateStore.read
+	});
+	if (managedConflict) return {
+		ok: false,
+		error: managedConflict
+	};
+	mkdirSync(dirname(lockPath), { recursive: true });
+	return tryClaimRemoteOwnershipLock({
+		lockPath,
+		claim: {
+			pid: currentPid,
+			localOrigin,
+			claimedAt: now()
+		},
+		currentPid,
+		isProcessRunningFn
+	});
+}
+function createManagedRemoteModule(params) {
+	const { loadConfig, localOrigin, onRemoteStateChange, uiEnabled } = params;
+	if (!uiEnabled) return null;
+	return new RemoteServiceModule({
+		loadConfig,
+		uiEnabled,
+		localOrigin,
+		statusStore: createNextclawRemoteStatusStore("service", onRemoteStateChange),
+		createConnector: (logger) => createNextclawRemoteConnector({ logger }),
+		claimOwnership: () => claimManagedRemoteRuntimeOwnership({ localOrigin }),
+		logger: {
+			info: (message) => console.log(`[remote] ${message}`),
+			warn: (message) => console.warn(`[remote] ${message}`),
+			error: (message) => console.error(`[remote] ${message}`)
+		}
+	});
+}
+function createManagedRemoteModuleForUi(params) {
+	const { loadConfig, localOriginOverride, onRemoteStateChange, uiConfig } = params;
+	const explicitLocalOrigin = localOriginOverride?.trim() ?? process.env.NEXTCLAW_REMOTE_LOCAL_ORIGIN?.trim();
+	return createManagedRemoteModule({
+		loadConfig,
+		uiEnabled: uiConfig.enabled,
+		onRemoteStateChange,
+		localOrigin: explicitLocalOrigin && explicitLocalOrigin.length > 0 ? explicitLocalOrigin.replace(/\/+$/, "") : resolveUiApiBase(uiConfig.host, uiConfig.port)
+	});
+}
+function writeInitialManagedServiceState(params) {
+	const { config, lease, readinessTimeoutMs, snapshot } = params;
+	managedServiceStateStore.write({
+		pid: snapshot.pid,
+		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		uiUrl: snapshot.uiUrl,
+		apiUrl: snapshot.apiUrl,
+		uiHost: snapshot.uiHost,
+		uiPort: snapshot.uiPort,
+		logPath: snapshot.logPath,
+		...lease ? { lease } : {},
+		startupLastProbeError: null,
+		startupTimeoutMs: readinessTimeoutMs,
+		startupCheckedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		...config.remote.enabled ? { remote: buildNextclawConfiguredRemoteState(config) } : {}
+	});
+}
+function writeReadyManagedServiceState(params) {
+	const { lease, readiness, readinessTimeoutMs, snapshot } = params;
+	const currentState = managedServiceStateStore.read();
+	const state = {
+		pid: snapshot.pid,
+		startedAt: currentState?.startedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		uiUrl: snapshot.uiUrl,
+		apiUrl: snapshot.apiUrl,
+		uiHost: snapshot.uiHost,
+		uiPort: snapshot.uiPort,
+		logPath: snapshot.logPath,
+		...lease ? { lease } : currentState?.lease ? { lease: currentState.lease } : {},
+		startupState: readiness.ready ? "ready" : "degraded",
+		startupLastProbeError: readiness.lastProbeError,
+		startupTimeoutMs: readinessTimeoutMs,
+		startupCheckedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		...currentState?.remote ? { remote: currentState.remote } : {}
+	};
+	managedServiceStateStore.write(state);
+	return state;
+}
+//#endregion
+export { claimManagedRemoteRuntimeOwnership, createManagedRemoteModule, createManagedRemoteModuleForUi, writeInitialManagedServiceState, writeReadyManagedServiceState };
+
+//# sourceMappingURL=service-remote-runtime.utils.js.map

package/dist/utils/runtime/service-remote-runtime.utils.js.map

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

package/dist/utils/runtime-helpers.utils.d.ts

@@ -0,0 +1,15 @@
+import { Config } from "@nextclaw/core";
+
+//#region src/utils/runtime-helpers.utils.d.ts
+declare function resolveSkillsInstallWorkdir(params: {
+  explicitWorkdir?: string;
+  configuredWorkspace?: string;
+}): string;
+declare function parseStartTimeoutMs(value: string | number | undefined): number | undefined;
+declare function resolveManagedServiceUiOverrides(params: {
+  uiPort: string | number | undefined;
+  forcedPublicHost: string;
+}): Partial<Config["ui"]>;
+//#endregion
+export { parseStartTimeoutMs, resolveManagedServiceUiOverrides, resolveSkillsInstallWorkdir };
+//# sourceMappingURL=runtime-helpers.utils.d.ts.map

package/dist/utils/runtime-helpers.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-helpers.utils.d.ts","names":[],"sources":["../../src/utils/runtime-helpers.utils.ts"],"mappings":";;;iBAEgB,2BAAA,CAA4B,MAAA;EAC1C,eAAA;EACA,mBAAA;AAAA;AAAA,iBAQc,mBAAA,CAAoB,KAAA;AAAA,iBAYpB,gCAAA,CAAiC,MAAA;EAC/C,MAAA;EACA,gBAAA;AAAA,IACE,OAAA,CAAQ,MAAA"}

package/dist/utils/runtime-helpers.utils.js

@@ -0,0 +1,28 @@
+import { expandHome, getWorkspacePath } from "@nextclaw/core";
+//#region src/utils/runtime-helpers.utils.ts
+function resolveSkillsInstallWorkdir(params) {
+	if (params.explicitWorkdir) return expandHome(params.explicitWorkdir);
+	return getWorkspacePath(params.configuredWorkspace);
+}
+function parseStartTimeoutMs(value) {
+	if (value === void 0) return;
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed <= 0) {
+		console.error("Invalid --start-timeout value. Provide milliseconds (e.g. 45000).");
+		process.exit(1);
+	}
+	return Math.floor(parsed);
+}
+function resolveManagedServiceUiOverrides(params) {
+	const uiOverrides = {
+		enabled: true,
+		host: params.forcedPublicHost,
+		open: false
+	};
+	if (params.uiPort) uiOverrides.port = Number(params.uiPort);
+	return uiOverrides;
+}
+//#endregion
+export { parseStartTimeoutMs, resolveManagedServiceUiOverrides, resolveSkillsInstallWorkdir };
+
+//# sourceMappingURL=runtime-helpers.utils.js.map

package/dist/utils/runtime-helpers.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-helpers.utils.js","names":[],"sources":["../../src/utils/runtime-helpers.utils.ts"],"sourcesContent":["import { expandHome, getWorkspacePath, type Config } from \"@nextclaw/core\";\n\nexport function resolveSkillsInstallWorkdir(params: {\n  explicitWorkdir?: string;\n  configuredWorkspace?: string;\n}): string {\n  if (params.explicitWorkdir) {\n    return expandHome(params.explicitWorkdir);\n  }\n  return getWorkspacePath(params.configuredWorkspace);\n}\n\nexport function parseStartTimeoutMs(value: string | number | undefined): number | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n  const parsed = Number(value);\n  if (!Number.isFinite(parsed) || parsed <= 0) {\n    console.error(\"Invalid --start-timeout value. Provide milliseconds (e.g. 45000).\");\n    process.exit(1);\n  }\n  return Math.floor(parsed);\n}\n\nexport function resolveManagedServiceUiOverrides(params: {\n  uiPort: string | number | undefined;\n  forcedPublicHost: string;\n}): Partial<Config[\"ui\"]> {\n  const uiOverrides: Partial<Config[\"ui\"]> = {\n    enabled: true,\n    host: params.forcedPublicHost,\n    open: false,\n  };\n  if (params.uiPort) {\n    uiOverrides.port = Number(params.uiPort);\n  }\n  return uiOverrides;\n}\n"],"mappings":";;AAEA,SAAgB,4BAA4B,QAGjC;AACT,KAAI,OAAO,gBACT,QAAO,WAAW,OAAO,gBAAgB;AAE3C,QAAO,iBAAiB,OAAO,oBAAoB;;AAGrD,SAAgB,oBAAoB,OAAwD;AAC1F,KAAI,UAAU,KAAA,EACZ;CAEF,MAAM,SAAS,OAAO,MAAM;AAC5B,KAAI,CAAC,OAAO,SAAS,OAAO,IAAI,UAAU,GAAG;AAC3C,UAAQ,MAAM,oEAAoE;AAClF,UAAQ,KAAK,EAAE;;AAEjB,QAAO,KAAK,MAAM,OAAO;;AAG3B,SAAgB,iCAAiC,QAGvB;CACxB,MAAM,cAAqC;EACzC,SAAS;EACT,MAAM,OAAO;EACb,MAAM;EACP;AACD,KAAI,OAAO,OACT,aAAY,OAAO,OAAO,OAAO,OAAO;AAE1C,QAAO"}

package/dist/utils/service-port-probe.utils.d.ts

@@ -0,0 +1,42 @@
+import { Config } from "@nextclaw/core";
+
+//#region src/utils/service-port-probe.utils.d.ts
+declare function checkPortAvailability(params: {
+  host: string;
+  port: number;
+}): Promise<{
+  available: boolean;
+  detail: string;
+}>;
+declare function probeHealthEndpoint(healthUrl: string): Promise<{
+  healthy: boolean;
+  error: string | null;
+}>;
+type UiTargetProbeResult = {
+  state: "available";
+  availabilityDetail: string;
+  probeError: null;
+} | {
+  state: "healthy-existing";
+  availabilityDetail: string;
+  probeError: null;
+} | {
+  state: "occupied-unhealthy";
+  availabilityDetail: string;
+  probeError: string | null;
+};
+declare function inspectUiTarget(params: {
+  host: string;
+  port: number;
+  healthUrl: string;
+  checkPortAvailabilityFn?: typeof checkPortAvailability;
+  probeHealthEndpointFn?: typeof probeHealthEndpoint;
+}): Promise<UiTargetProbeResult>;
+declare function describeUnmanagedHealthyTargetMessage(params: {
+  uiOverrides: Partial<Config["ui"]>;
+  checkPortAvailabilityFn?: typeof checkPortAvailability;
+  probeHealthEndpointFn?: typeof probeHealthEndpoint;
+}): Promise<string | null>;
+//#endregion
+export { UiTargetProbeResult, checkPortAvailability, describeUnmanagedHealthyTargetMessage, inspectUiTarget, probeHealthEndpoint };
+//# sourceMappingURL=service-port-probe.utils.d.ts.map

package/dist/utils/service-port-probe.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-port-probe.utils.d.ts","names":[],"sources":["../../src/utils/service-port-probe.utils.ts"],"mappings":";;;iBA6BsB,qBAAA,CAAsB,MAAA;EAC1C,IAAA;EACA,IAAA;AAAA,IACE,OAAA;EAAU,SAAA;EAAoB,MAAA;AAAA;AAAA,iBAoBZ,mBAAA,CAAoB,SAAA,WAAoB,OAAA;EAAU,OAAA;EAAkB,KAAA;AAAA;AAAA,KA6E9E,mBAAA;EAEN,KAAA;EACA,kBAAA;EACA,UAAA;AAAA;EAGA,KAAA;EACA,kBAAA;EACA,UAAA;AAAA;EAGA,KAAA;EACA,kBAAA;EACA,UAAA;AAAA;AAAA,iBAGgB,eAAA,CAAgB,MAAA;EACpC,IAAA;EACA,IAAA;EACA,SAAA;EACA,uBAAA,UAAiC,qBAAA;EACjC,qBAAA,UAA+B,mBAAA;AAAA,IAC7B,OAAA,CAAQ,mBAAA;AAAA,iBA8BU,qCAAA,CAAsC,MAAA;EAC1D,WAAA,EAAa,OAAA,CAAQ,MAAA;EACrB,uBAAA,UAAiC,qBAAA;EACjC,qBAAA,UAA+B,mBAAA;AAAA,IAC7B,OAAA"}