jishushell 0.4.17 → 0.4.24

package/dist/routes/instances.js

@@ -1,18 +1,17 @@
-import { createHash } from "crypto";
-import { existsSync, realpathSync } from "fs";
-import { readFile, stat } from "fs/promises";
-import { request as httpRequest } from "http";
-import { join } from "path";
 import { getServiceManagerType } from "../config.js";
-import { PROXY_IDENTITY_HEADERS } from "../constants.js";
 import { assertNotLocked } from "../services/backup-manager.js";
-import * as instanceManager from "../services/instance-manager.js";
+import * as instanceManager from "../services/app/app-manager.js";
 import * as llmProxy from "../services/llm-proxy/index.js";
-import * as pluginInstaller from "../services/plugin-installer.js";
+import { loadRemoteAppSpecYaml } from "../services/app/remote-spec.js";
+import { augmentInstanceMetadata, getInstanceCapabilities, getInstanceConfigMeta, resolveAgentType, } from "../services/runtime/instance.js";
+import { getAdapter, hasAdapter, listRegisteredAdapters } from "../services/runtime/index.js";
+import { normalizeInstanceId } from "../services/app/id-normalizer.js";
+import { assertTerminalSessionOwner, getTerminalSession, getTerminalSessionEvents, sendTerminalSessionInput, startTerminalSession, stopTerminalSession, subscribeTerminalSession, } from "../services/app/terminal-session-manager.js";
 import { TtlMap } from "../utils/ttl-cache.js";
-import { writeConfigFile, writeSecretFile, ensureDirContainer } from "../utils/fs.js";
-// Hop-by-hop headers that must not be forwarded by a proxy (RFC 2616 §13.5.1)
-const HOP_BY_HOP = new Set([
+import { writeSecretFile } from "../utils/fs.js";
+// Hop-by-hop headers that must not be forwarded by a proxy (RFC 2616 §13.5.1).
+// Exported for adapter-owned route modules that implement their own HTTP proxies.
+export const HOP_BY_HOP = new Set([
     "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
     "te", "trailer", "transfer-encoding", "upgrade",
 ]);
@@ -31,14 +30,257 @@ function parseHttpOrigin(value) {
         return null;
     }
 }
-function inferRequestOrigin(request) {
+export function inferRequestOrigin(request) {
     // Only trust browser-sent Origin/Referer for auto-allowlisting. Host and
     // X-Forwarded-* are proxy metadata and should not become persisted origin
     // policy by themselves.
     return (parseHttpOrigin(readHeaderValue(request?.headers?.origin))
         ?? parseHttpOrigin(readHeaderValue(request?.headers?.referer)));
 }
-function ensureControlUiAllowedOrigin(instanceId, origin) {
+function capabilityProxyPath(instanceId, capability) {
+    return `/api/instances/${encodeURIComponent(instanceId)}/provides/${encodeURIComponent(capability)}`;
+}
+function joinProxyPath(basePath, suffix) {
+    const normalizedBase = basePath.replace(/\/+$/, "");
+    const normalizedSuffix = suffix.replace(/^\/+/, "");
+    if (!normalizedSuffix)
+        return normalizedBase;
+    return `${normalizedBase}/${normalizedSuffix}`;
+}
+function joinUpstreamPath(basePath, suffix) {
+    const normalizedBase = typeof basePath === "string" && basePath.trim()
+        ? (basePath.startsWith("/") ? basePath : `/${basePath}`)
+        : "/";
+    const normalizedSuffix = suffix.replace(/^\/+/, "");
+    if (!normalizedSuffix)
+        return normalizedBase;
+    return `${normalizedBase.replace(/\/+$/, "")}/${normalizedSuffix}`;
+}
+function shouldRewriteProxyResponse(contentType) {
+    const value = (contentType ?? "").toLowerCase();
+    return value.includes("text/html") || value.includes("text/css");
+}
+function rewriteProxyTextBody(body, contentType, proxyBasePath) {
+    const value = (contentType ?? "").toLowerCase();
+    const proxyBaseWithSlash = `${proxyBasePath.replace(/\/+$/, "")}/`;
+    let rewritten = body;
+    if (value.includes("text/html")) {
+        if (!/<base\b/i.test(rewritten)) {
+            if (/<head[^>]*>/i.test(rewritten)) {
+                rewritten = rewritten.replace(/<head([^>]*)>/i, `<head$1><base href="${proxyBaseWithSlash}">`);
+            }
+            else {
+                rewritten = `<base href="${proxyBaseWithSlash}">${rewritten}`;
+            }
+        }
+        rewritten = rewritten.replace(/((?:href|src|action|poster)=['"])\/(?!\/)/gi, `$1${proxyBaseWithSlash}`);
+    }
+    if (value.includes("text/css") || value.includes("text/html")) {
+        rewritten = rewritten.replace(/url\((['"]?)\/(?!\/)/gi, `url($1${proxyBaseWithSlash}`);
+    }
+    return rewritten;
+}
+function buildProxyRequestBody(req) {
+    if (req.method === "GET" || req.method === "HEAD")
+        return undefined;
+    const body = req.body;
+    if (body == null)
+        return undefined;
+    if (typeof body === "string" || body instanceof Uint8Array || Buffer.isBuffer(body)) {
+        return body;
+    }
+    const contentType = String(req.headers["content-type"] ?? "").toLowerCase();
+    if (contentType.includes("application/x-www-form-urlencoded") && typeof body === "object") {
+        return new URLSearchParams(body).toString();
+    }
+    if (contentType.includes("application/json")) {
+        return JSON.stringify(body);
+    }
+    if (typeof body === "object") {
+        return JSON.stringify(body);
+    }
+    return undefined;
+}
+function parseCommandLine(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return [];
+    const args = [];
+    let current = "";
+    let quote = null;
+    let escaping = false;
+    for (const char of trimmed) {
+        if (escaping) {
+            current += char;
+            escaping = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaping = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (current) {
+                args.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += char;
+    }
+    if (escaping)
+        current += "\\";
+    if (quote)
+        throw new Error("Command contains an unterminated quote");
+    if (current)
+        args.push(current);
+    return args;
+}
+function isTerminalProvide(provide) {
+    return !!provide && String(provide.protocol).toLowerCase() === "terminal" && !!provide.terminal;
+}
+function resolveTerminalProvide(instanceId, capability) {
+    const provide = instanceManager
+        .getProvidedCapabilitiesForApp(instanceId)
+        .find((entry) => entry.capability === capability);
+    if (!provide)
+        throw new Error(`Capability '${capability}' not found`);
+    if (!isTerminalProvide(provide)) {
+        throw new Error(`Capability '${capability}' is not a terminal provide`);
+    }
+    return provide;
+}
+function buildTerminalCommand(baseCommand, input) {
+    if (!Array.isArray(baseCommand) || baseCommand.length === 0 || baseCommand.some((part) => typeof part !== "string" || !part.trim())) {
+        throw new Error("Terminal provide is missing a valid base command");
+    }
+    const parsed = parseCommandLine(input);
+    if (!parsed.length)
+        throw new Error("Command cannot be empty");
+    const baseName = baseCommand[0].split("/").pop() || baseCommand[0];
+    const matchesBase = parsed.length >= baseCommand.length && baseCommand.every((part, index) => parsed[index] === part);
+    const matchesBaseName = parsed[0] === baseName;
+    if (matchesBase)
+        return parsed;
+    if (matchesBaseName)
+        return [baseCommand[0], ...parsed.slice(1)];
+    return [...baseCommand, ...parsed];
+}
+async function proxyProvidedCapability(req, reply) {
+    const idErr = validateId(req.params.id);
+    if (idErr)
+        return reply.status(400).send({ detail: idErr });
+    const rawInst = instanceManager.getInstance(req.params.id);
+    if (!rawInst)
+        return reply.status(404).send({ detail: "Instance not found" });
+    if (!instanceManager.getApp(req.params.id))
+        return reply.status(404).send({ detail: "App not found" });
+    const capabilities = instanceManager.getProvidedCapabilitiesForApp(req.params.id);
+    const capability = capabilities.find((entry) => entry.capability === req.params.capability);
+    if (!capability) {
+        return reply.status(404).send({ detail: `Capability '${req.params.capability}' not found` });
+    }
+    if (capability.visibility === "internal") {
+        return reply.status(403).send({ detail: `Capability '${req.params.capability}' is not externally accessible` });
+    }
+    if (capability.protocol !== "http" && capability.protocol !== "https") {
+        return reply.status(400).send({ detail: `Capability '${req.params.capability}' does not use HTTP(S)` });
+    }
+    if (typeof capability.port !== "number" || capability.port < 1) {
+        return reply.status(500).send({ detail: `Capability '${req.params.capability}' has no resolved port` });
+    }
+    const upstreamHost = instanceManager.getListeningHostForPort(capability.port);
+    const upstreamOrigin = `${capability.protocol}://${instanceManager.urlHost(upstreamHost)}:${capability.port}`;
+    const wildcardSuffix = typeof req.params["*"] === "string" ? req.params["*"] : "";
+    const upstreamPath = joinUpstreamPath(capability.path, wildcardSuffix);
+    const querySuffix = req.raw.url?.includes("?") ? req.raw.url.slice(req.raw.url.indexOf("?")) : "";
+    const targetUrl = `${upstreamOrigin}${upstreamPath}${querySuffix}`;
+    const proxyBasePath = capabilityProxyPath(req.params.id, req.params.capability);
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (value == null)
+            continue;
+        const normalizedKey = key.toLowerCase();
+        if (HOP_BY_HOP.has(normalizedKey) || normalizedKey === "host" || normalizedKey === "content-length" || normalizedKey === "accept-encoding") {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                headers.append(key, item);
+        }
+        else {
+            headers.set(key, String(value));
+        }
+    }
+    headers.set("accept-encoding", "identity");
+    // `x-forwarded-prefix` is not a standard reverse-proxy header and some
+    // upstream frameworks (notably SvelteKit apps like Hollama) treat it as a
+    // deployment base path, which breaks `/_app/*` asset resolution under this
+    // generic proxy. The HTML/base rewrite below already handles path prefixing.
+    if (req.headers.host)
+        headers.set("x-forwarded-host", String(req.headers.host));
+    headers.set("x-forwarded-proto", req.protocol);
+    try {
+        const upstream = await fetch(targetUrl, {
+            method: req.method,
+            headers,
+            body: buildProxyRequestBody(req),
+            redirect: "manual",
+            signal: AbortSignal.timeout(60_000),
+        });
+        reply.code(upstream.status);
+        upstream.headers.forEach((value, key) => {
+            const normalizedKey = key.toLowerCase();
+            if (HOP_BY_HOP.has(normalizedKey) || normalizedKey === "content-length" || normalizedKey === "content-encoding") {
+                return;
+            }
+            if (normalizedKey === "location") {
+                if (value.startsWith("/")) {
+                    reply.header(key, joinProxyPath(proxyBasePath, value));
+                    return;
+                }
+                try {
+                    const parsed = new URL(value);
+                    const upstreamBase = new URL(upstreamOrigin);
+                    if (parsed.origin === upstreamBase.origin) {
+                        reply.header(key, `${joinProxyPath(proxyBasePath, parsed.pathname)}${parsed.search}${parsed.hash}`);
+                        return;
+                    }
+                }
+                catch {
+                    // fall through to raw location header
+                }
+            }
+            reply.header(key, value);
+        });
+        if (req.method === "HEAD") {
+            return reply.send();
+        }
+        if (shouldRewriteProxyResponse(upstream.headers.get("content-type"))) {
+            const rewritten = rewriteProxyTextBody(await upstream.text(), upstream.headers.get("content-type"), proxyBasePath);
+            return reply.send(rewritten);
+        }
+        const buffer = Buffer.from(await upstream.arrayBuffer());
+        return reply.send(buffer);
+    }
+    catch (error) {
+        return reply.status(502).send({ detail: error?.message || `Failed to proxy capability '${req.params.capability}'` });
+    }
+}
+export async function ensureControlUiAllowedOrigin(instanceId, origin) {
     const normalizedOrigin = origin.trim();
     if (!normalizedOrigin)
         return false;
@@ -54,13 +296,13 @@ function ensureControlUiAllowedOrigin(instanceId, origin) {
     if (normalized.has("*") || normalized.has(normalizedOrigin.toLowerCase()))
         return false;
     controlUi.allowedOrigins = [...existing.filter((value) => value.trim()), normalizedOrigin];
-    instanceManager.saveConfig(instanceId, config);
+    await instanceManager.saveConfig(instanceId, config);
     return true;
 }
 // Resolve service manager once at route registration, re-resolve on config change
 let _svc = null;
 let _svcType = "";
-async function getSvc() {
+export async function getSvc() {
     const currentType = getServiceManagerType();
     if (_svc && _svcType === currentType)
         return _svc;
@@ -76,6 +318,34 @@ export function validateId(id) {
     }
     return null;
 }
+function normalizeInstanceName(name) {
+    return name.trim().toLowerCase();
+}
+function isLegacyInstanceAppType(value) {
+    return value === "custom" || value === "ollama";
+}
+function getInstanceBackedInstalledApp(instanceId) {
+    return instanceManager.getApp(instanceId);
+}
+const DEFAULT_INSTANCE_TEMPLATE_BY_KIND = {
+    ollama: "ollama-with-hollama-binary.yaml",
+};
+function loadBuiltinAppSpecYaml(fileName) {
+    const template = instanceManager.listBuiltinAppSpecs().find((entry) => entry.fileName === fileName);
+    if (!template?.yaml) {
+        throw new Error(`Builtin app spec '${fileName}' not found`);
+    }
+    return template.yaml;
+}
+async function loadRemoteAppSpecYamlForInstance(urlText) {
+    return loadRemoteAppSpecYaml(urlText, { fieldName: "app_spec_url" });
+}
+function isConfigDocument(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const format = value.format;
+    return format === "json" || format === "yaml+env";
+}
 // TTL 15s: outlives the frontend 10s polling interval so most requests hit cache
 const statusCache = new TtlMap(15_000);
 const controlUiRestartInFlight = new Map();
@@ -83,12 +353,21 @@ function getCachedStatus(svc, instanceId) {
     const cached = statusCache.get(instanceId);
     if (cached !== undefined)
         return Promise.resolve(cached);
-    return Promise.resolve(svc.getStatus(instanceId)).then((data) => {
+    const statusPromise = getInstanceBackedInstalledApp(instanceId)
+        ? instanceManager.getAppStatus(instanceId).then((data) => ({
+            status: data.status,
+            pid: data.pid,
+            uptime: data.uptime,
+            memory_mb: data.memory_mb,
+            cpu_percent: data.cpu_percent,
+        }))
+        : Promise.resolve(svc.getStatus(instanceId));
+    return statusPromise.then((data) => {
         statusCache.set(instanceId, data);
         return data;
     });
 }
-async function restartRunningInstanceForControlUiOrigin(instanceId, origin) {
+export async function restartRunningInstanceForControlUiOrigin(instanceId, origin) {
     const inFlight = controlUiRestartInFlight.get(instanceId);
     if (inFlight)
         return inFlight;
@@ -116,21 +395,130 @@ export async function instanceRoutes(app) {
         const svc = await getSvc();
         const instances = instanceManager.listInstances();
         const statuses = await Promise.all(instances.map(inst => getCachedStatus(svc, inst.id).catch(() => ({ status: "unknown" }))));
-        return instances.map((inst, i) => ({ ...inst, service: statuses[i] }));
+        return Promise.all(instances.map(async (inst, i) => ({
+            ...(await augmentInstanceMetadata(inst.id, inst)),
+            service: statuses[i],
+        })));
     });
     // Create
     app.post("/api/instances", async (req, reply) => {
         const err = validateId(req.body.id);
         if (err)
             return reply.status(400).send({ detail: err });
+        const requestedName = typeof req.body.name === "string" ? req.body.name.trim() : "";
         // Validate name/description length
-        if (typeof req.body.name !== "string" || req.body.name.length === 0 || req.body.name.length > 256) {
+        if (!requestedName || requestedName.length > 256) {
             return reply.status(400).send({ detail: "Name must be 1-256 characters" });
         }
         if (req.body.description && req.body.description.length > 2048) {
             return reply.status(400).send({ detail: "Description must be at most 2048 characters" });
         }
-        // Validate clone_from if provided
+        // §32.2 / §32.8: pure adapter dispatch. The route layer has no
+        // knowledge of specific runtimes beyond trusting what the caller sent;
+        // `getAdapter(agentType)` throws cleanly if the type is unregistered.
+        // `app_type` is accepted as a legacy alias that predates the adapter
+        // contract (pre-§32.2) — both resolve to the same dispatch key.
+        const requestedKind = typeof req.body.agentType === "string" && req.body.agentType.trim()
+            ? req.body.agentType.trim()
+            : typeof req.body.app_type === "string" && req.body.app_type.trim()
+                ? req.body.app_type.trim()
+                : "openclaw";
+        const { getAdapter, hasAdapter } = await import("../services/runtime/index.js");
+        const legacyAppType = isLegacyInstanceAppType(requestedKind) ? requestedKind : null;
+        if (!hasAdapter(requestedKind) && !legacyAppType) {
+            return reply.status(400).send({
+                detail: `Unsupported agentType="${requestedKind}". Install the matching runtime first.`,
+            });
+        }
+        // Parse app_spec_yaml if provided (for YAML-backed install flows).
+        let appSpec;
+        let appSpecYaml = typeof req.body.app_spec_yaml === "string" ? req.body.app_spec_yaml.trim() : "";
+        if (!appSpecYaml && typeof req.body.app_spec_url === "string" && req.body.app_spec_url.trim()) {
+            try {
+                appSpecYaml = await loadRemoteAppSpecYamlForInstance(req.body.app_spec_url.trim());
+            }
+            catch (e) {
+                return reply.status(400).send({ detail: e.message });
+            }
+        }
+        // When a legacy dispatch key (e.g. app_type="ollama") is sent without
+        // an explicit AppSpec, auto-load the shipped default template so the
+        // caller doesn't have to know the YAML lives in apps/.
+        const defaultTemplateFile = DEFAULT_INSTANCE_TEMPLATE_BY_KIND[requestedKind];
+        if (!appSpecYaml && defaultTemplateFile) {
+            try {
+                appSpecYaml = loadBuiltinAppSpecYaml(defaultTemplateFile);
+            }
+            catch (e) {
+                return reply.status(500).send({ detail: e.message });
+            }
+        }
+        if (appSpecYaml) {
+            try {
+                const { parse: parseYaml } = await import("yaml");
+                const parsed = parseYaml(appSpecYaml);
+                if (!parsed || !parsed.tasks || !Array.isArray(parsed.tasks)) {
+                    return reply.status(400).send({ detail: "Invalid app-spec YAML: must contain a 'tasks' array" });
+                }
+                if (!parsed.id)
+                    parsed.id = req.body.id;
+                appSpec = parsed;
+            }
+            catch (e) {
+                return reply.status(400).send({ detail: `Invalid YAML: ${e.message}` });
+            }
+        }
+        // Normalize instance id: Tier-1 agents get "<agentType>-" prefix;
+        // custom apps get "<app_spec_ref>-" prefix (or the spec id verbatim
+        // for singleInstance). Idempotent when the user already types the
+        // expected prefix. See docs/app-dir-v2-plan.md §2.4.
+        //
+        // Gate: only apply normalization when the caller explicitly opted in
+        // by sending `agentType` (or the legacy `app_type` alias), or when an
+        // AppSpec is being installed. Requests without an explicit runtime
+        // hint keep the V1 contract (id preserved verbatim) so older API
+        // consumers and existing test fixtures continue working. Panel UI
+        // sends `agentType` explicitly (`frontend/src/pages/NewInstance.tsx`).
+        const explicitRuntime = (typeof req.body.agentType === "string" && req.body.agentType.trim().length > 0) ||
+            (typeof req.body.app_type === "string" && req.body.app_type.trim().length > 0);
+        // Skip normalization for legacy app types (ollama / custom old marker):
+        // these follow the V1 legacy short-circuit path (see
+        // docs/app-dir-v2-plan.md §2.1 "Legacy Ollama 口径"), so we keep their
+        // ids verbatim rather than retroactively prefixing them.
+        const shouldNormalize = (explicitRuntime || appSpecYaml.length > 0) && !legacyAppType;
+        const kind = requestedKind === "hermes" ? "hermes"
+            : requestedKind === "custom" ? "custom"
+                : requestedKind === "openclaw" ? "openclaw"
+                    : "openclaw";
+        let instanceId = req.body.id;
+        if (shouldNormalize) {
+            try {
+                instanceId = normalizeInstanceId(req.body.id, kind, appSpec ? { id: appSpec.id, singleInstance: appSpec.singleInstance } : undefined);
+            }
+            catch (e) {
+                return reply.status(400).send({ detail: e.message });
+            }
+        }
+        const existingById = instanceManager.getInstance(instanceId);
+        if (existingById) {
+            return reply.status(409).send({ detail: `Application '${instanceId}' already exists` });
+        }
+        const requestedNormalizedName = normalizeInstanceName(requestedName);
+        const existingByName = instanceManager.listInstances().find((instance) => {
+            if (!instance || typeof instance.name !== "string")
+                return false;
+            return normalizeInstanceName(instance.name) === requestedNormalizedName;
+        });
+        if (existingByName) {
+            return reply.status(409).send({
+                detail: `Application name '${requestedName}' already exists`,
+                existingId: existingByName.id,
+            });
+        }
+        // Validate clone_from if provided — adapter will reject it if the
+        // runtime does not support cloning, but we do the existence check
+        // here so the error message points at the wrong source, not at the
+        // wrong-runtime rejection.
         if (req.body.clone_from) {
             const cloneErr = validateId(req.body.clone_from);
             if (cloneErr)
@@ -140,21 +528,78 @@ export async function instanceRoutes(app) {
                 return reply.status(400).send({ detail: `Source instance '${req.body.clone_from}' not found` });
         }
         try {
-            const meta = await instanceManager.createInstance(req.body.id, req.body.name, req.body.description || "", req.body.clone_from, req.body.openclaw_home, undefined, // appSpec — not used from HTTP route
-            req.body.clone_options);
-            // Auto-start if default provider is configured (model ready to use)
+            let meta;
+            const createFromAppSpec = appSpecYaml.length > 0;
+            if (!createFromAppSpec) {
+                if (!hasAdapter(requestedKind)) {
+                    return reply.status(400).send({ detail: `Creating ${requestedKind} requires an app spec` });
+                }
+                const adapter = getAdapter(requestedKind);
+                if (typeof adapter.createInstance !== "function") {
+                    return reply.status(400).send({ detail: `Creating ${requestedKind} requires an app spec` });
+                }
+                meta = await adapter.createInstance({
+                    instanceId,
+                    name: requestedName,
+                    description: req.body.description || "",
+                    cloneFrom: req.body.clone_from,
+                    agentHome: req.body.agent_home ?? req.body.openclaw_home,
+                    cloneOptions: req.body.clone_options,
+                });
+            }
+            else {
+                await instanceManager.installApp(appSpecYaml, instanceId, {
+                    bootstrap: {
+                        name: requestedName,
+                        description: req.body.description || "",
+                        cloneFrom: req.body.clone_from,
+                        agentHome: req.body.agent_home ?? req.body.openclaw_home,
+                        cloneOptions: req.body.clone_options,
+                    },
+                });
+                meta = instanceManager.updateInstance(instanceId, requestedName, req.body.description || "") ?? instanceManager.getInstance(instanceId) ?? {
+                    id: instanceId,
+                    name: requestedName,
+                    description: req.body.description || "",
+                    created_at: new Date().toISOString(),
+                    ...(legacyAppType ? { app_type: legacyAppType } : {}),
+                    ...(appSpec ? { app_id: appSpec.app_id ?? instanceId } : {}),
+                };
+            }
+            // Auto-start if default provider is configured (model ready to use).
+            // Non-openclaw runtimes always auto-start — Hermes/Ollama/custom manage
+            // their own provider plumbing (or don't need one), so skipping the
+            // auto-start would make the first run feel broken.
             const { getPanelConfig } = await import("../config.js");
             const dp = getPanelConfig().default_provider;
-            if (dp && dp.providerId && !dp.skipped) {
-                const svc = await getSvc();
-                svc.startInstance(req.body.id).catch((e) => {
-                    console.warn(`[instances] Auto-start ${req.body.id} failed: ${e.message}`);
-                });
+            const shouldAutoStart = requestedKind !== "openclaw" || (dp && dp.providerId && !dp.skipped);
+            if (shouldAutoStart) {
+                void (async () => {
+                    const result = createFromAppSpec
+                        ? await instanceManager.startApp(instanceId)
+                        : await (await getSvc()).startInstance(instanceId);
+                    if (!result.ok) {
+                        console.warn(`[instances] Auto-start ${instanceId} failed: ${result.error ?? "unknown error"}`);
+                    }
+                })();
                 meta.autoStarted = true;
             }
-            return meta;
+            const decorated = await augmentInstanceMetadata(instanceId, meta);
+            if (meta.autoStarted)
+                decorated.autoStarted = true;
+            return decorated;
         }
         catch (e) {
+            // Structured rejection from createHermesInstance — return 409 with code
+            if (e && e.name === "InstanceCreationRejected") {
+                return reply.status(409).send({
+                    detail: e.hint,
+                    code: e.code,
+                    requestedKind: e.requestedKind,
+                    currentServiceManager: e.currentServiceManager,
+                    currentNomadDriver: e.currentNomadDriver,
+                });
+            }
             return reply.status(409).send({ detail: e.message });
         }
     });
@@ -167,8 +612,12 @@ export async function instanceRoutes(app) {
         const inst = instanceManager.getInstance(req.params.id);
         if (!inst)
             return reply.status(404).send({ detail: "Instance not found" });
-        const status = await svc.getStatus(req.params.id);
-        return { ...inst, service: status, llmError: llmProxy.getLastProxyError(req.params.id) ?? null };
+        const status = await getCachedStatus(svc, req.params.id);
+        return {
+            ...(await augmentInstanceMetadata(req.params.id, inst)),
+            service: status,
+            llmError: llmProxy.getLastProxyError(req.params.id) ?? null,
+        };
     });
     // Update
     app.put("/api/instances/:id", async (req, reply) => {
@@ -203,6 +652,15 @@ export async function instanceRoutes(app) {
         catch (e) {
             return reply.status(e.statusCode || 409).send({ detail: e.message });
         }
+        if (getInstanceBackedInstalledApp(req.params.id)) {
+            const sudoPassword = typeof req.body?.sudoPassword === "string" && req.body.sudoPassword.trim()
+                ? req.body.sudoPassword
+                : undefined;
+            await instanceManager.uninstallApp(req.params.id, sudoPassword ? { exec: { sudoPassword } } : {});
+            statusCache.delete(req.params.id);
+            llmProxy.cleanupInstance(req.params.id);
+            return { ok: true };
+        }
         const svc = await getSvc();
         let stopFailed = false;
         try {
@@ -240,10 +698,39 @@ export async function instanceRoutes(app) {
         return { ok: result.ok, warnings: warnings.length ? warnings : undefined };
     });
     // Config
+    app.get("/api/instances/:id/config-meta", async (req, reply) => {
+        const idErr = validateId(req.params.id);
+        if (idErr)
+            return reply.status(400).send({ detail: idErr });
+        const inst = instanceManager.getInstance(req.params.id);
+        if (!inst)
+            return reply.status(404).send({ detail: "Instance not found" });
+        return getInstanceConfigMeta(req.params.id, inst);
+    });
     app.get("/api/instances/:id/config", async (req, reply) => {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
+        const inst = instanceManager.getInstance(req.params.id);
+        if (!inst)
+            return reply.status(404).send({ detail: "Instance not found" });
+        const agentType = resolveAgentType(inst);
+        if (hasAdapter(agentType)) {
+            try {
+                const doc = await getAdapter(agentType).readConfig(req.params.id);
+                // Back-compat: frontend ConfigForm treats JSON-format responses as
+                // the raw config object (no {format, content} wrapper). Unwrap here
+                // so the existing OpenClaw editor keeps working without touching
+                // every consumer.
+                return doc.format === "json" ? doc.content : doc;
+            }
+            catch (e) {
+                if (/not found/i.test(e?.message || "")) {
+                    return reply.status(404).send({ detail: e.message });
+                }
+                throw e;
+            }
+        }
         const config = llmProxy.getInstanceConfig(req.params.id);
         if (!config)
             return reply.status(404).send({ detail: "Instance or config not found" });
@@ -253,17 +740,39 @@ export async function instanceRoutes(app) {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
+        const inst = instanceManager.getInstance(req.params.id);
+        if (!inst)
+            return reply.status(404).send({ detail: "Instance not found" });
+        const agentType = resolveAgentType(inst);
         // Basic payload validation
         const body = req.body;
-        if (!body || typeof body !== "object" || Array.isArray(body)) {
-            return reply.status(400).send({ detail: "Config must be a JSON object" });
-        }
         const bodyStr = JSON.stringify(body);
         if (bodyStr.length > 512 * 1024) {
             return reply.status(400).send({ detail: "Config too large (max 512KB)" });
         }
         try {
             assertNotLocked(req.params.id);
+            if (hasAdapter(agentType)) {
+                // Accept either a typed ConfigDocument (`{format, content|yaml+env}`)
+                // or a raw JSON object (legacy OpenClaw shape) — the route wraps
+                // the raw shape so adapter.writeConfig always sees the typed
+                // contract. Response is unwrapped symmetrically with GET.
+                let doc;
+                if (isConfigDocument(body)) {
+                    doc = body;
+                }
+                else if (body && typeof body === "object" && !Array.isArray(body)) {
+                    doc = { format: "json", content: body };
+                }
+                else {
+                    return reply.status(400).send({ detail: "Config must be a JSON object" });
+                }
+                const saved = await getAdapter(agentType).writeConfig(req.params.id, doc);
+                return { ok: true, config: saved.format === "json" ? saved.content : saved };
+            }
+            if (!body || typeof body !== "object" || Array.isArray(body)) {
+                return reply.status(400).send({ detail: "Config must be a JSON object" });
+            }
             const saved = await llmProxy.saveInstanceConfig(req.params.id, body);
             return { ok: true, config: saved };
         }
@@ -280,9 +789,12 @@ export async function instanceRoutes(app) {
         if (idErr)
             return reply.status(400).send({ detail: idErr });
         const svc = await getSvc();
-        if (!instanceManager.getInstance(req.params.id)) {
+        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
+        if (getInstanceBackedInstalledApp(req.params.id)) {
+            return instanceManager.getAppStatus(req.params.id);
+        }
         return svc.getStatus(req.params.id);
     });
     app.post("/api/instances/:id/service/start", async (req, reply) => {
@@ -296,13 +808,28 @@ export async function instanceRoutes(app) {
             return reply.status(e.statusCode || 409).send({ detail: e.message });
         }
         const svc = await getSvc();
-        if (!instanceManager.getInstance(req.params.id)) {
+        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
-        const result = await svc.startInstance(req.params.id);
+        const result = getInstanceBackedInstalledApp(req.params.id)
+            ? await instanceManager.startApp(req.params.id)
+            : await svc.startInstance(req.params.id);
         statusCache.delete(req.params.id);
-        if (!result.ok)
-            return reply.status(400).send({ detail: result.error });
+        if (!result.ok) {
+            const resultRecord = result;
+            // Surface the phase tag so the UI can highlight where the start
+            // pipeline failed (running_check / home_conflict / port_alloc /
+            // pre_start_hook / submit). Legacy clients that only read `detail`
+            // keep working.
+            const payload = { detail: result.error };
+            if (resultRecord.phase)
+                payload.phase = resultRecord.phase;
+            if (resultRecord.building)
+                payload.building = true;
+            if (resultRecord.taskId)
+                payload.taskId = resultRecord.taskId;
+            return reply.status(400).send(payload);
+        }
         return result;
     });
     app.post("/api/instances/:id/service/stop", async (req, reply) => {
@@ -316,10 +843,12 @@ export async function instanceRoutes(app) {
             return reply.status(e.statusCode || 409).send({ detail: e.message });
         }
         const svc = await getSvc();
-        if (!instanceManager.getInstance(req.params.id)) {
+        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
-        const result = await svc.stopInstance(req.params.id);
+        const result = getInstanceBackedInstalledApp(req.params.id)
+            ? await instanceManager.stopApp(req.params.id)
+            : await svc.stopInstance(req.params.id);
         statusCache.delete(req.params.id);
         if (!result.ok)
             return reply.status(400).send({ detail: result.error });
@@ -336,370 +865,17 @@ export async function instanceRoutes(app) {
             return reply.status(e.statusCode || 409).send({ detail: e.message });
         }
         const svc = await getSvc();
-        if (!instanceManager.getInstance(req.params.id)) {
+        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
-        const result = await svc.restartInstance(req.params.id);
+        const result = getInstanceBackedInstalledApp(req.params.id)
+            ? await instanceManager.restartApp(req.params.id)
+            : await svc.restartInstance(req.params.id);
         statusCache.delete(req.params.id);
         if (!result.ok)
             return reply.status(400).send({ detail: result.error || "Unknown error" });
         return result;
     });
-    // Plugin check & install — host-side, no container dependency
-    app.get("/api/instances/:id/plugins/check/:channelId", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
-        return {
-            channelId: req.params.channelId,
-            installed: instanceManager.isChannelPluginInstalled(req.params.id, req.params.channelId),
-        };
-    });
-    // Plugin status for all tracked IM plugins (feishu, openclaw-weixin)
-    app.get("/api/instances/:id/plugins/status", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
-        return { plugins: pluginInstaller.getAllPluginStatuses(req.params.id) };
-    });
-    // Quick status: IM binding + skill install state for the quick-skill panel
-    app.get("/api/instances/:id/quick-status", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
-        const id = req.params.id;
-        const cfg = instanceManager.getConfig(id) ?? {};
-        const channels = cfg.channels ?? {};
-        // IM binding: channel must be enabled AND have a non-empty token / accounts
-        const feishuCh = channels["feishu"] ?? channels["lark"] ?? {};
-        const weixinCh = channels["openclaw-weixin"] ?? {};
-        const feishuBound = !!(feishuCh.enabled && (feishuCh.appId || feishuCh.token || feishuCh.deviceToken || feishuCh.accessToken));
-        const weixinBound = !!(weixinCh.enabled && weixinCh.accounts && Object.keys(weixinCh.accounts).length > 0);
-        // Skill install state: scan workspace/skills/ and return all directory names
-        const { readdirSync: fsReaddir, existsSync: fsExists, readFileSync: fsRead } = await import("fs");
-        const { join: fsJoin } = await import("path");
-        const workspaceDir = fsJoin(instanceManager.getOpenclawHome(id), ".openclaw", "workspace");
-        const stateDir = fsJoin(workspaceDir, "skills");
-        let installedSkillDirs = [];
-        try {
-            installedSkillDirs = fsReaddir(stateDir, { withFileTypes: true })
-                .filter(e => e.isDirectory())
-                .map(e => e.name);
-        }
-        catch { }
-        // MCPorter install state — mcporter is installed as a skill in workspace/skills/mcporter
-        const mcporterInstalled = installedSkillDirs.some(d => d.toLowerCase() === 'mcporter');
-        // MCPorter configured servers
-        let mcporterServers = {};
-        const mcporterCfgPath = fsJoin(workspaceDir, "config", "mcporter.json");
-        try {
-            const raw = JSON.parse(fsRead(mcporterCfgPath, "utf8"));
-            mcporterServers = raw.mcpServers ?? {};
-        }
-        catch { }
-        return {
-            im: {
-                feishu: feishuBound,
-                weixin: weixinBound,
-            },
-            installedSkillDirs,
-            mcporterInstalled,
-            mcporterServers,
-        };
-    });
-    // Run `mcporter list --json` and return live server status
-    app.get("/api/instances/:id/mcporter/list", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
-        const id = req.params.id;
-        const openclawHome = instanceManager.getOpenclawHome(id);
-        const workspaceDir = join(openclawHome, ".openclaw", "workspace");
-        const mcporterBinPath = join(workspaceDir, ".npm-global", "bin", "mcporter");
-        const mcporterCfg = join(workspaceDir, "config", "mcporter.json");
-        if (!existsSync(mcporterBinPath)) {
-            return { servers: [], installed: false };
-        }
-        const { execFile } = await import("child_process");
-        const { promisify } = await import("util");
-        const execFileAsync = promisify(execFile);
-        try {
-            const { stdout } = await execFileAsync(mcporterBinPath, ["list", "--json"], {
-                env: { ...process.env, HOME: openclawHome, MCPORTER_CONFIG: mcporterCfg },
-                timeout: 60_000,
-            });
-            const parsed = JSON.parse(stdout);
-            return { servers: parsed.servers ?? [], installed: true };
-        }
-        catch (err) {
-            // execFile throws if exit code != 0; stdout may still have partial JSON
-            const raw = err?.stdout ?? "";
-            try {
-                const parsed = JSON.parse(raw);
-                return { servers: parsed.servers ?? [], installed: true };
-            }
-            catch { }
-            return { servers: [], installed: true, error: err?.message ?? "unknown" };
-        }
-    });
-    // Merge servers into mcporter.json
-    app.post("/api/instances/:id/mcporter/add", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
-        const { servers } = req.body;
-        if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
-            return reply.status(400).send({ detail: "servers must be an object" });
-        }
-        const openclawHome = instanceManager.getOpenclawHome(req.params.id);
-        const workspaceDir = join(openclawHome, ".openclaw", "workspace");
-        const mcporterCfgPath = join(workspaceDir, "config", "mcporter.json");
-        const { readFileSync } = await import("fs");
-        let cfg = { mcpServers: {}, imports: [] };
-        try {
-            cfg = JSON.parse(readFileSync(mcporterCfgPath, "utf8"));
-        }
-        catch { }
-        if (!cfg.mcpServers)
-            cfg.mcpServers = {};
-        // Explicit key-by-key copy instead of Object.assign to prevent prototype pollution:
-        // a crafted body with "__proto__" or "constructor" keys could corrupt the object prototype.
-        const PROTO_KEYS = new Set(["__proto__", "constructor", "prototype"]);
-        for (const [k, v] of Object.entries(servers)) {
-            if (!PROTO_KEYS.has(k))
-                cfg.mcpServers[k] = v;
-        }
-        try {
-            ensureDirContainer(join(workspaceDir, "config"));
-            writeConfigFile(mcporterCfgPath, JSON.stringify(cfg, null, 2));
-        }
-        catch (err) {
-            return reply.status(500).send({ detail: `Write failed: ${err.message}` });
-        }
-        return { ok: true, mcpServers: cfg.mcpServers };
-    });
-    // Remove a server from mcporter.json
-    app.delete("/api/instances/:id/mcporter/:serverName", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
-        const { serverName } = req.params;
-        if (!serverName || typeof serverName !== "string") {
-            return reply.status(400).send({ detail: "serverName is required" });
-        }
-        const openclawHome = instanceManager.getOpenclawHome(req.params.id);
-        const workspaceDir = join(openclawHome, ".openclaw", "workspace");
-        const mcporterCfgPath = join(workspaceDir, "config", "mcporter.json");
-        const { readFileSync } = await import("fs");
-        let cfg = { mcpServers: {}, imports: [] };
-        try {
-            cfg = JSON.parse(readFileSync(mcporterCfgPath, "utf8"));
-        }
-        catch { }
-        if (!cfg.mcpServers || !(serverName in cfg.mcpServers)) {
-            return reply.status(404).send({ detail: `Server '${serverName}' not found` });
-        }
-        delete cfg.mcpServers[serverName];
-        try {
-            writeConfigFile(mcporterCfgPath, JSON.stringify(cfg, null, 2));
-        }
-        catch (err) {
-            return reply.status(500).send({ detail: `Write failed: ${err.message}` });
-        }
-        return { ok: true, mcpServers: cfg.mcpServers };
-    });
-    // Delete a skill directory from workspace/skills/
-    app.delete("/api/instances/:id/skills/:skillDir", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
-        const { skillDir } = req.params;
-        // Prevent path traversal
-        if (!skillDir || skillDir.includes("/") || skillDir.includes("..") || skillDir.startsWith(".")) {
-            return reply.status(400).send({ detail: "Invalid skill directory name" });
-        }
-        const openclawHome = instanceManager.getOpenclawHome(req.params.id);
-        const skillPath = join(openclawHome, ".openclaw", "workspace", "skills", skillDir);
-        const { existsSync: fsEx, rmSync } = await import("fs");
-        if (!fsEx(skillPath)) {
-            return reply.status(404).send({ detail: `Skill '${skillDir}' not found` });
-        }
-        try {
-            rmSync(skillPath, { recursive: true, force: true });
-        }
-        catch (err) {
-            return reply.status(500).send({ detail: `Delete failed: ${err.message}` });
-        }
-        return { ok: true };
-    });
-    app.post("/api/instances/:id/plugins/install", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
-        try {
-            assertNotLocked(req.params.id);
-        }
-        catch (e) {
-            return reply.status(e.statusCode || 409).send({ detail: e.message });
-        }
-        const { channelId } = req.body;
-        if (!channelId || typeof channelId !== "string") {
-            return reply.status(400).send({ detail: "channelId is required" });
-        }
-        const pkg = instanceManager.CHANNEL_PLUGIN_MAP[channelId];
-        if (!pkg) {
-            return reply.status(400).send({ detail: `Unknown channel: ${channelId}` });
-        }
-        const pStatus = pluginInstaller.getPluginStatus(req.params.id, channelId);
-        if (pStatus.status === "installed")
-            return { ok: true, status: "already_installed" };
-        if (pStatus.status === "installing")
-            return { ok: true, status: "installing" };
-        pluginInstaller.enqueueInstall(req.params.id, channelId);
-        return { ok: true, status: "queued" };
-    });
-    // ── Helper: ensure a channel plugin is installed (check-only) ──
-    async function ensurePluginInstalled(instanceId, channelId) {
-        if (!instanceManager.CHANNEL_PLUGIN_MAP[channelId])
-            return;
-        if (!instanceManager.isChannelPluginInstalled(instanceId, channelId)) {
-            throw new Error(`Plugin ${channelId} is not installed. Please install it from the config page.`);
-        }
-    }
-    // ── Feishu/Lark OAuth Device Code Login ──
-    const FEISHU_AUTH_URL = "https://accounts.feishu.cn";
-    const MAX_LOGIN_SESSIONS = 100;
-    const feishuLogins = new Map();
-    app.post("/api/instances/:id/feishu/login", async (req, reply) => {
-        const channelKey = req.body?.channelKey || "feishu";
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
-        // Require instance to be running
-        const svc = await getSvc();
-        const svcStatus = await svc.getStatus(req.params.id);
-        if (svcStatus.status !== "running") {
-            return reply.status(400).send({ detail: "Instance must be running first" });
-        }
-        // Auto-install feishu plugin if not present
-        await ensurePluginInstalled(req.params.id, channelKey);
-        try {
-            // Step 1: init
-            await fetch(`${FEISHU_AUTH_URL}/oauth/v1/app/registration`, {
-                method: "POST",
-                headers: { "Content-Type": "application/x-www-form-urlencoded" },
-                body: "action=init",
-                signal: AbortSignal.timeout(30_000),
-            });
-            // Step 2: begin — get QR code URL and device code
-            const beginResp = await fetch(`${FEISHU_AUTH_URL}/oauth/v1/app/registration`, {
-                method: "POST",
-                headers: { "Content-Type": "application/x-www-form-urlencoded" },
-                body: "action=begin&archetype=PersonalAgent&auth_method=client_secret&request_user_info=open_id",
-                signal: AbortSignal.timeout(30_000),
-            });
-            if (!beginResp.ok)
-                throw new Error(`Feishu API error: ${beginResp.status}`);
-            const beginData = await beginResp.json();
-            const sessionKey = `${req.params.id}-${channelKey}-${Date.now()}`;
-            feishuLogins.set(sessionKey, {
-                instanceId: req.params.id,
-                deviceCode: beginData.device_code,
-                startedAt: Date.now(),
-                interval: beginData.interval || 5,
-                expireIn: beginData.expire_in || 600,
-                channelKey,
-            });
-            // Purge expired + enforce cap
-            for (const [k, v] of feishuLogins) {
-                if (Date.now() - v.startedAt > v.expireIn * 1000)
-                    feishuLogins.delete(k);
-            }
-            while (feishuLogins.size > MAX_LOGIN_SESSIONS) {
-                feishuLogins.delete(feishuLogins.keys().next().value);
-            }
-            return { qrcodeUrl: beginData.verification_uri_complete, sessionKey };
-        }
-        catch (e) {
-            return reply.status(502).send({ detail: e.message || "Failed to start Feishu login" });
-        }
-    });
-    app.get("/api/instances/:id/feishu/login/:sessionKey", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        const login = feishuLogins.get(req.params.sessionKey);
-        if (!login)
-            return reply.status(404).send({ detail: "Login session not found or expired" });
-        if (login.instanceId !== req.params.id)
-            return reply.status(403).send({ detail: "Session belongs to a different instance" });
-        if (Date.now() - login.startedAt > login.expireIn * 1000) {
-            feishuLogins.delete(req.params.sessionKey);
-            return { status: "expired", connected: false, message: "QR code expired, please regenerate." };
-        }
-        try {
-            const resp = await fetch(`${FEISHU_AUTH_URL}/oauth/v1/app/registration`, {
-                method: "POST",
-                headers: { "Content-Type": "application/x-www-form-urlencoded" },
-                body: `action=poll&device_code=${encodeURIComponent(login.deviceCode)}`,
-                signal: AbortSignal.timeout(10_000),
-            });
-            const data = await resp.json();
-            if (data.client_id && data.client_secret) {
-                const storedChannelKey = login.channelKey || "feishu";
-                feishuLogins.delete(req.params.sessionKey);
-                const domain = data.user_info?.tenant_brand === "lark" ? "lark" : "feishu";
-                instanceManager.saveFeishuCredentials(req.params.id, {
-                    appId: data.client_id,
-                    appSecret: data.client_secret,
-                    domain,
-                    channelKey: storedChannelKey,
-                });
-                return {
-                    status: "confirmed", connected: true, domain,
-                    message: domain === "lark" ? "Lark bot configured!" : "Feishu bot configured!",
-                };
-            }
-            if (data.error === "authorization_pending") {
-                return { status: "waiting", connected: false, message: "Waiting for scan..." };
-            }
-            if (data.error === "expired_token") {
-                feishuLogins.delete(req.params.sessionKey);
-                return { status: "expired", connected: false, message: "QR code expired, please regenerate." };
-            }
-            return { status: "waiting", connected: false, message: "Waiting for scan..." };
-        }
-        catch (e) {
-            return reply.status(502).send({ detail: e.message || "Poll failed" });
-        }
-    });
     // ── Pairing ──────────────────────────────────────────────────────────────
     // Pairing codes are uppercase alphanumeric, 4-16 chars (e.g. LVU7PNYK).
     const PAIRING_CODE_RE = /^[A-Z0-9]{4,16}$/;
@@ -709,20 +885,33 @@ export async function instanceRoutes(app) {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
+        const inst = instanceManager.getInstance(req.params.id);
+        if (!inst) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
+        const capabilities = await getInstanceCapabilities(req.params.id, inst);
+        if (!capabilities.pairing.list) {
+            return reply.status(501).send({ detail: "Pairing list is not supported for this runtime" });
+        }
+        const agentType = resolveAgentType(inst);
         const svc = await getSvc();
-        const result = await svc.exec(req.params.id, ["openclaw", "pairing", "list"], 15_000);
+        // Pure adapter dispatch — no hardcoded kind fallback.
+        const cmd = await getAdapter(agentType).buildPairingListCommand(req.params.id);
+        const result = await svc.exec(req.params.id, cmd, 15_000);
         return { output: result.stdout + result.stderr, exitCode: result.exitCode };
     });
     app.post("/api/instances/:id/pairing/approve", async (req, reply) => {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
+        const inst = instanceManager.getInstance(req.params.id);
+        if (!inst) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
+        const capabilities = await getInstanceCapabilities(req.params.id, inst);
+        if (!capabilities.pairing.approve) {
+            return reply.status(501).send({ detail: "Pairing approve is not supported for this runtime" });
+        }
         const { channel, code, notify } = req.body ?? {};
         if (!channel || !PAIRING_CHANNEL_RE.test(channel)) {
             return reply.status(400).send({ detail: "Invalid channel: must be lowercase alphanumeric/hyphen/underscore" });
@@ -730,9 +919,12 @@ export async function instanceRoutes(app) {
         if (!code || !PAIRING_CODE_RE.test(code)) {
             return reply.status(400).send({ detail: "Invalid pairing code: must be 4-16 uppercase alphanumeric characters" });
         }
-        const cmd = ["openclaw", "pairing", "approve", channel, code];
-        if (notify)
-            cmd.push("--notify");
+        const agentType = resolveAgentType(inst);
+        const cmd = await getAdapter(agentType).buildPairingApproveCommand(req.params.id, {
+            channel,
+            code,
+            notify,
+        });
         const svc = await getSvc();
         const result = await svc.exec(req.params.id, cmd, 15_000);
         if (result.exitCode !== 0) {
@@ -740,251 +932,259 @@ export async function instanceRoutes(app) {
         }
         return { ok: true, output: (result.stdout + result.stderr).trim() };
     });
-    // WeChat accounts query
-    app.get("/api/instances/:id/weixin/accounts", async (req, reply) => {
+    // Agent chat (inline chat panel for runtimes that expose an OpenAI-compat
+    // HTTP chat completion endpoint and declare chatPanel="inline" in their
+    // capability profile — currently only Hermes).
+    //
+    // Flow: panel JWT auth → read per-instance API_SERVER_KEY from agent-home/.env →
+    // read allocated host port from runtime.ports → POST forward to
+    // http://127.0.0.1:<port>/v1/chat/completions.
+    //
+    // The response is framed as Server-Sent Events with periodic `: ping`
+    // heartbeats while we wait for the agent to finish. Long-running agent
+    // tasks (tool loops, thinking, cold starts) can legitimately run far
+    // longer than a browser's default fetch-idle tolerance; the heartbeat
+    // keeps the connection visibly alive so the client can tell "still
+    // working" apart from "network dead". Once the agent responds we emit
+    // a single `result` event carrying the upstream JSON, then `done`.
+    // Errors before headers are sent fall back to HTTP 5xx JSON; errors
+    // after hijack go out as an `event: error` SSE payload.
+    //
+    // This is a thin server-side forwarder, NOT a new LLM proxy. The actual
+    // LLM call still goes through Hermes → jsproxy → JishuShell /proxy/v1 →
+    // upstream provider.
+    app.post("/api/instances/:id/agent/chat", async (req, reply) => {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
+        const rawInst = instanceManager.getInstance(req.params.id);
+        if (!rawInst)
             return reply.status(404).send({ detail: "Instance not found" });
+        // getInstance returns raw instance.json without `capabilities` (that's
+        // runtime-synthesized per §32.4). Use augmentInstanceMetadata so we
+        // read the adapter's live defaultCapabilities.
+        const inst = await augmentInstanceMetadata(req.params.id, rawInst);
+        // Only runtimes declaring chatPanel="inline" are supported here
+        const chatPanel = inst?.capabilities?.gateway?.chatPanel;
+        if (chatPanel !== "inline") {
+            return reply.status(400).send({
+                detail: `Runtime "${inst.agentType}" does not support inline chat (chatPanel=${chatPanel})`,
+            });
+        }
+        // Adapter-owned dispatch: the route no longer hardcodes Hermes's env
+        // var name or endpoint path. Any adapter that declares chatPanel
+        // "inline" MUST also supply `inlineChatDescriptor` (api key env var +
+        // optional path/header/timeout) so this forwarder can reach its agent.
+        const agentType = resolveAgentType(inst);
+        const adapter = getAdapter(agentType);
+        const desc = adapter.inlineChatDescriptor;
+        if (!desc) {
+            return reply.status(500).send({
+                detail: `Runtime "${agentType}" declares chatPanel=inline but no inlineChatDescriptor`,
+            });
+        }
+        // Resolve host port from the persisted RuntimeSpec.ports[] allocation.
+        const ports = Array.isArray(inst?.runtime?.ports) ? inst.runtime.ports : [];
+        const gw = ports.find((p) => p?.name === "gateway") || ports[0];
+        const hostPort = Number(gw?.hostPort) || 0;
+        if (!hostPort) {
+            return reply.status(500).send({ detail: "Gateway host port not allocated" });
+        }
+        // Agent API key lives in the adapter-managed secretEnv file. Adapter
+        // declares which env var holds it (Hermes → API_SERVER_KEY).
+        const secretEnv = inst?.paths?.secretEnv;
+        if (!secretEnv) {
+            return reply.status(500).send({ detail: "Instance has no secretEnv path" });
+        }
+        const envVars = instanceManager.parseEnvFile(secretEnv);
+        const apiKey = envVars[desc.apiKeyEnvVar] || "";
+        if (!apiKey) {
+            return reply.status(500).send({
+                detail: `${desc.apiKeyEnvVar} not set in instance env; agent may not be configured`,
+            });
+        }
+        const endpointPath = desc.endpointPath ?? "/v1/chat/completions";
+        const authHeader = desc.authHeader ?? "Authorization";
+        const authScheme = desc.authScheme ?? "Bearer ";
+        // Upstream budget: the Hermes call itself still gets a hard ceiling so
+        // a wedged container can't hold the connection forever. Adapter can
+        // extend this via inlineChatDescriptor.timeoutMs; default is 30 min
+        // which comfortably covers multi-step tool loops.
+        const upstreamTimeoutMs = desc.timeoutMs ?? 30 * 60_000;
+        // Don't hardcode 127.0.0.1. Nomad's docker driver binds the published
+        // port to whichever loopback address it enumerates first from `lo`, and
+        // on modern Linux (Debian 12, Ubuntu 22.04+) that's frequently `::1`
+        // rather than `127.0.0.1` — so a hardcoded IPv4 fetch() returns
+        // ECONNREFUSED and the user sees "Failed to reach agent".
+        const gwHost = await instanceManager.getGatewayHost(req.params.id);
+        const target = `http://${instanceManager.urlHost(gwHost)}:${hostPort}${endpointPath}`;
+        // Hijack the response so we own the raw socket — lets us flush SSE
+        // headers + heartbeats before the upstream fetch resolves.
+        reply.hijack();
+        const raw = reply.raw;
+        raw.writeHead(200, {
+            "Content-Type": "text/event-stream; charset=utf-8",
+            "Cache-Control": "no-cache, no-transform",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        });
+        const writeEvent = (event, data) => {
+            const payload = typeof data === "string" ? data : JSON.stringify(data);
+            raw.write(`event: ${event}\ndata: ${payload}\n\n`);
+        };
+        // Kick off one heartbeat immediately so buffering proxies flush.
+        raw.write(": ping\n\n");
+        const HEARTBEAT_MS = 10_000;
+        const heartbeat = setInterval(() => {
+            try {
+                raw.write(": ping\n\n");
+            }
+            catch { /* socket closed */ }
+        }, HEARTBEAT_MS);
+        // Abort upstream if the client goes away.
+        const abortController = new AbortController();
+        const clientGone = () => abortController.abort();
+        req.raw.on("close", clientGone);
+        const upstreamTimer = setTimeout(() => abortController.abort(), upstreamTimeoutMs);
+        try {
+            const resp = await fetch(target, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    [authHeader]: `${authScheme}${apiKey}`,
+                },
+                body: JSON.stringify(req.body || {}),
+                signal: abortController.signal,
+            });
+            const text = await resp.text();
+            clearInterval(heartbeat);
+            clearTimeout(upstreamTimer);
+            req.raw.off("close", clientGone);
+            writeEvent("result", {
+                status: resp.status,
+                contentType: resp.headers.get("content-type") || "application/json",
+                body: text,
+            });
+            writeEvent("done", {});
+            raw.end();
+        }
+        catch (e) {
+            clearInterval(heartbeat);
+            clearTimeout(upstreamTimer);
+            req.raw.off("close", clientGone);
+            try {
+                writeEvent("error", { detail: `Failed to reach agent: ${e?.message || String(e)}` });
+                raw.end();
+            }
+            catch { /* socket already closed */ }
         }
-        return { accounts: instanceManager.getWeixinAccounts(req.params.id) };
     });
-    // ── WeChat QR Login ──
-    const WEIXIN_API_BASE = "https://ilinkai.weixin.qq.com";
-    const WEIXIN_BOT_TYPE = "3";
-    // In-memory active login sessions (short-lived, 5 min TTL)
-    const weixinLogins = new Map();
-    app.post("/api/instances/:id/weixin/login", async (req, reply) => {
+    app.post("/api/instances/:id/provides/:capability/terminal/session", async (req, reply) => {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id)) {
+        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
-        // Require instance to be running
-        const svc = await getSvc();
-        const svcStatus = await svc.getStatus(req.params.id);
-        if (svcStatus.status !== "running") {
-            return reply.status(400).send({ detail: "Instance must be running first" });
-        }
-        // Auto-install weixin plugin if not present
-        await ensurePluginInstalled(req.params.id, "openclaw-weixin");
         try {
-            const resp = await fetch(`${WEIXIN_API_BASE}/ilink/bot/get_bot_qrcode?bot_type=${WEIXIN_BOT_TYPE}`, { signal: AbortSignal.timeout(30_000) });
-            if (!resp.ok)
-                throw new Error(`WeChat API error: ${resp.status}`);
-            const data = await resp.json();
-            const sessionKey = `${req.params.id}-${Date.now()}`;
-            weixinLogins.set(sessionKey, {
+            const provide = resolveTerminalProvide(req.params.id, req.params.capability);
+            const terminal = provide.terminal;
+            const input = typeof req.body?.input === "string" ? req.body.input : "";
+            const command = buildTerminalCommand(terminal.command, input);
+            const session = startTerminalSession({
                 instanceId: req.params.id,
-                qrcode: data.qrcode,
-                qrcodeUrl: data.qrcode_img_content,
-                startedAt: Date.now(),
+                capability: req.params.capability,
+                terminal,
+                command,
             });
-            // Purge expired sessions + enforce cap
-            for (const [k, v] of weixinLogins) {
-                if (Date.now() - v.startedAt > 5 * 60_000)
-                    weixinLogins.delete(k);
-            }
-            while (weixinLogins.size > MAX_LOGIN_SESSIONS) {
-                weixinLogins.delete(weixinLogins.keys().next().value);
-            }
-            return { qrcodeUrl: data.qrcode_img_content, sessionKey };
+            return reply.send(session);
         }
-        catch (e) {
-            return reply.status(502).send({ detail: e.message || "Failed to get QR code" });
+        catch (error) {
+            return reply.status(400).send({ detail: error?.message || "Failed to start terminal session" });
         }
     });
-    app.get("/api/instances/:id/weixin/login/:sessionKey", async (req, reply) => {
+    app.get("/api/instances/:id/provides/:capability/terminal/session/:sessionId/stream", async (req, reply) => {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
-        const login = weixinLogins.get(req.params.sessionKey);
-        if (!login)
-            return reply.status(404).send({ detail: "Login session not found or expired" });
-        if (login.instanceId !== req.params.id)
-            return reply.status(403).send({ detail: "Session belongs to a different instance" });
-        if (Date.now() - login.startedAt > 5 * 60_000) {
-            weixinLogins.delete(req.params.sessionKey);
-            return { status: "expired", connected: false, message: "QR code expired, please regenerate." };
+        if (!assertTerminalSessionOwner(req.params.sessionId, req.params.id, req.params.capability)) {
+            return reply.status(404).send({ detail: "Terminal session not found" });
+        }
+        const session = getTerminalSession(req.params.sessionId);
+        if (!session)
+            return reply.status(404).send({ detail: "Terminal session not found" });
+        const since = Math.max(parseInt(req.query.since || "0", 10) || 0, 0);
+        reply.hijack();
+        const raw = reply.raw;
+        raw.writeHead(200, {
+            "Content-Type": "text/event-stream; charset=utf-8",
+            "Cache-Control": "no-cache, no-transform",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        });
+        const writeEvent = (event, data) => {
+            raw.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+        };
+        for (const event of getTerminalSessionEvents(req.params.sessionId, since)) {
+            writeEvent(event.type, event);
         }
-        try {
-            const resp = await fetch(`${WEIXIN_API_BASE}/ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(login.qrcode)}`, { headers: { "iLink-App-ClientVersion": "1" }, signal: AbortSignal.timeout(35_000) });
-            if (!resp.ok)
-                throw new Error(`Status poll failed: ${resp.status}`);
-            const data = await resp.json();
-            if (data.status === "confirmed" && data.ilink_bot_id) {
-                weixinLogins.delete(req.params.sessionKey);
-                // Save credentials to instance
-                try {
-                    instanceManager.saveWeixinCredentials(req.params.id, {
-                        accountId: data.ilink_bot_id,
-                        token: data.bot_token || "",
-                        baseUrl: data.baseurl || WEIXIN_API_BASE,
-                        userId: data.ilink_user_id || "",
-                    });
-                }
-                catch (e) {
-                    console.error(`[weixin-login] Failed to save credentials: ${e.message}`);
-                    return reply.status(500).send({
-                        status: "confirmed", connected: false,
-                        detail: "WeChat authenticated but failed to save credentials: " + e.message,
-                    });
-                }
-                return {
-                    status: "confirmed", connected: true,
-                    accountId: data.ilink_bot_id,
-                    message: "WeChat connected!",
-                };
-            }
-            if (data.status === "expired") {
-                // Auto-refresh QR
-                try {
-                    const refreshResp = await fetch(`${WEIXIN_API_BASE}/ilink/bot/get_bot_qrcode?bot_type=${WEIXIN_BOT_TYPE}`, { signal: AbortSignal.timeout(30_000) });
-                    if (refreshResp.ok) {
-                        const refreshData = await refreshResp.json();
-                        login.qrcode = refreshData.qrcode;
-                        login.qrcodeUrl = refreshData.qrcode_img_content;
-                        login.startedAt = Date.now();
-                        return {
-                            status: "refreshed", connected: false,
-                            qrcodeUrl: refreshData.qrcode_img_content,
-                            message: "QR code refreshed, please scan again.",
-                        };
-                    }
-                }
-                catch { /* fall through */ }
-                weixinLogins.delete(req.params.sessionKey);
-                return { status: "expired", connected: false, message: "QR code expired, please regenerate." };
+        if (!session.running) {
+            writeEvent("done", { sessionId: req.params.sessionId });
+            raw.end();
+            return;
+        }
+        const unsubscribe = subscribeTerminalSession(req.params.sessionId, (event) => {
+            writeEvent(event.type, event);
+            if (event.type === "exit" || event.type === "error") {
+                writeEvent("done", { sessionId: req.params.sessionId });
+                unsubscribe?.();
+                raw.end();
             }
-            return {
-                status: data.status, connected: false,
-                message: data.status === "scaned" ? "Scanned, please confirm on WeChat..." : "Waiting for scan...",
-            };
+        });
+        req.raw.on("close", () => {
+            unsubscribe?.();
+        });
+        raw.write(": ping\n\n");
+    });
+    app.post("/api/instances/:id/provides/:capability/terminal/session/:sessionId/input", async (req, reply) => {
+        const idErr = validateId(req.params.id);
+        if (idErr)
+            return reply.status(400).send({ detail: idErr });
+        if (!assertTerminalSessionOwner(req.params.sessionId, req.params.id, req.params.capability)) {
+            return reply.status(404).send({ detail: "Terminal session not found" });
         }
-        catch (e) {
-            return reply.status(502).send({ detail: e.message || "Status poll failed" });
+        try {
+            sendTerminalSessionInput(req.params.sessionId, typeof req.body?.input === "string" ? req.body.input : "");
+            return reply.send({ ok: true });
+        }
+        catch (error) {
+            return reply.status(400).send({ detail: error?.message || "Failed to send terminal input" });
         }
     });
-    // Usage
-    app.get("/api/instances/:id/usage", async (req, reply) => {
+    app.post("/api/instances/:id/provides/:capability/terminal/session/:sessionId/stop", async (req, reply) => {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
-        const inst = instanceManager.getInstance(req.params.id);
-        if (!inst)
-            return reply.status(404).send({ detail: "Instance not found" });
-        const openclawHome = instanceManager.getOpenclawHome(req.params.id);
-        const sessionsIndex = join(openclawHome, ".openclaw", "agents", "main", "sessions", "sessions.json");
-        const emptyTotals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, costTotal: 0, messages: 0 };
-        if (!existsSync(sessionsIndex))
-            return { sessions: [], totals: emptyTotals };
-        // Check file size before reading
-        const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
-        const indexStat = await stat(sessionsIndex);
-        if (indexStat.size > MAX_FILE_SIZE) {
-            return reply.status(400).send({ detail: "sessions.json exceeds 10MB size limit" });
-        }
-        let sessionsMap;
+        if (!assertTerminalSessionOwner(req.params.sessionId, req.params.id, req.params.capability)) {
+            return reply.status(404).send({ detail: "Terminal session not found" });
+        }
         try {
-            const raw = await readFile(sessionsIndex, "utf-8");
-            sessionsMap = JSON.parse(raw);
+            stopTerminalSession(req.params.sessionId);
+            return reply.send({ ok: true });
         }
-        catch {
-            return reply.status(500).send({ detail: "Failed to parse sessions.json" });
+        catch (error) {
+            return reply.status(400).send({ detail: error?.message || "Failed to stop terminal session" });
         }
-        const sessions = [];
-        const totals = { ...emptyTotals };
-        for (const [sessionKey, sessionMeta] of Object.entries(sessionsMap)) {
-            const sessionFile = sessionMeta?.sessionFile;
-            if (!sessionFile || !existsSync(sessionFile))
-                continue;
-            // Prevent path traversal: sessionFile must be under the instance's openclaw home.
-            // Use realpathSync to resolve symlinks and prevent symlink-based bypasses.
-            try {
-                const resolvedSession = realpathSync(sessionFile);
-                const resolvedHome = realpathSync(openclawHome);
-                if (!resolvedSession.startsWith(resolvedHome + "/") && resolvedSession !== resolvedHome)
-                    continue;
-            }
-            catch {
-                continue;
-            }
-            // Check session file size before reading
-            let sessionStat;
-            try {
-                sessionStat = await stat(sessionFile);
-            }
-            catch {
-                continue;
-            }
-            if (sessionStat.size > MAX_FILE_SIZE)
-                continue;
-            const sessionUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, costTotal: 0, messages: 0 };
-            let model = "";
-            let firstTs = "";
-            let lastTs = "";
-            const originLabel = sessionMeta?.origin?.label || "";
-            const channel = sessionMeta?.origin?.provider || "";
-            let sessionContent;
-            try {
-                sessionContent = await readFile(sessionFile, "utf-8");
-            }
-            catch {
-                continue;
-            }
-            for (const line of sessionContent.split("\n")) {
-                let entry;
-                try {
-                    entry = JSON.parse(line.trim());
-                }
-                catch {
-                    continue;
-                }
-                if (entry.type !== "message")
-                    continue;
-                const msg = entry.message || {};
-                const ts = entry.timestamp || "";
-                if (ts && !firstTs)
-                    firstTs = ts;
-                if (ts)
-                    lastTs = ts;
-                if (msg.role === "assistant") {
-                    if (!model && msg.model)
-                        model = msg.model;
-                    const usage = msg.usage;
-                    if (usage) {
-                        sessionUsage.input += usage.input || 0;
-                        sessionUsage.output += usage.output || 0;
-                        sessionUsage.cacheRead += usage.cacheRead || 0;
-                        sessionUsage.cacheWrite += usage.cacheWrite || 0;
-                        sessionUsage.totalTokens += usage.totalTokens || 0;
-                        if (typeof usage.cost === "object")
-                            sessionUsage.costTotal += usage.cost.total || 0;
-                    }
-                    sessionUsage.messages++;
-                }
-                else if (msg.role === "user") {
-                    sessionUsage.messages++;
-                }
-            }
-            sessions.push({ key: sessionKey, model, channel, origin: originLabel, firstMessage: firstTs, lastMessage: lastTs, usage: sessionUsage });
-            for (const k of ["input", "output", "cacheRead", "cacheWrite", "totalTokens", "messages"]) {
-                totals[k] += sessionUsage[k];
-            }
-            totals.costTotal += sessionUsage.costTotal;
-        }
-        sessions.sort((a, b) => (b.lastMessage || "").localeCompare(a.lastMessage || ""));
-        return { sessions, totals };
     });
+    app.all("/api/instances/:id/provides/:capability", async (req, reply) => proxyProvidedCapability(req, reply));
+    app.all("/api/instances/:id/provides/:capability/*", async (req, reply) => proxyProvidedCapability(req, reply));
     // Logs
     app.get("/api/instances/:id/logs", async (req, reply) => {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
         const svc = await getSvc();
-        if (!instanceManager.getInstance(req.params.id)) {
+        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
         const logType = req.query.log_type || "stderr";
@@ -993,7 +1193,9 @@ export async function instanceRoutes(app) {
         }
         const MAX_LOG_LINES = 5000;
         const lines = Math.min(parseInt(req.query.lines || "100", 10) || 100, MAX_LOG_LINES);
-        const logLines = await svc.getLogs(req.params.id, lines, logType);
+        const logLines = getInstanceBackedInstalledApp(req.params.id)
+            ? await instanceManager.getAppLogs(req.params.id, "", lines, logType)
+            : await svc.getLogs(req.params.id, lines, logType);
         return { lines: logLines };
     });
     // Admin: re-encrypt all instance secrets with current AES key
@@ -1071,279 +1273,60 @@ export async function instanceRoutes(app) {
         }
         return { ok: true, results };
     });
-    app.get("/api/instances/:id/gateway-launch", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        const inst = instanceManager.getInstance(req.params.id);
-        if (!inst)
-            return reply.status(404).send({ detail: "Instance not found" });
-        const panelOrigin = inferRequestOrigin(req);
-        if (panelOrigin) {
-            let addedAllowedOrigin = false;
-            try {
-                addedAllowedOrigin = ensureControlUiAllowedOrigin(req.params.id, panelOrigin);
-            }
-            catch (err) {
-                console.warn(`[gateway-launch] failed to add allowed origin for ${req.params.id}:`, err.message || err);
-            }
-            if (addedAllowedOrigin) {
-                await restartRunningInstanceForControlUiOrigin(req.params.id, panelOrigin);
-            }
+    // ── Docker image check & pull ───────────────────────────────────────────
+    // Generic Docker operations used by NewInstance UI to verify / pull runtime
+    // images before creating an instance. Framework-level (not adapter-scoped)
+    // because every container runtime shares the same docker CLI here.
+    app.get("/api/docker/image-check", async (req, reply) => {
+        const image = req.query.image;
+        if (!image || typeof image !== "string") {
+            return reply.status(400).send({ detail: "Missing 'image' query parameter" });
+        }
+        // Validate image name to prevent command injection
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9\-_.:/@]*$/.test(image) || image.length > 256) {
+            return reply.status(400).send({ detail: "Invalid Docker image name" });
         }
-        const baseUrl = `/api/instances/${req.params.id}/gateway/`;
-        const cfg = instanceManager.getStoredConfig(req.params.id);
-        const token = cfg?.gateway?.auth?.token;
-        if (typeof token !== "string" || !token.trim()) {
-            return { url: baseUrl };
+        try {
+            const { execFileSync } = await import("child_process");
+            execFileSync("docker", ["image", "inspect", image], { timeout: 10000, stdio: "ignore" });
+            return { exists: true, image };
+        }
+        catch {
+            return { exists: false, image };
         }
-        return { url: `${baseUrl}#token=${encodeURIComponent(token.trim())}` };
     });
-    // Reverse-proxy to OpenClaw gateway web UI (gateway binds 127.0.0.1 only)
-    // NOTE: WebSocket upgrades are handled via server.on('upgrade') in server.ts
-    //       to avoid Fastify's HTTP lifecycle timeouts killing long-lived connections.
-    const gatewayProxy = async (request, reply) => {
-        const { id } = request.params;
-        const idErr = validateId(id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        const inst = instanceManager.getInstance(id);
-        if (!inst)
-            return reply.status(404).send({ detail: "Instance not found" });
-        const port = instanceManager.getGatewayPort(id);
-        const gwHost = await instanceManager.getGatewayHost(id);
-        const suffix = request.params["*"] || "";
-        const qs = request.url.includes("?") ? request.url.slice(request.url.indexOf("?")) : "";
-        // Raw HTTP proxy — stream the request body and preserve headers.
-        // Bracket IPv6 literals (`::1`) because `http://::1:18789/` is not a
-        // valid URL; see instance-manager.urlHost. Nomad 1.6.5 on Linux with
-        // `network_interface = "lo"` can allocate the task port to `::1`
-        // whenever the kernel enumerates the lo interface's v6 address first.
-        const urlGwHost = instanceManager.urlHost(gwHost);
-        const targetUrl = `http://${urlGwHost}:${port}/${suffix}${qs}`;
+    app.post("/api/docker/image-pull", async (req, reply) => {
+        const image = req.body?.image;
+        if (!image || typeof image !== "string") {
+            return reply.status(400).send({ detail: "Missing 'image' in request body" });
+        }
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9\-_.:/@]*$/.test(image) || image.length > 256) {
+            return reply.status(400).send({ detail: "Invalid Docker image name" });
+        }
         try {
-            // Build upstream headers: keep everything except hop-by-hop, rewrite host/origin
-            const fwdHeaders = {};
-            const rawHeaders = request.raw.headers;
-            for (const [k, v] of Object.entries(rawHeaders)) {
-                if (v === undefined)
-                    continue;
-                const lk = k.toLowerCase();
-                if (HOP_BY_HOP.has(lk) ||
-                    PROXY_IDENTITY_HEADERS.has(lk) ||
-                    lk === "host" ||
-                    // Strip panel auth credentials — do not leak to downstream OpenClaw gateway
-                    lk === "cookie" ||
-                    lk === "authorization")
-                    continue;
-                fwdHeaders[k] = Array.isArray(v) ? v.join(", ") : v;
-            }
-            fwdHeaders["host"] = `${urlGwHost}:${port}`;
-            // Request uncompressed responses — avoids having to decompress before HTML injection,
-            // and lets us stream non-HTML bodies without content-encoding mismatch.
-            fwdHeaders["accept-encoding"] = "identity";
-            // Use http.request for raw body streaming (avoids Fastify's parsed body)
-            const upstreamRes = await new Promise((resolve, reject) => {
-                const proxyReq = httpRequest(targetUrl, {
-                    method: request.method,
-                    headers: fwdHeaders,
-                }, resolve);
-                proxyReq.on("error", reject);
-                // Pipe the raw incoming body directly to the upstream
-                if (request.method !== "GET" && request.method !== "HEAD") {
-                    request.raw.pipe(proxyReq);
-                }
-                else {
-                    proxyReq.end();
-                }
-            });
-            reply.status(upstreamRes.statusCode || 502);
-            // Forward response headers — preserve most, rewrite security headers for iframe
-            for (const [k, v] of Object.entries(upstreamRes.headers)) {
-                if (v === undefined)
-                    continue;
-                const lk = k.toLowerCase();
-                if (HOP_BY_HOP.has(lk))
-                    continue;
-                if (lk === "x-frame-options") {
-                    reply.header("x-frame-options", "SAMEORIGIN");
-                    continue;
-                }
-                if (lk === "content-security-policy") {
-                    // Replace frame-ancestors directive, preserve the rest
-                    const csp = Array.isArray(v) ? v.join(", ") : v;
-                    const rewritten = csp.replace(/frame-ancestors\s+[^;]*/i, "frame-ancestors 'self'");
-                    reply.header("content-security-policy", rewritten === csp ? `${csp}; frame-ancestors 'self'` : rewritten);
-                    continue;
-                }
-                reply.header(k, Array.isArray(v) ? v.join(", ") : v);
-            }
-            // Rewrite control-ui-config.json to set basePath for proxied gateway
-            const respCt = upstreamRes.headers["content-type"] || "";
-            if (suffix === "__openclaw/control-ui-config.json" && respCt.includes("application/json")) {
-                const chunks = [];
-                for await (const chunk of upstreamRes)
-                    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-                try {
-                    const config = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
-                    config.basePath = `/api/instances/${id}/gateway`;
-                    const buf = Buffer.from(JSON.stringify(config));
-                    reply.header("content-length", buf.length);
-                    reply.removeHeader("content-encoding");
-                    return reply.send(buf);
-                }
-                catch { /* fall through to stream */ }
-            }
-            // For HTML responses: buffer to inject crypto shim + basePath
-            if (respCt.includes("text/html")) {
-                const chunks = [];
-                for await (const chunk of upstreamRes)
-                    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-                let html = Buffer.concat(chunks).toString("utf-8");
-                const basePath = `/api/instances/${id}/gateway`;
-                const injectScript = [
-                    `window.__OPENCLAW_CONTROL_UI_BASE_PATH__=${JSON.stringify(basePath)};`,
-                    `(()=>{`,
-                    `  try {`,
-                    `    const settingsKey='openclaw.control.settings.v1';`,
-                    `    const tokenStoragePrefix='openclaw.control.token.v1:';`,
-                    `    const normalizeGatewayScope=(gatewayUrl)=>{`,
-                    `      const raw=(gatewayUrl||'').trim();`,
-                    `      if(!raw) return 'default';`,
-                    `      try {`,
-                    `        const base=\`\${window.location.protocol}//\${window.location.host}\${window.location.pathname||'/'}\`;`,
-                    `        const parsed=new URL(raw, base);`,
-                    `        const pathname=parsed.pathname==='/'?'':(parsed.pathname.replace(/\\/+$/,'')||parsed.pathname);`,
-                    `        return \`\${parsed.protocol}//\${parsed.host}\${pathname}\`;`,
-                    `      } catch {`,
-                    `        return raw;`,
-                    `      }`,
-                    `    };`,
-                    `    const proto=window.location.protocol==='https:'?'wss':'ws';`,
-                    `    const gatewayUrl=\`\${proto}://\${window.location.host}${basePath}\`;`,
-                    `    const tokenSessionKey=\`\${tokenStoragePrefix}\${normalizeGatewayScope(gatewayUrl)}\`;`,
-                    `    const raw=window.localStorage.getItem(settingsKey);`,
-                    `    let next={};`,
-                    `    try { next=raw ? JSON.parse(raw) : {}; } catch { next={}; }`,
-                    `    next.gatewayUrl=gatewayUrl;`,
-                    `    if('token' in next) delete next.token;`,
-                    `    const hashParams=new URLSearchParams(window.location.hash.startsWith('#')?window.location.hash.slice(1):window.location.hash);`,
-                    `    const searchParams=new URLSearchParams(window.location.search);`,
-                    `    const launchToken=(hashParams.get('token')||searchParams.get('token')||'').trim();`,
-                    `    if(launchToken){`,
-                    `      window.sessionStorage.setItem(tokenSessionKey, launchToken);`,
-                    `    }`,
-                    `    window.localStorage.setItem(settingsKey, JSON.stringify(next));`,
-                    `    const autoConnect=()=>{`,
-                    `      const attempt=()=>{`,
-                    `        const app=document.querySelector('openclaw-app');`,
-                    `        if(!app||typeof app.connect!=='function'||typeof app.applySettings!=='function'||!app.settings||typeof app.settings!=='object') return false;`,
-                    `        const sessionToken=(window.sessionStorage.getItem(tokenSessionKey)||'').trim();`,
-                    `        const token=(sessionToken||launchToken||app.settings.token||'').trim();`,
-                    `        if(!token) return false;`,
-                    `        const nextSettings={...app.settings, gatewayUrl, token};`,
-                    `        if(nextSettings.gatewayUrl!==app.settings.gatewayUrl||nextSettings.token!==app.settings.token){`,
-                    `          app.applySettings(nextSettings);`,
-                    `        }`,
-                    `        if(app.connected) return true;`,
-                    `        const wsState=app.client&&app.client.ws?app.client.ws.readyState:null;`,
-                    `        const connecting=wsState===0||wsState===1;`,
-                    `        if(!connecting){`,
-                    `          window.setTimeout(()=>{`,
-                    `            try { if(!app.connected) app.connect(); } catch {}`,
-                    `          }, 0);`,
-                    `        }`,
-                    `        return false;`,
-                    `      };`,
-                    `      const start=()=>{`,
-                    `        let tries=0;`,
-                    `        let timer=0;`,
-                    `        const tick=()=>{`,
-                    `          tries+=1;`,
-                    `          if(attempt()||tries>=120){`,
-                    `            window.clearInterval(timer);`,
-                    `          }`,
-                    `        };`,
-                    `        tick();`,
-                    `        timer=window.setInterval(()=>{`,
-                    `          tick();`,
-                    `        },500);`,
-                    `      };`,
-                    `      if(window.customElements&&typeof window.customElements.whenDefined==='function'){`,
-                    `        window.customElements.whenDefined('openclaw-app').then(start).catch(()=>{});`,
-                    `      }else{`,
-                    `        start();`,
-                    `      }`,
-                    `    };`,
-                    `    autoConnect();`,
-                    `  } catch {}`,
-                    `})();`,
-                ].join("");
-                const inject = `<script>${injectScript}</script>`;
-                // Append jishu-inject listener as a separate script tag (keeps CSP hash separate)
-                const injectCmdScript = [
-                    `(function(){`,
-                    `  var _jishuInject=function(cmd,send){`,
-                    `    // Primary path: use openclaw-app Lit component API directly.`,
-                    `    // app.chatMessage is the reactive property backing the textarea draft.`,
-                    `    // app.handleSendChat(cmd) invokes the component's own send handler.`,
-                    `    var app=document.querySelector('openclaw-app');`,
-                    `    if(!app)return false;`,
-                    `    if(send){`,
-                    `      // Only send when gateway WebSocket is connected`,
-                    `      if(!app.connected)return false;`,
-                    `      try{app.handleSendChat(cmd);return true;}catch(e){}`,
-                    `      return false;`,
-                    `    }else{`,
-                    `      // Draft-only: set reactive property so Lit re-renders the textarea`,
-                    `      try{app.chatMessage=cmd;return true;}catch(e){}`,
-                    `      return false;`,
-                    `    }`,
-                    `  };`,
-                    `  window.addEventListener('message',function(e){`,
-                    `    if(!e.data||e.data.type!=='jishu:inject-cmd')return;`,
-                    `    var cmd=e.data.cmd,send=!!e.data.send,tries=0;`,
-                    `    var poll=function(){if(_jishuInject(cmd,send)||++tries>=50)return;setTimeout(poll,200);};`,
-                    `    poll();`,
-                    `  },false);`,
-                    `})();`,
-                ].join("");
-                const injectCmdScriptHash = createHash("sha256").update(injectCmdScript, "utf8").digest("base64");
-                const fullHtmlInject = `${inject}<script>${injectCmdScript}</script>`;
-                html = html.replace(/<head\b[^>]*>/i, (match) => `${match}${fullHtmlInject}`);
-                const inlineScriptHash = createHash("sha256").update(injectScript, "utf8").digest("base64");
-                const cspHeader = reply.getHeader("content-security-policy");
-                if (typeof cspHeader === "string" && cspHeader) {
-                    const hashToken = `'sha256-${inlineScriptHash}'`;
-                    const hashToken2 = `'sha256-${injectCmdScriptHash}'`;
-                    const addHashes = (src) => {
-                        let s = src;
-                        if (!s.includes(hashToken))
-                            s = s + ` ${hashToken}`;
-                        if (!s.includes(hashToken2))
-                            s = s + ` ${hashToken2}`;
-                        return s;
-                    };
-                    const nextCsp = /\bscript-src\b/i.test(cspHeader)
-                        ? cspHeader.replace(/\bscript-src\b([^;]*)/i, (_m, value) => `script-src${addHashes(value)}`)
-                        : `${cspHeader}; script-src 'self' ${hashToken} ${hashToken2}`;
-                    reply.header("content-security-policy", nextCsp);
-                }
-                const buf = Buffer.from(html, "utf-8");
-                reply.header("cache-control", "no-store");
-                reply.header("content-length", buf.length);
-                reply.removeHeader("content-encoding");
-                return reply.send(buf);
-            }
-            // Non-HTML: stream response directly
-            return reply.send(upstreamRes);
+            const { execFile } = await import("child_process");
+            const { promisify } = await import("util");
+            const execFileAsync = promisify(execFile);
+            await execFileAsync("docker", ["pull", image], { timeout: 600_000 });
+            return { ok: true, image };
+        }
+        catch (e) {
+            return reply.status(500).send({ detail: `Failed to pull image: ${e.message}` });
+        }
+    });
+    // ── Adapter-owned routes (§32.2.5) ─────────────────────────────────────
+    // Each registered runtime adapter may contribute its own HTTP endpoints.
+    // OpenClaw owns plugins/mcporter/skills/feishu/weixin/usage/gateway-launch/
+    // gateway proxy; Hermes currently owns none. Adding a new agent that
+    // needs custom routes is a matter of implementing registerRoutes() in
+    // the adapter — the framework layer never hard-codes kind-specific paths.
+    for (const adapter of listRegisteredAdapters()) {
+        try {
+            await adapter.registerRoutes?.(app);
         }
         catch (err) {
-            console.error(`[gateway-proxy] ${id}:`, err.message || err);
-            return reply.status(502).send({ detail: "Cannot reach OpenClaw gateway" });
+            console.error(`[instances] adapter ${adapter.agentType} registerRoutes failed:`, err);
         }
-    };
-    app.all("/api/instances/:id/gateway/*", gatewayProxy);
-    app.all("/api/instances/:id/gateway", gatewayProxy);
+    }
 }
 //# sourceMappingURL=instances.js.map