jishushell 0.5.22 → 0.6.5

package/dist/routes/instances.js

@@ -1,15 +1,19 @@
 import { getServiceManagerType } from "../config.js";
 import { assertNotLocked } from "../services/backup-manager.js";
 import * as instanceManager from "../services/app/app-manager.js";
-import * as llmProxy from "../services/llm-proxy/index.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 { cleanupInstance as cleanupProxyInstance, getLastProxyError, invalidateConfigCache, } from "../services/llm-proxy/instance-proxy.js";
+import { createInstance, isInstanceAdminError, validateId, } from "../services/instance-admin.js";
+import { getConnectionStatus, getConnectionSummary, isConnectionAdminError, replaceConnections, } from "../services/connection-admin.js";
+import { getAppConfigMeta, isAppConfigAdminError, readAppConfig, writeAppConfig, } from "../services/app-config-admin.js";
+import { augmentInstanceMetadata, getInstanceCapabilities, resolveAgentType, } from "../services/runtime/instance.js";
+import { getAdapter, hasAdapter } from "../services/runtime/index.js";
+import { invalidateRuntimeIdentity, resolveRuntimeIdentity, } from "../services/runtime-identity.js";
+import { acknowledgeRuntimeRestartAdvisory } from "../services/system-reconciler.js";
 import { assertTerminalSessionOwner, getTerminalSession, getTerminalSessionEvents, sendTerminalSessionInput, startTerminalSession, stopTerminalSession, subscribeTerminalSession, } from "../services/app/terminal-session-manager.js";
 import { TtlMap } from "../utils/ttl-cache.js";
 import { writeSecretFile } from "../utils/fs.js";
 import { Readable } from "node:stream";
+export { validateId };
 // 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([
@@ -175,6 +179,156 @@ function browserlessDebuggerBootstrap(instanceId) {
         "})();</script>",
     ].join("");
 }
+const JISHU_KB_PRELOAD_SESSION_LIMIT = 50;
+const JISHU_KB_PRELOAD_MESSAGE_LIMIT = 20;
+const JISHU_KB_PRELOAD_TIMEOUT_MS = 5_000;
+const JISHU_KB_PRELOAD_GLOBAL = "__JISHU_KB_PRELOADED_SESSIONS__";
+function trimString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function parseJishuKbConversationId(value) {
+    if (typeof value === "number") {
+        return Number.isSafeInteger(value) && value > 0 ? value : null;
+    }
+    const raw = trimString(value);
+    if (!/^\d+$/.test(raw))
+        return null;
+    const parsed = Number(raw);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+function parseJishuKbTimestamp(value) {
+    const numeric = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(numeric) ? numeric : 0;
+}
+function parseJishuKbRole(value) {
+    const normalized = trimString(value);
+    return normalized === "user" || normalized === "assistant" || normalized === "system"
+        ? normalized
+        : null;
+}
+function parseJishuKbCitations(value) {
+    if (Array.isArray(value))
+        return value;
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function relayAbort(parentSignal, controller) {
+    if (parentSignal.aborted) {
+        controller.abort(parentSignal.reason);
+        return () => { };
+    }
+    const abort = () => controller.abort(parentSignal.reason);
+    parentSignal.addEventListener("abort", abort, { once: true });
+    return () => parentSignal.removeEventListener("abort", abort);
+}
+async function fetchJsonWithTimeout(upstreamOrigin, relativePath, parentSignal) {
+    const controller = new AbortController();
+    const cleanupAbort = relayAbort(parentSignal, controller);
+    const timer = setTimeout(() => controller.abort(new Error("timeout")), JISHU_KB_PRELOAD_TIMEOUT_MS);
+    try {
+        const response = await fetch(new URL(relativePath, `${upstreamOrigin}/`).toString(), {
+            headers: { accept: "application/json" },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const detail = (await response.text()).slice(0, 200);
+            throw new Error(`${relativePath} -> ${response.status}${detail ? `: ${detail}` : ""}`);
+        }
+        return await response.json();
+    }
+    finally {
+        clearTimeout(timer);
+        cleanupAbort();
+    }
+}
+async function loadJishuKbPreloadedSessions(upstreamOrigin, parentSignal) {
+    const kbList = await fetchJsonWithTimeout(upstreamOrigin, "/api/kb", parentSignal);
+    const kbIds = Array.from(new Set((Array.isArray(kbList) ? kbList : [])
+        .map((kb) => trimString(kb?.id))
+        .filter(Boolean)));
+    if (!kbIds.length)
+        kbIds.push("default");
+    const conversationLists = await Promise.all(kbIds.map(async (kbId) => {
+        const query = new URLSearchParams({ kb_id: kbId }).toString();
+        const rows = await fetchJsonWithTimeout(upstreamOrigin, `/api/conversations?${query}`, parentSignal);
+        return Array.isArray(rows)
+            ? rows.map((row) => ({
+                ...row,
+                kb_id: trimString(row?.kb_id) || kbId,
+            }))
+            : [];
+    }));
+    const selected = conversationLists
+        .flat()
+        .sort((left, right) => parseJishuKbTimestamp(right.updated_at) - parseJishuKbTimestamp(left.updated_at))
+        .slice(0, JISHU_KB_PRELOAD_SESSION_LIMIT);
+    const hydrated = await Promise.all(selected.map(async (conversation) => {
+        const conversationId = parseJishuKbConversationId(conversation.id);
+        const kbId = trimString(conversation.kb_id);
+        if (!conversationId || !kbId) {
+            console.warn("[cap-proxy] skipping jishukb conversation preload with unsupported id/kb", {
+                id: conversation.id,
+                kbId,
+            });
+            return null;
+        }
+        const messages = await fetchJsonWithTimeout(upstreamOrigin, `/api/conversations/${encodeURIComponent(String(conversationId))}/messages`, parentSignal);
+        const normalizedMessages = (Array.isArray(messages) ? messages : [])
+            .map((message) => {
+            const role = parseJishuKbRole(message?.role);
+            const content = typeof message?.content === "string" ? message.content : "";
+            if (!role || !content)
+                return null;
+            const cites = parseJishuKbCitations(message?.citations);
+            return cites?.length
+                ? { role, content, cites }
+                : { role, content };
+        })
+            .filter((message) => message !== null)
+            .slice(-JISHU_KB_PRELOAD_MESSAGE_LIMIT);
+        return {
+            id: conversationId,
+            kb: kbId,
+            title: trimString(conversation.title) || "Untitled",
+            msgs: normalizedMessages,
+            _syncedMsgIdx: normalizedMessages.length,
+        };
+    }));
+    return hydrated
+        .filter((session) => session !== null)
+        .sort((left, right) => left.id - right.id);
+}
+function jishuKbConversationBootstrap(preloadedSessions) {
+    const serialized = JSON.stringify(preloadedSessions);
+    const globalName = JSON.stringify(JISHU_KB_PRELOAD_GLOBAL);
+    return [
+        "<script>(function(){",
+        "try{",
+        `var incoming=${serialized};`,
+        `window[${globalName}]=incoming;`,
+        "var current=[];",
+        "try{var raw=window.localStorage.getItem('jkb_sess');current=raw?JSON.parse(raw):[];}catch(_e){current=[];}",
+        "if(!Array.isArray(current))current=[];",
+        "var seen=Object.create(null);",
+        "var merged=[];",
+        "function key(entry){return String(entry&&entry.kb||'')+'::'+String(entry&&entry.id||'');}",
+        "function push(entry){if(!entry||typeof entry!=='object')return;var k=key(entry);if(seen[k])return;seen[k]=1;merged.push(entry);}",
+        "incoming.forEach(push);",
+        "current.forEach(push);",
+        "merged.sort(function(a,b){return Number(a&&a.id||0)-Number(b&&b.id||0);});",
+        `if(merged.length>${JISHU_KB_PRELOAD_SESSION_LIMIT})merged=merged.slice(-${JISHU_KB_PRELOAD_SESSION_LIMIT});`,
+        "window.localStorage.setItem('jkb_sess',JSON.stringify(merged));",
+        "}catch(_e){}",
+        "})();</script>",
+    ].join("");
+}
 /**
  * Inject a tiny <script> that monkey-patches `fetch`, `XMLHttpRequest.open`,
  * and `Element.prototype.{setAttribute,src,href}` so that same-origin absolute
@@ -416,23 +570,77 @@ function rewriteProxyTextBody(body, contentType, proxyBasePath, extraHeadHtml =
     }
     return rewritten;
 }
-function buildProxyRequestBody(req) {
+function isReadableBody(value) {
+    if (value instanceof Readable)
+        return true;
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.pipe === "function" &&
+        typeof candidate.on === "function" &&
+        typeof candidate[Symbol.asyncIterator] === "function");
+}
+async function readProxyBodyStream(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        if (typeof chunk === "string") {
+            chunks.push(Buffer.from(chunk));
+        }
+        else if (chunk instanceof Uint8Array) {
+            chunks.push(Buffer.from(chunk));
+        }
+        else {
+            chunks.push(Buffer.from(String(chunk)));
+        }
+    }
+    return Buffer.concat(chunks);
+}
+function bytesToArrayBuffer(bytes) {
+    const out = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(out).set(bytes);
+    return out;
+}
+function isPlainRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function encodeFormRecord(body) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(body)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                params.append(key, String(item));
+        }
+        else {
+            params.append(key, String(value));
+        }
+    }
+    return params.toString();
+}
+async 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)) {
+    if (typeof body === "string") {
         return body;
     }
+    if (body instanceof Uint8Array || Buffer.isBuffer(body))
+        return bytesToArrayBuffer(body);
+    if (isReadableBody(body)) {
+        return bytesToArrayBuffer(await readProxyBodyStream(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/x-www-form-urlencoded") && isPlainRecord(body)) {
+        return encodeFormRecord(body);
     }
-    if (contentType.includes("application/json")) {
+    if (contentType.includes("application/json") && isPlainRecord(body)) {
         return JSON.stringify(body);
     }
-    if (typeof body === "object") {
+    if (isPlainRecord(body)) {
         return JSON.stringify(body);
     }
     return undefined;
@@ -591,6 +799,16 @@ async function proxyProvidedCapability(req, reply) {
     if (req.headers.host)
         headers.set("x-forwarded-host", String(req.headers.host));
     headers.set("x-forwarded-proto", req.protocol);
+    const clientIp = typeof req.ip === "string" && req.ip
+        ? req.ip
+        : typeof req.raw?.socket?.remoteAddress === "string"
+            ? req.raw.socket.remoteAddress
+            : "";
+    if (clientIp) {
+        const forwardedFor = headers.get("x-forwarded-for");
+        headers.set("x-forwarded-for", forwardedFor ? `${forwardedFor}, ${clientIp}` : clientIp);
+        headers.set("x-real-ip", clientIp);
+    }
     // Intercept service worker scripts BEFORE talking to upstream.  SPAs like
     // OpenWebUI register a SvelteKit service worker that aggressively caches
     // HTML/JS at the proxy origin; once installed, the SW serves stale bodies
@@ -621,16 +839,23 @@ async function proxyProvidedCapability(req, reply) {
     // promise indefinitely and starve the event loop.
     const upstreamAbort = new AbortController();
     const connectTimer = setTimeout(() => upstreamAbort.abort(new Error("upstream connect timeout")), 30_000);
-    const onClientClose = () => upstreamAbort.abort();
-    req.raw.once("close", onClientClose);
+    const onClientClose = () => {
+        if (!reply.raw.writableEnded)
+            upstreamAbort.abort(new Error("client disconnected"));
+    };
+    reply.raw.once("close", onClientClose);
     try {
+        console.error("[cap-proxy] PRE buildBody method=", req.method, "bodyType=", typeof req.body, req.body?.constructor?.name, "signalAborted=", upstreamAbort.signal.aborted);
+        const requestBody = await buildProxyRequestBody(req);
+        console.error("[cap-proxy] POST buildBody size=", requestBody instanceof ArrayBuffer ? requestBody.byteLength : typeof requestBody === "string" ? requestBody.length : "undef", "signalAborted=", upstreamAbort.signal.aborted, "reason=", upstreamAbort.signal.reason?.message);
         const upstream = await fetch(targetUrl, {
             method: req.method,
             headers,
-            body: buildProxyRequestBody(req),
+            body: requestBody,
             redirect: "manual",
             signal: upstreamAbort.signal,
         }).finally(() => clearTimeout(connectTimer));
+        console.error("[cap-proxy] POST fetch status=", upstream.status);
         const upstreamContentType = upstream.headers.get("content-type");
         const willRewriteBody = shouldRewriteProxyResponse(upstreamContentType);
         const willInjectHtml = (upstreamContentType ?? "").toLowerCase().includes("text/html");
@@ -646,7 +871,7 @@ async function proxyProvidedCapability(req, reply) {
             // hard-coded redirect targets, etc.). Honoring the upstream cache hints
             // lets the browser pin a stale rewrite indefinitely: e.g. an early
             // visit that pre-dated the JS rewrite gets cached and survives across
-            // panel restarts, breaking the auth redirect logic until a hard refresh.
+            // app restarts, breaking the auth redirect logic until a hard refresh.
             // Strip cache validators and force revalidation on every load.
             if (willRewriteBody && (normalizedKey === "cache-control" ||
                 normalizedKey === "etag" ||
@@ -680,7 +905,7 @@ async function proxyProvidedCapability(req, reply) {
             reply.header(key, value);
         });
         if (req.method === "HEAD") {
-            req.raw.off("close", onClientClose);
+            reply.raw.off("close", onClientClose);
             return reply.send();
         }
         if (willRewriteBody) {
@@ -692,6 +917,15 @@ async function proxyProvidedCapability(req, reply) {
             if (req.params.capability === "browserless-debugger") {
                 extraHeadHtml = browserlessDebuggerBootstrap(req.params.id);
             }
+            if (willInjectHtml && req.params.capability === "web-jishukb") {
+                try {
+                    const preloadedSessions = await loadJishuKbPreloadedSessions(upstreamOrigin, upstreamAbort.signal);
+                    extraHeadHtml += jishuKbConversationBootstrap(preloadedSessions);
+                }
+                catch (error) {
+                    console.warn("[cap-proxy] jishukb conversation preload skipped:", error);
+                }
+            }
             // Inject a generic fetch/XHR monkey-patch for all capability-proxied
             // HTML pages.  SPA frameworks like SvelteKit compile absolute API paths
             // (e.g. `/api/v1/...`, `/ollama/...`) into JS bundles at build time.
@@ -718,20 +952,21 @@ async function proxyProvidedCapability(req, reply) {
                 }
             }
             const rawBody = await upstream.text();
-            req.raw.off("close", onClientClose);
+            reply.raw.off("close", onClientClose);
             const rewritten = rewriteProxyTextBody(rawBody, upstreamContentType, proxyBasePath, extraHeadHtml);
             return reply.send(rewritten);
         }
         if (!upstream.body) {
-            req.raw.off("close", onClientClose);
+            reply.raw.off("close", onClientClose);
             return reply.send();
         }
         const readable = Readable.fromWeb(upstream.body);
-        readable.once("close", () => req.raw.off("close", onClientClose));
+        readable.once("close", () => reply.raw.off("close", onClientClose));
         return reply.send(readable);
     }
     catch (error) {
-        req.raw.off("close", onClientClose);
+        console.error("[cap-proxy] CATCH", error?.constructor?.name, error?.name, error?.message, "signalAborted=", upstreamAbort.signal.aborted, "reason=", upstreamAbort.signal.reason?.message, "stack=", error?.stack?.split("\n").slice(0, 4).join(" | "));
+        reply.raw.off("close", onClientClose);
         return reply.status(502).send({ detail: error?.message || `Failed to proxy capability '${req.params.capability}'` });
     }
 }
@@ -767,68 +1002,23 @@ export async function getSvc() {
     _svcType = currentType;
     return _svc;
 }
-export function validateId(id) {
-    if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(id)) {
-        return "ID must be lowercase alphanumeric with hyphens, 1-63 chars";
-    }
-    return null;
-}
-function normalizeInstanceName(name) {
-    return name.trim().toLowerCase();
-}
-function isLegacyInstanceAppType(value) {
-    return value === "custom" || value === "ollama";
-}
 function getInstanceBackedInstalledApp(instanceId) {
     return instanceManager.getApp(instanceId);
 }
-/**
- * Resolve the spec used to drive the Connections feature.
- *
- * For V2 app-installed instances (`meta.app_id` set), pull the persisted
- * `app-spec.yaml` via app-manager. For legacy hermes/openclaw instances
- * created via the old "新建实例" flow (no `app_id`, no spec on disk),
- * synthesize an in-memory capability-only spec from the bundled
- * `apps/<agentType>-container.yaml` template.
- *
- * Returning `legacy: true` lets the PUT handler skip the adapter-driven
- * env injection that V2 expects — for legacy instances the apply hooks
- * fall back to writing `instance.json["connections-env"]`, which the
- * legacy start path is responsible for merging into runtime.env.
- */
-async function loadConnectionsSpec(meta) {
-    const { app_id } = meta;
-    if (app_id) {
-        const appData = instanceManager.getApp(app_id);
-        if (!appData)
-            return null;
-        return { spec: appData.spec, legacy: false, appId: app_id };
-    }
-    const { loadCapabilitySpecForLegacyInstance } = await import("../services/runtime/migrations.js");
-    const synthetic = loadCapabilitySpecForLegacyInstance(meta);
-    if (!synthetic)
-        return null;
-    return { spec: synthetic, legacy: true, appId: meta.id };
-}
-const DEFAULT_INSTANCE_TEMPLATE_BY_KIND = {
-    ollama: "ollama-with-hollama-binary.yaml",
-};
-const HIDDEN_CONNECTION_STATUS_CAPABILITIES = new Set(["mcp"]);
-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;
+function shouldUseAppManager(identity) {
+    if (!identity)
+        return false;
+    if (identity.driver === "app-job")
+        return true;
+    return identity.driver === "local-model" && !!getInstanceBackedInstalledApp(identity.id);
 }
-async function loadRemoteAppSpecYamlForInstance(urlText) {
-    return loadRemoteAppSpecYaml(urlText, { fieldName: "app_spec_url" });
+function shouldUseAppManagerForId(instanceId, identity) {
+    return shouldUseAppManager(identity) || (!identity && !!getInstanceBackedInstalledApp(instanceId));
 }
-function isConfigDocument(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const format = value.format;
-    return format === "json" || format === "yaml+env";
+function hasRuntimeIdentity(instanceId) {
+    return resolveRuntimeIdentity(instanceId) != null
+        || !!instanceManager.getInstance(instanceId)
+        || !!getInstanceBackedInstalledApp(instanceId);
 }
 // TTL 15s: outlives the frontend 10s polling interval so most requests hit cache
 const statusCache = new TtlMap(15_000);
@@ -837,7 +1027,8 @@ function getCachedStatus(svc, instanceId) {
     const cached = statusCache.get(instanceId);
     if (cached !== undefined)
         return Promise.resolve(cached);
-    const statusPromise = getInstanceBackedInstalledApp(instanceId)
+    const identity = resolveRuntimeIdentity(instanceId);
+    const statusPromise = shouldUseAppManagerForId(instanceId, identity)
         ? instanceManager.getAppStatus(instanceId).then((data) => ({
             status: data.status,
             pid: data.pid,
@@ -886,192 +1077,8 @@ export async function instanceRoutes(app) {
     });
     // 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 (!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" });
-        }
-        // §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 semantics"), 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)
-                return reply.status(400).send({ detail: `Invalid clone_from: ${cloneErr}` });
-            const sourceInstance = instanceManager.getInstance(req.body.clone_from);
-            if (!sourceInstance)
-                return reply.status(400).send({ detail: `Source instance '${req.body.clone_from}' not found` });
-        }
         try {
-            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;
-            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;
-            }
-            const decorated = await augmentInstanceMetadata(instanceId, meta);
-            if (meta.autoStarted)
-                decorated.autoStarted = true;
-            return decorated;
+            return await createInstance(req.body);
         }
         catch (e) {
             // Structured rejection from createHermesInstance — return 409 with code
@@ -1084,6 +1091,9 @@ export async function instanceRoutes(app) {
                     currentNomadDriver: e.currentNomadDriver,
                 });
             }
+            if (isInstanceAdminError(e)) {
+                return reply.status(e.statusCode).send(e.payload);
+            }
             return reply.status(409).send({ detail: e.message });
         }
     });
@@ -1100,7 +1110,7 @@ export async function instanceRoutes(app) {
         return {
             ...(await augmentInstanceMetadata(req.params.id, inst)),
             service: status,
-            llmError: llmProxy.getLastProxyError(req.params.id) ?? null,
+            llmError: getLastProxyError(req.params.id) ?? null,
         };
     });
     // Update
@@ -1123,6 +1133,7 @@ export async function instanceRoutes(app) {
         const inst = instanceManager.updateInstance(req.params.id, req.body.name, req.body.description);
         if (!inst)
             return reply.status(404).send({ detail: "Instance not found" });
+        invalidateRuntimeIdentity(req.params.id);
         return inst;
     });
     // Delete
@@ -1147,7 +1158,8 @@ export async function instanceRoutes(app) {
                 return reply.status(status).send({ detail: result.error, code });
             }
             statusCache.delete(req.params.id);
-            llmProxy.cleanupInstance(req.params.id);
+            invalidateRuntimeIdentity(req.params.id);
+            cleanupProxyInstance(req.params.id);
             return reply.status(202).send({
                 ok: true,
                 taskId: result.taskId,
@@ -1177,7 +1189,8 @@ export async function instanceRoutes(app) {
         }
         catch { /* ignore */ }
         statusCache.delete(req.params.id);
-        llmProxy.cleanupInstance(req.params.id);
+        invalidateRuntimeIdentity(req.params.id);
+        cleanupProxyInstance(req.params.id);
         const purgeBackups = req.query.purge_backups === "true";
         const result = await instanceManager.deleteInstance(req.params.id, purgeBackups);
         if (!result.ok && result.warnings?.some(w => w.includes("not found"))) {
@@ -1192,88 +1205,39 @@ export async function instanceRoutes(app) {
     });
     // 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);
+        try {
+            return getAppConfigMeta(req.params.id);
+        }
+        catch (e) {
+            if (isAppConfigAdminError(e)) {
+                const detail = e.code === "APP_NOT_FOUND" ? "Instance not found" : e.message;
+                return reply.status(e.statusCode).send({ detail, code: e.code });
+            }
+            throw e;
+        }
     });
     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;
+        try {
+            return await readAppConfig(req.params.id);
+        }
+        catch (e) {
+            if (isAppConfigAdminError(e)) {
+                const detail = e.code === "APP_NOT_FOUND" ? "Instance not found" : e.message;
+                return reply.status(e.statusCode).send({ detail, code: e.code });
             }
+            throw e;
         }
-        const config = llmProxy.getInstanceConfig(req.params.id);
-        if (!config)
-            return reply.status(404).send({ detail: "Instance or config not found" });
-        return config;
     });
     app.put("/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);
-        // Basic payload validation
-        const body = req.body;
-        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 };
+            return await writeAppConfig(req.params.id, req.body);
         }
         catch (e) {
-            const msg = e.message || "";
-            if (msg.includes("not found"))
-                return reply.status(404).send({ detail: msg });
-            return reply.status(400).send({ detail: msg });
+            if (isAppConfigAdminError(e)) {
+                const detail = e.code === "APP_NOT_FOUND" ? "Instance not found" : e.message;
+                return reply.status(e.statusCode).send({ detail, code: e.code });
+            }
+            throw e;
         }
     });
     // Service control
@@ -1282,10 +1246,11 @@ export async function instanceRoutes(app) {
         if (idErr)
             return reply.status(400).send({ detail: idErr });
         const svc = await getSvc();
-        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
+        const identity = resolveRuntimeIdentity(req.params.id);
+        if (!identity && !hasRuntimeIdentity(req.params.id)) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
-        if (getInstanceBackedInstalledApp(req.params.id)) {
+        if (shouldUseAppManagerForId(req.params.id, identity)) {
             return instanceManager.getAppStatus(req.params.id);
         }
         return svc.getStatus(req.params.id);
@@ -1301,13 +1266,15 @@ 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) && !getInstanceBackedInstalledApp(req.params.id)) {
+        const identity = resolveRuntimeIdentity(req.params.id);
+        if (!identity && !hasRuntimeIdentity(req.params.id)) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
-        const result = getInstanceBackedInstalledApp(req.params.id)
+        const result = shouldUseAppManagerForId(req.params.id, identity)
             ? await instanceManager.startApp(req.params.id)
             : await svc.startInstance(req.params.id);
         statusCache.delete(req.params.id);
+        invalidateRuntimeIdentity(req.params.id);
         if (!result.ok) {
             const resultRecord = result;
             // Surface the phase tag so the UI can highlight where the start
@@ -1331,6 +1298,7 @@ export async function instanceRoutes(app) {
                 : 400;
             return reply.status(statusCode).send(payload);
         }
+        await acknowledgeRuntimeRestartAdvisory(req.params.id);
         return result;
     });
     app.post("/api/instances/:id/service/stop", async (req, reply) => {
@@ -1344,13 +1312,15 @@ 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) && !getInstanceBackedInstalledApp(req.params.id)) {
+        const identity = resolveRuntimeIdentity(req.params.id);
+        if (!identity && !hasRuntimeIdentity(req.params.id)) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
-        const result = getInstanceBackedInstalledApp(req.params.id)
+        const result = shouldUseAppManagerForId(req.params.id, identity)
             ? await instanceManager.stopApp(req.params.id)
             : await svc.stopInstance(req.params.id);
         statusCache.delete(req.params.id);
+        invalidateRuntimeIdentity(req.params.id);
         if (!result.ok)
             return reply.status(400).send({ detail: result.error });
         return result;
@@ -1366,15 +1336,18 @@ 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) && !getInstanceBackedInstalledApp(req.params.id)) {
+        const identity = resolveRuntimeIdentity(req.params.id);
+        if (!identity && !hasRuntimeIdentity(req.params.id)) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
-        const result = getInstanceBackedInstalledApp(req.params.id)
+        const result = shouldUseAppManagerForId(req.params.id, identity)
             ? await instanceManager.restartApp(req.params.id)
             : await svc.restartInstance(req.params.id);
         statusCache.delete(req.params.id);
+        invalidateRuntimeIdentity(req.params.id);
         if (!result.ok)
             return reply.status(400).send({ detail: result.error || "Unknown error" });
+        await acknowledgeRuntimeRestartAdvisory(req.params.id);
         return result;
     });
     // ── Pairing ──────────────────────────────────────────────────────────────
@@ -1685,7 +1658,8 @@ export async function instanceRoutes(app) {
         if (idErr)
             return reply.status(400).send({ detail: idErr });
         const svc = await getSvc();
-        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
+        const identity = resolveRuntimeIdentity(req.params.id);
+        if (!identity && !hasRuntimeIdentity(req.params.id)) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
         const logType = req.query.log_type || "stderr";
@@ -1694,7 +1668,7 @@ 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 = getInstanceBackedInstalledApp(req.params.id)
+        const logLines = shouldUseAppManagerForId(req.params.id, identity)
             ? await instanceManager.getAppLogs(req.params.id, "", lines, logType)
             : await svc.getLogs(req.params.id, lines, logType);
         return { lines: logLines };
@@ -1770,7 +1744,7 @@ export async function instanceRoutes(app) {
         // Invalidate proxy config cache for migrated instances
         for (const r of results) {
             if (r.status === "migrated")
-                llmProxy.invalidateConfigCache(r.id);
+                invalidateConfigCache(r.id);
         }
         return { ok: true, results };
     });
@@ -1787,14 +1761,20 @@ export async function instanceRoutes(app) {
         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 {
-            const { execFileSync } = await import("child_process");
-            execFileSync("docker", ["image", "inspect", image], { timeout: 10000, stdio: "ignore" });
+        const { inspectDockerImage, toDockerInspectUserError } = await import("../utils/docker-inspect.js");
+        const result = inspectDockerImage(image, { timeout: 10000 });
+        if (result.ok) {
             return { exists: true, image };
         }
-        catch {
+        if (result.reason === "not_found")
             return { exists: false, image };
-        }
+        const inspectError = toDockerInspectUserError(image, result);
+        return reply.status(inspectError.statusCode).send({
+            detail: inspectError.message,
+            code: inspectError.code,
+            exists: false,
+            image,
+        });
     });
     app.post("/api/docker/image-pull", async (req, reply) => {
         const image = req.body?.image;
@@ -1818,160 +1798,31 @@ export async function instanceRoutes(app) {
     // ── Connections REST API (PR 4 of app-interconnect-design) ──────────────
     /** GET /api/instances/:id/connections — view spec.requires + bindings. */
     app.get("/api/instances/:id/connections", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        const meta = instanceManager.getInstance(req.params.id);
-        if (!meta)
-            return reply.status(404).send({ detail: "Instance not found" });
-        const specInfo = await loadConnectionsSpec(meta);
-        if (!specInfo) {
-            // Truly unknown agent type or missing spec — empty Connections view.
-            return { requires: [], connections: {}, pending: [] };
-        }
-        const { resolveConnections } = await import("../services/connection-resolver.js");
-        const capabilityRegistry = await import("../services/capability-registry.js");
-        const persistedConnections = (meta.connections ?? {});
-        const { resolved, pending } = resolveConnections(specInfo.spec, { connections: persistedConnections }, "preCreate");
-        // For UI display: each require slot, candidates pulled from registry.
-        // Two filters keep nonsensical bindings out of the dropdown:
-        //   1. Self-binding — an instance must never appear in its own slot's
-        //      candidates. Without this, e.g. hermes-h shows up as a candidate
-        //      for hermes-h's own `llm` slot, which would create an infinite
-        //      self-call loop at apply time.
-        //   2. Agent-on-agent — agent runtimes (hermes / openclaw) consume
-        //      `llm` for their internal reasoning. Letting them bind another
-        //      agent's `llm-agent` capability would chain agent → agent →
-        //      llm provider, which is structurally wrong (the inner agent is
-        //      not a model). Only true LLM model providers (capability
-        //      `llm-<vendor>` like `llm-ollama`, `llm-openai`) are valid.
-        //      The `llm-agent` capability stays available to non-agent
-        //      consumers (OpenWebUI etc.) where agent-as-LLM makes sense.
-        const consumerAgentType = String(meta?.agentType ?? "");
-        const consumerIsAgent = consumerAgentType === "hermes" || consumerAgentType === "openclaw";
-        const requires = (specInfo.spec.requires ?? []).map((r) => {
-            const isCategoryToken = ["llm", "search", "browser", "mcp", "files", "knowledge"].includes(r.capability);
-            const candidates = isCategoryToken
-                ? Object.entries(capabilityRegistry.snapshot().providersByCapability ?? {})
-                    .filter(([cap]) => cap.startsWith(r.capability + "-") || cap === r.capability)
-                    .flatMap(([_, list]) => list)
-                : capabilityRegistry.listProviders(r.capability);
-            const filtered = candidates.filter((c) => {
-                if (c.instanceId === req.params.id)
-                    return false;
-                if (consumerIsAgent && r.capability === "llm" && c.capability === "llm-agent")
-                    return false;
-                return true;
-            });
-            return {
-                capability: r.capability,
-                inject_as: r.inject_as,
-                required: r.required !== false,
-                cardinality: r.cardinality ?? "one",
-                apply: r.apply,
-                category: isCategoryToken ? r.capability : "default",
-                candidates: filtered.map((c) => ({
-                    providerId: c.instanceId,
-                    capability: c.capability,
-                    name: c.name,
-                    protocol: c.protocol,
-                    status: c.status,
-                    hostPort: c.hostPort,
-                    path: c.path,
-                })),
-            };
-        });
-        return {
-            requires,
-            connections: persistedConnections,
-            pending: pending.map((p) => ({
-                slot: p.slot,
-                capability: p.capability,
-                reason: p.reason,
-                required: p.required,
-            })),
-            // resolved is internal — surface as debug to help UI understand state.
-            _resolved: resolved.map((r) => ({
-                slot: r.slot,
-                capability: r.capability,
-                category: r.category,
-                source: r.source,
-                providerCount: r.entries.length,
-            })),
-        };
-    });
-    /** PUT /api/instances/:id/connections — save bindings via transactor. */
-    app.put("/api/instances/:id/connections", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        const meta = instanceManager.getInstance(req.params.id);
-        if (!meta)
-            return reply.status(404).send({ detail: "Instance not found" });
-        const specInfo = await loadConnectionsSpec(meta);
-        if (!specInfo) {
-            return reply.status(400).send({
-                detail: "Connections only available for app-installed instances",
-                code: "NOT_APP_INSTANCE",
-            });
-        }
-        const newConnections = (req.body?.connections ?? {});
-        const { applyConnections } = await import("../services/connection-transactor.js");
-        const safeJson = await import("../utils/safe-json.js");
-        const fs = await import("fs");
-        const path = await import("path");
-        const instancePath = instanceManager.instanceMetaPath(req.params.id);
-        const readInstanceJson = async (_id) => {
-            const cur = safeJson.safeReadJson(instancePath, `instance:${req.params.id}`);
-            return (cur ?? {});
-        };
-        const saveInstanceJson = async (_id, mutator) => {
-            const cur = safeJson.safeReadJson(instancePath, `instance:${req.params.id}`) ?? {};
-            const updated = mutator(cur);
-            // Ensure parent dir exists (instance dir is always there for app instances).
-            try {
-                fs.mkdirSync(path.dirname(instancePath), { recursive: true });
-            }
-            catch {
-                /* noop */
-            }
-            safeJson.safeWriteJson(instancePath, updated);
-        };
-        // Adapter resolution — adapter-managed consumers route writeConnectionEnv
-        // through adapter.applyConnectionEnv; generic apps go through
-        // instance.json["connections-env"].
-        let adapter = null;
         try {
-            const agentType = resolveAgentType(meta);
-            if (hasAdapter(agentType)) {
-                adapter = getAdapter(agentType);
-                // Only expose the optional methods if the adapter implements them.
-                if (typeof adapter.applyConnectionEnv !== "function")
-                    adapter = null;
-            }
+            return await getConnectionSummary(req.params.id);
         }
-        catch {
-            adapter = null;
+        catch (e) {
+            if (isConnectionAdminError(e)) {
+                const detail = e.code === "APP_NOT_FOUND" ? "Instance not found" : e.message;
+                return reply.status(e.statusCode).send({ detail, code: e.code });
+            }
+            throw e;
         }
+    });
+    /** PUT /api/instances/:id/connections — save bindings via transactor. */
+    app.put("/api/instances/:id/connections", async (req, reply) => {
         try {
-            const result = await applyConnections({
-                instance: meta,
-                spec: specInfo.spec,
-                newConnections,
-                saveInstanceJson,
-                readInstanceJson,
-                adapter,
-            });
-            return {
-                ok: true,
-                resolved: result.resolved.map((r) => ({
-                    slot: r.slot,
-                    capability: r.capability,
-                    category: r.category,
-                })),
-            };
+            return await replaceConnections(req.params.id, (req.body?.connections ?? {}));
         }
         catch (e) {
+            if (isConnectionAdminError(e)) {
+                const detail = e.code === "APP_NOT_FOUND" ? "Instance not found" : e.message;
+                return reply.status(e.statusCode).send({
+                    detail,
+                    code: e.code,
+                    ...(e.details ? { details: e.details } : {}),
+                });
+            }
             const status = e?.statusCode ?? 500;
             return reply.status(status).send({
                 detail: e?.message ?? "Connection apply failed",
@@ -1982,81 +1833,14 @@ export async function instanceRoutes(app) {
     });
     /** GET /api/instances/:id/connection-status — UI badge state. */
     app.get("/api/instances/:id/connection-status", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        const meta = instanceManager.getInstance(req.params.id);
-        if (!meta)
-            return reply.status(404).send({ detail: "Instance not found" });
-        const specInfo = await loadConnectionsSpec(meta);
-        if (!specInfo)
-            return { state: "empty", unboundRequired: [], unboundOptional: [] };
-        // An instance with no `requires` slots (pure provider — e.g. SearXNG,
-        // Ollama, Browserless) has nothing to bind. Returning `ok` would
-        // surface a misleading "Connected" badge in the UI; treat it as
-        // empty so the badge / Connect-Apps menu entry hide entirely
-        // (ConnectionsBadge already returns null on `empty`).
-        if (!Array.isArray(specInfo.spec.requires) || specInfo.spec.requires.length === 0) {
-            return { state: "empty", unboundRequired: [], unboundOptional: [] };
-        }
-        const { resolveConnections } = await import("../services/connection-resolver.js");
         try {
-            const { pending, resolved } = resolveConnections(specInfo.spec, { connections: (meta.connections ?? {}) }, "preCreate");
-            const hiddenSlots = new Set((specInfo.spec.requires ?? [])
-                .filter((req) => HIDDEN_CONNECTION_STATUS_CAPABILITIES.has(req.capability))
-                .map((req) => req.inject_as));
-            const visibleRequires = (specInfo.spec.requires ?? []).filter((req) => !hiddenSlots.has(req.inject_as));
-            if (visibleRequires.length === 0) {
-                return { state: "empty", unboundRequired: [], unboundOptional: [], bindable: 0 };
-            }
-            // Stale bindings — slot is bound (in `resolved`) but at least one
-            // bound provider entry is no longer running. preCreate mode skips
-            // the runtime status check so these otherwise stay invisible to
-            // the badge; surface them as synthetic pending so the badge drops
-            // out of `ok`.
-            const stalePending = resolved
-                .filter((r) => r.entries.some((e) => e.status !== "running"))
-                .map((r) => ({ slot: r.slot, capability: r.capability, required: r.required }));
-            const staleSlots = new Set(stalePending.map((p) => p.slot));
-            const allPending = [...pending, ...stalePending];
-            const visiblePending = allPending.filter((p) => !hiddenSlots.has(p.slot));
-            const unboundRequired = visiblePending.filter((p) => p.required).map((p) => p.slot);
-            const unboundOptional = visiblePending.filter((p) => !p.required).map((p) => p.slot);
-            // Count slots that the user can act on right now — i.e. unbound
-            // visible slots whose capability has at least one running candidate
-            // in the registry. Hidden categories like MCP should neither show
-            // cards in the UI nor inflate the badge count. Stale slots are
-            // always actionable (re-bind or start the bound provider) so they
-            // count even when no other candidate is running.
-            const capabilityRegistry = await import("../services/capability-registry.js");
-            const consumerAgentType = String(meta?.agentType ?? "");
-            const consumerIsAgent = consumerAgentType === "hermes" || consumerAgentType === "openclaw";
-            const isCategoryToken = (cap) => ["llm", "search", "browser", "mcp"].includes(cap);
-            const enumerateRunning = (cap) => {
-                const list = isCategoryToken(cap)
-                    ? Object.entries(capabilityRegistry.snapshot().providersByCapability ?? {})
-                        .filter(([k]) => k.startsWith(cap + "-") || k === cap)
-                        .flatMap(([_, v]) => v)
-                    : capabilityRegistry.listProviders(cap);
-                return list.filter((c) => {
-                    if (c.status !== "running")
-                        return false;
-                    if (c.instanceId === req.params.id)
-                        return false;
-                    if (consumerIsAgent && cap === "llm" && c.capability === "llm-agent")
-                        return false;
-                    return true;
-                });
-            };
-            const bindable = visiblePending.filter((p) => staleSlots.has(p.slot) || enumerateRunning(p.capability).length > 0).length;
-            let state = "ok";
-            if (unboundRequired.length > 0)
-                state = "error";
-            else if (bindable > 0)
-                state = "warn";
-            return { state, unboundRequired, unboundOptional, bindable };
+            return await getConnectionStatus(req.params.id);
         }
         catch (e) {
+            if (isConnectionAdminError(e)) {
+                const detail = e.code === "APP_NOT_FOUND" ? "Instance not found" : e.message;
+                return reply.status(e.statusCode).send({ detail, code: e.code });
+            }
             return { state: "error", unboundRequired: [], unboundOptional: [], bindable: 0, error: e.message };
         }
     });
@@ -2160,19 +1944,12 @@ export async function instanceRoutes(app) {
             return reply.status(400).send({ detail: e?.message ?? "Invalid suggestion id" });
         }
     });
-    // ── 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(`[instances] adapter ${adapter.agentType} registerRoutes failed:`, err);
-        }
+    try {
+        const { registerOpenclawRoutes } = await import("./openclaw-routes.js");
+        registerOpenclawRoutes(app);
+    }
+    catch (err) {
+        console.error("[instances] openclaw route registration failed:", err);
     }
 }
 //# sourceMappingURL=instances.js.map