jishushell 0.4.17 → 0.4.24

package/dist/services/runtime/adapters/hermes.js

@@ -0,0 +1,1316 @@
+/**
+ * HermesAdapter — first non-OpenClaw runtime adapter.
+ *
+ * Design: docs/multi-agent-runtime-generalization-plan.md §11, §28, §32.
+ *
+ * MVP scope (§32.3):
+ *   - Only create / buildRuntime / getRuntimeVersion are wired up.
+ *   - Baseline image mode only. Overlay upgrade CLI is deferred.
+ *   - Assumes panel.json.runtime_catalog.hermes has been populated by
+ *     setup-manager.installHermes(): defaultImage (+ optional defaultImageDigest),
+ *     shimPath, resources, homeDirName.
+ */
+import { execFileSync } from "child_process";
+import { createRequire } from "node:module";
+import { chmodSync, chownSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "fs";
+import { randomBytes } from "crypto";
+import { dirname, join } from "path";
+import { getPanelConfig, getRuntimeCatalogEntry, setRuntimeCatalogEntry, HERMES_DEFAULT_IMAGE, } from "../../../config.js";
+import { ensureDirContainer, writeConfigFile, writeSecretFile, } from "../../../utils/fs.js";
+import { safeWriteJson } from "../../../utils/safe-json.js";
+import { ensureInstanceProxyToken, getProxyBaseUrl } from "../../llm-proxy/index.js";
+import { allocateGatewayPort, releasePendingPort, resolveServiceUser, updateEnvFile, } from "../../instance-manager.js";
+import { getInstanceDir as instanceDir, instanceMetaPath } from "../../../config.js";
+import { createTask, emitTask, spawnWithTask, resolveDockerInvocation, captureImageDigest, } from "../../setup-manager.js";
+import { InstanceCreationRejected } from "../errors.js";
+import YAML from "yaml";
+import { registerAdapter } from "../registry.js";
+const HERMES_CONTAINER_PORT = 8642;
+const HERMES_CONTAINER_HOME = "/opt/data";
+const HERMES_CONTAINER_SHIM = "/usr/local/bin/jishushell-hermes-entry.sh";
+const HERMES_CONTAINER_WORKDIR = "/opt/hermes";
+// Runtime protocol versions this panel knows how to drive. Bumped together
+// with any backward-incompatible change to the shim/panel contract (command
+// line, env vars, entrypoint path, LABEL keys, …). Images advertise their
+// version via `LABEL runtime.protocol.version=N` in Dockerfile.hermes-slim.
+const SUPPORTED_HERMES_PROTOCOL_VERSIONS = [1];
+const HERMES_PROTOCOL_LABEL = "runtime.protocol.version";
+export const HERMES_DEFAULT_GATEWAY_PORT = HERMES_CONTAINER_PORT;
+/**
+ * Read the runtime.protocol.version LABEL from a local image. Returns null
+ * if docker is unreachable, the image isn't present locally, or the label
+ * isn't set — all of which buildRuntime treats as a hard failure because
+ * this panel no longer ships a legacy bind-mount fallback.
+ */
+function readHermesImageProtocolVersion(image) {
+    try {
+        const out = execFileSync("docker", ["inspect", "--format", `{{ index .Config.Labels "${HERMES_PROTOCOL_LABEL}" }}`, image], { timeout: 5_000, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        if (!out)
+            return null;
+        const parsed = Number.parseInt(out, 10);
+        return Number.isNaN(parsed) ? null : parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function assertHermesImageProtocolCompatible(image) {
+    const version = readHermesImageProtocolVersion(image);
+    if (version == null) {
+        throw new Error(`Hermes image ${image} does not advertise runtime.protocol.version. ` +
+            `This panel expects the baked-shim image (${HERMES_DEFAULT_IMAGE} or later). ` +
+            `Re-run POST /api/setup/install/hermes to pull a compatible image.`);
+    }
+    if (!SUPPORTED_HERMES_PROTOCOL_VERSIONS.includes(version)) {
+        throw new Error(`Hermes image ${image} declares runtime.protocol.version=${version}, ` +
+            `but this panel supports ${SUPPORTED_HERMES_PROTOCOL_VERSIONS.join(", ")}. ` +
+            `Upgrade the panel (or pull a compatible Hermes image).`);
+    }
+}
+const HERMES_VERSION_LABEL = "org.opencontainers.image.version";
+const HERMES_MUTABLE_TAG_RE = /:(latest|slim)$/;
+/**
+ * Read `org.opencontainers.image.version` LABEL from a local image.
+ * Returns the version string if it matches `N.N.N...`, null otherwise.
+ */
+function readHermesImageVersion(image) {
+    try {
+        const out = execFileSync("docker", ["inspect", "--format", `{{ index .Config.Labels "${HERMES_VERSION_LABEL}" }}`, image], { timeout: 5_000, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        return /^\d+\.\d+\.\d+/.test(out) ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * If `stored` has a mutable tag (`:latest` / `:slim`), read the bundled
+ * version from the image's LABEL and create a local `:${version}` tag
+ * alias, then drop the mutable source tag. Mirrors the OpenClaw pin in
+ * config.ts:migrateOpenclawImageTagIfNeeded, but uses the LABEL instead
+ * of spawning the container (Hermes images bake the version into the
+ * manifest, OpenClaw's used to lie — see that function's docstring).
+ *
+ * Returns the pinned tag on success, null when nothing was changed.
+ */
+function pinHermesImageToLabeledVersion(stored) {
+    if (!HERMES_MUTABLE_TAG_RE.test(stored))
+        return null;
+    const version = readHermesImageVersion(stored);
+    if (!version)
+        return null;
+    const colonIdx = stored.lastIndexOf(":");
+    const slashIdx = stored.lastIndexOf("/");
+    if (colonIdx <= slashIdx)
+        return null;
+    const pinnedTag = `${stored.slice(0, colonIdx)}:${version}`;
+    if (pinnedTag === stored)
+        return null;
+    try {
+        execFileSync("docker", ["tag", stored, pinnedTag], { timeout: 10_000, stdio: "ignore" });
+    }
+    catch {
+        return null;
+    }
+    try {
+        execFileSync("docker", ["rmi", stored], { timeout: 10_000, stdio: "ignore" });
+    }
+    catch { /* best-effort cleanup */ }
+    return pinnedTag;
+}
+/**
+ * One-shot startup migration for Hermes installs from older panels whose
+ * catalog still stores `:latest` / `:slim`. Silent no-op when the catalog
+ * already holds a pinned tag, when docker is unreachable, or when the
+ * local image lacks the expected LABEL. Called from server.ts onReady.
+ */
+export function migrateHermesImageTagIfNeeded() {
+    const entry = getRuntimeCatalogEntry("hermes");
+    if (!entry || typeof entry.defaultImage !== "string")
+        return;
+    const stored = entry.defaultImage;
+    const pinned = pinHermesImageToLabeledVersion(stored);
+    if (!pinned)
+        return;
+    setRuntimeCatalogEntry("hermes", { ...entry, defaultImage: pinned });
+    console.log(`[hermes] migrated runtime_catalog.hermes.defaultImage: ${stored} → ${pinned}`);
+}
+// ── Nomad primitives (mirrored from nomad-manager.ts so HermesAdapter's
+//    buildNomadTask is self-contained) ─────────────────────────────────
+const DOCKER_IMAGE_RE = /^[a-zA-Z0-9][a-zA-Z0-9\-_.:/@]*$/;
+const MAX_DOCKER_IMAGE_NAME_LEN = 256;
+const VALID_USER_RE = /^[a-z0-9._-]{1,32}$/;
+const DEFAULT_PIDS_LIMIT = 512;
+const MAX_CPU_MHZ = 4000;
+const MAX_MEMORY_MB = 4096;
+const MAX_MEMORY_MAX_MB = 4096;
+const NOMAD_TEMPLATE_UNSAFE_RE = /[{}"\\]/;
+// Matches the shape Feishu issues from `archetype=PersonalAgent` device-flow
+// (cli_ prefix + alphanumerics). Kept narrow on purpose — wider wildcards
+// would accept untrusted strings propagated from the OAuth response body.
+const FEISHU_APP_ID_RE = /^cli_[a-zA-Z0-9]{8,64}$/;
+// iLink Bot IDs are numeric-ish bot handles issued by Tencent. Keep the
+// same 128-char ceiling + charset OpenClaw's adapter uses so invalid
+// payloads from a tampered OAuth response don't become filesystem paths.
+const SAFE_WEIXIN_ACCOUNT_ID_RE = /^[a-zA-Z0-9@._-]{1,128}$/;
+function assertSafeTemplateId(id) {
+    if (NOMAD_TEMPLATE_UNSAFE_RE.test(id)) {
+        throw new Error(`Job ID "${id}" contains characters unsafe for Nomad Template interpolation`);
+    }
+}
+function resolveUidGid(username) {
+    try {
+        if (!VALID_USER_RE.test(username)) {
+            return `${process.getuid()}:${process.getgid()}`;
+        }
+        const passwd = readFileSync("/etc/passwd", "utf-8");
+        const line = passwd.split("\n").find((l) => l.startsWith(username + ":"));
+        if (line) {
+            const parts = line.split(":");
+            const uid = parseInt(parts[2], 10);
+            const gid = parseInt(parts[3], 10);
+            if (!isNaN(uid) && !isNaN(gid))
+                return `${uid}:${gid}`;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return `${process.getuid()}:${process.getgid()}`;
+}
+const DEFAULT_CAPABILITIES = {
+    gateway: {
+        http: true,
+        websocket: false,
+        // "inline" = JishuShell-side chat UI that POSTs to
+        // /api/instances/:id/agent/chat (which forwards to Hermes's own
+        // /v1/chat/completions endpoint with the per-instance API_SERVER_KEY).
+        // NOT the same as "openclaw" which iframes a full OpenClaw gateway UI.
+        chatPanel: "inline",
+    },
+    pairing: {
+        list: true,
+        approve: true,
+        // Capability is `false` until the adapter, routes, and CLI actually
+        // ship revoke / clear-pending surfaces. Declaring them true here
+        // with no backing implementation would mislead the UI and any
+        // external caller into attempting unreachable operations.
+        revoke: false,
+        clearPending: false,
+    },
+    configEditor: "yaml+env",
+    configSchema: false,
+    customProvider: true,
+    pluginInstall: false,
+    skills: true,
+    mcp: true,
+    memory: true,
+    backupRestore: false,
+    usageStats: false,
+    restartlessReload: false,
+    messagingPlatforms: [
+        "feishu",
+        "weixin",
+        "telegram",
+        "discord",
+        "slack",
+        "whatsapp",
+        "signal",
+        "email",
+    ],
+};
+const HERMES_AGENT_HOME_SUBDIRS = [
+    "cron",
+    "sessions",
+    "logs",
+    "hooks",
+    "memories",
+    "skills",
+    "skins",
+    "plans",
+    "workspace",
+    "home",
+];
+const HERMES_AGENT_HOME_NESTED_DIRS = [
+    ["weixin"],
+    ["weixin", "accounts"],
+    ["hermes-overlay"],
+];
+const HERMES_SECRET_ENV_RE = /(KEY|TOKEN|SECRET|PASSWORD)$/i;
+function defaultHermesModelId() {
+    const dp = getPanelConfig().default_provider;
+    const selected = typeof dp?.selectedModelId === "string" ? dp.selectedModelId.trim() : "";
+    if (selected)
+        return selected;
+    const first = Array.isArray(dp?.models) ? dp.models.find((model) => typeof model?.id === "string" && model.id.trim()) : null;
+    return first?.id || "default";
+}
+function defaultHermesConfigYaml() {
+    // Main agent routes through our `jsproxy` custom provider — honest: we
+    // really are an OpenAI-compatible proxy that may sit in front of any
+    // upstream (MiniMax/OpenAI/Anthropic/…). Aliasing to any built-in
+    // provider name (e.g. `minimax`) would leak upstream-specific request
+    // fields to unrelated backends and create surprising breakage.
+    //
+    // Hermes expects `custom_providers` as a YAML list (each entry an
+    // object with a `name` field). See Hermes config schema at
+    // https://hermes-agent.nousresearch.com/docs/user-guide/configuration/
+    const doc = {
+        model: {
+            provider: "jsproxy",
+            default: defaultHermesModelId(),
+        },
+        terminal: {
+            backend: "local",
+        },
+        custom_providers: [
+            {
+                name: "jsproxy",
+                base_url: getProxyBaseUrl(),
+                api_key: "${JSPROXY_API_KEY}",
+            },
+        ],
+    };
+    return YAML.stringify(doc).trimEnd() + "\n";
+}
+function defaultHermesEnvText() {
+    // Hermes refuses to bind 0.0.0.0 without an API_SERVER_KEY (safety gate).
+    // Generate a random 32-byte hex key per instance so unauthenticated access
+    // is impossible even though the host port is published.
+    const apiServerKey = randomBytes(32).toString("hex");
+    return [
+        "API_SERVER_ENABLED=true",
+        "API_SERVER_HOST=0.0.0.0",
+        `API_SERVER_PORT=${HERMES_CONTAINER_PORT}`,
+        `API_SERVER_KEY=${apiServerKey}`,
+        // Main agent provider lookup uses JSPROXY_API_KEY (referenced from
+        // config.yaml custom_providers). Seeded by ensureInstanceProxyToken.
+        "JSPROXY_API_KEY=",
+        // OPENAI_BASE_URL + OPENAI_API_KEY are the standard env vars Hermes's
+        // `auxiliary_client._try_custom_endpoint` reads to auto-discover a
+        // generic OpenAI-compatible endpoint. Pointing them at our jsproxy
+        // stops the auxiliary resolution chain from falling through to the
+        // Nous Portal (which needs cookie auth and emits a 401 warning at
+        // every agent startup). The aux token is a mirror of JSPROXY_API_KEY
+        // populated by syncHermesProxyEnv after ensureInstanceProxyToken runs.
+        `OPENAI_BASE_URL=${getProxyBaseUrl()}`,
+        "OPENAI_API_KEY=",
+        // Allow all users for the smoke path; production deployments should
+        // configure per-platform allowlists via TELEGRAM_ALLOWED_USERS etc.
+        "GATEWAY_ALLOW_ALL_USERS=true",
+        "",
+    ].join("\n");
+}
+/**
+ * After `ensureInstanceProxyToken(instanceId)` writes JSPROXY_API_KEY into
+ * the Hermes .env, mirror the same token into OPENAI_API_KEY and make
+ * sure OPENAI_BASE_URL points at our jsproxy. This gives the
+ * auxiliary_client / vision client / trajectory compressor a valid
+ * OpenAI-compatible endpoint to auto-discover, so startup no longer
+ * emits the `custom/main requested but no endpoint credentials found`
+ * warning + Nous 401. Safe to call repeatedly (idempotent).
+ */
+function syncHermesProxyEnv(instanceId) {
+    const paths = resolveHermesPaths(instanceId);
+    if (!paths.secretEnv || !existsSync(paths.secretEnv))
+        return;
+    const env = parseEnvFileFromText(readFileSync(paths.secretEnv, "utf-8"));
+    const token = env.JSPROXY_API_KEY?.trim();
+    if (!token)
+        return;
+    const updates = {};
+    if (env.OPENAI_API_KEY !== token)
+        updates.OPENAI_API_KEY = token;
+    const expectedBase = getProxyBaseUrl();
+    if (env.OPENAI_BASE_URL !== expectedBase)
+        updates.OPENAI_BASE_URL = expectedBase;
+    if (Object.keys(updates).length === 0)
+        return;
+    updateEnvFile(paths.secretEnv, updates);
+}
+function ensureHermesConfigFiles(paths) {
+    if (!paths.primaryConfig || !existsSync(paths.primaryConfig)) {
+        writeConfigFile(paths.primaryConfig, defaultHermesConfigYaml());
+    }
+    if (!paths.secretEnv || !existsSync(paths.secretEnv)) {
+        writeSecretFile(paths.secretEnv, defaultHermesEnvText());
+    }
+}
+function secretEnvFields(envText) {
+    const env = parseEnvFileFromText(envText);
+    return Object.keys(env)
+        .filter((key) => HERMES_SECRET_ENV_RE.test(key))
+        .map((key) => `env.${key}`);
+}
+function parseEnvFileFromText(envText) {
+    const env = {};
+    for (let line of envText.split("\n")) {
+        line = line.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        if (line.startsWith("export "))
+            line = line.slice(7).trimStart();
+        if (!line.includes("="))
+            continue;
+        const eqIdx = line.indexOf("=");
+        const key = line.slice(0, eqIdx).trim();
+        let value = line.slice(eqIdx + 1).trim();
+        if (!key)
+            continue;
+        if (value.length >= 2 && value[0] === value[value.length - 1] && (value[0] === "'" || value[0] === '"')) {
+            value = value.slice(1, -1);
+        }
+        env[key] = value;
+    }
+    return env;
+}
+function normalizeEnvText(raw) {
+    const trimmed = raw.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trimEnd();
+    return trimmed ? `${trimmed}\n` : "";
+}
+/**
+ * Resolve the hermes instance filesystem layout. Agent-home lives inside the
+ * per-instance directory and is bind-mounted to /opt/data inside the container.
+ */
+export function resolveHermesPaths(instanceId) {
+    const catalog = getRuntimeCatalogEntry("hermes");
+    const homeDirName = catalog?.homeDirName || "agent-home";
+    const resolvedInstanceDir = instanceDir(instanceId);
+    const agentHome = join(resolvedInstanceDir, homeDirName);
+    return {
+        instanceDir: resolvedInstanceDir,
+        agentHome,
+        primaryConfig: join(agentHome, "config.yaml"),
+        secretEnv: join(agentHome, ".env"),
+    };
+}
+function isPrecreatedManagedAppDir(dir) {
+    return existsSync(join(dir, "app-spec.yaml")) && existsSync(join(dir, "manifest.json"));
+}
+class HermesAdapter {
+    agentType = "hermes";
+    displayName = "Hermes Agent";
+    defaultCapabilities = DEFAULT_CAPABILITIES;
+    defaultGatewayPort = HERMES_DEFAULT_GATEWAY_PORT;
+    manifest = {
+        agentType: "hermes",
+        displayName: "Hermes Agent",
+        description: "NousResearch Hermes — Telegram / Discord / Slack / Signal 等 IM 接入",
+        defaultCapabilities: DEFAULT_CAPABILITIES,
+        requiresNomadDocker: true,
+        diskSpaceMB: 5120,
+    };
+    hooks = {
+        /**
+         * Hermes pre-start: validate the docker image exists locally. No config
+         * patches (the shim bootstraps `.env` / `config.yaml` on first run)
+         * and no Nomad Variables template (Hermes reads keys from the
+         * bind-mounted `.env`, not from secrets).
+         */
+        onBeforeStart: async (args) => {
+            const catalog = getRuntimeCatalogEntry("hermes");
+            const image = catalog?.defaultImageDigest
+                || catalog?.defaultImage;
+            if (!image) {
+                throw new Error("Hermes runtime is not installed. Run POST /api/setup/install/hermes first.");
+            }
+            if (!DOCKER_IMAGE_RE.test(image) || image.length > MAX_DOCKER_IMAGE_NAME_LEN) {
+                throw new Error(`Invalid Hermes docker image: "${image}"`);
+            }
+            try {
+                execFileSync("docker", ["image", "inspect", image], {
+                    timeout: 10000,
+                    stdio: "ignore",
+                });
+            }
+            catch {
+                throw new Error(`Hermes image ${image} is not present locally. ` +
+                    `Run POST /api/setup/install/hermes to pull it.`);
+            }
+            // Idempotent migration: pre-alias Hermes instances created before the
+            // OPENAI_* env switch still carry only JSPROXY_API_KEY. Every start
+            // mirrors that token into OPENAI_API_KEY and pins OPENAI_BASE_URL at
+            // the jsproxy so auxiliary_client auto-discovery stops hitting Nous.
+            // Safe to re-run on every restart.
+            try {
+                syncHermesProxyEnv(args.instanceId);
+            }
+            catch { /* best-effort */ }
+        },
+    };
+    /**
+     * Full Hermes instance bootstrap, physically migrated from the legacy
+     * `instance-manager.createHermesInstance()`. The framework routes layer
+     * calls this uniformly via `getAdapter(agentType).createInstance(args)` —
+     * instance-manager no longer owns any Hermes business logic.
+     *
+     * Rejection cases (all raise `InstanceCreationRejected`):
+     *   - panel.service_manager !== "nomad"
+     *   - panel.nomad_driver !== "docker"
+     *   - panel.runtime_catalog.hermes not present (install not run yet)
+     */
+    async createInstance(args) {
+        if (args.cloneFrom || args.agentHome || args.cloneOptions) {
+            throw new Error(`Hermes does not support clone_from / agent_home / clone_options — ` +
+                `these are OpenClaw-specific create fields.`);
+        }
+        const { instanceId, name, description = "" } = args;
+        const d = instanceDir(instanceId);
+        const metaPath = instanceMetaPath(instanceId);
+        if (existsSync(metaPath))
+            throw new Error(`Instance '${instanceId}' already exists`);
+        if (existsSync(d) && !isPrecreatedManagedAppDir(d)) {
+            throw new Error(`Instance '${instanceId}' already exists`);
+        }
+        // 1. Prereq validation (structured reject with hint)
+        const panel = getPanelConfig();
+        const svcMgr = panel.service_manager || "nomad";
+        const driver = panel.nomad_driver || "docker";
+        if (svcMgr !== "nomad") {
+            throw new InstanceCreationRejected({
+                code: "RUNTIME_REQUIRES_NOMAD_DOCKER",
+                requestedKind: "hermes",
+                currentServiceManager: svcMgr,
+                currentNomadDriver: driver,
+                hint: `Hermes requires service_manager="nomad" (current: "${svcMgr}"). ` +
+                    `Switch in panel.json or via settings before creating a Hermes instance.`,
+            });
+        }
+        if (driver !== "docker") {
+            throw new InstanceCreationRejected({
+                code: "RUNTIME_REQUIRES_NOMAD_DOCKER",
+                requestedKind: "hermes",
+                currentServiceManager: svcMgr,
+                currentNomadDriver: driver,
+                hint: `Hermes requires nomad_driver="docker" (current: "${driver}").`,
+            });
+        }
+        // Catalog must exist (populated by setup-manager.installHermes)
+        const catalog = panel.runtime_catalog?.hermes;
+        if (!catalog || !catalog.defaultImage) {
+            throw new InstanceCreationRejected({
+                code: "RUNTIME_PREREQ_MISSING",
+                requestedKind: "hermes",
+                currentServiceManager: svcMgr,
+                currentNomadDriver: driver,
+                hint: `Hermes runtime is not installed. Run POST /api/setup/install/hermes first.`,
+            });
+        }
+        // 2. Lay out filesystem
+        ensureDirContainer(d);
+        try {
+            const parentGid = statSync(dirname(d)).gid;
+            chownSync(d, -1, parentGid);
+        }
+        catch {
+            /* best effort */
+        }
+        const paths = await this.createInitialLayout({ instanceId, name, description });
+        // 3. Allocate gateway host port (kind-agnostic framework primitive)
+        const portAlloc = await allocateGatewayPort(instanceId, HERMES_DEFAULT_GATEWAY_PORT);
+        // 4. Build runtime spec, inject allocated port into ports[] / env / health
+        const runtimeSpec = await this.buildRuntime(instanceId);
+        if (runtimeSpec.ports && runtimeSpec.ports.length > 0) {
+            runtimeSpec.ports = runtimeSpec.ports.map((port, idx) => idx === 0
+                ? { ...port, hostPort: portAlloc.port, containerPort: portAlloc.port }
+                : port);
+        }
+        if (runtimeSpec.env && runtimeSpec.env.API_SERVER_PORT !== undefined) {
+            runtimeSpec.env.API_SERVER_PORT = String(portAlloc.port);
+        }
+        if (runtimeSpec.health && typeof runtimeSpec.health === "object" && runtimeSpec.health.port != null) {
+            runtimeSpec.health = { ...runtimeSpec.health, port: portAlloc.port };
+        }
+        // python-dotenv override=True can overwrite docker -e env vars, so the
+        // allocated port must also be rewritten into the .env file.
+        if (paths.secretEnv && existsSync(paths.secretEnv)) {
+            try {
+                updateEnvFile(paths.secretEnv, { API_SERVER_PORT: String(portAlloc.port) });
+            }
+            catch (e) {
+                console.warn(`[hermes] failed to patch .env API_SERVER_PORT for ${instanceId}: ${e.message}`);
+            }
+        }
+        // 5. Persist instance.json
+        const meta = {
+            id: instanceId,
+            name,
+            description,
+            agentType: "hermes",
+            paths: {
+                instanceDir: paths.instanceDir,
+                agentHome: paths.agentHome,
+                primaryConfig: paths.primaryConfig,
+                secretEnv: paths.secretEnv,
+            },
+            runtime: runtimeSpec,
+            created_at: new Date().toISOString(),
+        };
+        // Propagate panel.default_provider → instance.json.x-jishushell.proxy.upstream
+        // so the LLM proxy's deriveUpstreamConfig can find this Hermes instance's
+        // upstream. Hermes has no openclaw.json, so the upstream block is inlined
+        // into instance.json instead.
+        const dp = panel.default_provider;
+        if (dp && typeof dp === "object" && dp.providerId && !dp.skipped) {
+            const modelList = Array.isArray(dp.models)
+                ? dp.models
+                    .map((m) => ({
+                    id: String(m?.id ?? ""),
+                    name: String(m?.name ?? m?.id ?? ""),
+                    contextWindow: Number(m?.contextWindow) || 128000,
+                }))
+                    .filter((m) => m.id)
+                : [];
+            const selectedModelId = String(dp.selectedModelId || modelList[0]?.id || "");
+            if (selectedModelId && modelList.every((m) => m.id !== selectedModelId)) {
+                modelList.unshift({ id: selectedModelId, name: selectedModelId, contextWindow: 128000 });
+            }
+            meta["x-jishushell"] = {
+                proxy: {
+                    upstream: {
+                        providerId: String(dp.providerId),
+                        baseUrl: String(dp.baseUrl || ""),
+                        api: String(dp.api || "openai-completions"),
+                        authHeader: dp.authHeader === true,
+                        headers: {},
+                        models: modelList,
+                        selectedModelId,
+                        apiKey: "",
+                        hasApiKey: !!dp.apiKey,
+                        clearApiKey: false,
+                    },
+                },
+            };
+        }
+        try {
+            safeWriteJson(instanceMetaPath(instanceId), meta);
+            try {
+                ensureInstanceProxyToken(instanceId);
+                syncHermesProxyEnv(instanceId);
+            }
+            catch (e) {
+                console.warn(`[hermes] failed to seed proxy token for ${instanceId}: ${e.message}`);
+            }
+            // If running as root, hand ownership of created files to service user
+            const svcUser = resolveServiceUser();
+            if (svcUser) {
+                try {
+                    execFileSync("chown", ["-R", `${svcUser.uid}:${svcUser.gid}`, d], { timeout: 10_000 });
+                }
+                catch (e) {
+                    console.warn(`[hermes] chown for ${instanceId} failed:`, e.message);
+                }
+            }
+            if (portAlloc.skipped.length > 0) {
+                meta.port_allocation = {
+                    assigned: portAlloc.port,
+                    requested: HERMES_DEFAULT_GATEWAY_PORT,
+                    reason: "default_busy",
+                    skipped: portAlloc.skipped,
+                };
+            }
+            return meta;
+        }
+        finally {
+            releasePendingPort(portAlloc.port);
+        }
+    }
+    async createInitialLayout(ctx) {
+        const paths = resolveHermesPaths(ctx.instanceId);
+        mkdirSync(paths.agentHome, { recursive: true });
+        for (const sub of HERMES_AGENT_HOME_SUBDIRS) {
+            mkdirSync(join(paths.agentHome, sub), { recursive: true });
+        }
+        for (const segments of HERMES_AGENT_HOME_NESTED_DIRS) {
+            mkdirSync(join(paths.agentHome, ...segments), { recursive: true });
+        }
+        ensureHermesConfigFiles(paths);
+        return paths;
+    }
+    async buildRuntime(instanceId) {
+        const catalog = getRuntimeCatalogEntry("hermes");
+        if (!catalog) {
+            throw new Error("Hermes runtime is not installed. Run POST /api/setup/install/hermes first.");
+        }
+        // Prefer digest over tag for image pinning per §32.1. When installHermes
+        // captured a digest it is stored alongside the tag; adapter favors digest.
+        const image = catalog.defaultImageDigest
+            || catalog.defaultImage;
+        if (!image) {
+            throw new Error("Hermes runtime catalog missing defaultImage");
+        }
+        // Enforce the runtime protocol contract. The baked-shim image carries
+        // `runtime.protocol.version=1`; an image without the label pre-dates
+        // the shim bake and must be re-pulled so its /usr/local/bin/... entry
+        // script exists. Absence is a hard failure now rather than a warning
+        // because we have already removed the legacy bind-mount fallback.
+        assertHermesImageProtocolCompatible(image);
+        const paths = resolveHermesPaths(instanceId);
+        // Migrate pre-alias instances (created before the switch to
+        // provider:minimax) in-place: mirror JSPROXY_API_KEY into MINIMAX_API_KEY
+        // and pin MINIMAX_BASE_URL at the jsproxy. Idempotent — no-op on
+        // instances already aligned with the new template.
+        try {
+            syncHermesProxyEnv(instanceId);
+        }
+        catch { /* best-effort */ }
+        // §32.1.3: baseline mode is detected by ABSENCE of JISHUSHELL_HERMES_SOURCE_REF.
+        // We deliberately do NOT inject this env here. Only the (future) upgrade CLI
+        // populates it after a per-instance overlay build.
+        const env = {
+            API_SERVER_ENABLED: "true",
+            API_SERVER_HOST: "0.0.0.0",
+            API_SERVER_PORT: String(HERMES_CONTAINER_PORT),
+            HERMES_UID: String(process.getuid?.() ?? 1000),
+            HERMES_GID: String(process.getgid?.() ?? 1000),
+        };
+        const resources = catalog.resources && typeof catalog.resources === "object"
+            ? {
+                CPU: Number(catalog.resources.CPU) || 1000,
+                MemoryMB: Number(catalog.resources.MemoryMB) || 1024,
+                MemoryMaxMB: catalog.resources.MemoryMaxMB != null
+                    ? Number(catalog.resources.MemoryMaxMB)
+                    : undefined,
+            }
+            : { CPU: 1000, MemoryMB: 1024 };
+        return {
+            image,
+            // Invoke the shim via /bin/bash explicitly instead of execve'ing the
+            // script file directly. Debian-based containers always ship /bin/bash,
+            // and this bypasses EACCES on execve when bind-mounted script files
+            // occasionally lose their exec bit through the container runtime.
+            command: "/bin/bash",
+            args: [HERMES_CONTAINER_SHIM, "gateway", "run"],
+            cwd: HERMES_CONTAINER_WORKDIR,
+            user: "root", // shim exec-gosu-downgrades to hermes uid
+            env,
+            envFiles: paths.secretEnv ? [paths.secretEnv] : undefined,
+            resources,
+            volumes: [
+                { hostPath: paths.agentHome, containerPath: HERMES_CONTAINER_HOME, mode: "rw" },
+                // Shim no longer bind-mounted — it is baked at HERMES_CONTAINER_SHIM
+                // in the image (see Dockerfile.hermes-slim). Any remaining legacy
+                // shimPath in runtime_catalog is scrubbed by migrateHermesShimOut.
+            ],
+            ports: [
+                {
+                    name: "gateway",
+                    containerPort: HERMES_CONTAINER_PORT,
+                    hostPort: 0, // allocated by instance-manager
+                    visibility: "external",
+                },
+            ],
+            health: {
+                type: "http",
+                path: "/health",
+                port: HERMES_CONTAINER_PORT,
+            },
+        };
+    }
+    /**
+     * Hermes has no `openclaw.json` — it stores upstream metadata directly
+     * on instance.json under `x-jishushell`. Return a synthetic stub
+     * containing just that block so the LLM proxy's
+     * `deriveUpstreamConfig()` finds what it needs.
+     */
+    getNativeConfig(instanceId) {
+        return this.getStoredNativeConfig(instanceId);
+    }
+    getStoredNativeConfig(instanceId) {
+        // Lazy import to avoid pulling the full instance-manager into top-level
+        // static graph (adapters reach back for framework primitives on demand).
+        try {
+            const req = createRequire(import.meta.url);
+            const im = req("../../instance-manager.js");
+            const meta = im.getInstance(instanceId);
+            if (!meta)
+                return null;
+            return { "x-jishushell": meta["x-jishushell"] || {} };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Persist the `x-jishushell` meta block to instance.json. Hermes's user-
+     * facing config lives in yaml+env (editable via `writeConfig`), so this
+     * hook is scoped to the meta block only — any other keys in the payload
+     * are ignored intentionally.
+     *
+     * Called by `llm-proxy.saveInstanceConfig` when the editor saves a
+     * per-instance provider override. By implementing the same
+     * `saveNativeConfig(instanceId, {x-jishushell})` contract OpenClaw uses,
+     * Hermes piggy-backs on the shared API key encryption + rollback flow.
+     */
+    saveNativeConfig(instanceId, config) {
+        const xJishushell = config?.["x-jishushell"];
+        if (!xJishushell || typeof xJishushell !== "object")
+            return false;
+        try {
+            const req = createRequire(import.meta.url);
+            const im = req("../../instance-manager.js");
+            const metaPath = im.instanceMetaPath(instanceId);
+            if (!existsSync(metaPath))
+                return false;
+            const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+            meta["x-jishushell"] = xJishushell;
+            safeWriteJson(metaPath, meta);
+            return true;
+        }
+        catch (e) {
+            console.warn(`[hermes] saveNativeConfig failed for ${instanceId}: ${e.message}`);
+            return false;
+        }
+    }
+    async getRuntimeVersion(instanceId) {
+        const catalog = getRuntimeCatalogEntry("hermes");
+        const digest = catalog?.defaultImageDigest;
+        // Read per-instance SOURCE_REF from instance.json without introducing
+        // a runtime→instance-manager cycle: late require to break the chain.
+        // If the env isn't set, we are in baseline mode.
+        let ref;
+        try {
+            const { getInstance } = await import("../../instance-manager.js");
+            const meta = getInstance(instanceId);
+            const envRef = meta?.runtime?.env?.JISHUSHELL_HERMES_SOURCE_REF;
+            if (typeof envRef === "string" && envRef.trim())
+                ref = envRef.trim();
+        }
+        catch {
+            // best-effort: if instance lookup fails, report baseline
+        }
+        return {
+            agentType: "hermes",
+            ref,
+            digest,
+            mode: ref ? "overlay" : "baseline",
+        };
+    }
+    async getConfigMeta(instanceId) {
+        const doc = await this.readConfig(instanceId);
+        return {
+            agentType: "hermes",
+            format: "yaml+env",
+            schemaId: "hermes/v1",
+            capabilities: this.defaultCapabilities,
+            secretFields: doc.format === "yaml+env" ? secretEnvFields(doc.env) : [],
+            runtimeVersion: await this.getRuntimeVersion(instanceId),
+        };
+    }
+    async readConfig(instanceId) {
+        const paths = resolveHermesPaths(instanceId);
+        ensureHermesConfigFiles(paths);
+        // Surface the instance.json `x-jishushell` meta block alongside yaml/env
+        // so the Config form can round-trip per-instance upstream provider
+        // overrides through the same ConfigDocument shape OpenClaw uses.
+        const xJishushell = this.getStoredNativeConfig(instanceId)?.["x-jishushell"];
+        const doc = {
+            format: "yaml+env",
+            yaml: readFileSync(paths.primaryConfig, "utf-8"),
+            env: readFileSync(paths.secretEnv, "utf-8"),
+        };
+        if (xJishushell && typeof xJishushell === "object") {
+            doc["x-jishushell"] = xJishushell;
+        }
+        return doc;
+    }
+    async writeConfig(instanceId, doc) {
+        if (doc.format !== "yaml+env") {
+            throw new Error(`Hermes config requires format="yaml+env", got "${doc.format}"`);
+        }
+        YAML.parse(doc.yaml);
+        const envText = normalizeEnvText(doc.env);
+        parseEnvFileFromText(envText);
+        const paths = resolveHermesPaths(instanceId);
+        ensureHermesConfigFiles(paths);
+        // Atomicity: the x-jishushell save path (via llm-proxy.saveInstanceConfig)
+        // can reject for reasons we only learn after some I/O — missing upstream
+        // API key, provider.env write failure, etc. Snapshot the current YAML/ENV
+        // contents BEFORE overwriting them so we can restore on failure and
+        // callers never see a half-applied save (new YAML on disk + rejected
+        // x-jishushell would leave the instance in a dirty state).
+        const priorYaml = readFileSync(paths.primaryConfig, "utf-8");
+        const priorEnv = readFileSync(paths.secretEnv, "utf-8");
+        writeConfigFile(paths.primaryConfig, doc.yaml.trimEnd() + "\n");
+        writeSecretFile(paths.secretEnv, envText);
+        // If the caller included per-instance upstream metadata, route it
+        // through the shared llm-proxy save flow — that path owns API key
+        // encryption, provider.env persistence, rollback on secret failures,
+        // and upstream cache invalidation. We deliberately reuse it instead
+        // of duplicating the logic here so Hermes and OpenClaw agree bit-
+        // for-bit on how per-instance provider config is stored.
+        const xJishushell = doc["x-jishushell"];
+        if (xJishushell && typeof xJishushell === "object") {
+            try {
+                const { saveInstanceConfig } = await import("../../llm-proxy/index.js");
+                await saveInstanceConfig(instanceId, { "x-jishushell": xJishushell });
+            }
+            catch (e) {
+                try {
+                    writeConfigFile(paths.primaryConfig, priorYaml);
+                    writeSecretFile(paths.secretEnv, priorEnv);
+                }
+                catch (rollbackErr) {
+                    console.error(`[hermes] CRITICAL: YAML/ENV rollback failed for ${instanceId}:`, rollbackErr?.message || rollbackErr);
+                }
+                throw e;
+            }
+        }
+        return this.readConfig(instanceId);
+    }
+    /**
+     * Persist Feishu/Lark OAuth credentials returned by the device-flow
+     * endpoints (handled by openclaw-routes.ts but adapter-agnostic at the
+     * persistence layer — framework code dispatches here via
+     * `instance-manager.saveFeishuCredentials`).
+     *
+     * Hermes reads platform config from two places on every gateway start:
+     *   - `config.yaml` → `platforms.feishu.enabled` + `platforms.feishu.extra.*`
+     *   - `.env`         → `FEISHU_APP_ID`, `FEISHU_APP_SECRET`
+     *
+     * We write into BOTH. The YAML holds structural config (enabled flag,
+     * connection mode, domain) and references the secret env vars via
+     * `${...}` interpolation. That way the YAML can be backed up / shared
+     * without leaking credentials, and the real secrets live next to the
+     * .env the user already edits.
+     */
+    saveFeishuCredentials(instanceId, creds) {
+        if (!FEISHU_APP_ID_RE.test(creds.appId)) {
+            throw new Error(`Invalid Feishu appId format: expected cli_<alnum> (got "${creds.appId}")`);
+        }
+        if (!creds.appSecret || typeof creds.appSecret !== "string" || creds.appSecret.length < 4) {
+            throw new Error("Invalid Feishu appSecret: must be a non-empty string");
+        }
+        const domainName = creds.domain === "lark" ? "lark" : "feishu";
+        const paths = resolveHermesPaths(instanceId);
+        ensureHermesConfigFiles(paths);
+        // Merge into existing YAML rather than overwrite — the user may have
+        // customised model/terminal/custom_providers/etc. via the Config tab.
+        const currentYaml = readFileSync(paths.primaryConfig, "utf-8");
+        const parsed = YAML.parse(currentYaml) || {};
+        parsed.platforms = parsed.platforms || {};
+        const prior = parsed.platforms.feishu || {};
+        const priorExtra = prior.extra || {};
+        parsed.platforms.feishu = {
+            ...prior,
+            enabled: true,
+            extra: {
+                ...priorExtra,
+                // Env interpolation: hermes expands ${FOO} at load time against
+                // the process env, which Docker populates from agent-home/.env.
+                app_id: "${FEISHU_APP_ID}",
+                app_secret: "${FEISHU_APP_SECRET}",
+                domain_name: domainName,
+                connection_mode: priorExtra.connection_mode || "websocket",
+            },
+        };
+        writeConfigFile(paths.primaryConfig, YAML.stringify(parsed).trimEnd() + "\n");
+        // Env merge preserves unrelated keys (API_SERVER_KEY, JSPROXY_API_KEY, …).
+        updateEnvFile(paths.secretEnv, {
+            FEISHU_APP_ID: creds.appId,
+            FEISHU_APP_SECRET: creds.appSecret,
+        });
+        console.log(`[hermes] Feishu credentials saved for ${instanceId}, domain=${domainName}`);
+    }
+    /**
+     * Persist Weixin (个人微信) credentials returned by iLink Bot API's QR
+     * login flow. Called from the shared `/api/instances/:id/weixin/login`
+     * handler via `instance-manager.saveWeixinCredentials` → adapter dispatch.
+     *
+     * Upstream Hermes's `WeixinAdapter.__init__` scans
+     * `$HERMES_HOME/weixin/accounts/*.json` at startup and auto-connects every
+     * account file it finds, so the handshake we persist here is everything
+     * the runtime needs to come online after an instance restart. The JSON
+     * shape is pinned to upstream's `save_weixin_account` helper:
+     * `{token, base_url, user_id, saved_at}` with mode 0600.
+     *
+     * We also flip `platforms.weixin.enabled: true` in the instance's
+     * config.yaml so the gateway actually tries to connect the adapter on
+     * next start (without it, hermes ignores the weixin folder entirely).
+     */
+    saveWeixinCredentials(instanceId, creds) {
+        if (!creds.accountId || !SAFE_WEIXIN_ACCOUNT_ID_RE.test(creds.accountId)) {
+            throw new Error(`Invalid WeChat accountId: must be 1-128 chars of [a-zA-Z0-9@._-], got "${creds.accountId}"`);
+        }
+        if (!creds.token || typeof creds.token !== "string" || creds.token.length < 4) {
+            throw new Error("Invalid WeChat bot token: must be a non-empty string");
+        }
+        const home = resolveHermesPaths(instanceId).agentHome;
+        const accountsDir = join(home, "weixin", "accounts");
+        ensureDirContainer(accountsDir);
+        // Match upstream `save_weixin_account` exactly — WeixinAdapter reloads
+        // this file at connect time so we can't improvise the field names.
+        const payload = {
+            token: creds.token,
+            base_url: creds.baseUrl,
+            user_id: creds.userId || "",
+            saved_at: new Date().toISOString().replace(/\.\d+Z$/, "Z"),
+        };
+        const accountPath = join(accountsDir, `${creds.accountId}.json`);
+        safeWriteJson(accountPath, payload);
+        try {
+            chmodSync(accountPath, 0o600);
+        }
+        catch { /* best effort */ }
+        // Hermes runs as the `hermes` user inside the container; on the host
+        // the bind-mount is owned by the panel service user. `ensureDirContainer`
+        // already handles ownership for the dir — file-level chown is a noop
+        // in the container path and not available as a shared helper here, so
+        // we rely on the directory permissions inheriting to the new file.
+        // Enable platforms.weixin in config.yaml (merge, preserve other keys).
+        // Upstream WeixinAdapter resolves startup credentials in this order at
+        // init time (weixin.py:1066-1067):
+        //     token      = config.token || extra.token || env WEIXIN_TOKEN
+        //     account_id = extra.account_id           || env WEIXIN_ACCOUNT_ID
+        // The per-account JSON we wrote above is state storage (refresh
+        // cursor, context token cache), not the startup seed — without the
+        // YAML + env entries below the adapter crashes with
+        // "WEIXIN_TOKEN is required".
+        const paths = resolveHermesPaths(instanceId);
+        ensureHermesConfigFiles(paths);
+        const currentYaml = readFileSync(paths.primaryConfig, "utf-8");
+        const parsed = YAML.parse(currentYaml) || {};
+        parsed.platforms = parsed.platforms || {};
+        const prior = parsed.platforms.weixin || {};
+        const priorExtra = prior.extra || {};
+        parsed.platforms.weixin = {
+            ...prior,
+            enabled: true,
+            extra: {
+                ...priorExtra,
+                // Same env-interpolation convention used by the feishu save path:
+                // YAML references ${VAR}, the real value lives in agent-home/.env.
+                account_id: "${WEIXIN_ACCOUNT_ID}",
+                token: "${WEIXIN_TOKEN}",
+            },
+        };
+        writeConfigFile(paths.primaryConfig, YAML.stringify(parsed).trimEnd() + "\n");
+        updateEnvFile(paths.secretEnv, {
+            WEIXIN_ACCOUNT_ID: creds.accountId,
+            WEIXIN_TOKEN: creds.token,
+        });
+        console.log(`[hermes] WeChat credentials saved for ${instanceId}, account=${creds.accountId}`);
+    }
+    /**
+     * List connected WeChat accounts for an instance. Backs the panel UI's
+     * "Connected Accounts" section in WeixinLoginPanel. Tolerates a missing
+     * directory (returns empty) and skips sidecar files the runtime writes
+     * alongside account records (sync buffers + context-token caches).
+     */
+    getWeixinAccounts(instanceId) {
+        const home = resolveHermesPaths(instanceId).agentHome;
+        if (!home)
+            return [];
+        const accountsDir = join(home, "weixin", "accounts");
+        if (!existsSync(accountsDir))
+            return [];
+        const results = [];
+        for (const f of readdirSync(accountsDir)) {
+            if (!f.endsWith(".json"))
+                continue;
+            // Skip sidecar files written by the runtime (sync cursor + context
+            // token cache). They share the accounts dir but aren't accounts.
+            if (f.endsWith(".sync.json") || f.endsWith(".context-tokens.json"))
+                continue;
+            try {
+                const data = JSON.parse(readFileSync(join(accountsDir, f), "utf-8"));
+                results.push({
+                    accountId: f.replace(/\.json$/, ""),
+                    userId: typeof data.user_id === "string" ? data.user_id : undefined,
+                    savedAt: typeof data.saved_at === "string" ? data.saved_at : undefined,
+                });
+            }
+            catch {
+                /* malformed account file — skip */
+            }
+        }
+        return results;
+    }
+    /**
+     * Build the Nomad docker task spec directly from the persisted RuntimeSpec.
+     * Physically migrated from `nomad-manager.buildHermesTaskDocker`. Framework
+     * code now calls `getAdapter(agentType).buildNomadTask(id)` uniformly.
+     */
+    async buildNomadTask(instanceId) {
+        const { getInstanceRuntime } = await import("../../instance-manager.js");
+        const safeJobId = `${this.nomadJobPrefix}${instanceId}`;
+        assertSafeTemplateId(safeJobId);
+        const spec = getInstanceRuntime(instanceId);
+        if (!spec || typeof spec !== "object") {
+            throw new Error(`Hermes instance ${instanceId} has no persisted runtime spec`);
+        }
+        if (!spec.image || typeof spec.image !== "string") {
+            throw new Error(`Hermes runtime spec missing image for ${instanceId}`);
+        }
+        if (!DOCKER_IMAGE_RE.test(spec.image) || spec.image.length > MAX_DOCKER_IMAGE_NAME_LEN) {
+            throw new Error(`Invalid Hermes docker image: "${spec.image}"`);
+        }
+        const volumes = [];
+        for (const vol of (spec.volumes || [])) {
+            volumes.push(`${vol.hostPath}:${vol.containerPath}:${vol.mode}`);
+        }
+        const ports = Array.isArray(spec.ports) ? spec.ports : [];
+        const gatewayPort = Number(ports[0]?.hostPort) || 0;
+        if (!gatewayPort) {
+            throw new Error(`Hermes instance ${instanceId} has no allocated gateway hostPort`);
+        }
+        const resourcesRaw = (spec.resources || {});
+        const requestedCpu = Math.max(1, Math.min(Number(resourcesRaw.CPU) || 1000, MAX_CPU_MHZ));
+        const requestedMem = Math.max(1, Math.min(Number(resourcesRaw.MemoryMB) || 1024, MAX_MEMORY_MB));
+        const requestedMemMax = Math.min(Number(resourcesRaw.MemoryMaxMB ?? requestedMem), MAX_MEMORY_MAX_MB);
+        // Start non-root directly as the host's uid:gid — aligns with OpenClaw's
+        // security model (openclaw.ts:1404) and makes `cap_drop: ["ALL"]` viable
+        // without any cap_add. The entrypoint shim detects non-root via
+        // `if [ "$(id -u)" = "0" ]; then ... gosu ...; fi` and cleanly falls
+        // through to the venv-activation branch when started this way.
+        //
+        // Bind-mounted /opt/data on the host is already owned by this uid:gid
+        // (jishushell creates instance dirs as the panel user), so mkdir/cp/chmod
+        // inside the shim's non-root branch all succeed without CAP_CHOWN.
+        const hostUid = process.getuid?.() ?? 1000;
+        const hostGid = process.getgid?.() ?? 1000;
+        return {
+            Name: "gateway",
+            Driver: "docker",
+            User: `${hostUid}:${hostGid}`,
+            Config: {
+                image: spec.image,
+                force_pull: false,
+                entrypoint: [spec.command],
+                args: [...(spec.args || [])],
+                work_dir: spec.cwd || HERMES_CONTAINER_WORKDIR,
+                volumes,
+                extra_hosts: ["host.docker.internal:host-gateway"],
+                // No cap_add — starting as non-root uid:gid means the shim's
+                // privilege-drop ritual (usermod / chown / gosu) is skipped
+                // entirely. `security_opt: no-new-privileges` prevents the
+                // unprivileged process from regaining any caps via setuid
+                // binaries. If browser_navigate's chromium sandbox fails, fix
+                // it with `--no-sandbox` in Dockerfile.hermes-agent rather
+                // than adding CAP_SYS_ADMIN here.
+                cap_drop: ["ALL"],
+                security_opt: ["no-new-privileges"],
+                pids_limit: DEFAULT_PIDS_LIMIT,
+                readonly_rootfs: false,
+                //
+                // `init: true` asks docker to run docker-init (a tini fork) as PID 1.
+                // This is the authoritative zombie-reaper for our containers — the
+                // image itself deliberately does NOT set ENTRYPOINT, so anyone who
+                // runs the image outside of Nomad must pass `--init` themselves.
+                // Without a real init, the chromium / agent-browser subprocess
+                // zombies never get reaped and we hit `pids_limit` after ~50
+                // browser_navigate calls.
+                //
+                // `shm_size` raises /dev/shm from docker's 64 MB default. Chromium
+                // uses shared memory for render/GPU buffers; 64 MB SIGBUSes on any
+                // JS-heavy page. 1 GB matches Chrome's default heap budget and is
+                // what Playwright / Puppeteer docker guides recommend.
+                //
+                init: true,
+                shm_size: 1073741824,
+                mounts: [{ type: "tmpfs", target: "/tmp", tmpfs_options: { size: 536870912 } }],
+            },
+            Env: { ...spec.env },
+            Resources: {
+                CPU: requestedCpu,
+                MemoryMB: requestedMem,
+                MemoryMaxMB: requestedMemMax,
+                Networks: [{ ReservedPorts: [{ Label: "gateway", Value: gatewayPort }] }],
+            },
+            LogConfig: { MaxFiles: 3, MaxFileSizeMB: 10 },
+        };
+    }
+    /**
+     * Rewrite a persisted Hermes runtime spec to use a new host port.
+     * Hermes persists its port in `ports[0].hostPort/containerPort`,
+     * `env.API_SERVER_PORT`, and `health.port`.
+     */
+    reallocateRuntimePort(runtime, newPort) {
+        if (Array.isArray(runtime.ports) && runtime.ports.length > 0) {
+            runtime.ports = runtime.ports.map((port, idx) => idx === 0 ? { ...port, hostPort: newPort, containerPort: newPort } : port);
+        }
+        if (runtime.env && runtime.env.API_SERVER_PORT !== undefined) {
+            runtime.env.API_SERVER_PORT = String(newPort);
+        }
+        if (runtime.health && typeof runtime.health === "object" && runtime.health.port != null) {
+            runtime.health = { ...runtime.health, port: newPort };
+        }
+    }
+    // Each adapter owns its own Nomad job prefix, derived from the agent
+    // type (`hermes-<id>`, `openclaw-<id>`, …). Any new runtime should
+    // declare its own prefix here so job IDs are self-describing and
+    // multiple runtime kinds never collide in the Nomad Raft namespace.
+    nomadJobPrefix = "hermes-";
+    migrateStartup() {
+        migrateHermesImageTagIfNeeded();
+    }
+    // Inline chat forwarder dispatch — framework reads this from
+    // `routes/instances.ts:/api/instances/:id/agent/chat`. Declaring the
+    // descriptor (rather than hardcoding API_SERVER_KEY in the route) lets
+    // other OpenAI-compat agents plug in without touching framework code.
+    inlineChatDescriptor = {
+        apiKeyEnvVar: "API_SERVER_KEY",
+        endpointPath: "/v1/chat/completions",
+    };
+    async buildPairingListCommand(_instanceId) {
+        return ["hermes", "pairing", "list"];
+    }
+    async buildPairingApproveCommand(_instanceId, input) {
+        return ["hermes", "pairing", "approve", input.channel, input.code];
+    }
+    // ── §32.2.4 runtime install (aligned with OpenClaw pull flow) ─────────
+    //
+    // Pull-only flow — no local Dockerfile build fallback. Hermes ships as
+    // a ~2.4 GB pre-built image on GHCR; building from upstream source on
+    // a Raspberry Pi would take 20+ minutes and almost always fails on
+    // resource-constrained hardware. If the pull fails we return a clear
+    // error so the user can fix network / registry access rather than
+    // silently burning an hour on a futile source build.
+    //
+    // Steps:
+    //   1. docker image inspect — reuse existing local image if present
+    //   2. docker pull ghcr.io/x-aijishu/hermes-runtime:latest
+    //   3. capture RepoDigest for digest pinning (best-effort)
+    //   4. Copy templates/hermes-entrypoint.sh to ~/.jishushell/runtimes/hermes/
+    //   5. Write runtime catalog entry into panel.json
+    async installRuntime(_opts) {
+        const task = createTask("hermes");
+        try {
+            await this.prepareHermesWithTask(task);
+            if (task.status === "error") {
+                return {
+                    ok: false,
+                    message: "Hermes installation failed",
+                    taskId: task.id,
+                };
+            }
+            return {
+                ok: true,
+                message: "Hermes runtime installed",
+                taskId: task.id,
+            };
+        }
+        catch (e) {
+            emitTask(task, { type: "error", message: `Hermes 安装失败: ${e.message}` });
+            task.status = "error";
+            return {
+                ok: false,
+                message: "Hermes installation failed",
+                error: e.message,
+                taskId: task.id,
+            };
+        }
+    }
+    /**
+     * Non-blocking variant — returns a task id immediately and runs the
+     * install in the background. Matches OpenClaw's startBuildRuntimeImage.
+     */
+    startInstallRuntime(_opts) {
+        const task = createTask("hermes");
+        this.prepareHermesWithTask(task).catch((e) => {
+            // Mirror errors to stderr so post-mortem via journalctl works.
+            // Task events live in memory and vanish after TASK_MAX_AGE / panel
+            // restart — leaving us blind if the UI stops polling before the
+            // failure arrives.
+            console.error(`[hermes] install failed (task=${task.id}):`, e?.stack || e?.message || e);
+            emitTask(task, { type: "error", message: `Hermes 安装失败: ${e?.message || e}` });
+            task.status = "error";
+        });
+        return { ok: true, message: "Hermes install started", taskId: task.id };
+    }
+    /**
+     * Shared helper that pulls (or builds) the Hermes runtime image and
+     * finalises the runtime catalog entry. Mirrors OpenClaw's
+     * `pullOrBuildOpenclawImageWithTask` so both runtimes expose the same
+     * install UX (local → pull → fallback build → digest pin).
+     */
+    async prepareHermesWithTask(task) {
+        emitTask(task, { type: "progress", message: "准备 Hermes runtime...", progress: 0 });
+        const invocation = resolveDockerInvocation();
+        // Always pull. When the image is already local and up-to-date with
+        // upstream, docker pull returns in a few seconds after a registry
+        // digest check — the trade is worthwhile because it keeps "重新安装"
+        // from turning into a three-second no-op. Failures are clearly
+        // reported instead of silently retrying with a local fallback: Hermes
+        // cannot be built locally (Python toolchain + wheels OOMs on Pi).
+        emitTask(task, {
+            type: "progress",
+            message: `拉取 Hermes 镜像: ${HERMES_DEFAULT_IMAGE} (已缓存时约 10s)...`,
+            progress: 10,
+        });
+        const pull = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "pull", HERMES_DEFAULT_IMAGE], { timeout: 1800000 });
+        if (!pull.ok) {
+            console.error(`[hermes] docker pull failed for ${HERMES_DEFAULT_IMAGE} — output follows:\n${pull.output}`);
+            emitTask(task, {
+                type: "error",
+                message: `Hermes 镜像拉取失败。请检查网络/registry 认证，或手动执行: docker pull ${HERMES_DEFAULT_IMAGE}`,
+            });
+            task.status = "error";
+            return;
+        }
+        // 3. capture digest (best-effort)
+        emitTask(task, { type: "progress", message: "捕获镜像 digest...", progress: 75 });
+        const digest = captureImageDigest(HERMES_DEFAULT_IMAGE);
+        if (digest) {
+            emitTask(task, { type: "log", message: `Digest: ${digest}` });
+        }
+        else {
+            emitTask(task, {
+                type: "log",
+                message: "No RepoDigest available (local build); will use :latest tag",
+            });
+        }
+        // 4. pin the mutable tag to the image's LABEL version (e.g.
+        //    ghcr.io/…:latest → ghcr.io/…:0.10.0). Parity with OpenClaw's
+        //    migrateOpenclawImageTagIfNeeded: keeps panel.json referencing an
+        //    immutable tag so nothing — Nomad image_pull, doctor, UI — ever
+        //    sees a mutable alias after install. No-op when the image was
+        //    locally built or lacks the LABEL.
+        emitTask(task, { type: "progress", message: "锁定镜像版本标签...", progress: 85 });
+        const pinnedTag = pinHermesImageToLabeledVersion(HERMES_DEFAULT_IMAGE);
+        const storedImage = pinnedTag ?? HERMES_DEFAULT_IMAGE;
+        if (pinnedTag) {
+            emitTask(task, { type: "log", message: `Pinned tag: ${pinnedTag}` });
+        }
+        // 5. persist runtime catalog
+        // The shim is baked into the image (see Dockerfile.hermes-slim's
+        // COPY / LABEL). No host-side shim install needed anymore — we
+        // assert the image carries runtime.protocol.version=1 at
+        // buildRuntime() time instead.
+        emitTask(task, { type: "progress", message: "写入 runtime catalog...", progress: 95 });
+        setRuntimeCatalogEntry("hermes", {
+            defaultImage: storedImage,
+            defaultImageDigest: digest,
+            configFormat: "yaml+env",
+            homeDirName: "agent-home",
+            resources: { CPU: 1000, MemoryMB: 1024 },
+            allowDockerSock: false,
+        });
+        emitTask(task, {
+            type: "done",
+            message: digest
+                ? `Hermes 安装完成, 镜像已 pin 到 digest (tag=${storedImage})`
+                : `Hermes 安装完成 (tag=${storedImage})`,
+            progress: 100,
+        });
+        task.status = "done";
+    }
+    /**
+     * Hermes readiness: the runtime_catalog entry is written on successful
+     * install (image pull + shim), so its presence + defaultImage is the
+     * canonical gate. `imageReady` is true once a digest has been captured.
+     */
+    getInstallStatus() {
+        const entry = getRuntimeCatalogEntry("hermes");
+        if (!entry || !entry.defaultImage) {
+            return { installed: false, imageReady: false };
+        }
+        return {
+            installed: true,
+            imageReady: !!entry.defaultImageDigest,
+            digest: entry.defaultImageDigest,
+        };
+    }
+}
+export const hermesAdapter = new HermesAdapter();
+registerAdapter(hermesAdapter);
+//# sourceMappingURL=hermes.js.map