jishushell 0.4.24 → 0.5.15

package/dist/routes/instances.js

@@ -9,6 +9,7 @@ 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 { writeSecretFile } from "../utils/fs.js";
+import { Readable } from "node:stream";
 // 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([
@@ -47,6 +48,17 @@ function joinProxyPath(basePath, suffix) {
         return normalizedBase;
     return `${normalizedBase}/${normalizedSuffix}`;
 }
+function canonicalCapabilityProxyBase(basePath, capabilityPath) {
+    const normalizedCapabilityPath = typeof capabilityPath === "string" ? capabilityPath.trim() : "";
+    const needsTrailingSlash = !normalizedCapabilityPath || normalizedCapabilityPath.endsWith("/");
+    return needsTrailingSlash ? `${basePath}/` : basePath;
+}
+function rewriteCapabilityLocation(basePath, canonicalBasePath, pathname, search = "", hash = "") {
+    const rewrittenPath = pathname === "/"
+        ? canonicalBasePath
+        : joinProxyPath(basePath, pathname);
+    return `${rewrittenPath}${search}${hash}`;
+}
 function joinUpstreamPath(basePath, suffix) {
     const normalizedBase = typeof basePath === "string" && basePath.trim()
         ? (basePath.startsWith("/") ? basePath : `/${basePath}`)
@@ -60,11 +72,307 @@ function shouldRewriteProxyResponse(contentType) {
     const value = (contentType ?? "").toLowerCase();
     return value.includes("text/html") || value.includes("text/css");
 }
-function rewriteProxyTextBody(body, contentType, proxyBasePath) {
+function browserlessDebuggerBootstrap(instanceId) {
+    const apiProxyPath = `${capabilityProxyPath(instanceId, "browserless-api")}`;
+    const escapedPath = JSON.stringify(apiProxyPath + "/");
+    const escapedProxyBase = JSON.stringify(apiProxyPath);
+    const escapedWorkerPrelude = JSON.stringify([
+        "(function(){",
+        `var P=${escapedProxyBase};`,
+        "var _WS=self.WebSocket;",
+        "if(typeof _WS!=='function')return;",
+        "self.WebSocket=function(url,protocols){",
+        "try{var p=new URL(url,self.location.origin);",
+        "if(p.host===self.location.host&&!p.pathname.startsWith('/api/')){",
+        "var s=self.location.protocol==='https:'?'wss:':'ws:';",
+        "url=s+'//'+self.location.host+P+p.pathname+p.search;",
+        "}}catch(_e){}",
+        "return protocols!==undefined?new _WS(url,protocols):new _WS(url);",
+        "};",
+        "self.WebSocket.prototype=_WS.prototype;",
+        "self.WebSocket.CONNECTING=_WS.CONNECTING;",
+        "self.WebSocket.OPEN=_WS.OPEN;",
+        "self.WebSocket.CLOSING=_WS.CLOSING;",
+        "self.WebSocket.CLOSED=_WS.CLOSED;",
+        "})();",
+    ].join(""));
+    // 1) Set baseURL in localStorage so the debugger's HTTP API calls go through
+    //    the capability proxy.
+    // 2) Monkey-patch WebSocket in the page and any same-origin workers so that
+    //    Browserless connections targeting the panel origin (e.g.
+    //    ws://panel:8090/?launch=...) are rewritten through the capability proxy.
+    return [
+        "<script>(function(){",
+        // --- localStorage apiSettings.baseURL ---
+        // Browserless reads `state.apiSettings.baseURL` (a NESTED object); writing
+        // a flat `state.baseURL` is silently ignored, and the SPA falls back to
+        // `window.location.origin` (no proxy prefix) — producing connect URLs like
+        // `ws://panel:8090/?launch=...` that bypass the capability proxy.
+        "try{var key='browserless-debugger:'+window.location.origin+window.location.pathname;",
+        "var raw=window.localStorage.getItem(key)||'{}';",
+        "var state={};try{state=JSON.parse(raw)||{}}catch(_e){}",
+        `var base=new URL(${escapedPath},window.location.origin);`,
+        "var token=new URL(window.location.href).searchParams.get('token');",
+        "if(token)base.searchParams.set('token',token);",
+        "var settings=(state&&typeof state.apiSettings==='object'&&state.apiSettings)?state.apiSettings:{};",
+        "settings.baseURL=base.href;",
+        "state.apiSettings=settings;",
+        "window.localStorage.setItem(key,JSON.stringify(state));",
+        "}catch(_e){}",
+        // --- WebSocket monkey-patch ---
+        "var _WS=window.WebSocket;",
+        `var _base=${escapedProxyBase};`,
+        "window.WebSocket=function(url,protocols){",
+        "try{var p=new URL(url,window.location.origin);",
+        "if(p.host===window.location.host&&!p.pathname.startsWith('/api/')){",
+        "var s=window.location.protocol==='https:'?'wss:':'ws:';",
+        "url=s+'//'+window.location.host+_base+p.pathname+p.search;",
+        "}}catch(_e){}",
+        "return protocols!==undefined?new _WS(url,protocols):new _WS(url);",
+        "};",
+        "window.WebSocket.prototype=_WS.prototype;",
+        "window.WebSocket.CONNECTING=_WS.CONNECTING;",
+        "window.WebSocket.OPEN=_WS.OPEN;",
+        "window.WebSocket.CLOSING=_WS.CLOSING;",
+        "window.WebSocket.CLOSED=_WS.CLOSED;",
+        // --- Worker monkey-patch ---
+        "var _Worker=window.Worker;",
+        `var _workerPrelude=${escapedWorkerPrelude};`,
+        "function shouldWrapWorker(url){",
+        "try{var p=new URL(String(url),window.location.href);",
+        "return p.protocol==='blob:'||p.protocol==='data:'||p.origin===window.location.origin;",
+        "}catch(_e){return false;}",
+        "}",
+        "function wrapWorker(url,options){",
+        "if(typeof _Worker!=='function'||!shouldWrapWorker(url))return url;",
+        "try{var resolved=new URL(String(url),window.location.href).href;",
+        "var isModule=!!(options&&options.type==='module');",
+        "var source=isModule?_workerPrelude+'\\nimport '+JSON.stringify(resolved)+';':_workerPrelude+'\\nimportScripts('+JSON.stringify(resolved)+');';",
+        "return URL.createObjectURL(new Blob([source],{type:'text/javascript'}));",
+        "}catch(_e){return url;}",
+        "}",
+        "if(typeof _Worker==='function'){",
+        "window.Worker=function(url,options){",
+        "var wrapped=wrapWorker(url,options);",
+        "return options!==undefined?new _Worker(wrapped,options):new _Worker(wrapped);",
+        "};",
+        "window.Worker.prototype=_Worker.prototype;",
+        "}",
+        "})();</script>",
+    ].join("");
+}
+/**
+ * Inject a tiny <script> that monkey-patches `fetch`, `XMLHttpRequest.open`,
+ * and `Element.prototype.{setAttribute,src,href}` so that same-origin absolute
+ * paths (e.g. `/api/v1/...`, `/static/...`) are transparently rewritten to go
+ * through the capability proxy prefix.
+ *
+ * The alternative — rewriting every JS bundle byte-for-byte — is fragile and
+ * expensive; a runtime shim at document load is the standard approach used by
+ * reverse-proxy front-ends (cf. Cloudflare Access, oauth2-proxy, etc.).
+ */
+function capabilityProxyBootstrap(proxyBasePath) {
+    const prefix = JSON.stringify(proxyBasePath.replace(/\/+$/, ""));
+    const workerPrelude = JSON.stringify([
+        "(function(){",
+        `var P=${prefix};`,
+        "function px(path){",
+        "if(!path||path.charAt(0)!=='/'||path.charAt(1)==='/'||path.indexOf(P)===0||path.indexOf('/api/instances/')===0)return path;",
+        "return P+path;",
+        "}",
+        "function str(u){return typeof u==='string'?u:(u&&typeof u.href==='string'?u.href:null);}",
+        "function rwWs(u){",
+        "var s0=str(u);if(!s0)return u;",
+        "var H=typeof __capProxyHost==='string'?__capProxyHost:self.location.host;",
+        "var L=typeof __capProxyProtocol==='string'?__capProxyProtocol:self.location.protocol;",
+        "var B=(L==='https:'?'https:':'http:')+'//'+H+'/';",
+        "try{var p=new URL(s0,B);",
+        "if(p.host===H&&(p.protocol==='ws:'||p.protocol==='wss:'||p.protocol===L)){",
+        "var pp=px(p.pathname);",
+        "if(pp!==p.pathname){var s=L==='https:'?'wss:':'ws:';return s+'//'+H+pp+p.search+p.hash;}",
+        "}}catch(_e){}",
+        "return u;",
+        "}",
+        "var _WS=self.WebSocket;",
+        "if(typeof _WS==='function')self.WebSocket=function(url,protocols){url=rwWs(url);return protocols!==undefined?new _WS(url,protocols):new _WS(url);};",
+        "if(typeof _WS==='function'){self.WebSocket.prototype=_WS.prototype;self.WebSocket.CONNECTING=_WS.CONNECTING;self.WebSocket.OPEN=_WS.OPEN;self.WebSocket.CLOSING=_WS.CLOSING;self.WebSocket.CLOSED=_WS.CLOSED;}",
+        "})();",
+    ].join(""));
+    return [
+        "<script>(function(){",
+        `var P=${prefix};`,
+        "var O=window.location.origin;",
+        // --- Service Worker neutralization ---
+        // Embedded SPAs like OpenWebUI register a service worker that aggressively
+        // caches HTML and JS chunks at the proxy origin. After we update the proxy
+        // bootstrap, the SW would keep serving the old (unpatched) HTML, so socket.io
+        // never gets the WebSocket monkey-patch and the splash screen spins forever.
+        // Unregister any existing SW, purge its caches, and block future
+        // registrations for the lifetime of the iframe.
+        "try{if(navigator.serviceWorker){",
+        "if(navigator.serviceWorker.getRegistrations){",
+        "navigator.serviceWorker.getRegistrations().then(function(rs){rs.forEach(function(r){try{r.unregister()}catch(_e){}})}).catch(function(){});",
+        "}",
+        "navigator.serviceWorker.register=function(){return Promise.reject(new Error('service worker disabled in capability proxy'))};",
+        "}}catch(_e){}",
+        "try{if(window.caches&&caches.keys){caches.keys().then(function(ks){ks.forEach(function(k){try{caches.delete(k)}catch(_e){}})}).catch(function(){});}}catch(_e){}",
+        // Only rewrite paths that do NOT already start with the proxy prefix and
+        // that are simple absolute paths (start with `/` but not `//`).
+        "function px(path){",
+        "if(!path||path.charAt(0)!=='/'||path.charAt(1)==='/'||path.indexOf(P)===0||path.indexOf('/api/instances/')===0)return path;",
+        "return P+path;",
+        "}",
+        "function str(u){return typeof u==='string'?u:(u&&typeof u.href==='string'?u.href:null);}",
+        "function rw(u){",
+        "var s0=str(u);if(!s0)return u;",
+        "var direct=px(s0);",
+        "if(direct!==s0)return direct;",
+        "try{var p=new URL(s0,window.location.href);",
+        "if(p.origin===O){var pp=px(p.pathname);if(pp!==p.pathname)return pp+p.search+p.hash;}",
+        "}catch(_e){}",
+        "return u;",
+        "}",
+        "function rwWs(u){",
+        "var s0=str(u);if(!s0)return u;",
+        "try{var p=new URL(s0,window.location.href);",
+        "if(p.host===window.location.host&&(p.protocol==='ws:'||p.protocol==='wss:'||p.protocol===window.location.protocol)){",
+        "var pp=px(p.pathname);",
+        "if(pp!==p.pathname){var s=window.location.protocol==='https:'?'wss:':'ws:';return s+'//'+window.location.host+pp+p.search+p.hash;}",
+        "}}catch(_e){}",
+        "return u;",
+        "}",
+        // --- fetch() ---
+        "var _f=window.fetch;",
+        "window.fetch=function(r,o){",
+        "if(typeof r==='string'||(r&&typeof r.href==='string'))r=rw(r);",
+        "else if(r instanceof Request){",
+        "var nr=rw(r.url);if(nr!==r.url)r=new Request(nr,r);}",
+        "return _f.call(this,r,o);};",
+        // --- XMLHttpRequest.open() ---
+        "var _xo=XMLHttpRequest.prototype.open;",
+        "XMLHttpRequest.prototype.open=function(m,u){",
+        "arguments[1]=rw(u);",
+        "return _xo.apply(this,arguments);};",
+        // --- history.pushState / replaceState ---
+        // SPA routers (SvelteKit, React Router, etc.) navigate via pushState.
+        // Without this, pushing "/" lands on the panel's own SPA.
+        "var _ps=history.pushState;",
+        "var _rs=history.replaceState;",
+        "history.pushState=function(s,t,u){",
+        "if(typeof u==='string')u=rw(u);",
+        "return _ps.call(this,s,t,u);};",
+        "history.replaceState=function(s,t,u){",
+        "if(typeof u==='string')u=rw(u);",
+        "return _rs.call(this,s,t,u);};",
+        // --- location.assign / location.replace ---
+        "var _la=location.assign.bind(location);",
+        "var _lr=location.replace.bind(location);",
+        "location.assign=function(u){return _la(rw(u));};",
+        "location.replace=function(u){return _lr(rw(u));};",
+        // --- frame-busting defense ---
+        // Embedded SPAs (e.g. WeKnora) frequently do
+        //   window.top.location.href = '/login'
+        // when they see a 401, intending to log the user out. Inside our
+        // capability proxy iframe `top` is the panel's main window — that
+        // tears the user away from the instance detail page entirely.
+        // Redirect `top`/`parent` to the iframe's own window so the
+        // navigation stays inside the embed. Safe because the iframe IS
+        // same-origin as the panel (our reverse proxy serves it from the
+        // panel's host); cross-origin access would throw and fail closed.
+        "try{",
+        "Object.defineProperty(window,'top',{configurable:true,get:function(){return window;}});",
+        "Object.defineProperty(window,'parent',{configurable:true,get:function(){return window;}});",
+        "}catch(_e){}",
+        // --- dynamic property assignment: img.src = '/static/...' ---
+        "function patchProp(tag,prop){",
+        "var d=Object.getOwnPropertyDescriptor(tag.prototype,prop);",
+        "if(!d||!d.set)return;",
+        "var orig=d.set;",
+        "Object.defineProperty(tag.prototype,prop,{",
+        "set:function(v){return orig.call(this,rw(v));},",
+        "get:d.get,configurable:true,enumerable:true});",
+        "}",
+        "patchProp(HTMLImageElement,'src');",
+        "patchProp(HTMLScriptElement,'src');",
+        "patchProp(HTMLLinkElement,'href');",
+        "patchProp(HTMLSourceElement,'src');",
+        // --- Worker monkey-patch ---
+        // Some SPA clients create socket.io/WebSocket connections from workers.
+        // Patch same-origin workers so the same proxy-prefixing rule applies there.
+        "var _Worker=window.Worker;",
+        `var _workerPrelude=${workerPrelude};`,
+        "function shouldWrapWorker(url){",
+        "try{var p=new URL(String(url),window.location.href);return p.protocol==='blob:'||p.protocol==='data:'||p.origin===O;}catch(_e){return false;}",
+        "}",
+        "function wrapWorker(url,options){",
+        "if(typeof _Worker!=='function'||!shouldWrapWorker(url))return url;",
+        "try{var resolved=new URL(String(url),window.location.href).href;",
+        "var isModule=!!(options&&options.type==='module');",
+        "var workerEnv='var __capProxyHost='+JSON.stringify(window.location.host)+';var __capProxyProtocol='+JSON.stringify(window.location.protocol)+';';",
+        "var source=isModule?workerEnv+_workerPrelude+'\\nimport '+JSON.stringify(resolved)+';':workerEnv+_workerPrelude+'\\nimportScripts('+JSON.stringify(resolved)+');';",
+        "return URL.createObjectURL(new Blob([source],{type:'text/javascript'}));",
+        "}catch(_e){return url;}",
+        "}",
+        "if(typeof _Worker==='function'){",
+        "window.Worker=function(url,options){var wrapped=wrapWorker(url,options);return options!==undefined?new _Worker(wrapped,options):new _Worker(wrapped);};",
+        "window.Worker.prototype=_Worker.prototype;",
+        "}",
+        // --- WebSocket ---
+        // SPAs like OpenWebUI use socket.io over WebSocket. The socket.io client
+        // builds ws:// URLs from window.location and the configured path; the URL
+        // ends up pointing at the panel root (e.g. ws://panel:8090/ws/socket.io)
+        // instead of the capability proxy.  Without this patch the WS upgrade
+        // request either gets destroyed (no route) or hits the wrong backend.
+        "var _WS=window.WebSocket;",
+        "if(typeof _WS==='function'){",
+        "window.WebSocket=function(url,protocols){",
+        "url=rwWs(url);",
+        "return protocols!==undefined?new _WS(url,protocols):new _WS(url);",
+        "};",
+        "window.WebSocket.prototype=_WS.prototype;",
+        "window.WebSocket.CONNECTING=_WS.CONNECTING;",
+        "window.WebSocket.OPEN=_WS.OPEN;",
+        "window.WebSocket.CLOSING=_WS.CLOSING;",
+        "window.WebSocket.CLOSED=_WS.CLOSED;",
+        "}",
+        // --- EventSource ---
+        // Some frameworks use SSE (Server-Sent Events) for real-time updates.
+        "var _ES=window.EventSource;",
+        "if(typeof _ES==='function'){",
+        "window.EventSource=function(url,opts){",
+        "if(typeof url==='string')url=rw(url);",
+        "return new _ES(url,opts);",
+        "};",
+        "window.EventSource.prototype=_ES.prototype;",
+        "window.EventSource.CONNECTING=_ES.CONNECTING;",
+        "window.EventSource.OPEN=_ES.OPEN;",
+        "window.EventSource.CLOSED=_ES.CLOSED;",
+        "}",
+        "})();</script>",
+    ].join("");
+}
+function rewriteProxyTextBody(body, contentType, proxyBasePath, extraHeadHtml = "") {
     const value = (contentType ?? "").toLowerCase();
     const proxyBaseWithSlash = `${proxyBasePath.replace(/\/+$/, "")}/`;
     let rewritten = body;
     if (value.includes("text/html")) {
+        // Rewrite asset URLs FIRST, then optionally inject a <base> tag.
+        // Reversing the order would let the regex below match (and double-
+        // prefix) the leading slash of the just-inserted `<base href="/api/...">`,
+        // producing
+        //   <base href="/api/instances/X/provides/Y/api/instances/X/provides/Y/">
+        // which then resolves every relative asset to a 404.
+        rewritten = rewritten.replace(/((?:href|src|action|poster)=['"])\/(?!\/)/gi, `$1${proxyBaseWithSlash}`);
+        // Rewrite dynamic import() paths inside inline <script> blocks so that
+        // SvelteKit (and similar frameworks) resolve JS modules through the proxy.
+        // Matches import("/_app/...") and import('/_app/...').
+        rewritten = rewritten.replace(/\bimport\(\s*(['"])\/(?!\/)/g, `import($1${proxyBaseWithSlash}`);
+        // Rewrite SvelteKit's client-side base path so that client-side routing
+        // and subsequent chunk fetches go through the capability proxy path.
+        // Older SvelteKit SSR output: __sveltekit_XXXXX = { base: "" };
+        rewritten = rewritten.replace(/(__sveltekit_\w+\s*=\s*\{\s*base\s*:\s*)(["'])["']/, `$1$2${proxyBasePath.replace(/\/+$/, "")}$2`);
+        // SvelteKit 2.x start() config: paths: { base: "", assets: "..." }
+        rewritten = rewritten.replace(/(paths\s*:\s*\{\s*base\s*:\s*)(["'])["'](\s*,\s*assets\s*:)/, `$1$2${proxyBasePath.replace(/\/+$/, "")}$2$3`);
         if (!/<base\b/i.test(rewritten)) {
             if (/<head[^>]*>/i.test(rewritten)) {
                 rewritten = rewritten.replace(/<head([^>]*)>/i, `<head$1><base href="${proxyBaseWithSlash}">`);
@@ -73,11 +381,25 @@ function rewriteProxyTextBody(body, contentType, proxyBasePath) {
                 rewritten = `<base href="${proxyBaseWithSlash}">${rewritten}`;
             }
         }
-        rewritten = rewritten.replace(/((?:href|src|action|poster)=['"])\/(?!\/)/gi, `$1${proxyBaseWithSlash}`);
+        if (extraHeadHtml) {
+            if (/<base\b/i.test(rewritten)) {
+                rewritten = rewritten.replace(/<base\b[^>]*>/i, (match) => `${match}${extraHeadHtml}`);
+            }
+            else if (/<head[^>]*>/i.test(rewritten)) {
+                rewritten = rewritten.replace(/<head([^>]*)>/i, `<head$1>${extraHeadHtml}`);
+            }
+            else {
+                rewritten = `${extraHeadHtml}${rewritten}`;
+            }
+        }
     }
-    if (value.includes("text/css") || value.includes("text/html")) {
+    if (value.includes("text/css")) {
         rewritten = rewritten.replace(/url\((['"]?)\/(?!\/)/gi, `url($1${proxyBaseWithSlash}`);
     }
+    else if (value.includes("text/html")) {
+        // HTML can contain inline scripts like new URL("/..."); only rewrite lowercase CSS url(...).
+        rewritten = rewritten.replace(/url\((['"]?)\/(?!\/)/g, `url($1${proxyBaseWithSlash}`);
+    }
     return rewritten;
 }
 function buildProxyRequestBody(req) {
@@ -202,13 +524,19 @@ async function proxyProvidedCapability(req, reply) {
     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 upstreamHost = await instanceManager.getHostForAppPort(req.params.id, 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 proxyBasePath = capabilityProxyPath(req.params.id, req.params.capability);
     const querySuffix = req.raw.url?.includes("?") ? req.raw.url.slice(req.raw.url.indexOf("?")) : "";
+    const requestPath = req.raw.url?.split("?")[0] ?? "";
+    const canonicalProxyBase = canonicalCapabilityProxyBase(proxyBasePath, capability.path);
+    if (!wildcardSuffix && canonicalProxyBase !== proxyBasePath && !requestPath.endsWith("/")) {
+        reply.code(308).header("location", `${canonicalProxyBase}${querySuffix}`);
+        return reply.send();
+    }
+    const upstreamPath = joinUpstreamPath(capability.path, wildcardSuffix);
     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)
@@ -226,6 +554,8 @@ async function proxyProvidedCapability(req, reply) {
         }
     }
     headers.set("accept-encoding", "identity");
+    if (headers.has("origin"))
+        headers.set("origin", upstreamOrigin);
     // `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
@@ -233,30 +563,85 @@ 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);
+    // 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
+    // and the page never receives our latest bootstrap (WebSocket / fetch
+    // monkey-patch).  We replace the SW body with a self-unregistration stub so
+    // the next browser update cycle removes the offending worker and restores
+    // network-backed loading.
+    if (/(?:^|\/)(?:service-worker|sw)\.js$/i.test(requestPath)) {
+        reply
+            .code(200)
+            .header("content-type", "application/javascript; charset=utf-8")
+            .header("cache-control", "no-store, no-cache, must-revalidate, max-age=0")
+            .header("pragma", "no-cache")
+            .header("service-worker-allowed", "/");
+        return reply.send("// Capability proxy: service worker intentionally disabled.\n" +
+            "self.addEventListener('install',function(e){self.skipWaiting()});\n" +
+            "self.addEventListener('activate',function(e){\n" +
+            "  e.waitUntil((async function(){\n" +
+            "    try{var cs=await caches.keys();for(var i=0;i<cs.length;i++){try{await caches.delete(cs[i])}catch(_e){}}}catch(_e){}\n" +
+            "    try{var clients=await self.clients.matchAll({includeUncontrolled:true});clients.forEach(function(c){try{c.navigate(c.url)}catch(_e){}})}catch(_e){}\n" +
+            "    try{await self.registration.unregister()}catch(_e){}\n" +
+            "  })());\n" +
+            "});\n");
+    }
+    // Single AbortController so we can cancel the upstream when the client
+    // disconnects. AbortSignal.timeout() only limits connection establishment;
+    // long-poll/SSE bodies (e.g. socket.io) would otherwise pin the fetch
+    // 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);
     try {
         const upstream = await fetch(targetUrl, {
             method: req.method,
             headers,
             body: buildProxyRequestBody(req),
             redirect: "manual",
-            signal: AbortSignal.timeout(60_000),
-        });
+            signal: upstreamAbort.signal,
+        }).finally(() => clearTimeout(connectTimer));
+        const upstreamContentType = upstream.headers.get("content-type");
+        const willRewriteBody = shouldRewriteProxyResponse(upstreamContentType);
+        const willInjectHtml = (upstreamContentType ?? "").toLowerCase().includes("text/html");
         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;
             }
+            // When we rewrite the response body (HTML/CSS/JS), the upstream ETag /
+            // Cache-Control values describe the *original* upstream bytes — but the
+            // body the browser receives is post-rewrite (proxy-prefixed paths, JS
+            // 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.
+            // Strip cache validators and force revalidation on every load.
+            if (willRewriteBody && (normalizedKey === "cache-control" ||
+                normalizedKey === "etag" ||
+                normalizedKey === "last-modified" ||
+                normalizedKey === "expires" ||
+                normalizedKey === "pragma")) {
+                return;
+            }
+            if (willInjectHtml && (normalizedKey === "content-security-policy" ||
+                normalizedKey === "content-security-policy-report-only" ||
+                normalizedKey === "x-frame-options")) {
+                return;
+            }
             if (normalizedKey === "location") {
                 if (value.startsWith("/")) {
-                    reply.header(key, joinProxyPath(proxyBasePath, value));
+                    reply.header(key, rewriteCapabilityLocation(proxyBasePath, canonicalProxyBase, 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}`);
+                        reply.header(key, rewriteCapabilityLocation(proxyBasePath, canonicalProxyBase, parsed.pathname, parsed.search, parsed.hash));
                         return;
                     }
                 }
@@ -267,16 +652,58 @@ async function proxyProvidedCapability(req, reply) {
             reply.header(key, value);
         });
         if (req.method === "HEAD") {
+            req.raw.off("close", onClientClose);
             return reply.send();
         }
-        if (shouldRewriteProxyResponse(upstream.headers.get("content-type"))) {
-            const rewritten = rewriteProxyTextBody(await upstream.text(), upstream.headers.get("content-type"), proxyBasePath);
+        if (willRewriteBody) {
+            // Pair with the cache-validator strip above.
+            reply.header("cache-control", "no-cache, no-store, must-revalidate");
+            reply.header("pragma", "no-cache");
+            reply.header("expires", "0");
+            let extraHeadHtml = "";
+            if (req.params.capability === "browserless-debugger") {
+                extraHeadHtml = browserlessDebuggerBootstrap(req.params.id);
+            }
+            // 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.
+            // When the page is served under the proxy path those requests bypass
+            // the proxy and hit the panel's own `/api/` routes instead.  The patch
+            // intercepts fetch() and XMLHttpRequest.open() and rewrites same-origin
+            // absolute paths that do NOT already start with the proxy prefix.
+            extraHeadHtml += capabilityProxyBootstrap(proxyBasePath);
+            // First-visit cleanup: if the browser still has a stale ServiceWorker
+            // registered from an earlier panel build (which would intercept this
+            // navigation and serve cached HTML *without* the bootstrap patches),
+            // emit Clear-Site-Data so the browser drops the SW + its cache and
+            // reloads through the proxy. We mark the success with a long-lived
+            // cookie scoped to the proxy path to avoid a reload loop.
+            // Gate to HTML only — JS/CSS sub-resources also flow through this branch
+            // now that we rewrite JS bundles, and emitting Clear-Site-Data on a JS
+            // response would clear storage mid-page-load.
+            if (willInjectHtml) {
+                const cookieHeader = (req.headers.cookie || "").toString();
+                const swCleaned = /(?:^|;\s*)cap_proxy_sw_clean=1(?:;|$)/.test(cookieHeader);
+                if (!swCleaned) {
+                    reply.header("Clear-Site-Data", '"cache", "storage"');
+                    reply.header("Set-Cookie", `cap_proxy_sw_clean=1; Path=${proxyBasePath}; Max-Age=2592000; SameSite=Lax`);
+                }
+            }
+            const rawBody = await upstream.text();
+            req.raw.off("close", onClientClose);
+            const rewritten = rewriteProxyTextBody(rawBody, upstreamContentType, proxyBasePath, extraHeadHtml);
             return reply.send(rewritten);
         }
-        const buffer = Buffer.from(await upstream.arrayBuffer());
-        return reply.send(buffer);
+        if (!upstream.body) {
+            req.raw.off("close", onClientClose);
+            return reply.send();
+        }
+        const readable = Readable.fromWeb(upstream.body);
+        readable.once("close", () => req.raw.off("close", onClientClose));
+        return reply.send(readable);
     }
     catch (error) {
+        req.raw.off("close", onClientClose);
         return reply.status(502).send({ detail: error?.message || `Failed to proxy capability '${req.params.capability}'` });
     }
 }
@@ -327,9 +754,38 @@ function isLegacyInstanceAppType(value) {
 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) {
@@ -483,7 +939,7 @@ export async function instanceRoutes(app) {
             (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
+        // 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"
@@ -828,7 +1284,15 @@ export async function instanceRoutes(app) {
                 payload.building = true;
             if (resultRecord.taskId)
                 payload.taskId = resultRecord.taskId;
-            return reply.status(400).send(payload);
+            if (resultRecord.code)
+                payload.code = resultRecord.code;
+            // Honor the structured ConnectionError statusCode (412 / 409 / 400)
+            // when present so the UI can distinguish missing-required from
+            // ambiguous-prefix from invalid-binding without parsing the message.
+            const statusCode = typeof resultRecord.statusCode === "number" && resultRecord.statusCode >= 400
+                ? resultRecord.statusCode
+                : 400;
+            return reply.status(statusCode).send(payload);
         }
         return result;
     });
@@ -1199,7 +1663,7 @@ export async function instanceRoutes(app) {
         return { lines: logLines };
     });
     // Admin: re-encrypt all instance secrets with current AES key
-    app.post("/api/admin/migrate-secrets", async (_req, reply) => {
+    app.post("/api/admin/migrate-secrets", async (_req, _reply) => {
         const { getAesKey, getJwtSecret } = await import("../config.js");
         const { scryptSync, createDecipheriv, createCipheriv, randomBytes } = await import("crypto");
         const { readFileSync, existsSync: fsExistsSync } = await import("fs");
@@ -1314,6 +1778,351 @@ export async function instanceRoutes(app) {
             return reply.status(500).send({ detail: `Failed to pull image: ${e.message}` });
         }
     });
+    // ── 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;
+            }
+        }
+        catch {
+            adapter = null;
+        }
+        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,
+                })),
+            };
+        }
+        catch (e) {
+            const status = e?.statusCode ?? 500;
+            return reply.status(status).send({
+                detail: e?.message ?? "Connection apply failed",
+                code: e?.code,
+                ...(e?.details ? { details: e.details } : {}),
+            });
+        }
+    });
+    /** 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 };
+        }
+        catch (e) {
+            return { state: "error", unboundRequired: [], unboundOptional: [], bindable: 0, error: e.message };
+        }
+    });
+    // ── Suggestions API (PR 6) ─────────────────────────────────────────────
+    app.get("/api/suggestions", async () => {
+        const { computeSuggestions } = await import("../services/suggestions.js");
+        return { suggestions: computeSuggestions() };
+    });
+    app.post("/api/suggestions/:id/apply", async (req, reply) => {
+        const { computeSuggestions } = await import("../services/suggestions.js");
+        const all = computeSuggestions();
+        const target = all.find((s) => s.id === req.params.id);
+        if (!target) {
+            return reply.status(404).send({ detail: "Suggestion no longer applies" });
+        }
+        // Apply by issuing the equivalent PUT /connections — read current
+        // bindings, splice in the new one for `slot`, persist via the
+        // transactor.
+        const meta = instanceManager.getInstance(target.consumerInstanceId);
+        if (!meta)
+            return reply.status(404).send({ detail: "Consumer instance not found" });
+        // Resolve consumer spec — app-installed instances have it in the app
+        // registry; legacy instances (no app_id) fall back to the
+        // yaml-template synthesizer used everywhere else for legacy
+        // capability work.
+        let consumerSpec = null;
+        if (target.appId) {
+            const appData = instanceManager.getApp(target.appId);
+            if (!appData)
+                return reply.status(404).send({ detail: "App spec not found" });
+            consumerSpec = appData.spec;
+        }
+        else {
+            const { loadCapabilitySpecForLegacyInstance } = await import("../services/runtime/migrations.js");
+            consumerSpec = loadCapabilitySpecForLegacyInstance(meta);
+            if (!consumerSpec) {
+                return reply.status(404).send({ detail: "No capability spec for legacy instance" });
+            }
+        }
+        const newConnections = {
+            ...(meta.connections ?? {}),
+            [target.slot]: {
+                kind: "single",
+                providerId: target.candidate.providerId,
+                capability: target.candidate.capability,
+            },
+        };
+        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(target.consumerInstanceId);
+        const readInstanceJson = async () => (safeJson.safeReadJson(instancePath, `instance:${target.consumerInstanceId}`) ?? {});
+        const saveInstanceJson = async (_id, mutator) => {
+            const cur = (safeJson.safeReadJson(instancePath, `instance:${target.consumerInstanceId}`) ?? {});
+            try {
+                fs.mkdirSync(path.dirname(instancePath), { recursive: true });
+            }
+            catch {
+                /* noop */
+            }
+            safeJson.safeWriteJson(instancePath, mutator(cur));
+        };
+        let adapter = null;
+        try {
+            const agentType = resolveAgentType(meta);
+            if (hasAdapter(agentType)) {
+                adapter = getAdapter(agentType);
+                if (typeof adapter.applyConnectionEnv !== "function")
+                    adapter = null;
+            }
+        }
+        catch {
+            adapter = null;
+        }
+        try {
+            const result = await applyConnections({
+                instance: meta,
+                spec: consumerSpec,
+                newConnections,
+                saveInstanceJson,
+                readInstanceJson,
+                adapter,
+            });
+            return { ok: true, applied: target.id, resolved: result.resolved.length };
+        }
+        catch (e) {
+            return reply.status(e?.statusCode ?? 500).send({
+                detail: e?.message ?? "Suggestion apply failed",
+                code: e?.code,
+            });
+        }
+    });
+    app.post("/api/suggestions/:id/dismiss", async (req, reply) => {
+        const { dismissSuggestion } = await import("../services/suggestions.js");
+        try {
+            await dismissSuggestion(req.params.id);
+            return { ok: true };
+        }
+        catch (e) {
+            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/