jishushell 0.4.17 → 0.4.24-beta.2

package/dist/services/setup-manager.js

@@ -1,29 +1,29 @@
 import { execFileSync, execSync, spawn as nodeSpawn } from "child_process";
 import { chmodSync, copyFileSync, existsSync, mkdtempSync, readFileSync, renameSync, rmSync, symlinkSync, unlinkSync } from "fs";
-import { userInfo } from "node:os";
+import { userInfo, platform as osPlatform } from "node:os";
 import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
 import { dirname, join } from "path";
 import { StringDecoder } from "string_decoder";
 import { fileURLToPath } from "url";
-import { JISHUSHELL_HOME, getPanelConfig, savePanelConfig, setOpenclawDockerImage, getOpenclawDockerImage, DEFAULT_OPENCLAW_DOCKER_IMAGE } from "../config.js";
+import { JISHUSHELL_HOME, getPanelConfig, savePanelConfig, setOpenclawDockerImage, getOpenclawDockerImage, DEFAULT_OPENCLAW_DOCKER_IMAGE, getRuntimeCatalogEntry, OPENCLAW_MODULES, OPENCLAW_BIN_DIR, } from "../config.js";
 import { ensureDirContainer, ensureDirHost, writeConfigFile, writeSecretFile, writeExecutableFile, writeSystemTmpFile } from "../utils/fs.js";
+import { buildDockerClientEnv, managedColimaSocketPath, resolveDockerHost } from "../utils/docker-host.js";
+import { getAdapter, listRegisteredAdapters } from "./runtime/index.js";
+// Internal usage of task primitives — re-exports further down preserve the
+// public import surface used by runtime/adapters/*, routes, and CLI.
+import { createTask, emitTask, getRunningTasks } from "./task-registry.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // ── Paths ──────────────────────────────────────────────────────────
 const BIN_DIR = join(JISHUSHELL_HOME, "bin");
-const PACKAGES_DIR = join(JISHUSHELL_HOME, "packages");
-const OPENCLAW_PKG_DIR = join(PACKAGES_DIR, "openclaw");
-/** npm global-prefix layout: lib/node_modules/<pkg>, bin/<cmd> */
-const OPENCLAW_MODULES = join(OPENCLAW_PKG_DIR, "lib", "node_modules");
-const OPENCLAW_BIN_DIR = join(OPENCLAW_PKG_DIR, "bin");
 const NOMAD_BIN = join(BIN_DIR, "nomad");
 const NOMAD_CONFIG_DIR = join(JISHUSHELL_HOME, "nomad");
 const NOMAD_DATA_DIR = join(JISHUSHELL_HOME, "nomad", "data");
 const NOMAD_ALLOC_DIR = join(JISHUSHELL_HOME, "nomad", "data", "alloc");
 const COLIMA_DIR = join(JISHUSHELL_HOME, "colima");
 const COLIMA_PROFILE = "jishushell";
-const COLIMA_SOCKET = join(COLIMA_DIR, COLIMA_PROFILE, "docker.sock");
+const COLIMA_SOCKET = managedColimaSocketPath(JISHUSHELL_HOME, COLIMA_PROFILE);
 const NOMAD_VERSION = "1.6.5";
 let _serverPort = 8090;
 export function setServerPort(port) { _serverPort = port; }
@@ -76,72 +76,13 @@ function resolveServiceUser() {
     catch { /* /etc/passwd unreadable */ }
     throw new Error("Cannot determine service user. Run with a non-root user or set SUDO_UID.");
 }
-const tasks = new Map();
-const TASK_MAX_AGE = 600000; // 10 minutes
-// Periodically clean up completed tasks to prevent memory accumulation
-setInterval(() => {
-    const now = Date.now();
-    for (const [id, task] of tasks) {
-        if (task.status !== "running" && now - parseInt(id.split("-").pop() || "0") > TASK_MAX_AGE) {
-            tasks.delete(id);
-        }
-    }
-}, 60000).unref();
-function createTask(name) {
-    const id = `${name}-${Date.now()}`;
-    const task = { id, name, status: "running", events: [], listeners: new Set() };
-    tasks.set(id, task);
-    return task;
-}
-const MAX_TASK_EVENTS = 500;
-function emitTask(task, event) {
-    task.events.push(event);
-    // Cap events to prevent unbounded memory growth on long-running tasks
-    // (e.g., Docker pull/build can produce thousands of progress lines)
-    if (task.events.length > MAX_TASK_EVENTS) {
-        task.events.splice(0, task.events.length - MAX_TASK_EVENTS);
-    }
-    for (const listener of task.listeners) {
-        listener(event);
-    }
-}
-export function getTask(id) {
-    return tasks.get(id);
-}
-export function getTaskSnapshot(id) {
-    const task = tasks.get(id);
-    if (!task)
-        return undefined;
-    return {
-        id: task.id,
-        name: task.name,
-        status: task.status,
-        events: [...task.events],
-    };
-}
-/** Find running tasks, optionally filtered by name prefix */
-export function getRunningTasks(namePrefix) {
-    const result = [];
-    for (const [id, task] of tasks) {
-        if (task.status !== "running")
-            continue;
-        if (namePrefix && !task.name.startsWith(namePrefix))
-            continue;
-        result.push({ id, name: task.name });
-    }
-    return result;
-}
-export function subscribeTask(id, listener) {
-    const task = tasks.get(id);
-    if (!task)
-        return null;
-    task.listeners.add(listener);
-    // Send existing events
-    for (const event of task.events) {
-        listener(event);
-    }
-    return () => task.listeners.delete(listener);
-}
+// ── Task tracker (for SSE progress) ────────────────────────────────
+// Storage, event dispatch, and subscribe plumbing now live in
+// task-registry.ts so non-setup callers (runtime-apps/*) can publish
+// tasks without pulling in the rest of setup-manager's bootstrap
+// surface. These re-exports preserve the original import surface used
+// by runtime/adapters/*, routes, and CLI.
+export { createTask, emitTask, getTask, getTaskSnapshot, getRunningTasks, subscribeTask, } from "./task-registry.js";
 const ANSI_ESCAPE_RE = /\u001B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
 function sanitizeTaskLine(line) {
     return line
@@ -150,7 +91,7 @@ function sanitizeTaskLine(line) {
         .trimEnd();
 }
 /** Run a shell command as a spawned process, streaming output to a task */
-function spawnWithTask(task, cmd, args, options = {}) {
+export function spawnWithTask(task, cmd, args, options = {}) {
     return new Promise((resolve) => {
         const env = { ...process.env, ...options.env };
         const child = nodeSpawn(cmd, args, {
@@ -214,7 +155,7 @@ function spawnWithTask(task, cmd, args, options = {}) {
     });
 }
 // ── Progress parsers ───────────────────────────────────────────────
-function npmProgressParser(line) {
+export function npmProgressParser(line) {
     // npm shows "added X packages" at the end
     if (line.includes("added") && line.includes("packages"))
         return 100;
@@ -223,7 +164,7 @@ function npmProgressParser(line) {
         return null; // just a log line
     return null;
 }
-function dockerBuildProgressParser(line) {
+export function dockerBuildProgressParser(line) {
     // Docker build steps: "Step 1/6", "Step 2/6", etc.
     const legacyMatch = line.match(/Step\s+(\d+)\/(\d+)/);
     if (legacyMatch) {
@@ -248,7 +189,7 @@ function curlProgressParser(line) {
     return null;
 }
 // ── Dir size tracker for npm installs ──────────────────────────────
-function getDirSizeMB(dir) {
+export function getDirSizeMB(dir) {
     try {
         const result = execFileSync("du", ["-sm", dir], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
         return parseInt(result.split("\t")[0]) || 0;
@@ -284,21 +225,34 @@ function isPortListening(port) {
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         return false;
     const p = String(port);
+    const matchesPort = (output) => new RegExp(`:${p}\\s`).test(output);
     try {
         if (process.platform === "darwin") {
-            const result = execFileSync("lsof", ["-iTCP:" + p, "-sTCP:LISTEN", "-t"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
-            return result.trim().length > 0;
-        }
-        else {
-            // Linux: prefer ss, fall back to netstat
+            try {
+                const result = execFileSync("lsof", ["-iTCP:" + p, "-sTCP:LISTEN", "-t"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+                if (result.trim().length > 0)
+                    return true;
+            }
+            catch {
+            }
             try {
                 const result = execFileSync("ss", ["-tlnp"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
-                return new RegExp(`:${p}\\s`).test(result);
+                if (matchesPort(result))
+                    return true;
             }
             catch {
-                const result = execFileSync("netstat", ["-tlnp"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
-                return new RegExp(`:${p}\\s`).test(result);
             }
+            const result = execFileSync("netstat", ["-tlnp"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+            return matchesPort(result);
+        }
+        // Linux: prefer ss, fall back to netstat
+        try {
+            const result = execFileSync("ss", ["-tlnp"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+            return matchesPort(result);
+        }
+        catch {
+            const result = execFileSync("netstat", ["-tlnp"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+            return matchesPort(result);
         }
     }
     catch {
@@ -360,9 +314,10 @@ export function ensureCgroupMemory() {
     return false;
 }
 function canAccessDockerDaemon(timeout = 10000) {
-    const env = process.platform === "darwin" && existsSync(COLIMA_SOCKET)
-        ? { ...process.env, DOCKER_HOST: `unix://${COLIMA_SOCKET}` }
-        : undefined;
+    const env = buildDockerClientEnv({
+        jishuHome: JISHUSHELL_HOME,
+        colimaProfile: COLIMA_PROFILE,
+    });
     try {
         execFileSync("docker", ["info"], { timeout, stdio: "ignore", env });
         return true;
@@ -386,7 +341,7 @@ function getDockerVersionLine(timeout = 10000) {
     catch { }
     return "installed";
 }
-export function getSetupStatus() {
+export async function getSetupStatus() {
     // Fast path: if setup is already complete, do lightweight checks before returning cached result
     const config = getPanelConfig();
     if (config.service_manager) {
@@ -433,6 +388,7 @@ export function getSetupStatus() {
                 ready,
                 providerConfigured: !!config.default_provider,
                 hasSudo: true,
+                runtimes: await buildRuntimesStatus(),
             };
         }
     }
@@ -512,7 +468,42 @@ export function getSetupStatus() {
         needsReboot = true;
     }
     const runningTasks = getRunningTasks();
-    return { node: nodeStatus, docker: dockerStatus, nomad: nomadStatus, openclaw: openclawStatus, ready, providerConfigured, dockerImageReady, hasSudo: checkSudo(), needsReboot, runningTasks: runningTasks.length ? runningTasks : undefined };
+    return { node: nodeStatus, docker: dockerStatus, nomad: nomadStatus, openclaw: openclawStatus, ready, providerConfigured, dockerImageReady, hasSudo: checkSudo(), needsReboot, runningTasks: runningTasks.length ? runningTasks : undefined, runtimes: await buildRuntimesStatus() };
+}
+/**
+ * Build the per-runtime install status block by iterating over every
+ * registered adapter. A new adapter that implements `getInstallStatus()`
+ * automatically appears here — no change required in this function.
+ *
+ * Each probe is bounded by a short timeout so a hung adapter (slow docker
+ * socket, DNS stall) cannot block the `/api/setup/status` endpoint. This
+ * mirrors the pattern used by `routes/runtime.ts:probeInstallStatus` so
+ * Setup wizard and `/api/runtime/catalog` see a consistent view.
+ */
+const BUILD_RUNTIMES_PROBE_TIMEOUT_MS = 2500;
+async function buildRuntimesStatus() {
+    const adapters = listRegisteredAdapters().filter((a) => typeof a.getInstallStatus === "function");
+    const probes = adapters.map(async (adapter) => {
+        try {
+            const status = await Promise.race([
+                Promise.resolve(adapter.getInstallStatus()),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("install-status probe timed out")), BUILD_RUNTIMES_PROBE_TIMEOUT_MS)),
+            ]);
+            if (!status)
+                return null;
+            const sync = status;
+            return [adapter.agentType, { ...sync, required: !!adapter.required }];
+        }
+        catch {
+            return null;
+        }
+    });
+    const out = {};
+    for (const result of await Promise.all(probes)) {
+        if (result)
+            out[result[0]] = result[1];
+    }
+    return Object.keys(out).length ? out : undefined;
 }
 // ── Upgrade Node.js ────────────────────────────────────────────────
 export async function upgradeNode(targetMajor = 22) {
@@ -1025,6 +1016,7 @@ export async function installNomad() {
                 if (versionLine) {
                     const match = versionLine.match(/v(\d+\.\d+\.\d+)/);
                     const currentVersion = match ? match[1] : "";
+                    let migrated = false;
                     if (currentVersion && isNomadVersionGreater(currentVersion, NOMAD_VERSION)) {
                         // Current > target — auto-migrate (nomad 1.11.3 BSL → 1.6.5 MPL).
                         // Migration failure is a hard stop: the old state has been
@@ -1040,9 +1032,12 @@ export async function installNomad() {
                                 error: migErr?.message || String(migErr),
                             };
                         }
-                        const newLine = execSync(`"${NOMAD_BIN}" version`, { encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
-                        return { ok: true, message: `Nomad migrated to ${newLine}` };
+                        migrated = true;
+                        versionLine = execSync(`"${NOMAD_BIN}" version`, { encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
                     }
+                    // Always (re)write config so the installed nomad.hcl stays up-to-date
+                    // with the current defaults (e.g. raw_exec plugin, acl, limits).
+                    writeNomadConfig();
                     // Ensure Nomad is started even if already installed
                     if (!isPortListening(4646)) {
                         try {
@@ -1053,7 +1048,9 @@ export async function installNomad() {
                             await startNomad();
                         }
                     }
-                    return { ok: true, message: `Nomad already installed: ${versionLine}` };
+                    return migrated
+                        ? { ok: true, message: `Nomad migrated to ${versionLine}` }
+                        : { ok: true, message: `Nomad already installed: ${versionLine}` };
                 }
             }
         }
@@ -1067,6 +1064,7 @@ export async function installNomad() {
                     symlinkSync(systemNomad, NOMAD_BIN);
                     const version = execSync(`${NOMAD_BIN} version`, { encoding: "utf-8", timeout: 5000 }).trim();
                     console.log(`[nomad] Linked system nomad ${systemNomad} → ${NOMAD_BIN}`);
+                    writeNomadConfig();
                     return { ok: true, message: `Nomad linked from system: ${version.split("\n")[0]}` };
                 }
             }
@@ -1144,7 +1142,16 @@ function writeNomadConfig() {
     ensureDirHost(NOMAD_CONFIG_DIR);
     ensureDirContainer(NOMAD_DATA_DIR);
     ensureDirContainer(NOMAD_ALLOC_DIR);
-    const loopbackIface = process.platform === "darwin" ? "lo0" : "lo";
+    const platform = osPlatform();
+    const loopbackIface = platform === "darwin" ? "lo0" : "lo";
+    const externalIface = detectNomadExternalInterface(loopbackIface);
+    const externalHostNetworkBlock = externalIface
+        ? `
+  host_network "external" {
+    interface = "${externalIface}"
+  }
+`
+        : "";
     const config = `
 data_dir = "${NOMAD_DATA_DIR}"
 
@@ -1168,6 +1175,7 @@ client {
   servers = ["127.0.0.1:4647"]
   network_interface = "${loopbackIface}"
   alloc_dir = "${NOMAD_ALLOC_DIR}"
+${externalHostNetworkBlock}
 
   # drain_on_shutdown intentionally omitted: on single-node Pi there is
   # nowhere to drain workloads to, and draining on every systemctl restart
@@ -1184,12 +1192,45 @@ plugin "docker" {
   }
 }
 
+plugin "raw_exec" {
+  config {
+    enabled = true
+  }
+}
+
 acl {
   enabled = true
 }
+
+limits {
+  http_max_conns_per_client = 0
+}
 `;
     writeConfigFile(join(NOMAD_CONFIG_DIR, "nomad.hcl"), config);
 }
+function detectNomadExternalInterface(loopbackIface) {
+    try {
+        if (osPlatform() === "darwin") {
+            const route = execFileSync("route", ["-n", "get", "default"], {
+                encoding: "utf8",
+                timeout: 3000,
+            });
+            const match = route.match(/interface:\s*(\S+)/);
+            const iface = match?.[1]?.trim() ?? "";
+            return iface && iface !== loopbackIface ? iface : "";
+        }
+        const route = execFileSync("ip", ["route", "show", "default"], {
+            encoding: "utf8",
+            timeout: 3000,
+        });
+        const match = route.match(/\bdev\s+(\S+)/);
+        const iface = match?.[1]?.trim() ?? "";
+        return iface && iface !== loopbackIface ? iface : "";
+    }
+    catch {
+        return "";
+    }
+}
 export function loadNomadToken() {
     if (process.env.NOMAD_TOKEN)
         return;
@@ -1533,7 +1574,14 @@ export function installNomadSystemd() {
         if (process.platform === "darwin") {
             const plistLabel = "com.jishushell.nomad";
             const logPath = join(NOMAD_CONFIG_DIR, "nomad.log");
-            const dockerSock = COLIMA_SOCKET;
+            const dockerHost = resolveDockerHost({
+                jishuHome: JISHUSHELL_HOME,
+                colimaProfile: COLIMA_PROFILE,
+            });
+            const dockerHostEntry = dockerHost
+                ? `
+    <key>DOCKER_HOST</key><string>${dockerHost}</string>`
+                : "";
             const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -1546,8 +1594,7 @@ export function installNomadSystemd() {
     <string>-config=${configPath}</string>
   </array>
   <key>EnvironmentVariables</key>
-  <dict>
-    <key>DOCKER_HOST</key><string>unix://${dockerSock}</string>
+  <dict>${dockerHostEntry}
     <key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
   </dict>
   <key>RunAtLoad</key><true/>
@@ -1582,6 +1629,8 @@ EnvironmentFile=-/etc/jishushell/nomad.env
 ExecStart=${nomadPath} agent -config=${configPath}
 Restart=on-failure
 RestartSec=3
+Delegate=yes
+TasksMax=infinity
 
 [Install]
 WantedBy=multi-user.target
@@ -1624,7 +1673,6 @@ export function installJishushellSystemd(port) {
 export JISHUSHELL_HOME="${JISHUSHELL_HOME}"
 export HOME="${realHome}"
 export NODE_ENV=production
-export DOCKER_HOST="unix://${COLIMA_SOCKET}"
 export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin:${dirname(nodeBin)}:\${PATH}"
 exec "${nodeBin}" "${cliBin}" serve --port ${resolvedPort}
 `;
@@ -1693,64 +1741,77 @@ WantedBy=multi-user.target
     }
 }
 // ── Install OpenClaw (async with progress) ─────────────────────────
-const OPENCLAW_EXPECTED_SIZE_MB = 700;
+/**
+ * Install OpenClaw runtime — thin dispatch wrapper.
+ *
+ * The heavy lifting lives in `OpenClawAdapter.installRuntime()` (§32.2.4).
+ * This wrapper is kept only for back-compat with the existing
+ * `routes/setup.ts` endpoint and the CLI installer.
+ */
 export async function installOpenclaw(version = "latest") {
+    const adapter = getAdapter("openclaw");
+    if (typeof adapter.installRuntime !== "function") {
+        return { ok: false, message: "OpenClawAdapter.installRuntime is not implemented" };
+    }
+    return adapter.installRuntime({ version });
+}
+// ── Hermes install (§32.1 / §32.3) ─────────────────────────────────
+//
+// Hermes constants (HERMES_DEFAULT_IMAGE, HERMES_RUNTIME_DIR,
+// HERMES_SHIM_FILENAME) and the shim template resolver have moved to
+// `src/config.ts` (§32 Phase 8). setup-manager no longer defines them.
+// The HermesAdapter imports them directly from config.ts.
+/**
+ * Capture the immutable digest of a locally-present image so HermesAdapter
+ * can pin via digest rather than the mutable tag. Returns undefined if the
+ * image has no RepoDigests (e.g. locally-built image) — caller may still
+ * proceed using the tag alone.
+ */
+export function captureImageDigest(imageRef) {
     try {
-        const openclawPkgDir = join(OPENCLAW_MODULES, "openclaw");
-        if (existsSync(openclawPkgDir)) {
-            const ver = getLocalOpenclawVersion() || "unknown";
-            return { ok: true, message: `OpenClaw already installed: ${ver}` };
-        }
-        const task = createTask("openclaw");
-        ensureDirHost(OPENCLAW_PKG_DIR);
-        emitTask(task, { type: "progress", message: "开始安装 OpenClaw...", progress: 0 });
-        // Monitor directory size for progress estimation
-        const sizeTracker = setInterval(() => {
-            const sizeMB = getDirSizeMB(OPENCLAW_PKG_DIR);
-            const pct = Math.min(95, Math.round((sizeMB / OPENCLAW_EXPECTED_SIZE_MB) * 95));
-            if (pct > 0) {
-                emitTask(task, { type: "progress", message: `下载安装中... ${sizeMB}MB / ~${OPENCLAW_EXPECTED_SIZE_MB}MB`, progress: pct });
-            }
-        }, 3000);
-        // Use npm install -g with --prefix so npm uses global-install semantics:
-        // packages go to <prefix>/lib/node_modules/, bins to <prefix>/bin/
-        // This makes postinstall scripts run naturally (no manual workarounds needed).
-        const result = await spawnWithTask(task, "npm", ["install", "-g", "--prefix", OPENCLAW_PKG_DIR, `openclaw@${version}`], { timeout: 600000, progressParser: npmProgressParser });
-        clearInterval(sizeTracker);
-        if (!result.ok) {
-            emitTask(task, { type: "error", message: "OpenClaw 安装失败" });
-            task.status = "error";
-            return { ok: false, message: "OpenClaw installation failed", error: result.output, taskId: task.id };
-        }
-        // Read version from package.json since openclaw --version needs Node 22+
-        let ver = "installed";
-        try {
-            const pkg = join(OPENCLAW_MODULES, "openclaw", "package.json");
-            if (existsSync(pkg)) {
-                const pkgJson = JSON.parse(readFileSync(pkg, "utf-8"));
-                ver = pkgJson.version || "installed";
-            }
-        }
-        catch { }
-        emitTask(task, { type: "done", message: `OpenClaw 安装完成: ${ver}`, progress: 100 });
-        task.status = "done";
-        return { ok: true, message: `OpenClaw installed: ${ver}`, taskId: task.id };
+        const raw = execFileSync("docker", [
+            "image",
+            "inspect",
+            "--format",
+            "{{range .RepoDigests}}{{.}}{{\"\\n\"}}{{end}}",
+            imageRef,
+        ], { encoding: "utf-8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"] });
+        const first = raw.split("\n").map((l) => l.trim()).find(Boolean);
+        return first || undefined;
     }
-    catch (e) {
-        return { ok: false, message: "OpenClaw installation failed", error: e.message };
+    catch {
+        return undefined;
     }
 }
-// ── Helpers ──────────────────────────────────────────────────────
-function getLocalOpenclawVersion() {
-    try {
-        const pkg = join(OPENCLAW_MODULES, "openclaw", "package.json");
-        if (existsSync(pkg))
-            return JSON.parse(readFileSync(pkg, "utf-8")).version || "";
+/**
+ * Install Hermes runtime — thin dispatch wrapper.
+ *
+ * Heavy lifting lives in `HermesAdapter.installRuntime()` (§32.2.4).
+ */
+export async function installHermes() {
+    const adapter = getAdapter("hermes");
+    if (typeof adapter.installRuntime !== "function") {
+        return { ok: false, message: "HermesAdapter.installRuntime is not implemented" };
     }
-    catch { }
-    return "";
+    return adapter.installRuntime();
+}
+/**
+ * Non-blocking variant — returns a task id immediately. Implementation
+ * dispatches via `HermesAdapter.startInstallRuntime()`.
+ */
+export function startInstallHermes() {
+    const adapter = getAdapter("hermes");
+    if (typeof adapter.startInstallRuntime !== "function") {
+        return { ok: false, message: "HermesAdapter.startInstallRuntime is not implemented" };
+    }
+    return adapter.startInstallRuntime();
+}
+/** Helper for setup status — true when runtime catalog has hermes entry. */
+export function isHermesInstalled() {
+    const entry = getRuntimeCatalogEntry("hermes");
+    return !!entry && !!entry.defaultImage;
 }
-function resolveDockerInvocation() {
+export function resolveDockerInvocation() {
     try {
         execFileSync("docker", ["info"], { timeout: 5000, stdio: "ignore" });
         return { cmd: "docker", argsPrefix: [] };
@@ -1810,452 +1871,31 @@ function checkDockerImageExists() {
         return false;
     }
 }
-// The stable tag for the JishuShell base image (slim — no OpenClaw binary baked in).
+// The stable tag for the JishuShell base image. Reads panel.json — framework-level.
 function resolveDockerImageTag() {
     return getOpenclawDockerImage();
 }
-// Base image and mirror list for the OpenClaw Docker build.
-// Mirrors are tried in order when docker.io is unreachable (e.g. behind GFW or rate-limited).
-const DOCKER_BASE_IMAGE = "node:22-slim";
-const DOCKER_BASE_MIRRORS = [
-    "node:22-slim",
-    "hub-mirror.c.163.com/library/node:22-slim",
-    "mirrors.tencent.com/library/node:22-slim",
-    "registry.cn-hangzhou.aliyuncs.com/library/node:22-slim",
-];
-// Pull DOCKER_BASE_IMAGE from mirrors if not already cached locally.
-// Returns the image content digest (sha256:…) so that the subsequent
-// docker build can use `FROM <digest>`, which BuildKit resolves from
-// the local daemon without any outbound registry metadata request.
-async function ensureDockerBaseImage(invocation, task) {
-    // Fast path: already in local daemon cache — return image name (not digest) for Dockerfile FROM
-    try {
-        execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", DOCKER_BASE_IMAGE], {
-            timeout: 5000,
-            stdio: "ignore",
-        });
-        emitTask(task, { type: "log", message: `基础镜像已缓存: ${DOCKER_BASE_IMAGE}` });
-        return DOCKER_BASE_IMAGE;
-    }
-    catch { /* not cached, fall through */ }
-    for (const mirror of DOCKER_BASE_MIRRORS) {
-        emitTask(task, { type: "log", message: `拉取基础镜像: ${mirror} ...` });
-        const result = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "pull", mirror], { timeout: 300000 });
-        if (result.ok) {
-            if (mirror !== DOCKER_BASE_IMAGE) {
-                try {
-                    execFileSync(invocation.cmd, [...invocation.argsPrefix, "tag", mirror, DOCKER_BASE_IMAGE], { timeout: 10000 });
-                }
-                catch { /* tag failure is non-fatal */ }
-            }
-            emitTask(task, { type: "log", message: `基础镜像就绪: ${DOCKER_BASE_IMAGE}` });
-            return DOCKER_BASE_IMAGE;
-        }
-        emitTask(task, { type: "log", message: `  → ${mirror} 不可达，尝试下一个镜像源...` });
-    }
-    throw new Error(`无法获取基础镜像 ${DOCKER_BASE_IMAGE}。请检查网络或手动执行: docker pull ${DOCKER_BASE_MIRRORS[1]}`);
-}
-function resolveVersionedBuildTag() {
-    try {
-        const pkg = join(OPENCLAW_MODULES, "openclaw", "package.json");
-        if (existsSync(pkg)) {
-            const ver = JSON.parse(readFileSync(pkg, "utf-8")).version;
-            if (ver)
-                return `jishushell-openclaw:${ver}`;
-        }
-    }
-    catch { }
-    return resolveDockerImageTag();
-}
-async function buildOpenclawDockerImageWithTask(task, tag) {
-    const targetTag = tag || resolveVersionedBuildTag();
-    try {
-        const invocation = resolveDockerInvocation();
-        // Fast check: if image with this exact tag exists, skip build (tag encodes version)
-        try {
-            execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", targetTag], {
-                timeout: 10000,
-                stdio: "ignore",
-            });
-            setOpenclawDockerImage(targetTag);
-            emitTask(task, { type: "done", message: `Docker 镜像已存在: ${targetTag}`, progress: 100 });
-            task.status = "done";
-            return { ok: true, message: `Docker image ${targetTag} already exists`, taskId: task.id };
-        }
-        catch { /* image not found, proceed to build */ }
-        // Clean up old openclaw:* images that predate the new slim-base architecture.
-        // Skip if the stored tag matches targetTag or is a remote registry image.
-        const oldTag = getPanelConfig().openclaw_image;
-        if (oldTag && oldTag !== targetTag && !oldTag.includes("/") && /^openclaw:/i.test(oldTag)) {
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "rmi", oldTag], { timeout: 15000, stdio: "ignore" });
-            }
-            catch { }
-        }
-        // Ensure node:22-slim base image is in the local daemon cache before building.
-        emitTask(task, { type: "progress", message: "准备基础镜像...", progress: 5 });
-        const baseImageId = await ensureDockerBaseImage(invocation, task);
-        // Slim Dockerfile: no COPY of openclaw node_modules — the binary is bind-mounted
-        // from the host at runtime, so this image needs no OpenClaw-specific layers.
-        // Build context is an empty temp directory (no files to COPY).
-        const dockerfile = `FROM ${baseImageId}
-RUN apt-get update && apt-get install -y --no-install-recommends \\
-    ca-certificates curl \\
-    python3 python3-pip python3-venv python3-dev && \\
-    ln -sf /usr/bin/python3 /usr/local/bin/python && \\
-    rm -rf /var/lib/apt/lists/*
-WORKDIR /data
-USER node
-ENTRYPOINT ["node", "/usr/lib/node_modules/openclaw/openclaw.mjs"]
-CMD ["gateway", "run", "--port", "18789", "--allow-unconfigured"]
-`;
-        // Use a temp dir as build context — no files to COPY means no large transfer.
-        const buildDir = join(tmpdir(), `jishushell-base-build-${Date.now()}`);
-        ensureDirHost(buildDir);
-        const dockerfilePath = join(buildDir, "Dockerfile");
-        writeConfigFile(dockerfilePath, dockerfile);
-        emitTask(task, { type: "progress", message: `构建基础镜像 ${targetTag}（无需拷贝二进制，速度极快）...`, progress: 10 });
-        let result;
-        try {
-            result = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "build", "--network=host", "-t", targetTag, buildDir], {
-                timeout: 1800000,
-                progressParser: dockerBuildProgressParser,
-                env: {},
-            });
-        }
-        finally {
-            // Always clean up temp build dir
-            try {
-                execSync(`rm -rf "${buildDir}"`, { timeout: 5000 });
-            }
-            catch { }
-        }
-        if (!result.ok) {
-            // Clean up dangling images from failed build
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "prune", "-f"], { timeout: 15000, stdio: "ignore" });
-            }
-            catch { }
-            emitTask(task, { type: "error", message: "Docker 镜像构建失败" });
-            task.status = "error";
-            return { ok: false, message: "Docker image build failed", error: result.output, taskId: task.id };
-        }
-        const localTag = "jishushell-openclaw:local";
-        if (targetTag !== localTag) {
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "tag", targetTag, localTag], { timeout: 10000, stdio: "ignore" });
-            }
-            catch { }
-        }
-        setOpenclawDockerImage(localTag);
-        emitTask(task, { type: "done", message: `Docker 镜像构建完成: ${targetTag}`, progress: 100 });
-        task.status = "done";
-        return { ok: true, message: `Docker image ${targetTag} built`, taskId: task.id };
-    }
-    catch (e) {
-        // Clean up build artifacts on unexpected errors
-        try {
-            execSync("docker image prune -f", { timeout: 15000, stdio: "ignore" });
-        }
-        catch { }
-        emitTask(task, { type: "error", message: `Docker 镜像构建失败: ${e.message}` });
-        task.status = "error";
-        return { ok: false, message: "Docker image build failed", error: e.message, taskId: task.id };
-    }
-}
-export async function buildOpenclawDockerImage(tag) {
-    const task = createTask("openclaw-docker");
-    return buildOpenclawDockerImageWithTask(task, tag);
-}
-export function startBuildOpenclawDockerImage(tag) {
-    const task = createTask("openclaw-docker");
-    void buildOpenclawDockerImageWithTask(task, tag).catch((err) => {
-        emitTask(task, { type: "error", message: `Docker 镜像构建失败: ${err?.message || err}` });
-        task.status = "error";
-    });
-    return { ok: true, message: "Docker image build started", taskId: task.id };
-}
-// ── Build OpenClaw Docker image from npm package + Python ─────────
-async function buildCustomOpenclawImageWithTask(task, tag) {
-    const targetTag = tag || DEFAULT_OPENCLAW_DOCKER_IMAGE;
-    try {
-        const invocation = resolveDockerInvocation();
-        // Fast check: if image already exists locally, skip
-        try {
-            execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", targetTag], {
-                timeout: 10000,
-                stdio: "ignore",
-            });
-            setOpenclawDockerImage(targetTag);
-            emitTask(task, { type: "done", message: `Docker 镜像已存在: ${targetTag}`, progress: 100 });
-            task.status = "done";
-            return { ok: true, message: `Docker image ${targetTag} already exists`, taskId: task.id };
-        }
-        catch { /* image not found, proceed */ }
-        // Clean up old legacy images
-        const oldTag = getPanelConfig().openclaw_image;
-        if (oldTag && oldTag !== targetTag && /^jishushell-base:/i.test(oldTag)) {
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "rmi", oldTag], { timeout: 15000, stdio: "ignore" });
-            }
-            catch { }
-        }
-        // Step 1: Ensure OpenClaw npm package is installed (used as build context)
-        const openclawPkgDir = join(OPENCLAW_MODULES, "openclaw");
-        if (!existsSync(openclawPkgDir)) {
-            emitTask(task, { type: "progress", message: "安装 OpenClaw npm 包...", progress: 5 });
-            const installResult = await installOpenclaw();
-            if (!installResult.ok) {
-                emitTask(task, { type: "error", message: "OpenClaw 安装失败" });
-                task.status = "error";
-                return { ok: false, message: "OpenClaw npm install failed", error: installResult.error, taskId: task.id };
-            }
-        }
-        // Step 2: Ensure base image is available
-        emitTask(task, { type: "progress", message: "准备基础镜像...", progress: 10 });
-        const baseImageId = await ensureDockerBaseImage(invocation, task);
-        // Step 3: Build image — COPY node_modules + Python
-        emitTask(task, { type: "progress", message: `构建 OpenClaw 镜像（含 Python）: ${targetTag} ...`, progress: 30 });
-        const dockerfile = `FROM ${baseImageId}
-USER root
-RUN apt-get update && apt-get install -y --no-install-recommends \\
-    procps hostname curl git lsof openssl \\
-    python3 python3-pip python3-venv python3-dev && \\
-    ln -sf /usr/bin/python3 /usr/local/bin/python && \\
-    rm -rf /var/lib/apt/lists/*
-WORKDIR /app
-COPY --chown=node:node lib/node_modules/ ./node_modules/
-RUN ln -sf /app/node_modules/openclaw/openclaw.mjs /app/openclaw.mjs && \\
-    ln -sf /app/node_modules/openclaw/openclaw.mjs /usr/local/bin/openclaw && \\
-    cp /app/node_modules/openclaw/package.json /app/package.json 2>/dev/null || true
-USER node
-CMD ["node", "openclaw.mjs", "gateway", "--allow-unconfigured"]
-`;
-        // Write Dockerfile into the npm package directory (build context)
-        const dockerfilePath = join(OPENCLAW_PKG_DIR, "Dockerfile");
-        writeConfigFile(dockerfilePath, dockerfile);
-        let buildResult;
-        try {
-            buildResult = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "build", "--network=host", "-t", targetTag, OPENCLAW_PKG_DIR], { timeout: 1800000, progressParser: dockerBuildProgressParser });
-        }
-        finally {
-            try {
-                unlinkSync(dockerfilePath);
-            }
-            catch { }
-        }
-        if (!buildResult.ok) {
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "prune", "-f"], { timeout: 15000, stdio: "ignore" });
-            }
-            catch { }
-            emitTask(task, { type: "error", message: "Docker 镜像构建失败" });
-            task.status = "error";
-            return { ok: false, message: "Docker image build failed", error: buildResult.output, taskId: task.id };
-        }
-        setOpenclawDockerImage(targetTag);
-        emitTask(task, { type: "done", message: `OpenClaw 镜像就绪: ${targetTag}（含 Python）`, progress: 100 });
-        task.status = "done";
-        return { ok: true, message: `Docker image ${targetTag} built`, taskId: task.id };
-    }
-    catch (e) {
-        emitTask(task, { type: "error", message: `镜像构建失败: ${e.message}` });
-        task.status = "error";
-        return { ok: false, message: "Docker image build failed", error: e.message, taskId: task.id };
-    }
-}
-// ── Pull or build OpenClaw Docker image ───────────────────────────
-/** Matches a semver-ish tag suffix, e.g. "...:2026.4.9" or "...:v1.2.3-beta". */
-const PINNED_IMAGE_TAG_RE = /:[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9.-]+)?$/;
-/**
- * Query the npm registry for the current OpenClaw version. Used to bust the
- * Docker layer cache for `RUN npm install openclaw@${ver}` during local build.
- * Returns "latest" when npm is unreachable so the build can still proceed.
- */
-function resolveOpenclawNpmVersion() {
-    try {
-        const out = execFileSync("npm", ["view", "openclaw", "version"], {
-            timeout: 15000,
-            encoding: "utf-8",
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-        if (/^\d+\.\d+\.\d+/.test(out))
-            return out;
-    }
-    catch { /* npm not reachable */ }
-    return "latest";
-}
-/**
- * Read the OpenClaw version actually bundled at /app/ inside a Docker image,
- * bypassing `openclaw-entry.sh`'s `.npm-global/` override. This is the
- * authoritative source of truth — the image's OCI label can be wrong
- * (CI bugs, layer cache reuse), but `/app/node_modules/openclaw/package.json`
- * is the exact content that ran through `npm install`.
- *
- * Spawns a throw-away container with `--entrypoint node` so Node prints the
- * version directly. Returns "" when docker is unavailable or the path is
- * missing (e.g. a non-openclaw image).
- */
-function readBundledOpenclawVersion(invocation, image) {
-    try {
-        const out = execFileSync(invocation.cmd, [
-            ...invocation.argsPrefix,
-            "run", "--rm",
-            "--entrypoint", "node",
-            image,
-            "-p",
-            "require('/app/node_modules/openclaw/package.json').version",
-        ], { timeout: 20000, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-        if (/^\d+\.\d+\.\d+/.test(out))
-            return out;
-    }
-    catch { /* docker unavailable, image missing, or path not present */ }
-    return "";
-}
-/**
- * After a successful pull or build, capture the image's real OpenClaw version
- * and return a pinned tag of the form `ghcr.io/.../openclaw-runtime:<version>`.
- * The pinned tag is added as a local alias via `docker tag` so subsequent
- * Nomad allocations see an immutable reference and never re-pull on restart.
- *
- * Version discovery order:
- *  1. `explicitVersion` when the caller already knows it (e.g. the local build
- *     path, which queries npm for the version and passes it as `--build-arg`).
- *  2. Bundled `/app/node_modules/openclaw/package.json` inside the image
- *     (authoritative — bypasses both the `.npm-global/` override layer and a
- *     potentially stale OCI label).
- *
- * Returns the original tag unchanged when:
- *  - the target is already a pinned version tag
- *  - no version can be discovered
- *  - docker tag fails for any reason
- */
-function capturePinnedImageTag(invocation, targetTag, explicitVersion) {
-    // Already pinned? Nothing to do.
-    if (PINNED_IMAGE_TAG_RE.test(targetTag))
-        return targetTag;
-    let version = explicitVersion && /^\d+\.\d+\.\d+/.test(explicitVersion) ? explicitVersion : "";
-    if (!version) {
-        version = readBundledOpenclawVersion(invocation, targetTag);
-    }
-    if (!version || !/^\d+\.\d+\.\d+/.test(version))
-        return targetTag;
-    // Build the pinned tag by replacing the mutable tag portion.
-    // "ghcr.io/foo/bar:latest"   → "ghcr.io/foo/bar:2026.4.9"
-    // "ghcr.io/foo/bar"          → "ghcr.io/foo/bar:2026.4.9"
-    const colonIdx = targetTag.lastIndexOf(":");
-    const slashIdx = targetTag.lastIndexOf("/");
-    const hasTag = colonIdx > slashIdx;
-    const repo = hasTag ? targetTag.slice(0, colonIdx) : targetTag;
-    const pinnedTag = `${repo}:${version}`;
-    if (pinnedTag === targetTag)
-        return targetTag;
-    try {
-        execFileSync(invocation.cmd, [...invocation.argsPrefix, "tag", targetTag, pinnedTag], { timeout: 10000, stdio: "ignore" });
-    }
-    catch {
-        // Could not create the local alias — fall back to original tag.
-        return targetTag;
-    }
-    // Drop the mutable original alias (`:latest` / `:slim`) now that the pinned
-    // tag is in place. Removing a tag is cheap and leaves the underlying image
-    // alive because the new pinned reference still points to it. Best-effort:
-    // silent when the tag is already gone or in use.
-    if (/:(latest|slim)$/.test(targetTag)) {
-        try {
-            execFileSync(invocation.cmd, [...invocation.argsPrefix, "rmi", targetTag], { timeout: 10000, stdio: "ignore" });
-        }
-        catch { /* best-effort cleanup */ }
-    }
-    return pinnedTag;
-}
-async function pullOrBuildOpenclawImageWithTask(task, tag) {
-    const targetTag = tag || DEFAULT_OPENCLAW_DOCKER_IMAGE;
-    try {
-        const invocation = resolveDockerInvocation();
-        // Fast check: if image already exists locally, skip
-        try {
-            execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", targetTag], {
-                timeout: 10000,
-                stdio: "ignore",
-            });
-            const pinned = capturePinnedImageTag(invocation, targetTag);
-            setOpenclawDockerImage(pinned);
-            emitTask(task, { type: "done", message: `Docker 镜像已存在: ${pinned}`, progress: 100 });
-            task.status = "done";
-            return { ok: true, message: `Docker image ${pinned} already exists`, taskId: task.id };
-        }
-        catch { /* image not found, proceed */ }
-        // ── Step 1: Try docker pull from registry ─────────────────────
-        emitTask(task, { type: "progress", message: `正在拉取镜像: ${targetTag} ...`, progress: 10 });
-        const pullResult = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "pull", targetTag], { timeout: 600000 });
-        if (pullResult.ok) {
-            const pinned = capturePinnedImageTag(invocation, targetTag);
-            setOpenclawDockerImage(pinned);
-            emitTask(task, { type: "done", message: `镜像拉取成功: ${pinned}`, progress: 100 });
-            task.status = "done";
-            return { ok: true, message: `Docker image ${pinned} pulled`, taskId: task.id };
-        }
-        // ── Step 2: Fallback to local build ───────────────────────────
-        console.log(`[setup] docker pull failed for ${targetTag}, falling back to local build...`);
-        emitTask(task, { type: "progress", message: `拉取失败，正在本地构建镜像: ${targetTag} ...`, progress: 20 });
-        const projectRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
-        const dockerfilePath = join(projectRoot, "Dockerfile.openclaw-slim");
-        if (!existsSync(dockerfilePath)) {
-            emitTask(task, { type: "error", message: "Dockerfile.openclaw-slim not found, cannot fallback to local build" });
-            task.status = "error";
-            return { ok: false, message: "Docker pull failed and Dockerfile.openclaw-slim not found", taskId: task.id };
-        }
-        // Resolve the OpenClaw version from npm so the build-arg busts the Docker
-        // layer cache for `RUN npm install openclaw@${ver}`. The Dockerfile's
-        // ARG OPENCLAW_VERSION=latest default would otherwise cause the layer to
-        // be silently reused across releases.
-        const openclawVersion = resolveOpenclawNpmVersion();
-        console.log(`[setup] building openclaw image with OPENCLAW_VERSION=${openclawVersion}`);
-        const buildResult = await spawnWithTask(task, invocation.cmd, [
-            ...invocation.argsPrefix,
-            "build",
-            "--network=host",
-            "--build-arg", `OPENCLAW_VERSION=${openclawVersion}`,
-            "-f", dockerfilePath,
-            "-t", targetTag,
-            projectRoot,
-        ], { timeout: 1800000, progressParser: dockerBuildProgressParser });
-        if (!buildResult.ok) {
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "prune", "-f"], { timeout: 15000, stdio: "ignore" });
-            }
-            catch { }
-            emitTask(task, { type: "error", message: "Docker 镜像构建失败" });
-            task.status = "error";
-            return { ok: false, message: "Docker image build failed", error: buildResult.output, taskId: task.id };
-        }
-        // Local builds don't get labels from the GitHub Action's `labels:` field,
-        // so pass the npm version we already know to let capturePinnedImageTag
-        // mint the pinned tag without relying on docker inspect.
-        const pinned = capturePinnedImageTag(invocation, targetTag, openclawVersion);
-        setOpenclawDockerImage(pinned);
-        emitTask(task, { type: "done", message: `OpenClaw 镜像就绪 (本地构建): ${pinned}`, progress: 100 });
-        task.status = "done";
-        return { ok: true, message: `Docker image ${pinned} built locally`, taskId: task.id };
-    }
-    catch (e) {
-        emitTask(task, { type: "error", message: `镜像获取失败: ${e.message}` });
-        task.status = "error";
-        return { ok: false, message: "Docker image pull/build failed", error: e.message, taskId: task.id };
-    }
-}
+// ── Docker image build dispatch wrappers ───────────────────────────────
+//
+// All OpenClaw-specific image build logic now lives in
+// `OpenClawAdapter.buildRuntimeImage()` (§32.2.4 physical migration). These
+// exports remain as thin wrappers so `routes/setup.ts` and
+// `install.ts` callers don't need to learn adapter dispatch.
+/** Blocking: pull or build the OpenClaw docker image. */
 export async function buildSlimOpenclawImage(tag) {
-    const task = createTask("openclaw-docker-pull");
-    return pullOrBuildOpenclawImageWithTask(task, tag);
+    const adapter = getAdapter("openclaw");
+    if (typeof adapter.buildRuntimeImage !== "function") {
+        return { ok: false, message: "OpenClawAdapter.buildRuntimeImage is not implemented" };
+    }
+    return adapter.buildRuntimeImage({ tag });
 }
+/** Non-blocking: returns immediately with a task id for SSE polling. */
 export function startBuildSlimOpenclawImage(tag) {
-    const task = createTask("openclaw-docker-pull");
-    void pullOrBuildOpenclawImageWithTask(task, tag).catch((err) => {
-        emitTask(task, { type: "error", message: `镜像获取失败: ${err?.message || err}` });
-        task.status = "error";
-    });
-    return { ok: true, message: "Docker image pull started", taskId: task.id };
+    const adapter = getAdapter("openclaw");
+    if (typeof adapter.startBuildRuntimeImage !== "function") {
+        return { ok: false, message: "OpenClawAdapter.startBuildRuntimeImage is not implemented" };
+    }
+    return adapter.startBuildRuntimeImage({ tag });
 }
 /** @deprecated Use buildSlimOpenclawImage instead */
 export async function buildCustomOpenclawImage(tag) {
@@ -2306,7 +1946,10 @@ export async function runFullSetup(options = {}) {
             }
         }
     }
-    // Prepare Docker image: pull official image or build slim base (legacy).
+    // Prepare each registered agent's runtime artefacts (docker image, shim,
+    // etc.). This loops over every adapter so onboarding a new agent only
+    // requires implementing `buildRuntimeImage` or `installRuntime` in its
+    // adapter — runFullSetup picks it up automatically.
     if (defaults.buildDockerImage) {
         // Restart Nomad so it re-detects Docker driver after Docker was installed
         try {
@@ -2318,12 +1961,50 @@ export async function runFullSetup(options = {}) {
             }
         }
         catch { }
-        steps.push({ step: "docker-image", status: "running", message: "Building OpenClaw Docker image..." });
-        const imgResult = await buildSlimOpenclawImage();
-        steps[steps.length - 1].status = imgResult.ok ? "done" : "error";
-        steps[steps.length - 1].message = imgResult.message;
-        if (!imgResult.ok)
-            allOk = false;
+        for (const adapter of listRegisteredAdapters()) {
+            const stepName = `runtime-${adapter.agentType}`;
+            // Prefer buildRuntimeImage (pure docker image prep) over
+            // installRuntime (legacy host-mode npm install). Adapters that only
+            // implement one will use whichever is present; adapters with neither
+            // are skipped silently.
+            const runner = adapter.buildRuntimeImage
+                ? adapter.buildRuntimeImage.bind(adapter)
+                : adapter.installRuntime
+                    ? adapter.installRuntime.bind(adapter)
+                    : null;
+            if (!runner)
+                continue;
+            const isRequired = !!adapter.required;
+            steps.push({
+                step: stepName,
+                status: "running",
+                message: `Preparing ${adapter.agentType} runtime…`,
+            });
+            try {
+                const imgResult = (await runner());
+                const okStep = !!imgResult.ok;
+                steps[steps.length - 1].status = okStep ? "done" : "error";
+                steps[steps.length - 1].message = okStep
+                    ? imgResult.message
+                    : isRequired
+                        ? imgResult.message
+                        : `${imgResult.message} (optional — panel will continue)`;
+                // Required adapter failures abort the overall setup; optional ones
+                // are warnings so that upgrade paths don't break when a third-party
+                // agent's registry is unreachable.
+                if (!okStep && isRequired)
+                    allOk = false;
+            }
+            catch (e) {
+                const msg = e?.message || "runtime prepare failed";
+                steps[steps.length - 1].status = "error";
+                steps[steps.length - 1].message = isRequired
+                    ? msg
+                    : `${msg} (optional — panel will continue)`;
+                if (isRequired)
+                    allOk = false;
+            }
+        }
     }
     if (isPortListening(4646)) {
         await finalizeNomadStartup();