@memtensor/memos-cloud-openclaw-plugin 0.1.20 → 0.1.21-beta.0

package/lib/config-ui-server.js

@@ -1,578 +1,578 @@
-
+
 import { createHash, randomBytes } from "node:crypto";
 import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { createServer } from "node:http";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Script } from "node:vm";
 import { checkForPluginUpdate, getPackageVersion } from "./check-update.js";
 import { getConfigResolution } from "./memos-cloud-api.js";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-const PLUGIN_ID = "memos-cloud-openclaw-plugin";
-const UI_HOST = "127.0.0.1";
-const UI_BASE_PORT = 38463;
-const UI_PORT_ATTEMPTS = 24;
-const GLOBAL_STATE_KEY = "__memosCloudConfigUiState";
-const ASSET_DIR = join(__dirname, "config-ui");
-const ANSI_BOLD = "\x1b[1m";
-const ANSI_CYAN = "\x1b[36m";
-const ANSI_GREEN = "\x1b[32m";
-const ANSI_YELLOW = "\x1b[33m";
-const ANSI_RESET = "\x1b[0m";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const PLUGIN_ID = "memos-cloud-openclaw-plugin";
+const UI_HOST = "127.0.0.1";
+const UI_BASE_PORT = 38463;
+const UI_PORT_ATTEMPTS = 24;
+const GLOBAL_STATE_KEY = "__memosCloudConfigUiState";
+const ASSET_DIR = join(__dirname, "config-ui");
+const ANSI_BOLD = "\x1b[1m";
+const ANSI_CYAN = "\x1b[36m";
+const ANSI_GREEN = "\x1b[32m";
+const ANSI_YELLOW = "\x1b[33m";
+const ANSI_RESET = "\x1b[0m";
 const DEFAULT_GATEWAY_READY_PORT = 18789;
 const UPDATE_STATUS_CACHE_MS = 30 * 60 * 1000;
-
-// Hook policies that the gateway requires non-bundled plugins to opt into.
-// Without these, the gateway blocks `agent_end` (and other conversation-access
-// hooks) at registration time. Keep this list in sync with the policies the
-// plugin actually relies on so we never drift from runtime behavior.
-const REQUIRED_HOOK_POLICIES = ["allowConversationAccess"];
-
-const FIELD_GROUPS = [
-  { id: "connection", title: "Connection", description: "MemOS endpoint, authentication, and identity mapping." },
-  { id: "session", title: "Session And Recall", description: "Conversation id strategy, recall scope, and injection behavior." },
-  { id: "capture", title: "Capture And Storage", description: "What gets written back to MemOS after each agent run." },
-  { id: "agent", title: "Agent Isolation", description: "Multi-agent isolation, app metadata, and sharing permissions." },
-  { id: "filter", title: "Recall Filter", description: "Optional model-based second-pass filtering before memories are injected." },
-  { id: "advanced", title: "Advanced", description: "Timeouts, throttling, and low-level controls." },
-];
-
-const FIELD_DEFINITIONS = [
-  { key: "baseUrl", group: "connection", type: "string", label: "MemOS Base URL", description: "Base URL for the MemOS OpenMem API.", placeholder: "https://memos.memtensor.cn/api/openmem/v1" },
-  { key: "apiKey", group: "connection", type: "secret", label: "MemOS API Key", description: "Token auth key. Leave inherited to use env files.", placeholder: "mpg-..." },
-  { key: "userId", group: "connection", type: "string", label: "User ID", description: "Unique identifier of the user associated with added messages and queried memories.", placeholder: "openclaw-user" },
-  { key: "useDirectSessionUserId", group: "connection", type: "boolean", label: "Use Direct Session User ID", description: "Use direct-session user id from session key when available." },
-  { key: "conversationId", group: "session", type: "string", label: "Conversation ID Override", description: "Unique identifier of the conversation. Reusing the same value keeps turns in the same context." },
-  { key: "conversationIdPrefix", group: "session", type: "string", label: "Conversation Prefix", description: "Prepended to the derived conversation id." },
-  { key: "conversationIdSuffix", group: "session", type: "string", label: "Conversation Suffix", description: "Appended to the derived conversation id." },
-  { key: "conversationSuffixMode", group: "session", type: "enum", label: "Suffix Mode", description: "Choose whether /new increments a numeric suffix.", options: [{ value: "none", label: "none" }, { value: "counter", label: "counter" }] },
-  { key: "resetOnNew", group: "session", type: "boolean", label: "Reset On /new", description: "Requires hooks.internal.enabled when counter suffix mode is used." },
-  { key: "queryPrefix", group: "session", type: "textarea", rows: 4, label: "Query Prefix", description: "Extra text prepended to query before retrieval.", placeholder: "important user context preferences decisions " },
-  { key: "maxQueryChars", group: "session", type: "integer", label: "Max Query Chars", description: "Limit the query text length before sending recall search.", placeholder: "0" },
-  { key: "recallEnabled", group: "session", type: "boolean", label: "Recall Enabled", description: "Enable before_agent_start memory recall." },
-  { key: "recallGlobal", group: "session", type: "boolean", label: "Global Recall", description: "When enabled, query is sent without conversation_id, so current-session weighting is not emphasized." },
-  { key: "maxItemChars", group: "session", type: "integer", label: "Max Item Chars", description: "Maximum characters kept when injecting each recalled memory item into context.", placeholder: "8000" },
-  { key: "memoryLimitNumber", group: "session", type: "integer", label: "Memory Limit", description: "Maximum number of recalled memories. Default is 9, max is 25.", placeholder: "9" },
-  { key: "preferenceLimitNumber", group: "session", type: "integer", label: "Preference Limit", description: "Maximum number of recalled preference memories. Default is 9, max is 25.", placeholder: "9" },
-  { key: "includePreference", group: "session", type: "boolean", label: "Include Preferences", description: "Whether to enable preference memory recall." },
-  { key: "includeToolMemory", group: "session", type: "boolean", label: "Include Tool Memory", description: "Whether to enable tool memory recall." },
-  { key: "toolMemoryLimitNumber", group: "session", type: "integer", label: "Tool Memory Limit", description: "Maximum number of tool memories returned. Effective only when tool memory recall is enabled.", placeholder: "6" },
-  { key: "relativity", group: "session", type: "number", label: "Relativity Threshold", description: "Recall relevance threshold from 0 to 1. Set to 0 to disable relevance filtering.", placeholder: "0.45", step: "0.01" },
-  { key: "filter", group: "session", type: "json", rows: 7, label: "Search Filter (JSON)", description: "Filter conditions used before retrieval. Supports agent_id, app_id, time fields, info fields, and and/or/gte/lte/gt/lt.", placeholder: '{\n  "agent_id": "assistant-1"\n}' },
-  { key: "knowledgebaseIds", group: "session", type: "stringArray", rows: 4, label: "Knowledge Base IDs", description: "Restrict the knowledgebase scope for this search. Use one ID per line, or all.", placeholder: "kb-001\nkb-002" },
-  { key: "addEnabled", group: "capture", type: "boolean", label: "Add Enabled", description: "Enable adding message arrays and writing resulting memories at agent_end." },
-  { key: "captureStrategy", group: "capture", type: "enum", label: "Capture Strategy", description: "Choose whether messages contains only the last turn or the full session.", options: [{ value: "last_turn", label: "last_turn" }, { value: "full_session", label: "full_session" }] },
-  { key: "maxMessageChars", group: "capture", type: "integer", label: "Max Message Chars", description: "Maximum characters kept per stored message before building the messages array.", placeholder: "20000" },
-  { key: "includeAssistant", group: "capture", type: "boolean", label: "Include Assistant", description: "Include assistant replies in the messages array." },
-  { key: "tags", group: "capture", type: "stringArray", rows: 4, label: "Tags", description: "Custom tags used to classify added messages. One value per line.", placeholder: "openclaw" },
-  { key: "info", group: "capture", type: "json", rows: 7, label: "Info Payload (JSON)", description: "Structured metadata merged into info for filtering, tracing, and source tracking.", placeholder: '{\n  "channel": "webchat"\n}' },
-  { key: "asyncMode", group: "capture", type: "boolean", label: "Async Mode", description: "Add memories asynchronously in the background to avoid blocking the call chain." },
-  { key: "agentId", group: "agent", type: "string", label: "Static Agent ID", description: "Unique identifier of the Agent associated with added messages and retrieved memories." },
-  { key: "multiAgentMode", group: "agent", type: "boolean", label: "Multi-Agent Mode", description: "Isolate recall and add payloads by ctx.agentId when available." },
-  { key: "allowedAgents", group: "agent", type: "stringArray", rows: 4, label: "Allowed Agents", description: "Only listed agent ids are allowed to recall and add; empty means all agents." },
-  { key: "agentOverrides", group: "agent", type: "json", rows: 10, label: "Agent Overrides (JSON)", description: "Per-agent overrides. Key is agent id, value is an object of supported override fields.", placeholder: '{\n  "assistant-1": {\n    "knowledgebaseIds": ["kb-001"],\n    "recallEnabled": true\n  }\n}' },
-  { key: "appId", group: "agent", type: "string", label: "App ID", description: "Unique identifier of the App associated with added messages and retrieved memories." },
-  { key: "allowPublic", group: "agent", type: "boolean", label: "Allow Public", description: "Allow generated memories to be written to the public memory store." },
-  { key: "allowKnowledgebaseIds", group: "agent", type: "stringArray", rows: 4, label: "Allowed Knowledge Base IDs", description: "Knowledgebase scope where generated memories are allowed to be written. One ID per line.", placeholder: "kb-public\nkb-team" },
-  { key: "recallFilterEnabled", group: "filter", type: "boolean", label: "Recall Filter Enabled", description: "Enable second-pass model filtering for recall candidates." },
-  { key: "recallFilterBaseUrl", group: "filter", type: "string", label: "Filter Base URL", description: "OpenAI-compatible endpoint used for recall filtering.", placeholder: "http://127.0.0.1:11434/v1" },
-  { key: "recallFilterApiKey", group: "filter", type: "secret", label: "Filter API Key", description: "Optional bearer token for the recall filter model endpoint." },
-  { key: "recallFilterModel", group: "filter", type: "string", label: "Filter Model", description: "Model name used by the recall filter endpoint.", placeholder: "qwen2.5:7b" },
-  { key: "recallFilterTimeoutMs", group: "filter", type: "integer", label: "Filter Timeout (ms)", description: "Request timeout for the recall filter model.", placeholder: "6000" },
-  { key: "recallFilterRetries", group: "filter", type: "integer", label: "Filter Retries", description: "Retry count when the recall filter request fails.", placeholder: "0" },
-  { key: "recallFilterCandidateLimit", group: "filter", type: "integer", label: "Candidate Limit", description: "Per-category candidate limit before filtering.", placeholder: "30" },
-  { key: "recallFilterMaxItemChars", group: "filter", type: "integer", label: "Filter Max Item Chars", description: "Maximum characters kept per candidate item before filtering.", placeholder: "500" },
-  { key: "recallFilterFailOpen", group: "filter", type: "boolean", label: "Fail Open", description: "Fall back to unfiltered recall if the filter model errors." },
-  { key: "timeoutMs", group: "advanced", type: "integer", label: "MemOS Timeout (ms)", description: "Timeout used for MemOS API requests.", placeholder: "5000" },
-  { key: "retries", group: "advanced", type: "integer", label: "MemOS Retries", description: "Retry count for MemOS API requests.", placeholder: "1" },
-  { key: "throttleMs", group: "advanced", type: "integer", label: "Throttle (ms)", description: "Skip add/message when the previous capture happened too recently.", placeholder: "0" },
-];
-
-function getGlobalState() {
-  if (!globalThis[GLOBAL_STATE_KEY]) {
-    globalThis[GLOBAL_STATE_KEY] = {
-      promise: null,
-      service: null,
-      cleanupInstalled: false,
-      restartHookInstalled: false,
-      restartTimer: null,
-      restartPending: false,
-      recyclePromise: null,
-      shuttingDown: false,
-      child: null,
-    };
-  }
-  return globalThis[GLOBAL_STATE_KEY];
-}
-
-function isPlainObject(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-function deepClone(value) {
-  if (value === undefined) return undefined;
-  return JSON.parse(JSON.stringify(value));
-}
-
-function sanitizeStructuredValue(value, depth = 0) {
-  if (depth > 16) throw new Error("Config payload is too deeply nested.");
-  if (value === null) return null;
-  if (typeof value === "string" || typeof value === "boolean") return value;
-  if (typeof value === "number") {
-    if (!Number.isFinite(value)) throw new Error("Config payload contains a non-finite number.");
-    return value;
-  }
-  if (Array.isArray(value)) return value.map((item) => sanitizeStructuredValue(item, depth + 1));
-  if (isPlainObject(value)) {
-    const next = {};
-    for (const [key, child] of Object.entries(value)) {
-      const normalized = sanitizeStructuredValue(child, depth + 1);
-      if (normalized !== undefined) next[key] = normalized;
-    }
-    return next;
-  }
-  if (value === undefined) return undefined;
-  throw new Error("Config payload contains an unsupported value type.");
-}
-
-function sortForHash(value) {
-  if (Array.isArray(value)) return value.map((item) => sortForHash(item));
-  if (isPlainObject(value)) {
-    return Object.keys(value)
-      .sort()
-      .reduce((acc, key) => {
-        acc[key] = sortForHash(value[key]);
-        return acc;
-      }, {});
-  }
-  return value;
-}
-
-function createRevision(value) {
-  return createHash("sha1").update(JSON.stringify(sortForHash(value))).digest("hex").slice(0, 12);
-}
-
-function detectRuntimeProfile() {
-  const scriptPath = String(process.argv[1] || "").toLowerCase();
-  const execPath = String(process.execPath || "").toLowerCase();
-
-  if (scriptPath.includes("moltbot") || execPath.includes("moltbot")) {
-    return { id: "moltbot", displayName: "Moltbot", cliName: "moltbot", configPath: join(homedir(), ".moltbot", "moltbot.json") };
-  }
-  if (scriptPath.includes("clawdbot") || execPath.includes("clawdbot")) {
-    return { id: "clawdbot", displayName: "ClawDBot", cliName: "clawdbot", configPath: join(homedir(), ".clawdbot", "clawdbot.json") };
-  }
-  return { id: "openclaw", displayName: "OpenClaw", cliName: "openclaw", configPath: join(homedir(), ".openclaw", "openclaw.json") };
-}
-
-/**
- * Detect the version of the host CLI (openclaw / moltbot / clawdbot).
- *
- * Strategy (in order of preference):
- *  1. Parse `@X.Y.Z` out of `process.argv[1]` — pnpm/npm global installs
- *     always embed the version in the store path
- *     (e.g. `.../openclaw@2026.4.26/node_modules/openclaw/openclaw.mjs`).
- *  2. Walk up from `process.argv[1]` looking for a `package.json` that has
- *     a `version` field — covers local `node` invocations and bundled builds.
- *  3. Return `null` if neither succeeds.
- */
-export function detectHostVersion() {
-  const scriptPath = String(process.argv[1] || "");
-
-  const atMatch = scriptPath.match(/@(\d+\.\d+(?:\.\d+)?)/);
-  if (atMatch) return atMatch[1];
-
-  try {
-    let dir = dirname(scriptPath);
-    for (let i = 0; i < 8; i++) {
-      try {
-        const raw = readFileSync(join(dir, "package.json"), "utf8");
-        const pkg = JSON.parse(raw);
-        if (pkg.version && typeof pkg.version === "string") return pkg.version;
-      } catch {
-        // not found at this level, keep walking
-      }
-      const parent = dirname(dir);
-      if (parent === dir) break;
-      dir = parent;
-    }
-  } catch {
-    // ignore
-  }
-
-  return null;
-}
-
-/**
- * Compare two CalVer / semver version strings component by component.
- * Returns -1 when a < b, 0 when equal, 1 when a > b.
- * Non-numeric components (e.g. pre-release suffixes) are ignored.
- */
-export function compareVersionStrings(a, b) {
-  const partsA = String(a ?? "").split(".").map(Number);
-  const partsB = String(b ?? "").split(".").map(Number);
-  const len = Math.max(partsA.length, partsB.length);
-  for (let i = 0; i < len; i++) {
-    const na = Number.isFinite(partsA[i]) ? partsA[i] : 0;
-    const nb = Number.isFinite(partsB[i]) ? partsB[i] : 0;
-    if (na < nb) return -1;
-    if (na > nb) return 1;
-  }
-  return 0;
-}
-
-function parsePositiveInteger(value, fallback) {
-  const parsed = Number(value);
-  if (Number.isFinite(parsed) && parsed > 0) return Math.floor(parsed);
-  return fallback;
-}
-
-function resolveGatewayReadyProbeTarget(rootConfig = {}) {
-  const gateway = isPlainObject(rootConfig?.gateway) ? rootConfig.gateway : {};
-  const port = parsePositiveInteger(gateway.port, DEFAULT_GATEWAY_READY_PORT);
-  const bind = typeof gateway.bind === "string" ? gateway.bind.trim().toLowerCase() : "";
-  const customBindHost = typeof gateway.customBindHost === "string" ? gateway.customBindHost.trim() : "";
-  const host = bind === "custom" && customBindHost ? customBindHost : "127.0.0.1";
-  return { host, port, url: `http://${host}:${port}/ready` };
-}
-
-export async function waitForGatewayReady(rootConfig = {}, log = console, options = {}) {
-  const timeoutMs = parsePositiveInteger(options.timeoutMs, 45000);
-  const intervalMs = parsePositiveInteger(options.intervalMs, 300);
-  const deadline = Date.now() + timeoutMs;
-  const target = resolveGatewayReadyProbeTarget(rootConfig);
-
-  while (Date.now() < deadline) {
-    try {
-      const response = await fetch(target.url, {
-        method: "GET",
-        cache: "no-store",
-      });
-      if (response.ok) {
-        let body = null;
-        try {
-          body = await response.json();
-        } catch {
-          body = null;
-        }
-        if (!body || body.ready !== false) return true;
-      }
-    } catch {
-      // Ignore probe failures until timeout expires.
-    }
-
-    await new Promise((resolve) => setTimeout(resolve, intervalMs));
-  }
-
-  log.warn?.(`[memos-cloud] Gateway readiness probe timed out at ${target.url}; config UI will not start yet.`);
-  return false;
-}
-
-// Returns true when the current process was launched by an `openclaw gateway`
-// command that actually starts (or restarts) the long-lived gateway. Other
-// CLI entry points (`plugins install`, `security audit`, `--help`, ...) also
-// load this plugin to inspect/register it, but they perform their own
-// config commits and must not be racing with our hook-policy patcher.
-function isGatewayStartCommand() {
-  const args = process.argv.map((value) => String(value || "").toLowerCase());
-  const gatewayIndex = args.lastIndexOf("gateway");
-  if (gatewayIndex === -1) return false;
-
-  const nextArg = args[gatewayIndex + 1];
-  if (!nextArg || nextArg.startsWith("-")) return true;
-  return nextArg === "start" || nextArg === "restart" || nextArg === "run";
-}
-
-function shouldStartConfigUi() {
-  return isGatewayStartCommand();
-}
-
-export function isGatewayRuntimeStartup() {
-  return isGatewayStartCommand();
-}
-
-function stripBom(text) {
-  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
-}
-
-function parseJson5File(text, filePath) {
-  const source = stripBom(String(text || "")).trim();
-  if (!source) return {};
-
-  try {
-    const parsed = JSON.parse(source);
-    if (!isPlainObject(parsed)) throw new Error("Root config must be an object.");
-    return parsed;
-  } catch {
-    const script = new Script(`(${source}\n)`, { filename: filePath });
-    const parsed = script.runInNewContext(Object.create(null), { timeout: 500 });
-    if (!isPlainObject(parsed)) throw new Error("Root config must be an object.");
-    return parsed;
-  }
-}
-
-function hasIncludeDirective(value, depth = 0) {
-  if (depth > 8) return false;
-  if (Array.isArray(value)) return value.some((item) => hasIncludeDirective(item, depth + 1));
-  if (!isPlainObject(value)) return false;
-  if (Object.prototype.hasOwnProperty.call(value, "$include")) return true;
-  return Object.values(value).some((child) => hasIncludeDirective(child, depth + 1));
-}
-
-function readGatewayConfig(profile) {
-  let root = {};
-  let fileExists = true;
-  let stat = null;
-
-  try {
-    root = parseJson5File(readFileSync(profile.configPath, "utf8"), profile.configPath);
-    stat = statSync(profile.configPath);
-  } catch (error) {
-    if (error?.code !== "ENOENT") throw error;
-    fileExists = false;
-  }
-
-  const plugins = isPlainObject(root.plugins) ? root.plugins : {};
-  const entries = isPlainObject(plugins.entries) ? plugins.entries : {};
-  const entry = isPlainObject(entries[PLUGIN_ID]) ? entries[PLUGIN_ID] : null;
-  const config = entry && isPlainObject(entry.config) ? deepClone(entry.config) : {};
-  const enabled = entry ? entry.enabled !== false : true;
-
-  return {
-    profile,
-    fileExists,
-    configPath: profile.configPath,
-    entryExists: Boolean(entry),
-    enabled,
-    config,
-    root,
-    hasInclude: hasIncludeDirective(root.plugins) || hasIncludeDirective(root),
-    revision: createRevision({
-      config,
-      enabled,
-      entryExists: Boolean(entry),
-      fileExists,
-      mtimeMs: stat?.mtimeMs ?? 0,
-      size: stat?.size ?? 0,
-    }),
-  };
-}
-
-function writeGatewayConfig(profile, payload) {
-  const current = readGatewayConfig(profile);
-  const nextRoot = isPlainObject(current.root) ? deepClone(current.root) : {};
-  if (!isPlainObject(nextRoot.plugins)) nextRoot.plugins = {};
-  if (!isPlainObject(nextRoot.plugins.entries)) nextRoot.plugins.entries = {};
-
-  // Preserve any entry-level fields the user already set (e.g. `hooks`,
-  // policy opt-ins, future gateway metadata) so that saving from the config
-  // UI never silently drops gateway-required settings such as
-  // `hooks.allowConversationAccess`.
-  const previousEntry = isPlainObject(nextRoot.plugins.entries[PLUGIN_ID])
-    ? nextRoot.plugins.entries[PLUGIN_ID]
-    : {};
-  const entry = { ...previousEntry, enabled: payload.enabled !== false };
-
-  const config = sanitizeStructuredValue(payload.config ?? {});
-  if (!isPlainObject(config)) throw new Error("Config payload must be an object.");
-  if (Object.keys(config).length > 0) {
-    entry.config = config;
-  } else {
-    delete entry.config;
-  }
-
-  nextRoot.plugins.entries[PLUGIN_ID] = entry;
-
-  mkdirSync(dirname(profile.configPath), { recursive: true });
-  writeFileSync(profile.configPath, `${JSON.stringify(nextRoot, null, 2)}\n`, "utf8");
-  return readGatewayConfig(profile);
-}
-
-function getPluginEntry(root) {
-  const plugins = isPlainObject(root?.plugins) ? root.plugins : null;
-  if (!plugins) return null;
-  const entries = isPlainObject(plugins.entries) ? plugins.entries : null;
-  if (!entries) return null;
-  return isPlainObject(entries[PLUGIN_ID]) ? entries[PLUGIN_ID] : null;
-}
-
-function getMissingHookPolicies(root, hookKeys) {
-  const entry = getPluginEntry(root);
-  const hooks = isPlainObject(entry?.hooks) ? entry.hooks : {};
-  return hookKeys.filter((key) => hooks[key] !== true);
-}
-
-/**
- * Ensure the gateway config grants this plugin the typed-hook policies it
- * needs. The gateway blocks non-bundled plugins from registering hooks like
- * `agent_end` unless `plugins.entries.<id>.hooks.allowConversationAccess` is
- * explicitly set to `true`. Users hit this on every fresh install because the
- * key is not part of any default config template, so we patch it in
- * automatically on first load.
- *
- * Behavior:
- *  - Fast-path: if `rootConfig` already has all required keys, do nothing
- *    silently — no logs, no disk reads.
- *  - Otherwise: read the on-disk config (to preserve unrelated edits made
- *    after the gateway booted), merge in the missing keys, write it back,
- *    and return `{ changed: true }` so the caller can ask the user to
- *    restart the gateway. We only mutate the keys we own.
- *  - If the config uses `$include` directives we cannot safely rewrite the
- *    merged tree, so we just warn and leave the file untouched.
- *
- * NOTE: callers are responsible for deciding *when* to invoke this. In
- * particular it must NOT be called from short-lived CLI commands such as
- * `plugins install` that perform their own config commits — racing with
- * them triggers `ConfigMutationConflictError`. See `isGatewayRuntimeStartup`.
- */
-export function ensurePluginHookPolicy(rootConfig = null, log = console, options = {}) {
-  const hookKeys = Array.isArray(options.hookKeys) && options.hookKeys.length > 0
-    ? options.hookKeys
-    : REQUIRED_HOOK_POLICIES;
-
-  const profile = detectRuntimeProfile();
-
-  if (isPlainObject(rootConfig) && getMissingHookPolicies(rootConfig, hookKeys).length === 0) {
-    return { changed: false, configPath: profile.configPath, profile };
-  }
-
-  let current;
-  try {
-    current = readGatewayConfig(profile);
-  } catch (error) {
-    log.warn?.(
-      `[memos-cloud] failed to read ${profile.configPath} while ensuring plugin hook policy: ${String(error?.message ?? error)}`,
-    );
-    return { changed: false, error, configPath: profile.configPath, profile };
-  }
-
-  if (current.hasInclude) {
-    const missing = getMissingHookPolicies(current.root, hookKeys);
-    if (missing.length > 0) {
-      log.warn?.(
-        `[memos-cloud] gateway config at ${profile.configPath} uses $include directives, ` +
-          `cannot auto-enable required plugin hook policies: ${missing.join(", ")}. ` +
-          `Add plugins.entries.${PLUGIN_ID}.hooks={${missing.map((k) => `${k}:true`).join(", ")}} manually and restart the gateway.`,
-      );
-    }
-    return { changed: false, hasInclude: true, configPath: profile.configPath, profile };
-  }
-
-  const missingKeys = getMissingHookPolicies(current.root, hookKeys);
-  if (missingKeys.length === 0) return { changed: false, configPath: profile.configPath, profile };
-
-  const nextRoot = isPlainObject(current.root) ? deepClone(current.root) : {};
-  if (!isPlainObject(nextRoot.plugins)) nextRoot.plugins = {};
-  if (!isPlainObject(nextRoot.plugins.entries)) nextRoot.plugins.entries = {};
-  if (!isPlainObject(nextRoot.plugins.entries[PLUGIN_ID])) {
-    nextRoot.plugins.entries[PLUGIN_ID] = {};
-  }
-  const entry = nextRoot.plugins.entries[PLUGIN_ID];
-  if (entry.enabled === undefined) entry.enabled = true;
-  if (!isPlainObject(entry.hooks)) entry.hooks = {};
-  for (const key of missingKeys) {
-    entry.hooks[key] = true;
-  }
-
-  try {
-    mkdirSync(dirname(profile.configPath), { recursive: true });
-    writeFileSync(profile.configPath, `${JSON.stringify(nextRoot, null, 2)}\n`, "utf8");
-  } catch (error) {
-    log.warn?.(
-      `[memos-cloud] failed to write ${profile.configPath} to enable required plugin hook policies (${missingKeys.join(", ")}): ${String(error?.message ?? error)}`,
-    );
-    return { changed: false, error, configPath: profile.configPath, profile };
-  }
-
-  // Emit the eye-catching banner directly through stdout so the gateway's
-  // log-line prefix (`[plugins] [memos-cloud] ...`) does not break up the
-  // box drawing. Then also emit a single terse `log.warn` line so any
-  // structured log aggregator / CI capture still gets the event.
-//   console.log(renderHookPolicyRestartBanner(profile, missingKeys));
-  log.warn?.(
-    `[memos-cloud] hook policy patched in ${profile.configPath} (added: ${missingKeys.join(", ")}). ` +
-      `Manual gateway restart required: \`${profile.cliName} gateway restart\`.`,
-  );
-
-  return { changed: true, addedKeys: missingKeys, configPath: profile.configPath, profile };
-}
-
-/**
- * Returns metadata describing how `ensurePluginHookPolicy` would behave for
- * the current runtime, without writing anything. Useful in tests and for
- * letting host code surface "we will write to <path>" diagnostics before any
- * IO actually happens.
- */
-export function describePluginHookPolicyTarget() {
-  const profile = detectRuntimeProfile();
-  return {
-    runtime: profile.id,
-    configPath: profile.configPath,
-    hookKeys: [...REQUIRED_HOOK_POLICIES],
-  };
-}
-
-function buildStatePayload(service) {
-  const state = readGatewayConfig(service.profile);
-  const resolution = getConfigResolution(state.config);
-  return {
+
+// Hook policies that the gateway requires non-bundled plugins to opt into.
+// Without these, the gateway blocks `agent_end` (and other conversation-access
+// hooks) at registration time. Keep this list in sync with the policies the
+// plugin actually relies on so we never drift from runtime behavior.
+const REQUIRED_HOOK_POLICIES = ["allowConversationAccess"];
+
+const FIELD_GROUPS = [
+  { id: "connection", title: "Connection", description: "MemOS endpoint, authentication, and identity mapping." },
+  { id: "session", title: "Session And Recall", description: "Conversation id strategy, recall scope, and injection behavior." },
+  { id: "capture", title: "Capture And Storage", description: "What gets written back to MemOS after each agent run." },
+  { id: "agent", title: "Agent Isolation", description: "Multi-agent isolation, app metadata, and sharing permissions." },
+  { id: "filter", title: "Recall Filter", description: "Optional model-based second-pass filtering before memories are injected." },
+  { id: "advanced", title: "Advanced", description: "Timeouts, throttling, and low-level controls." },
+];
+
+const FIELD_DEFINITIONS = [
+  { key: "baseUrl", group: "connection", type: "string", label: "MemOS Base URL", description: "Base URL for the MemOS OpenMem API.", placeholder: "https://memos.memtensor.cn/api/openmem/v1" },
+  { key: "apiKey", group: "connection", type: "secret", label: "MemOS API Key", description: "Token auth key. Leave inherited to use env files.", placeholder: "mpg-..." },
+  { key: "userId", group: "connection", type: "string", label: "User ID", description: "Unique identifier of the user associated with added messages and queried memories.", placeholder: "openclaw-user" },
+  { key: "useDirectSessionUserId", group: "connection", type: "boolean", label: "Use Direct Session User ID", description: "Use direct-session user id from session key when available." },
+  { key: "conversationId", group: "session", type: "string", label: "Conversation ID Override", description: "Unique identifier of the conversation. Reusing the same value keeps turns in the same context." },
+  { key: "conversationIdPrefix", group: "session", type: "string", label: "Conversation Prefix", description: "Prepended to the derived conversation id." },
+  { key: "conversationIdSuffix", group: "session", type: "string", label: "Conversation Suffix", description: "Appended to the derived conversation id." },
+  { key: "conversationSuffixMode", group: "session", type: "enum", label: "Suffix Mode", description: "Choose whether /new increments a numeric suffix.", options: [{ value: "none", label: "none" }, { value: "counter", label: "counter" }] },
+  { key: "resetOnNew", group: "session", type: "boolean", label: "Reset On /new", description: "Requires hooks.internal.enabled when counter suffix mode is used." },
+  { key: "queryPrefix", group: "session", type: "textarea", rows: 4, label: "Query Prefix", description: "Extra text prepended to query before retrieval.", placeholder: "important user context preferences decisions " },
+  { key: "maxQueryChars", group: "session", type: "integer", label: "Max Query Chars", description: "Limit the query text length before sending recall search.", placeholder: "0" },
+  { key: "recallEnabled", group: "session", type: "boolean", label: "Recall Enabled", description: "Enable before_agent_start memory recall." },
+  { key: "recallGlobal", group: "session", type: "boolean", label: "Global Recall", description: "When enabled, query is sent without conversation_id, so current-session weighting is not emphasized." },
+  { key: "maxItemChars", group: "session", type: "integer", label: "Max Item Chars", description: "Maximum characters kept when injecting each recalled memory item into context.", placeholder: "8000" },
+  { key: "memoryLimitNumber", group: "session", type: "integer", label: "Memory Limit", description: "Maximum number of recalled memories. Default is 9, max is 25.", placeholder: "9" },
+  { key: "preferenceLimitNumber", group: "session", type: "integer", label: "Preference Limit", description: "Maximum number of recalled preference memories. Default is 9, max is 25.", placeholder: "9" },
+  { key: "includePreference", group: "session", type: "boolean", label: "Include Preferences", description: "Whether to enable preference memory recall." },
+  { key: "includeToolMemory", group: "session", type: "boolean", label: "Include Tool Memory", description: "Whether to enable tool memory recall." },
+  { key: "toolMemoryLimitNumber", group: "session", type: "integer", label: "Tool Memory Limit", description: "Maximum number of tool memories returned. Effective only when tool memory recall is enabled.", placeholder: "6" },
+  { key: "relativity", group: "session", type: "number", label: "Relativity Threshold", description: "Recall relevance threshold from 0 to 1. Set to 0 to disable relevance filtering.", placeholder: "0.45", step: "0.01" },
+  { key: "filter", group: "session", type: "json", rows: 7, label: "Search Filter (JSON)", description: "Filter conditions used before retrieval. Supports agent_id, app_id, time fields, info fields, and and/or/gte/lte/gt/lt.", placeholder: '{\n  "agent_id": "assistant-1"\n}' },
+  { key: "knowledgebaseIds", group: "session", type: "stringArray", rows: 4, label: "Knowledge Base IDs", description: "Restrict the knowledgebase scope for this search. Use one ID per line, or all.", placeholder: "kb-001\nkb-002" },
+  { key: "addEnabled", group: "capture", type: "boolean", label: "Add Enabled", description: "Enable adding message arrays and writing resulting memories at agent_end." },
+  { key: "captureStrategy", group: "capture", type: "enum", label: "Capture Strategy", description: "Choose whether messages contains only the last turn or the full session.", options: [{ value: "last_turn", label: "last_turn" }, { value: "full_session", label: "full_session" }] },
+  { key: "maxMessageChars", group: "capture", type: "integer", label: "Max Message Chars", description: "Maximum characters kept per stored message before building the messages array.", placeholder: "20000" },
+  { key: "includeAssistant", group: "capture", type: "boolean", label: "Include Assistant", description: "Include assistant replies in the messages array." },
+  { key: "tags", group: "capture", type: "stringArray", rows: 4, label: "Tags", description: "Custom tags used to classify added messages. One value per line.", placeholder: "openclaw" },
+  { key: "info", group: "capture", type: "json", rows: 7, label: "Info Payload (JSON)", description: "Structured metadata merged into info for filtering, tracing, and source tracking.", placeholder: '{\n  "channel": "webchat"\n}' },
+  { key: "asyncMode", group: "capture", type: "boolean", label: "Async Mode", description: "Add memories asynchronously in the background to avoid blocking the call chain." },
+  { key: "agentId", group: "agent", type: "string", label: "Static Agent ID", description: "Unique identifier of the Agent associated with added messages and retrieved memories." },
+  { key: "multiAgentMode", group: "agent", type: "boolean", label: "Multi-Agent Mode", description: "Isolate recall and add payloads by ctx.agentId when available." },
+  { key: "allowedAgents", group: "agent", type: "stringArray", rows: 4, label: "Allowed Agents", description: "Only listed agent ids are allowed to recall and add; empty means all agents." },
+  { key: "agentOverrides", group: "agent", type: "json", rows: 10, label: "Agent Overrides (JSON)", description: "Per-agent overrides. Key is agent id, value is an object of supported override fields.", placeholder: '{\n  "assistant-1": {\n    "knowledgebaseIds": ["kb-001"],\n    "recallEnabled": true\n  }\n}' },
+  { key: "appId", group: "agent", type: "string", label: "App ID", description: "Unique identifier of the App associated with added messages and retrieved memories." },
+  { key: "allowPublic", group: "agent", type: "boolean", label: "Allow Public", description: "Allow generated memories to be written to the public memory store." },
+  { key: "allowKnowledgebaseIds", group: "agent", type: "stringArray", rows: 4, label: "Allowed Knowledge Base IDs", description: "Knowledgebase scope where generated memories are allowed to be written. One ID per line.", placeholder: "kb-public\nkb-team" },
+  { key: "recallFilterEnabled", group: "filter", type: "boolean", label: "Recall Filter Enabled", description: "Enable second-pass model filtering for recall candidates." },
+  { key: "recallFilterBaseUrl", group: "filter", type: "string", label: "Filter Base URL", description: "OpenAI-compatible endpoint used for recall filtering.", placeholder: "http://127.0.0.1:11434/v1" },
+  { key: "recallFilterApiKey", group: "filter", type: "secret", label: "Filter API Key", description: "Optional bearer token for the recall filter model endpoint." },
+  { key: "recallFilterModel", group: "filter", type: "string", label: "Filter Model", description: "Model name used by the recall filter endpoint.", placeholder: "qwen2.5:7b" },
+  { key: "recallFilterTimeoutMs", group: "filter", type: "integer", label: "Filter Timeout (ms)", description: "Request timeout for the recall filter model.", placeholder: "6000" },
+  { key: "recallFilterRetries", group: "filter", type: "integer", label: "Filter Retries", description: "Retry count when the recall filter request fails.", placeholder: "0" },
+  { key: "recallFilterCandidateLimit", group: "filter", type: "integer", label: "Candidate Limit", description: "Per-category candidate limit before filtering.", placeholder: "30" },
+  { key: "recallFilterMaxItemChars", group: "filter", type: "integer", label: "Filter Max Item Chars", description: "Maximum characters kept per candidate item before filtering.", placeholder: "500" },
+  { key: "recallFilterFailOpen", group: "filter", type: "boolean", label: "Fail Open", description: "Fall back to unfiltered recall if the filter model errors." },
+  { key: "timeoutMs", group: "advanced", type: "integer", label: "MemOS Timeout (ms)", description: "Timeout used for MemOS API requests.", placeholder: "5000" },
+  { key: "retries", group: "advanced", type: "integer", label: "MemOS Retries", description: "Retry count for MemOS API requests.", placeholder: "1" },
+  { key: "throttleMs", group: "advanced", type: "integer", label: "Throttle (ms)", description: "Skip add/message when the previous capture happened too recently.", placeholder: "0" },
+];
+
+function getGlobalState() {
+  if (!globalThis[GLOBAL_STATE_KEY]) {
+    globalThis[GLOBAL_STATE_KEY] = {
+      promise: null,
+      service: null,
+      cleanupInstalled: false,
+      restartHookInstalled: false,
+      restartTimer: null,
+      restartPending: false,
+      recyclePromise: null,
+      shuttingDown: false,
+      child: null,
+    };
+  }
+  return globalThis[GLOBAL_STATE_KEY];
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function deepClone(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function sanitizeStructuredValue(value, depth = 0) {
+  if (depth > 16) throw new Error("Config payload is too deeply nested.");
+  if (value === null) return null;
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("Config payload contains a non-finite number.");
+    return value;
+  }
+  if (Array.isArray(value)) return value.map((item) => sanitizeStructuredValue(item, depth + 1));
+  if (isPlainObject(value)) {
+    const next = {};
+    for (const [key, child] of Object.entries(value)) {
+      const normalized = sanitizeStructuredValue(child, depth + 1);
+      if (normalized !== undefined) next[key] = normalized;
+    }
+    return next;
+  }
+  if (value === undefined) return undefined;
+  throw new Error("Config payload contains an unsupported value type.");
+}
+
+function sortForHash(value) {
+  if (Array.isArray(value)) return value.map((item) => sortForHash(item));
+  if (isPlainObject(value)) {
+    return Object.keys(value)
+      .sort()
+      .reduce((acc, key) => {
+        acc[key] = sortForHash(value[key]);
+        return acc;
+      }, {});
+  }
+  return value;
+}
+
+function createRevision(value) {
+  return createHash("sha1").update(JSON.stringify(sortForHash(value))).digest("hex").slice(0, 12);
+}
+
+function detectRuntimeProfile() {
+  const scriptPath = String(process.argv[1] || "").toLowerCase();
+  const execPath = String(process.execPath || "").toLowerCase();
+
+  if (scriptPath.includes("moltbot") || execPath.includes("moltbot")) {
+    return { id: "moltbot", displayName: "Moltbot", cliName: "moltbot", configPath: join(homedir(), ".moltbot", "moltbot.json") };
+  }
+  if (scriptPath.includes("clawdbot") || execPath.includes("clawdbot")) {
+    return { id: "clawdbot", displayName: "ClawDBot", cliName: "clawdbot", configPath: join(homedir(), ".clawdbot", "clawdbot.json") };
+  }
+  return { id: "openclaw", displayName: "OpenClaw", cliName: "openclaw", configPath: join(homedir(), ".openclaw", "openclaw.json") };
+}
+
+/**
+ * Detect the version of the host CLI (openclaw / moltbot / clawdbot).
+ *
+ * Strategy (in order of preference):
+ *  1. Parse `@X.Y.Z` out of `process.argv[1]` — pnpm/npm global installs
+ *     always embed the version in the store path
+ *     (e.g. `.../openclaw@2026.4.26/node_modules/openclaw/openclaw.mjs`).
+ *  2. Walk up from `process.argv[1]` looking for a `package.json` that has
+ *     a `version` field — covers local `node` invocations and bundled builds.
+ *  3. Return `null` if neither succeeds.
+ */
+export function detectHostVersion() {
+  const scriptPath = String(process.argv[1] || "");
+
+  const atMatch = scriptPath.match(/@(\d+\.\d+(?:\.\d+)?)/);
+  if (atMatch) return atMatch[1];
+
+  try {
+    let dir = dirname(scriptPath);
+    for (let i = 0; i < 8; i++) {
+      try {
+        const raw = readFileSync(join(dir, "package.json"), "utf8");
+        const pkg = JSON.parse(raw);
+        if (pkg.version && typeof pkg.version === "string") return pkg.version;
+      } catch {
+        // not found at this level, keep walking
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    // ignore
+  }
+
+  return null;
+}
+
+/**
+ * Compare two CalVer / semver version strings component by component.
+ * Returns -1 when a < b, 0 when equal, 1 when a > b.
+ * Non-numeric components (e.g. pre-release suffixes) are ignored.
+ */
+export function compareVersionStrings(a, b) {
+  const partsA = String(a ?? "").split(".").map(Number);
+  const partsB = String(b ?? "").split(".").map(Number);
+  const len = Math.max(partsA.length, partsB.length);
+  for (let i = 0; i < len; i++) {
+    const na = Number.isFinite(partsA[i]) ? partsA[i] : 0;
+    const nb = Number.isFinite(partsB[i]) ? partsB[i] : 0;
+    if (na < nb) return -1;
+    if (na > nb) return 1;
+  }
+  return 0;
+}
+
+function parsePositiveInteger(value, fallback) {
+  const parsed = Number(value);
+  if (Number.isFinite(parsed) && parsed > 0) return Math.floor(parsed);
+  return fallback;
+}
+
+function resolveGatewayReadyProbeTarget(rootConfig = {}) {
+  const gateway = isPlainObject(rootConfig?.gateway) ? rootConfig.gateway : {};
+  const port = parsePositiveInteger(gateway.port, DEFAULT_GATEWAY_READY_PORT);
+  const bind = typeof gateway.bind === "string" ? gateway.bind.trim().toLowerCase() : "";
+  const customBindHost = typeof gateway.customBindHost === "string" ? gateway.customBindHost.trim() : "";
+  const host = bind === "custom" && customBindHost ? customBindHost : "127.0.0.1";
+  return { host, port, url: `http://${host}:${port}/ready` };
+}
+
+export async function waitForGatewayReady(rootConfig = {}, log = console, options = {}) {
+  const timeoutMs = parsePositiveInteger(options.timeoutMs, 45000);
+  const intervalMs = parsePositiveInteger(options.intervalMs, 300);
+  const deadline = Date.now() + timeoutMs;
+  const target = resolveGatewayReadyProbeTarget(rootConfig);
+
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(target.url, {
+        method: "GET",
+        cache: "no-store",
+      });
+      if (response.ok) {
+        let body = null;
+        try {
+          body = await response.json();
+        } catch {
+          body = null;
+        }
+        if (!body || body.ready !== false) return true;
+      }
+    } catch {
+      // Ignore probe failures until timeout expires.
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+
+  log.warn?.(`[memos-cloud] Gateway readiness probe timed out at ${target.url}; config UI will not start yet.`);
+  return false;
+}
+
+// Returns true when the current process was launched by an `openclaw gateway`
+// command that actually starts (or restarts) the long-lived gateway. Other
+// CLI entry points (`plugins install`, `security audit`, `--help`, ...) also
+// load this plugin to inspect/register it, but they perform their own
+// config commits and must not be racing with our hook-policy patcher.
+function isGatewayStartCommand() {
+  const args = process.argv.map((value) => String(value || "").toLowerCase());
+  const gatewayIndex = args.lastIndexOf("gateway");
+  if (gatewayIndex === -1) return false;
+
+  const nextArg = args[gatewayIndex + 1];
+  if (!nextArg || nextArg.startsWith("-")) return true;
+  return nextArg === "start" || nextArg === "restart" || nextArg === "run";
+}
+
+function shouldStartConfigUi() {
+  return isGatewayStartCommand();
+}
+
+export function isGatewayRuntimeStartup() {
+  return isGatewayStartCommand();
+}
+
+function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+function parseJson5File(text, filePath) {
+  const source = stripBom(String(text || "")).trim();
+  if (!source) return {};
+
+  try {
+    const parsed = JSON.parse(source);
+    if (!isPlainObject(parsed)) throw new Error("Root config must be an object.");
+    return parsed;
+  } catch {
+    const script = new Script(`(${source}\n)`, { filename: filePath });
+    const parsed = script.runInNewContext(Object.create(null), { timeout: 500 });
+    if (!isPlainObject(parsed)) throw new Error("Root config must be an object.");
+    return parsed;
+  }
+}
+
+function hasIncludeDirective(value, depth = 0) {
+  if (depth > 8) return false;
+  if (Array.isArray(value)) return value.some((item) => hasIncludeDirective(item, depth + 1));
+  if (!isPlainObject(value)) return false;
+  if (Object.prototype.hasOwnProperty.call(value, "$include")) return true;
+  return Object.values(value).some((child) => hasIncludeDirective(child, depth + 1));
+}
+
+function readGatewayConfig(profile) {
+  let root = {};
+  let fileExists = true;
+  let stat = null;
+
+  try {
+    root = parseJson5File(readFileSync(profile.configPath, "utf8"), profile.configPath);
+    stat = statSync(profile.configPath);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    fileExists = false;
+  }
+
+  const plugins = isPlainObject(root.plugins) ? root.plugins : {};
+  const entries = isPlainObject(plugins.entries) ? plugins.entries : {};
+  const entry = isPlainObject(entries[PLUGIN_ID]) ? entries[PLUGIN_ID] : null;
+  const config = entry && isPlainObject(entry.config) ? deepClone(entry.config) : {};
+  const enabled = entry ? entry.enabled !== false : true;
+
+  return {
+    profile,
+    fileExists,
+    configPath: profile.configPath,
+    entryExists: Boolean(entry),
+    enabled,
+    config,
+    root,
+    hasInclude: hasIncludeDirective(root.plugins) || hasIncludeDirective(root),
+    revision: createRevision({
+      config,
+      enabled,
+      entryExists: Boolean(entry),
+      fileExists,
+      mtimeMs: stat?.mtimeMs ?? 0,
+      size: stat?.size ?? 0,
+    }),
+  };
+}
+
+function writeGatewayConfig(profile, payload) {
+  const current = readGatewayConfig(profile);
+  const nextRoot = isPlainObject(current.root) ? deepClone(current.root) : {};
+  if (!isPlainObject(nextRoot.plugins)) nextRoot.plugins = {};
+  if (!isPlainObject(nextRoot.plugins.entries)) nextRoot.plugins.entries = {};
+
+  // Preserve any entry-level fields the user already set (e.g. `hooks`,
+  // policy opt-ins, future gateway metadata) so that saving from the config
+  // UI never silently drops gateway-required settings such as
+  // `hooks.allowConversationAccess`.
+  const previousEntry = isPlainObject(nextRoot.plugins.entries[PLUGIN_ID])
+    ? nextRoot.plugins.entries[PLUGIN_ID]
+    : {};
+  const entry = { ...previousEntry, enabled: payload.enabled !== false };
+
+  const config = sanitizeStructuredValue(payload.config ?? {});
+  if (!isPlainObject(config)) throw new Error("Config payload must be an object.");
+  if (Object.keys(config).length > 0) {
+    entry.config = config;
+  } else {
+    delete entry.config;
+  }
+
+  nextRoot.plugins.entries[PLUGIN_ID] = entry;
+
+  mkdirSync(dirname(profile.configPath), { recursive: true });
+  writeFileSync(profile.configPath, `${JSON.stringify(nextRoot, null, 2)}\n`, "utf8");
+  return readGatewayConfig(profile);
+}
+
+function getPluginEntry(root) {
+  const plugins = isPlainObject(root?.plugins) ? root.plugins : null;
+  if (!plugins) return null;
+  const entries = isPlainObject(plugins.entries) ? plugins.entries : null;
+  if (!entries) return null;
+  return isPlainObject(entries[PLUGIN_ID]) ? entries[PLUGIN_ID] : null;
+}
+
+function getMissingHookPolicies(root, hookKeys) {
+  const entry = getPluginEntry(root);
+  const hooks = isPlainObject(entry?.hooks) ? entry.hooks : {};
+  return hookKeys.filter((key) => hooks[key] !== true);
+}
+
+/**
+ * Ensure the gateway config grants this plugin the typed-hook policies it
+ * needs. The gateway blocks non-bundled plugins from registering hooks like
+ * `agent_end` unless `plugins.entries.<id>.hooks.allowConversationAccess` is
+ * explicitly set to `true`. Users hit this on every fresh install because the
+ * key is not part of any default config template, so we patch it in
+ * automatically on first load.
+ *
+ * Behavior:
+ *  - Fast-path: if `rootConfig` already has all required keys, do nothing
+ *    silently — no logs, no disk reads.
+ *  - Otherwise: read the on-disk config (to preserve unrelated edits made
+ *    after the gateway booted), merge in the missing keys, write it back,
+ *    and return `{ changed: true }` so the caller can ask the user to
+ *    restart the gateway. We only mutate the keys we own.
+ *  - If the config uses `$include` directives we cannot safely rewrite the
+ *    merged tree, so we just warn and leave the file untouched.
+ *
+ * NOTE: callers are responsible for deciding *when* to invoke this. In
+ * particular it must NOT be called from short-lived CLI commands such as
+ * `plugins install` that perform their own config commits — racing with
+ * them triggers `ConfigMutationConflictError`. See `isGatewayRuntimeStartup`.
+ */
+export function ensurePluginHookPolicy(rootConfig = null, log = console, options = {}) {
+  const hookKeys = Array.isArray(options.hookKeys) && options.hookKeys.length > 0
+    ? options.hookKeys
+    : REQUIRED_HOOK_POLICIES;
+
+  const profile = detectRuntimeProfile();
+
+  if (isPlainObject(rootConfig) && getMissingHookPolicies(rootConfig, hookKeys).length === 0) {
+    return { changed: false, configPath: profile.configPath, profile };
+  }
+
+  let current;
+  try {
+    current = readGatewayConfig(profile);
+  } catch (error) {
+    log.warn?.(
+      `[memos-cloud] failed to read ${profile.configPath} while ensuring plugin hook policy: ${String(error?.message ?? error)}`,
+    );
+    return { changed: false, error, configPath: profile.configPath, profile };
+  }
+
+  if (current.hasInclude) {
+    const missing = getMissingHookPolicies(current.root, hookKeys);
+    if (missing.length > 0) {
+      log.warn?.(
+        `[memos-cloud] gateway config at ${profile.configPath} uses $include directives, ` +
+          `cannot auto-enable required plugin hook policies: ${missing.join(", ")}. ` +
+          `Add plugins.entries.${PLUGIN_ID}.hooks={${missing.map((k) => `${k}:true`).join(", ")}} manually and restart the gateway.`,
+      );
+    }
+    return { changed: false, hasInclude: true, configPath: profile.configPath, profile };
+  }
+
+  const missingKeys = getMissingHookPolicies(current.root, hookKeys);
+  if (missingKeys.length === 0) return { changed: false, configPath: profile.configPath, profile };
+
+  const nextRoot = isPlainObject(current.root) ? deepClone(current.root) : {};
+  if (!isPlainObject(nextRoot.plugins)) nextRoot.plugins = {};
+  if (!isPlainObject(nextRoot.plugins.entries)) nextRoot.plugins.entries = {};
+  if (!isPlainObject(nextRoot.plugins.entries[PLUGIN_ID])) {
+    nextRoot.plugins.entries[PLUGIN_ID] = {};
+  }
+  const entry = nextRoot.plugins.entries[PLUGIN_ID];
+  if (entry.enabled === undefined) entry.enabled = true;
+  if (!isPlainObject(entry.hooks)) entry.hooks = {};
+  for (const key of missingKeys) {
+    entry.hooks[key] = true;
+  }
+
+  try {
+    mkdirSync(dirname(profile.configPath), { recursive: true });
+    writeFileSync(profile.configPath, `${JSON.stringify(nextRoot, null, 2)}\n`, "utf8");
+  } catch (error) {
+    log.warn?.(
+      `[memos-cloud] failed to write ${profile.configPath} to enable required plugin hook policies (${missingKeys.join(", ")}): ${String(error?.message ?? error)}`,
+    );
+    return { changed: false, error, configPath: profile.configPath, profile };
+  }
+
+  // Emit the eye-catching banner directly through stdout so the gateway's
+  // log-line prefix (`[plugins] [memos-cloud] ...`) does not break up the
+  // box drawing. Then also emit a single terse `log.warn` line so any
+  // structured log aggregator / CI capture still gets the event.
+//   console.log(renderHookPolicyRestartBanner(profile, missingKeys));
+  log.warn?.(
+    `[memos-cloud] hook policy patched in ${profile.configPath} (added: ${missingKeys.join(", ")}). ` +
+      `Manual gateway restart required: \`${profile.cliName} gateway restart\`.`,
+  );
+
+  return { changed: true, addedKeys: missingKeys, configPath: profile.configPath, profile };
+}
+
+/**
+ * Returns metadata describing how `ensurePluginHookPolicy` would behave for
+ * the current runtime, without writing anything. Useful in tests and for
+ * letting host code surface "we will write to <path>" diagnostics before any
+ * IO actually happens.
+ */
+export function describePluginHookPolicyTarget() {
+  const profile = detectRuntimeProfile();
+  return {
+    runtime: profile.id,
+    configPath: profile.configPath,
+    hookKeys: [...REQUIRED_HOOK_POLICIES],
+  };
+}
+
+function buildStatePayload(service) {
+  const state = readGatewayConfig(service.profile);
+  const resolution = getConfigResolution(state.config);
+  return {
     runtime: state.profile.id,
     runtimeDisplayName: state.profile.displayName,
     pluginVersion: getPackageVersion(),
     configPath: state.configPath,
-    entryExists: state.entryExists,
-    fileExists: state.fileExists,
-    enabled: state.enabled,
-    config: state.config,
-    resolvedConfig: resolution.resolved,
-    fieldMeta: resolution.fieldMeta,
-    revision: state.revision,
-    hasInclude: state.hasInclude,
-    bootId: service.bootId,
-    assetRevision: getAssetRevision(),
-    port: service.port,
-    url: service.url,
-  };
-}
-
-function getCachedStatePayload(service, maxAgeMs = 1200) {
-  const now = Date.now();
-  if (service.stateCache && now - service.stateCache.createdAt < maxAgeMs) {
-    return service.stateCache.payload;
-  }
-  const payload = buildStatePayload(service);
-  service.stateCache = {
-    createdAt: now,
-    payload,
-  };
-  return payload;
-}
-
+    entryExists: state.entryExists,
+    fileExists: state.fileExists,
+    enabled: state.enabled,
+    config: state.config,
+    resolvedConfig: resolution.resolved,
+    fieldMeta: resolution.fieldMeta,
+    revision: state.revision,
+    hasInclude: state.hasInclude,
+    bootId: service.bootId,
+    assetRevision: getAssetRevision(),
+    port: service.port,
+    url: service.url,
+  };
+}
+
+function getCachedStatePayload(service, maxAgeMs = 1200) {
+  const now = Date.now();
+  if (service.stateCache && now - service.stateCache.createdAt < maxAgeMs) {
+    return service.stateCache.payload;
+  }
+  const payload = buildStatePayload(service);
+  service.stateCache = {
+    createdAt: now,
+    payload,
+  };
+  return payload;
+}
+
 function getCachedHeartbeatPayload(service, maxAgeMs = 1200) {
-  const now = Date.now();
-  if (service.heartbeatCache && now - service.heartbeatCache.createdAt < maxAgeMs) {
-    return {
-      ...service.heartbeatCache.payload,
-      timestamp: now,
-    };
-  }
-  const payload = {
-    ok: true,
-    runtime: service.profile.id,
-    bootId: service.bootId,
-    assetRevision: getAssetRevision(),
-  };
-  service.heartbeatCache = {
-    createdAt: now,
-    payload,
-  };
-  return {
-    ...payload,
-    timestamp: now,
-  };
+  const now = Date.now();
+  if (service.heartbeatCache && now - service.heartbeatCache.createdAt < maxAgeMs) {
+    return {
+      ...service.heartbeatCache.payload,
+      timestamp: now,
+    };
+  }
+  const payload = {
+    ok: true,
+    runtime: service.profile.id,
+    bootId: service.bootId,
+    assetRevision: getAssetRevision(),
+  };
+  service.heartbeatCache = {
+    createdAt: now,
+    payload,
+  };
+  return {
+    ...payload,
+    timestamp: now,
+  };
 }
 
 async function getCachedUpdateStatusPayload(service, maxAgeMs = UPDATE_STATUS_CACHE_MS, options = {}) {
@@ -608,260 +608,260 @@ async function getCachedUpdateStatusPayload(service, maxAgeMs = UPDATE_STATUS_CA
 }
 
 function loadAssetTemplate(name) {
-  return readFileSync(join(ASSET_DIR, name), "utf8");
-}
-
-function getAssetRevision() {
-  const files = ["index.html", "app.js", "app.css"];
-  const parts = [];
-  for (const name of files) {
-    try {
-      const stat = statSync(join(ASSET_DIR, name));
-      parts.push(`${name}:${stat.mtimeMs}:${stat.size}`);
-    } catch {
-      parts.push(`${name}:missing`);
-    }
-  }
-  return createRevision(parts);
-}
-
-function replaceTokens(template, tokenMap) {
-  let output = template;
-  for (const [token, value] of Object.entries(tokenMap)) {
-    output = output.split(token).join(value);
-  }
-  return output;
-}
-
-function jsonString(value) {
-  return JSON.stringify(value).replace(/</g, "\\u003c");
-}
-
-function getAccessibleUrls(port) {
-  return [`http://127.0.0.1:${port}`];
-}
-
-function centerText(text, width) {
-  const left = Math.max(0, Math.floor((width - text.length) / 2));
-  const right = Math.max(0, width - text.length - left);
-  return `${" ".repeat(left)}${text}${" ".repeat(right)}`;
-}
-
-function padBoxLine(content, visibleLength, width) {
-  return `${ANSI_GREEN}| ${ANSI_RESET}${content}${" ".repeat(Math.max(0, width - visibleLength))}${ANSI_GREEN} |${ANSI_RESET}`;
-}
-
-function renderConfigAddressBanner(port) {
-  const urls = getAccessibleUrls(port);
-  const titleArt = [
-  "  __  __   ______   __  __    ____     _____  ",
-  " |  \\/  | |  ____| |  \\/  |  / __ \\   / ____| ",
-  " | \\  / | | |__    | \\  / | | |  | | | (___   ",
-  " | |\\/| | |  __|   | |\\/| | | |  | |  \\___ \\  ",
-  " | |  | | | |____  | |  | | | |__| |  ____) | ",
-  " |_|  |_| |______| |_|  |_|  \\____/  |_____/  "
-];
-  const heading = "Plugin Configuration";
-  const urlLines = urls.map((url, index) => ` [${index + 1}] ${url}`);
-  const plainLines = [
-    "",
-    ...titleArt,
-    "",
-    heading,
-    "",
-    "Plugin configuration page is ready.",
-    "Open one of the following URLs in your browser:",
-    "",
-    ...urlLines,
-    "",
-    "Tip: keep this window open while you finish the setup.",
-    "",
-  ];
-  const contentWidth = plainLines.reduce((max, line) => Math.max(max, line.length), 0);
-  const centeredTitleArt = titleArt.map((line) => centerText(line, contentWidth));
-  const centeredHeading = centerText(heading, contentWidth);
-  const visibleLineWidths = [
-    0,
-    ...centeredTitleArt.map(() => contentWidth),
-    0,
-    contentWidth,
-    contentWidth,
-    "Plugin configuration page is ready.".length,
-    "Open one of the following URLs in your browser:".length,
-    0,
-    ...urlLines.map((line) => line.length),
-    0,
-    "Tip: keep this window open while you finish the setup.".length,
-    0,
-  ];
-  const separator = "-".repeat(contentWidth);
-  const coloredLines = [
-    "",
-    ...centeredTitleArt.map((line) => `${ANSI_BOLD}${ANSI_CYAN}${line}${ANSI_RESET}`),
-    "",
-    `${ANSI_BOLD}${centeredHeading}${ANSI_RESET}`,
-    `${ANSI_GREEN}${separator}${ANSI_RESET}`,
-    "Plugin configuration page is ready.",
-    "Open one of the following URLs in your browser:",
-    "",
-    ...urlLines.map((line) => `${ANSI_BOLD}${ANSI_GREEN}${line}${ANSI_RESET}`),
-    "",
-    "Tip: keep this window open while you finish the setup.",
-    "",
-  ];
-  const horizontalBorder = `+${"=".repeat(contentWidth + 2)}+`;
-
-  return `\n${ANSI_GREEN}${horizontalBorder}${ANSI_RESET}\n${coloredLines
-    .map((line, index) => padBoxLine(line, visibleLineWidths[index], contentWidth))
-    .join("\n")}\n${ANSI_GREEN}${horizontalBorder}${ANSI_RESET}`;
-}
-
-function renderHookPolicyRestartBanner(profile, addedKeys) {
-  const heading = "PLUGIN HOOK POLICY UPDATED";
-  const subheading = "Manual gateway restart required";
-  const command = `${profile.cliName} gateway restart`;
-  const keyLines = addedKeys.map((key) => `  - ${key}`);
-
-  const plainLines = [
-    "",
-    heading,
-    subheading,
-    "",
-    "Patched file:",
-    `  ${profile.configPath}`,
-    "",
-    "Added hook policies:",
-    ...keyLines,
-    "",
-    "To apply the change, restart the gateway:",
-    "",
-    `  $ ${command}`,
-    "",
-    "Without a restart, hooks like `agent_end` will not be registered,",
-    "so memory capture / recall will silently stop working.",
-    "",
-  ];
-
-  const contentWidth = plainLines.reduce((max, line) => Math.max(max, line.length), 0);
-  const centeredHeading = centerText(heading, contentWidth);
-  const centeredSubheading = centerText(subheading, contentWidth);
-  const separator = "-".repeat(contentWidth);
-
-  const coloredLines = plainLines.map((line) => {
-    if (line === heading) return `${ANSI_BOLD}${ANSI_YELLOW}${centeredHeading}${ANSI_RESET}`;
-    if (line === subheading) return `${ANSI_YELLOW}${centeredSubheading}${ANSI_RESET}`;
-    if (line === `  $ ${command}`) return `${ANSI_BOLD}${ANSI_GREEN}${line}${ANSI_RESET}`;
-    if (line === `  ${profile.configPath}`) return `${ANSI_CYAN}${line}${ANSI_RESET}`;
-    if (line.startsWith("  - ")) return `${ANSI_CYAN}${line}${ANSI_RESET}`;
-    return line;
-  });
-
-  const visibleLineWidths = plainLines.map((line, index) => {
-    if (index === 1 || index === 2) return contentWidth;
-    return line.length;
-  });
-
-  // Insert a separator line between the subheading block and the body so
-  // the title visually anchors to the top of the box.
-  const headingBoundaryIndex = 3;
-  coloredLines.splice(headingBoundaryIndex, 0, `${ANSI_YELLOW}${separator}${ANSI_RESET}`);
-  visibleLineWidths.splice(headingBoundaryIndex, 0, contentWidth);
-
-  const padYellowBoxLine = (content, visibleLength) =>
-    `${ANSI_YELLOW}| ${ANSI_RESET}${content}${" ".repeat(Math.max(0, contentWidth - visibleLength))}${ANSI_YELLOW} |${ANSI_RESET}`;
-
-  const horizontalBorder = `${ANSI_YELLOW}+${"=".repeat(contentWidth + 2)}+${ANSI_RESET}`;
-
-  return `\n${horizontalBorder}\n${coloredLines
-    .map((line, index) => padYellowBoxLine(line, visibleLineWidths[index]))
-    .join("\n")}\n${horizontalBorder}\n`;
-}
-
-function renderHtml(service) {
-  return replaceTokens(loadAssetTemplate("index.html"), {
-    "__PLUGIN_ID__": PLUGIN_ID,
-    "__APP_JS_URL__": `/app.js?token=${service.token}`,
-  });
-}
-
-function renderAppJs(service) {
-  return replaceTokens(loadAssetTemplate("app.js"), {
-    "__CONFIG_UI_TOKEN__": jsonString(service.token),
-    "__FIELD_GROUPS__": jsonString(FIELD_GROUPS),
-    "__FIELD_DEFINITIONS__": jsonString(FIELD_DEFINITIONS),
-  });
-}
-
- // Legacy restart functions removed for sandbox compliance
-
-function listenOnPort(server, host, port) {
-  return new Promise((resolve, reject) => {
-    const onError = (error) => {
-      cleanup();
-      reject(error);
-    };
-    const onListening = () => {
-      cleanup();
-      resolve(port);
-    };
-    const cleanup = () => {
-      server.off("error", onError);
-      server.off("listening", onListening);
-    };
-    server.once("error", onError);
-    server.once("listening", onListening);
-    server.listen(port, host);
-  });
-}
-
-async function bindWithFallback(server) {
-  for (let offset = 0; offset < UI_PORT_ATTEMPTS; offset += 1) {
-    const port = UI_BASE_PORT + offset;
-    try {
-      await listenOnPort(server, UI_HOST, port);
-      return port;
-    } catch (error) {
-      if (error?.code !== "EADDRINUSE") throw error;
-    }
-  }
-  throw new Error(`Could not bind config UI after trying ${UI_PORT_ATTEMPTS} ports from ${UI_BASE_PORT}.`);
-}
-
-function readRequestBody(req) {
-  return new Promise((resolve, reject) => {
-    let body = "";
-    req.setEncoding("utf8");
-    req.on("data", (chunk) => {
-      body += chunk;
-      if (body.length > 1024 * 1024) {
-        reject(new Error("Request body too large."));
-        req.destroy();
-      }
-    });
-    req.on("end", () => resolve(body));
-    req.on("error", reject);
-  });
-}
-
-function sendJson(res, statusCode, payload) {
-  res.writeHead(statusCode, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" });
-  res.end(JSON.stringify(payload));
-}
-
-function sendText(res, statusCode, message) {
-  res.writeHead(statusCode, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" });
-  res.end(message);
-}
-
-function isAuthorized(req, service) {
-  return req.headers["x-memos-config-token"] === service.token;
-}
-
-async function createService(log) {
-  const profile = detectRuntimeProfile();
-  const token = randomBytes(24).toString("hex");
-  const bootId = randomBytes(10).toString("hex");
-
+  return readFileSync(join(ASSET_DIR, name), "utf8");
+}
+
+function getAssetRevision() {
+  const files = ["index.html", "app.js", "app.css"];
+  const parts = [];
+  for (const name of files) {
+    try {
+      const stat = statSync(join(ASSET_DIR, name));
+      parts.push(`${name}:${stat.mtimeMs}:${stat.size}`);
+    } catch {
+      parts.push(`${name}:missing`);
+    }
+  }
+  return createRevision(parts);
+}
+
+function replaceTokens(template, tokenMap) {
+  let output = template;
+  for (const [token, value] of Object.entries(tokenMap)) {
+    output = output.split(token).join(value);
+  }
+  return output;
+}
+
+function jsonString(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+
+function getAccessibleUrls(port) {
+  return [`http://127.0.0.1:${port}`];
+}
+
+function centerText(text, width) {
+  const left = Math.max(0, Math.floor((width - text.length) / 2));
+  const right = Math.max(0, width - text.length - left);
+  return `${" ".repeat(left)}${text}${" ".repeat(right)}`;
+}
+
+function padBoxLine(content, visibleLength, width) {
+  return `${ANSI_GREEN}| ${ANSI_RESET}${content}${" ".repeat(Math.max(0, width - visibleLength))}${ANSI_GREEN} |${ANSI_RESET}`;
+}
+
+function renderConfigAddressBanner(port) {
+  const urls = getAccessibleUrls(port);
+  const titleArt = [
+  "  __  __   ______   __  __    ____     _____  ",
+  " |  \\/  | |  ____| |  \\/  |  / __ \\   / ____| ",
+  " | \\  / | | |__    | \\  / | | |  | | | (___   ",
+  " | |\\/| | |  __|   | |\\/| | | |  | |  \\___ \\  ",
+  " | |  | | | |____  | |  | | | |__| |  ____) | ",
+  " |_|  |_| |______| |_|  |_|  \\____/  |_____/  "
+];
+  const heading = "Plugin Configuration";
+  const urlLines = urls.map((url, index) => ` [${index + 1}] ${url}`);
+  const plainLines = [
+    "",
+    ...titleArt,
+    "",
+    heading,
+    "",
+    "Plugin configuration page is ready.",
+    "Open one of the following URLs in your browser:",
+    "",
+    ...urlLines,
+    "",
+    "Tip: keep this window open while you finish the setup.",
+    "",
+  ];
+  const contentWidth = plainLines.reduce((max, line) => Math.max(max, line.length), 0);
+  const centeredTitleArt = titleArt.map((line) => centerText(line, contentWidth));
+  const centeredHeading = centerText(heading, contentWidth);
+  const visibleLineWidths = [
+    0,
+    ...centeredTitleArt.map(() => contentWidth),
+    0,
+    contentWidth,
+    contentWidth,
+    "Plugin configuration page is ready.".length,
+    "Open one of the following URLs in your browser:".length,
+    0,
+    ...urlLines.map((line) => line.length),
+    0,
+    "Tip: keep this window open while you finish the setup.".length,
+    0,
+  ];
+  const separator = "-".repeat(contentWidth);
+  const coloredLines = [
+    "",
+    ...centeredTitleArt.map((line) => `${ANSI_BOLD}${ANSI_CYAN}${line}${ANSI_RESET}`),
+    "",
+    `${ANSI_BOLD}${centeredHeading}${ANSI_RESET}`,
+    `${ANSI_GREEN}${separator}${ANSI_RESET}`,
+    "Plugin configuration page is ready.",
+    "Open one of the following URLs in your browser:",
+    "",
+    ...urlLines.map((line) => `${ANSI_BOLD}${ANSI_GREEN}${line}${ANSI_RESET}`),
+    "",
+    "Tip: keep this window open while you finish the setup.",
+    "",
+  ];
+  const horizontalBorder = `+${"=".repeat(contentWidth + 2)}+`;
+
+  return `\n${ANSI_GREEN}${horizontalBorder}${ANSI_RESET}\n${coloredLines
+    .map((line, index) => padBoxLine(line, visibleLineWidths[index], contentWidth))
+    .join("\n")}\n${ANSI_GREEN}${horizontalBorder}${ANSI_RESET}`;
+}
+
+function renderHookPolicyRestartBanner(profile, addedKeys) {
+  const heading = "PLUGIN HOOK POLICY UPDATED";
+  const subheading = "Manual gateway restart required";
+  const command = `${profile.cliName} gateway restart`;
+  const keyLines = addedKeys.map((key) => `  - ${key}`);
+
+  const plainLines = [
+    "",
+    heading,
+    subheading,
+    "",
+    "Patched file:",
+    `  ${profile.configPath}`,
+    "",
+    "Added hook policies:",
+    ...keyLines,
+    "",
+    "To apply the change, restart the gateway:",
+    "",
+    `  $ ${command}`,
+    "",
+    "Without a restart, hooks like `agent_end` will not be registered,",
+    "so memory capture / recall will silently stop working.",
+    "",
+  ];
+
+  const contentWidth = plainLines.reduce((max, line) => Math.max(max, line.length), 0);
+  const centeredHeading = centerText(heading, contentWidth);
+  const centeredSubheading = centerText(subheading, contentWidth);
+  const separator = "-".repeat(contentWidth);
+
+  const coloredLines = plainLines.map((line) => {
+    if (line === heading) return `${ANSI_BOLD}${ANSI_YELLOW}${centeredHeading}${ANSI_RESET}`;
+    if (line === subheading) return `${ANSI_YELLOW}${centeredSubheading}${ANSI_RESET}`;
+    if (line === `  $ ${command}`) return `${ANSI_BOLD}${ANSI_GREEN}${line}${ANSI_RESET}`;
+    if (line === `  ${profile.configPath}`) return `${ANSI_CYAN}${line}${ANSI_RESET}`;
+    if (line.startsWith("  - ")) return `${ANSI_CYAN}${line}${ANSI_RESET}`;
+    return line;
+  });
+
+  const visibleLineWidths = plainLines.map((line, index) => {
+    if (index === 1 || index === 2) return contentWidth;
+    return line.length;
+  });
+
+  // Insert a separator line between the subheading block and the body so
+  // the title visually anchors to the top of the box.
+  const headingBoundaryIndex = 3;
+  coloredLines.splice(headingBoundaryIndex, 0, `${ANSI_YELLOW}${separator}${ANSI_RESET}`);
+  visibleLineWidths.splice(headingBoundaryIndex, 0, contentWidth);
+
+  const padYellowBoxLine = (content, visibleLength) =>
+    `${ANSI_YELLOW}| ${ANSI_RESET}${content}${" ".repeat(Math.max(0, contentWidth - visibleLength))}${ANSI_YELLOW} |${ANSI_RESET}`;
+
+  const horizontalBorder = `${ANSI_YELLOW}+${"=".repeat(contentWidth + 2)}+${ANSI_RESET}`;
+
+  return `\n${horizontalBorder}\n${coloredLines
+    .map((line, index) => padYellowBoxLine(line, visibleLineWidths[index]))
+    .join("\n")}\n${horizontalBorder}\n`;
+}
+
+function renderHtml(service) {
+  return replaceTokens(loadAssetTemplate("index.html"), {
+    "__PLUGIN_ID__": PLUGIN_ID,
+    "__APP_JS_URL__": `/app.js?token=${service.token}`,
+  });
+}
+
+function renderAppJs(service) {
+  return replaceTokens(loadAssetTemplate("app.js"), {
+    "__CONFIG_UI_TOKEN__": jsonString(service.token),
+    "__FIELD_GROUPS__": jsonString(FIELD_GROUPS),
+    "__FIELD_DEFINITIONS__": jsonString(FIELD_DEFINITIONS),
+  });
+}
+
+ // Legacy restart functions removed for sandbox compliance
+
+function listenOnPort(server, host, port) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => {
+      cleanup();
+      reject(error);
+    };
+    const onListening = () => {
+      cleanup();
+      resolve(port);
+    };
+    const cleanup = () => {
+      server.off("error", onError);
+      server.off("listening", onListening);
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, host);
+  });
+}
+
+async function bindWithFallback(server) {
+  for (let offset = 0; offset < UI_PORT_ATTEMPTS; offset += 1) {
+    const port = UI_BASE_PORT + offset;
+    try {
+      await listenOnPort(server, UI_HOST, port);
+      return port;
+    } catch (error) {
+      if (error?.code !== "EADDRINUSE") throw error;
+    }
+  }
+  throw new Error(`Could not bind config UI after trying ${UI_PORT_ATTEMPTS} ports from ${UI_BASE_PORT}.`);
+}
+
+function readRequestBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk) => {
+      body += chunk;
+      if (body.length > 1024 * 1024) {
+        reject(new Error("Request body too large."));
+        req.destroy();
+      }
+    });
+    req.on("end", () => resolve(body));
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res, statusCode, payload) {
+  res.writeHead(statusCode, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" });
+  res.end(JSON.stringify(payload));
+}
+
+function sendText(res, statusCode, message) {
+  res.writeHead(statusCode, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" });
+  res.end(message);
+}
+
+function isAuthorized(req, service) {
+  return req.headers["x-memos-config-token"] === service.token;
+}
+
+async function createService(log) {
+  const profile = detectRuntimeProfile();
+  const token = randomBytes(24).toString("hex");
+  const bootId = randomBytes(10).toString("hex");
+
   const service = {
     profile,
     token,
@@ -873,50 +873,50 @@ async function createService(log) {
     heartbeatCache: null,
     updateStatusCache: null,
   };
-
-  const server = createServer(async (req, res) => {
-    try {
-      const requestUrl = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
-
-      if (requestUrl.pathname === "/favicon.ico") {
-        res.writeHead(204);
-        res.end();
-        return;
-      }
-
-      if (requestUrl.pathname === "/icon.svg") {
-        res.writeHead(200, { "Content-Type": "image/svg+xml; charset=utf-8", "Cache-Control": "no-store" });
-        res.end(loadAssetTemplate("icon.svg"));
-        return;
-      }
-
-      if (requestUrl.pathname === "/app.css") {
-        res.writeHead(200, { "Content-Type": "text/css; charset=utf-8", "Cache-Control": "no-store" });
-        res.end(loadAssetTemplate("app.css"));
-        return;
-      }
-
-      if (requestUrl.pathname === "/app.js") {
-        if (requestUrl.searchParams.get("token") !== service.token) {
-          sendText(res, 403, "Forbidden");
-          return;
-        }
-        res.writeHead(200, { "Content-Type": "application/javascript; charset=utf-8", "Cache-Control": "no-store" });
-        res.end(renderAppJs(service));
-        return;
-      }
-
-      if (requestUrl.pathname === "/api/heartbeat" && req.method === "GET") {
-        sendJson(res, 200, getCachedHeartbeatPayload(service));
-        return;
-      }
-
-      if (requestUrl.pathname.startsWith("/api/")) {
-        if (!isAuthorized(req, service)) {
-          sendText(res, 403, "Forbidden");
-          return;
-        }
-
+
+  const server = createServer(async (req, res) => {
+    try {
+      const requestUrl = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
+
+      if (requestUrl.pathname === "/favicon.ico") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      if (requestUrl.pathname === "/icon.svg") {
+        res.writeHead(200, { "Content-Type": "image/svg+xml; charset=utf-8", "Cache-Control": "no-store" });
+        res.end(loadAssetTemplate("icon.svg"));
+        return;
+      }
+
+      if (requestUrl.pathname === "/app.css") {
+        res.writeHead(200, { "Content-Type": "text/css; charset=utf-8", "Cache-Control": "no-store" });
+        res.end(loadAssetTemplate("app.css"));
+        return;
+      }
+
+      if (requestUrl.pathname === "/app.js") {
+        if (requestUrl.searchParams.get("token") !== service.token) {
+          sendText(res, 403, "Forbidden");
+          return;
+        }
+        res.writeHead(200, { "Content-Type": "application/javascript; charset=utf-8", "Cache-Control": "no-store" });
+        res.end(renderAppJs(service));
+        return;
+      }
+
+      if (requestUrl.pathname === "/api/heartbeat" && req.method === "GET") {
+        sendJson(res, 200, getCachedHeartbeatPayload(service));
+        return;
+      }
+
+      if (requestUrl.pathname.startsWith("/api/")) {
+        if (!isAuthorized(req, service)) {
+          sendText(res, 403, "Forbidden");
+          return;
+        }
+
         if (requestUrl.pathname === "/api/state" && req.method === "GET") {
           sendJson(res, 200, getCachedStatePayload(service));
           return;
@@ -930,109 +930,109 @@ async function createService(log) {
         }
 
         if (requestUrl.pathname === "/api/save" && req.method === "POST") {
-          let parsed = {};
-          try {
-            parsed = JSON.parse((await readRequestBody(req)) || "{}");
-          } catch {
-            sendText(res, 400, "Invalid JSON payload.");
-            return;
-          }
-          if (!isPlainObject(parsed)) {
-            sendText(res, 400, "Invalid JSON payload.");
-            return;
-          }
-          if (typeof parsed.enabled !== "boolean") {
-            sendText(res, 400, "Payload.enabled must be a boolean.");
-            return;
-          }
-          if (!isPlainObject(parsed.config)) {
-            sendText(res, 400, "Payload.config must be an object.");
-            return;
-          }
-
-          const nextState = writeGatewayConfig(profile, parsed);
-          service.stateCache = null;
-          service.heartbeatCache = null;
-          sendJson(res, 200, { ok: true, state: buildStatePayload({ ...service, profile: nextState.profile }) });
-          return;
-        }
-
-        // Legacy `/api/restart` has been entirely removed
-        sendText(res, 404, "Not found");
-        return;
-      }
-
-      if (requestUrl.pathname !== "/") {
-        sendText(res, 404, "Not found");
-        return;
-      }
-
-      res.writeHead(200, {
-        "Content-Type": "text/html; charset=utf-8",
-        "Cache-Control": "no-store",
-        "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:;",
-      });
-      res.end(renderHtml(service));
-    } catch (error) {
-      sendText(res, 500, `Internal error: ${String(error?.message || error)}`);
-    }
-  });
-
-  service.server = server;
-  service.port = await bindWithFallback(server);
-  service.url = `http://${UI_HOST}:${service.port}`;
-
-  setTimeout(() => {
-    console.log(renderConfigAddressBanner(service.port));
-  }, 1200);
-  return service;
-}
-
-export function ensureConfigUiService(log = console) {
-  if (!shouldStartConfigUi()) {
-    return Promise.resolve(null);
-  }
-
-  const globalState = getGlobalState();
-  if (globalState.promise) return globalState.promise;
-
-  globalState.promise = createService(log)
-    .then((service) => {
-      globalState.service = service;
-      return service;
-    })
-    .catch((error) => {
-      globalState.service = null;
-      globalState.promise = null;
-      throw error;
-    });
-
-  return globalState.promise;
-}
-
-export async function closeConfigUiService(options = {}) {
-  const globalState = getGlobalState();
-
-  if (!globalState.service) {
-    globalState.promise = null;
-    return;
-  }
-
-  const { service } = globalState;
-  globalState.service = null;
-  globalState.promise = null;
-
-  if (service?.server) {
-    await new Promise((resolve) => {
-      try {
-        service.server.close(() => resolve());
-      } catch {
-        resolve();
-      }
-    });
-  }
-}
-
-export async function runConfigUiChildProcess(log = console) {
-  // no-op
-}
+          let parsed = {};
+          try {
+            parsed = JSON.parse((await readRequestBody(req)) || "{}");
+          } catch {
+            sendText(res, 400, "Invalid JSON payload.");
+            return;
+          }
+          if (!isPlainObject(parsed)) {
+            sendText(res, 400, "Invalid JSON payload.");
+            return;
+          }
+          if (typeof parsed.enabled !== "boolean") {
+            sendText(res, 400, "Payload.enabled must be a boolean.");
+            return;
+          }
+          if (!isPlainObject(parsed.config)) {
+            sendText(res, 400, "Payload.config must be an object.");
+            return;
+          }
+
+          const nextState = writeGatewayConfig(profile, parsed);
+          service.stateCache = null;
+          service.heartbeatCache = null;
+          sendJson(res, 200, { ok: true, state: buildStatePayload({ ...service, profile: nextState.profile }) });
+          return;
+        }
+
+        // Legacy `/api/restart` has been entirely removed
+        sendText(res, 404, "Not found");
+        return;
+      }
+
+      if (requestUrl.pathname !== "/") {
+        sendText(res, 404, "Not found");
+        return;
+      }
+
+      res.writeHead(200, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-store",
+        "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:;",
+      });
+      res.end(renderHtml(service));
+    } catch (error) {
+      sendText(res, 500, `Internal error: ${String(error?.message || error)}`);
+    }
+  });
+
+  service.server = server;
+  service.port = await bindWithFallback(server);
+  service.url = `http://${UI_HOST}:${service.port}`;
+
+  setTimeout(() => {
+    console.log(renderConfigAddressBanner(service.port));
+  }, 1200);
+  return service;
+}
+
+export function ensureConfigUiService(log = console) {
+  if (!shouldStartConfigUi()) {
+    return Promise.resolve(null);
+  }
+
+  const globalState = getGlobalState();
+  if (globalState.promise) return globalState.promise;
+
+  globalState.promise = createService(log)
+    .then((service) => {
+      globalState.service = service;
+      return service;
+    })
+    .catch((error) => {
+      globalState.service = null;
+      globalState.promise = null;
+      throw error;
+    });
+
+  return globalState.promise;
+}
+
+export async function closeConfigUiService(options = {}) {
+  const globalState = getGlobalState();
+
+  if (!globalState.service) {
+    globalState.promise = null;
+    return;
+  }
+
+  const { service } = globalState;
+  globalState.service = null;
+  globalState.promise = null;
+
+  if (service?.server) {
+    await new Promise((resolve) => {
+      try {
+        service.server.close(() => resolve());
+      } catch {
+        resolve();
+      }
+    });
+  }
+}
+
+export async function runConfigUiChildProcess(log = console) {
+  // no-op
+}