jishushell 0.5.22 → 0.6.18

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

@@ -1,1631 +0,0 @@
-/**
- * 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, writeFileSync } 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 { JISHUSHELL_HOME, 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";
-import { SEARXNG_MCP_SHIM_SOURCE } from "../mcp-shims/searxng-shim.js";
-import { resolveEnvTemplate, writeMcpEntry } from "../mcp-shims/write-mcp-entry.js";
-import * as capabilityRegistry from "../../capability-registry.js";
-const SEARXNG_SHIM_REL_PATH = "__mcp_shims__/searxng/index.mjs";
-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";
-export const HERMES_DEFAULT_GATEWAY_PORT = HERMES_CONTAINER_PORT;
-const HERMES_VERSION_LABEL = "org.opencontainers.image.version";
-const HERMES_MUTABLE_TAG_RE = /:(latest|slim)$/;
-const HERMES_CATALOG_DEFAULTS = {
-    configFormat: "yaml+env",
-    homeDirName: "agent-home",
-    resources: { CPU: 1000, MemoryMB: 1024 },
-    allowDockerSock: false,
-};
-function readOfficialHermesRepoDigest(image) {
-    const repo = imageRepository(HERMES_DEFAULT_IMAGE);
-    if (!repo)
-        return null;
-    try {
-        const invocation = resolveDockerInvocation();
-        const raw = execFileSync(invocation.cmd, [
-            ...invocation.argsPrefix,
-            "image",
-            "inspect",
-            "--format",
-            "{{range .RepoDigests}}{{.}}{{println}}{{end}}",
-            image,
-        ], { timeout: 5_000, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
-        const prefix = `${repo}@sha256:`;
-        return raw
-            .split("\n")
-            .map((line) => line.trim())
-            .find((line) => line.startsWith(prefix) && /^[a-f0-9]{64}$/i.test(line.slice(prefix.length))) ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-function assertOfficialHermesImage(image) {
-    const digest = readOfficialHermesRepoDigest(image);
-    if (digest)
-        return digest;
-    const repo = imageRepository(HERMES_DEFAULT_IMAGE) ?? HERMES_DEFAULT_IMAGE;
-    throw new Error(`Hermes image ${image} is not a JishuShell-provided runtime image. ` +
-        `It must be pulled from ${repo} and retain an official RepoDigest.`);
-}
-function imageRepository(image) {
-    const digestIdx = image.indexOf("@");
-    const withoutDigest = digestIdx >= 0 ? image.slice(0, digestIdx) : image;
-    const colonIdx = withoutDigest.lastIndexOf(":");
-    const slashIdx = withoutDigest.lastIndexOf("/");
-    if (colonIdx > slashIdx)
-        return withoutDigest.slice(0, colonIdx);
-    return withoutDigest || null;
-}
-function imageTag(image) {
-    const colonIdx = image.lastIndexOf(":");
-    const slashIdx = image.lastIndexOf("/");
-    if (colonIdx <= slashIdx)
-        return null;
-    const tag = image.slice(colonIdx + 1);
-    return tag && tag !== "<none>" && tag !== "none" ? tag : null;
-}
-function imageTagVersion(image) {
-    const tag = imageTag(image);
-    return tag && /^\d+\.\d+\.\d+/.test(tag) ? tag : undefined;
-}
-function versionScore(image) {
-    const tag = imageTag(image) ?? "";
-    const semver = tag.match(/^v?(\d+)\.(\d+)\.(\d+)/);
-    if (semver) {
-        return [
-            3,
-            Number.parseInt(semver[1], 10),
-            Number.parseInt(semver[2], 10),
-            Number.parseInt(semver[3], 10),
-            tag,
-        ];
-    }
-    if (tag === "latest")
-        return [2, 0, 0, 0, tag];
-    if (tag === "slim")
-        return [1, 0, 0, 0, tag];
-    return [0, 0, 0, 0, tag];
-}
-function compareLocalHermesImages(left, right) {
-    const a = versionScore(left);
-    const b = versionScore(right);
-    for (let i = 0; i < 4; i++) {
-        const diff = b[i] - a[i];
-        if (diff !== 0)
-            return diff;
-    }
-    return b[4].localeCompare(a[4]);
-}
-function findLocalHermesImage() {
-    const repo = imageRepository(HERMES_DEFAULT_IMAGE);
-    if (!repo)
-        return null;
-    try {
-        const invocation = resolveDockerInvocation();
-        const out = execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "ls", "--format", "{{.Repository}}:{{.Tag}}"], { timeout: 5_000, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
-        const candidates = out
-            .split("\n")
-            .map((line) => line.trim())
-            .filter((line) => line.startsWith(`${repo}:`) && !!imageTag(line));
-        for (const candidate of candidates.sort(compareLocalHermesImages)) {
-            const digest = readOfficialHermesRepoDigest(candidate);
-            if (digest)
-                return { image: candidate, digest };
-        }
-        return null;
-    }
-    catch {
-        return null;
-    }
-}
-function persistHermesCatalogForImage(image, existing, officialDigest) {
-    const next = {
-        ...HERMES_CATALOG_DEFAULTS,
-        ...(existing ?? {}),
-        defaultImage: image,
-    };
-    const digest = officialDigest ?? readOfficialHermesRepoDigest(image);
-    if (digest)
-        next.defaultImageDigest = digest;
-    else
-        delete next.defaultImageDigest;
-    setRuntimeCatalogEntry("hermes", next);
-}
-/**
- * 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()}`;
-}
-// Mirrors nomad-manager.ts:nomadConfigDeclaresHostNetwork. When the host
-// nomad.hcl declares `host_network "external" { ... }`, the legacy hermes
-// job needs to attach `HostNetwork: "external"` to its ReservedPorts so
-// docker publishes the gateway to the LAN address instead of 127.0.0.1.
-function nomadHasExternalHostNetwork() {
-    const path = join(JISHUSHELL_HOME, "nomad", "nomad.hcl");
-    if (!existsSync(path))
-        return false;
-    try {
-        return /host_network\s+"external"\s*\{/.test(readFileSync(path, "utf-8"));
-    }
-    catch {
-        return false;
-    }
-}
-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"));
-}
-/**
- * §17 — find the capability-registry entry that produced a given
- * resolved env URL (e.g. `SEARCH_API_BASE_URL = http://x:8080/search`).
- * Match by host:port (and path when declared). Returns the entry so
- * applyConnectionEnv can read its `toolSchema`. Returns null when no
- * match — caller falls back to the legacy PR 7 path.
- */
-function findSearchProviderForUrl(rawUrl) {
-    let parsed;
-    try {
-        parsed = new URL(rawUrl);
-    }
-    catch {
-        return null;
-    }
-    const targetHost = parsed.hostname.toLowerCase();
-    const targetPort = Number(parsed.port) || (parsed.protocol === "https:" ? 443 : 80);
-    const targetPath = parsed.pathname.replace(/\/+$/u, "");
-    const snapshot = capabilityRegistry.snapshot().providersByCapability ?? {};
-    for (const [cap, entries] of Object.entries(snapshot)) {
-        if (!cap.startsWith("search"))
-            continue;
-        for (const entry of entries) {
-            const entryHost = (entry.host ?? "").toLowerCase();
-            const entryPort = entry.hostPort;
-            const entryPath = (entry.path ?? "").replace(/\/+$/u, "");
-            if (entryPort !== targetPort)
-                continue;
-            if (entryHost && entryHost !== targetHost) {
-                // Tolerate localhost <-> 127.0.0.1 / advertised-host mismatches by
-                // accepting any host when the port + path match — env URLs go
-                // through nomad-manager's host rewriting which can disagree with
-                // registry's stored host.
-            }
-            if (entryPath && targetPath && entryPath !== targetPath)
-                continue;
-            return entry;
-        }
-    }
-    return null;
-}
-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: verify the docker image retains the official
-         * ghcr.io/x-aijishu/hermes-runtime RepoDigest before Nomad receives it.
-         * 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}"`);
-            }
-            assertOfficialHermesImage(image);
-            // 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");
-        }
-        // Only run JishuShell-provided Hermes runtime images. A local tag alone
-        // is not enough because anyone can retag an arbitrary image; RepoDigest
-        // records that Docker pulled this image from our official repository.
-        assertOfficialHermesImage(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;
-        }
-    }
-    /**
-     * Connection-apply hook (§7 / §17 of app-interconnect-design):
-     * translate resolved bindings into Hermes-native config.yaml updates.
-     *
-     * Hermes' web tool only supports Firecrawl/Tavily/Exa/Parallel as direct
-     * search backends — it does NOT recognize SearXNG natively. We expose
-     * SearXNG (and any other MCP-shaped capability) to the agent via the
-     * jishushell MCP firewall (see `mcp-shims/firewall.ts`).
-     *
-     * The firewall replaces the upstream package's `tools/list` description
-     * with the canonical wording declared in app yaml's
-     * `provides[].tool_schema` — preventing prompt-injection like the
-     * "news / recent events" + `time_range` slots of upstream `mcp-searxng`,
-     * which was rewriting Chinese queries into English and hallucinating
-     * dates on MiniMax-class models.
-     *
-     * For each `SEARCH_API_BASE_URL` (or future MCP-shaped slot):
-     *   1. Find the producing capability entry in the registry.
-     *   2. If it carries `toolSchema`, drop firewall + config.json into
-     *      agent-home and write `mcp_servers.<cap_id>` pointing at it.
-     *   3. If it doesn't (legacy yaml without §17 fields), fall back to
-     *      the PR 7 in-tree searxng-shim — kept for one release cycle as
-     *      backstop while community apps migrate.
-     *
-     * Other env (OPENAI_API_BASE_URL etc.) is a no-op here; the framework
-     * still injects them via `nomad-manager.injectConnectionsRuntimeEnv`
-     * and Hermes picks them up natively.
-     */
-    async applyConnectionEnv(instanceId, env) {
-        const searchUrl = env.SEARCH_API_BASE_URL;
-        if (typeof searchUrl !== "string")
-            return;
-        if (searchUrl === "") {
-            // Empty value = unbind. Strip any connection-managed searxng /
-            // search-* entries from mcp_servers so the next start doesn't keep
-            // routing through a dead provider. We're conservative: only entries
-            // we know we may have written (`searxng` for the legacy shim path,
-            // and any `*_search` shaped key for the §17 firewall path's stable
-            // alias) get removed.
-            try {
-                const paths = resolveHermesPaths(instanceId);
-                if (!paths.primaryConfig || !existsSync(paths.primaryConfig))
-                    return;
-                const yamlText = readFileSync(paths.primaryConfig, "utf-8");
-                const parsed = YAML.parse(yamlText) ?? {};
-                if (parsed?.mcp_servers && typeof parsed.mcp_servers === "object") {
-                    for (const key of Object.keys(parsed.mcp_servers)) {
-                        if (key === "searxng" || /(^|_)search$/.test(key)) {
-                            delete parsed.mcp_servers[key];
-                        }
-                    }
-                }
-                writeConfigFile(paths.primaryConfig, YAML.stringify(parsed).trimEnd() + "\n");
-            }
-            catch (e) {
-                console.warn(`[hermes] applyConnectionEnv unbind failed for ${instanceId}: ${e.message}`);
-            }
-            return;
-        }
-        try {
-            const paths = resolveHermesPaths(instanceId);
-            ensureHermesConfigFiles(paths);
-            const yamlText = readFileSync(paths.primaryConfig, "utf-8");
-            const parsed = YAML.parse(yamlText) ?? {};
-            parsed.mcp_servers = parsed.mcp_servers ?? {};
-            // Try the §17 firewall path first — look up the producer capability
-            // entry to find a tool_schema declared by the provider's yaml.
-            const provider = findSearchProviderForUrl(searchUrl);
-            const svcUser = resolveServiceUser();
-            const serviceUser = svcUser ? { uid: svcUser.uid, gid: svcUser.gid } : undefined;
-            if (provider?.toolSchema) {
-                const upstreamEnv = resolveEnvTemplate(provider.toolSchema.upstream.env_template, env);
-                const entry = writeMcpEntry({
-                    agentHomeDir: paths.agentHome,
-                    containerHomeDir: HERMES_CONTAINER_HOME,
-                    capabilityId: provider.capability,
-                    toolSchema: provider.toolSchema,
-                    upstreamEnv,
-                    serviceUser,
-                });
-                // mcp_servers map key — use a stable short alias (the bare tool
-                // name) so users editing config.yaml see something readable.
-                const mapKey = provider.toolSchema.name.replace(/_web_search$|_search$/u, "")
-                    || provider.capability;
-                parsed.mcp_servers[mapKey] = { ...entry, enabled: true };
-            }
-            else {
-                // Fallback: legacy PR 7 per-capability shim. Strip trailing
-                // /search to get the SearXNG origin for the shim's SEARXNG_URL env.
-                // The URL is re-rendered from the registry on each instance start
-                // (PR 9 phaseRefreshConnections), so host IP changes are picked
-                // up automatically when the user restarts the consuming agent.
-                let baseUrl = searchUrl;
-                try {
-                    const u = new URL(searchUrl);
-                    if (u.pathname === "/search" || u.pathname === "/search/") {
-                        u.pathname = "";
-                        baseUrl = u.toString().replace(/\/$/, "");
-                    }
-                }
-                catch {
-                    return;
-                }
-                const shimAbsPath = join(paths.agentHome, SEARXNG_SHIM_REL_PATH);
-                mkdirSync(dirname(shimAbsPath), { recursive: true });
-                writeFileSync(shimAbsPath, SEARXNG_MCP_SHIM_SOURCE, { mode: 0o755 });
-                try {
-                    if (serviceUser) {
-                        chownSync(dirname(shimAbsPath), serviceUser.uid, serviceUser.gid);
-                        chownSync(shimAbsPath, serviceUser.uid, serviceUser.gid);
-                    }
-                }
-                catch {
-                    /* best-effort */
-                }
-                parsed.mcp_servers.searxng = {
-                    command: "node",
-                    args: [`${HERMES_CONTAINER_HOME}/${SEARXNG_SHIM_REL_PATH}`],
-                    env: { SEARXNG_URL: baseUrl },
-                    enabled: true,
-                };
-            }
-            writeConfigFile(paths.primaryConfig, YAML.stringify(parsed).trimEnd() + "\n");
-        }
-        catch (e) {
-            console.warn(`[hermes] applyConnectionEnv failed for ${instanceId}: ${e.message}`);
-        }
-    }
-    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 WeChat (personal-account) 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;
-        // Without HostNetwork, Nomad's docker driver publishes the gateway to
-        // 127.0.0.1, so cross-container consumers (e.g. OpenWebUI binding
-        // hermes via the llm-agent capability) can't reach it. Match the
-        // modern app-yaml path (nomad-manager.ts:hostNetworkForPort): when
-        // the agent's nomad.hcl declares `host_network "external"`, attach
-        // it to the ReservedPort so docker binds to the LAN address.
-        const hostNetwork = nomadHasExternalHostNetwork() ? "external" : undefined;
-        return {
-            Name: "gateway",
-            Driver: "docker",
-            User: `${hostUid}:${hostGid}`,
-            Config: {
-                image: spec.image,
-                force_pull: false,
-                // Match nomad-manager.ts:buildAppTask — default 5-minute pull
-                // timeout is too short for Pi-class networks pulling a 1+ GiB
-                // hermes image; bump to 15 minutes.
-                image_pull_timeout: "15m",
-                entrypoint: [spec.command],
-                args: [...(spec.args || [])],
-                work_dir: spec.cwd || HERMES_CONTAINER_WORKDIR,
-                volumes,
-                // Tell the docker driver to publish the labeled "gateway" port,
-                // so it routes the host_network IP rather than the loopback default.
-                ports: ["gateway"],
-                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,
-                                To: gatewayPort,
-                                ...(hostNetwork ? { HostNetwork: hostNetwork } : {}),
-                            },
-                        ],
-                    },
-                ],
-            },
-            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 "reinstall"
-        // 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
-        // verify the official RepoDigest at buildRuntime()/onBeforeStart time.
-        emitTask(task, { type: "progress", message: "写入 runtime catalog...", progress: 95 });
-        setRuntimeCatalogEntry("hermes", {
-            ...HERMES_CATALOG_DEFAULTS,
-            defaultImage: storedImage,
-            ...(digest ? { defaultImageDigest: digest } : {}),
-        });
-        emitTask(task, {
-            type: "done",
-            message: digest
-                ? `Hermes 安装完成, 镜像已 pin 到 digest (tag=${storedImage})`
-                : `Hermes 安装完成 (tag=${storedImage})`,
-            progress: 100,
-        });
-        task.status = "done";
-    }
-    /**
-     * Hermes readiness: the image must retain an official RepoDigest from
-     * ghcr.io/x-aijishu/hermes-runtime. This accepts images pulled directly
-     * from our registry (and docker save/load copies that preserve RepoDigests)
-     * while rejecting arbitrary local retags that only look like Hermes runtime.
-     */
-    getInstallStatus() {
-        const entry = getRuntimeCatalogEntry("hermes");
-        const storedImage = typeof entry?.defaultImage === "string" ? entry.defaultImage.trim() : "";
-        if (storedImage) {
-            const digest = readOfficialHermesRepoDigest(storedImage);
-            if (digest) {
-                return {
-                    installed: true,
-                    imageReady: true,
-                    version: imageTagVersion(storedImage),
-                    digest: entry?.defaultImageDigest ?? digest,
-                };
-            }
-            const localImage = findLocalHermesImage();
-            if (localImage) {
-                persistHermesCatalogForImage(localImage.image, entry, localImage.digest);
-                return {
-                    installed: true,
-                    imageReady: true,
-                    version: imageTagVersion(localImage.image),
-                    digest: localImage.digest,
-                };
-            }
-            return {
-                installed: true,
-                imageReady: false,
-                version: imageTagVersion(storedImage),
-                digest: entry?.defaultImageDigest,
-            };
-        }
-        const localImage = findLocalHermesImage();
-        if (!localImage)
-            return { installed: false, imageReady: false };
-        persistHermesCatalogForImage(localImage.image, entry, localImage.digest);
-        return {
-            installed: true,
-            imageReady: true,
-            version: imageTagVersion(localImage.image),
-            digest: localImage.digest,
-        };
-    }
-}
-export const hermesAdapter = new HermesAdapter();
-registerAdapter(hermesAdapter);
-//# sourceMappingURL=hermes.js.map