@wootsup/yt-builder-mcp 1.12.0 → 2.0.0

package/dist/proxy/bridge.js

@@ -1,10 +1,27 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { resolveMode } from './mode.js';
+import { RestClient } from '../client.js';
+import { probeCompatNotice } from '../compat-probe.js';
+import { ConfigError } from '../errors.js';
+import { configProblemFor } from '../sites/config-problem.js';
+import { SitesFileError } from '../sites/store.js';
+import { buildProxyInstructions } from './instructions.js';
+import { resolveBridgeTarget } from './mode.js';
+import { createProxyMultiSite } from './multi-site.js';
+import { buildProxyRequestHeaders } from './request-headers.js';
+import { TOOLS_LIST_WIRE_CAP_BYTES, oversizeToolsList } from './tools-list-cap.js';
+import { createShadowToolBridge } from './shadow-tools.js';
+import { buildInstructions } from '../skill-instructions.js';
 import { diagnoseNetworkError } from '../diagnostics/diagnose-network-error.js';
-import { mergeExtraHeaders, parseExtraHeaders } from '../net/extra-headers.js';
-import { applyUserinfoToUrl, parseSiteBasicAuth } from '../net/site-basic-auth.js';
-/** Narrow an unknown caught value to a human-readable message (no `any`). */
+import { transportUncertaintyHint } from './transport-uncertainty.js';
+import { parseExtraHeaders } from '../net/extra-headers.js';
+import { parseSiteBasicAuth } from '../net/site-basic-auth.js';
+import { createSessionRecoveryFetch } from '../net/session-recovery-fetch.js';
+import { activeSiteFromRouting, textWithActiveSite, withActiveSiteKey, } from '../tools/active-site.js';
+import { HostPrompter, needsHostPrompt, parksForHostPrompt, previewPayload, spliceHostPrompt, } from './confirm-elicitation.js';
+import { promptFromPreview } from './confirm-question.js';
+const PROXY_COMPAT_PROBE_TIMEOUT_MS = 4_000;
+import { upstreamRpcError, upstreamRpcErrorMessage } from './upstream-error.js';
 function errorMessage(err) {
     if (err instanceof Error)
         return err.message;
@@ -17,10 +34,6 @@ function errorMessage(err) {
         return 'unknown error';
     }
 }
-/**
- * A forwarded message is request-shaped (and therefore answerable with a
- * JSON-RPC error) iff it carries a non-null `id`. Notifications have no `id`.
- */
 function requestId(msg) {
     if (msg !== null && typeof msg === 'object' && 'id' in msg) {
         const id = msg.id;
@@ -41,38 +54,15 @@ function isNestedCallToolResult(v) {
     const content = v.content;
     return Array.isArray(content) && content.length > 0 && isTextContentBlock(content[0]);
 }
-/**
- * Normalise the WordPress↔Joomla `/mcp` envelope asymmetry for `tools/call`
- * responses.
- *
- * The WP mcp-adapter (`ToolsHandler`) treats an Ability's return value as raw
- * data and `wp_json_encode`s our already-final `CallToolResult` into a fresh
- * text-content block. Over the wire that yields a DOUBLE-wrapped result —
- * `result.content[0].text` is itself a serialised `CallToolResult`
- * (`{"content":[{"type":"text","text":"<real-data-json>"}],"isError":…}`).
- * Joomla's `/api/` handler single-wraps: `result.content[0].text` is already
- * the real data JSON. The proxy bridge is a verbatim pipe, so a WP customer
- * would receive doubly-nested tool output while a Joomla customer would not.
- *
- * Strip EXACTLY ONE level of that nesting, and ONLY when the inner payload is
- * unmistakably a nested `CallToolResult`. Every shape check is defensive
- * (try/catch around the parse, strict block typing) so a genuine Joomla data
- * payload is never touched. Non-`tools/call` frames (initialize, tools/list,
- * JSON-RPC errors, notifications) are returned by reference, unchanged.
- *
- * Exported for unit tests.
- */
 export function normalizeProxyResponse(msg) {
     if (msg === null || typeof msg !== 'object')
         return msg;
     const result = msg.result;
     if (result === null || typeof result !== 'object')
         return msg;
-    // Only tools/call responses carry a `result.content` array.
     const content = result.content;
     if (!Array.isArray(content))
         return msg;
-    // A double-wrap is EXACTLY one text block whose text is a serialised result.
     if (content.length !== 1)
         return msg;
     const block = content[0];
@@ -83,15 +73,10 @@ export function normalizeProxyResponse(msg) {
         inner = JSON.parse(block.text);
     }
     catch {
-        // Joomla single-wrap (text is the real data JSON, not nested) or plain
-        // prose — leave the frame untouched.
         return msg;
     }
     if (!isNestedCallToolResult(inner))
         return msg;
-    // Unpack one level: keep the outer result's fields, swap in the inner
-    // content, and let the inner isError / structuredContent win when present
-    // (the inner is the REAL tool result; the outer is the adapter's wrapper).
     const normalizedResult = {
         ...result,
         content: inner.content,
@@ -103,67 +88,373 @@ export function normalizeProxyResponse(msg) {
     }
     return { ...msg, result: normalizedResult };
 }
-/**
- * Wire two MCP transports into a transparent pipe: every message from one side
- * is relayed to the other, and a close/error on either side tears down the
- * other. The local→remote direction is verbatim; the remote→local direction
- * normalises the WP double-wrap (see `normalizeProxyResponse`) so WP and Joomla
- * customers receive identical, spec-clean tool results. The PHP server otherwise
- * owns the protocol semantics.
- * The caller is responsible for start()ing both transports.
- *
- * `StreamableHTTPClientTransport.send()` re-throws on any upstream failure
- * (401/5xx/connection refused / missing PHP endpoint). The forwarders MUST NOT
- * fire-and-forget that rejection: an unhandled rejection crashes the Node
- * process, so a wrong key / unreachable site would kill the proxy on the first
- * `initialize` instead of surfacing an actionable error. Each direction
- * therefore `.catch()`es its `send()`.
- */
-export function bridgeTransports(local, remote) {
-    local.onmessage = (msg) => {
-        remote.send(msg).catch((err) => {
-            const message = errorMessage(err);
-            // Turn an opaque transport failure (TLS-inspection CA, proxy, DNS,
-            // timeout) into an actionable hint — the customer stress-test died with a
-            // 30s timeout that looked like an auth problem. Falls back to the generic
-            // config hint when the cause is not recognised.
-            const diag = diagnoseNetworkError(err);
-            const hint = diag !== null ? `${diag.summary} Fix: ${diag.fix}` : 'Check YTB_MCP_SITE_URL / YTB_MCP_BEARER_TOKEN.';
-            // stderr only — stdout is the JSON-RPC channel.
-            console.error('[yt-builder-proxy] upstream send failed:', message + (diag !== null ? `\n  → ${diag.fix}` : ''));
-            const id = requestId(msg);
-            if (id !== null) {
-                // Hand the client an actionable error instead of a dead pipe.
-                const frame = {
-                    jsonrpc: '2.0',
-                    id,
-                    error: {
-                        code: -32000,
-                        message: `Proxy upstream error: ${message}. ${hint}`,
-                    },
-                };
-                local.send(frame).catch((sendErr) => {
-                    console.error('[yt-builder-proxy] failed to deliver error frame:', errorMessage(sendErr));
-                });
+function isInitializeResult(result) {
+    return (typeof result.protocolVersion === 'string' &&
+        result.serverInfo !== null &&
+        typeof result.serverInfo === 'object');
+}
+function injectShadowSurface(msg, instructions, extraToolEntries) {
+    if (msg === null || typeof msg !== 'object')
+        return msg;
+    const result = msg.result;
+    if (result === null || typeof result !== 'object')
+        return msg;
+    const r = result;
+    if (instructions !== undefined && isInitializeResult(r)) {
+        return { ...msg, result: { ...r, instructions } };
+    }
+    if (extraToolEntries.length > 0 && Array.isArray(r.tools) && !('content' in r)) {
+        const ownNames = new Set(extraToolEntries.map((t) => t.name));
+        const foreign = r.tools.filter((t) => !ownNames.has(t.name));
+        return {
+            ...msg,
+            result: { ...r, tools: [...foreign, ...extraToolEntries] },
+        };
+    }
+    return msg;
+}
+function isNamedToolCall(msg, names) {
+    if (msg === null || typeof msg !== 'object')
+        return false;
+    const m = msg;
+    if (m.method !== 'tools/call')
+        return false;
+    const params = m.params;
+    if (params === null || typeof params !== 'object')
+        return false;
+    const name = params.name;
+    if (typeof name !== 'string' || !names.includes(name))
+        return false;
+    return requestId(msg) !== null;
+}
+function isToolCallRequest(msg) {
+    if (msg === null || typeof msg !== 'object')
+        return false;
+    const m = msg;
+    if (m.method !== 'tools/call')
+        return false;
+    const params = m.params;
+    if (params === null || typeof params !== 'object')
+        return false;
+    if (typeof params.name !== 'string')
+        return false;
+    return requestId(msg) !== null;
+}
+export const GATEWAY_TOOL_NAMES = [
+    'yootheme_builder_advanced',
+    'yootheme_builder_advanced_read',
+];
+export const HEALTH_TOOL_NAME = 'yootheme_builder_health';
+const MAX_PENDING_HEALTH_CALLS = 64;
+function rememberActiveSite(pending, id, active) {
+    if (pending.size >= MAX_PENDING_HEALTH_CALLS) {
+        const oldest = pending.keys().next();
+        if (!(oldest.done ?? false))
+            pending.delete(oldest.value);
+    }
+    pending.set(id, active);
+}
+function rememberConfirmIntent(pending, id, toolName) {
+    if (pending.size >= MAX_PENDING_HEALTH_CALLS) {
+        const oldest = pending.keys().next();
+        if (!(oldest.done ?? false))
+            pending.delete(oldest.value);
+    }
+    pending.set(id, toolName);
+}
+function releaseConfirmIntent(pending, id) {
+    if (id !== null)
+        pending.delete(id);
+}
+function spliceActiveSite(result, active) {
+    const out = { ...result };
+    const structured = out.structuredContent;
+    if (structured !== null && typeof structured === 'object' && !Array.isArray(structured)) {
+        out.structuredContent = withActiveSiteKey(structured, active);
+    }
+    const content = out.content;
+    if (Array.isArray(content) && content.length > 0) {
+        const first = content[0];
+        if (isTextContentBlock(first) && first.type === 'text') {
+            const enriched = textWithActiveSite(first.text, active);
+            if (enriched !== null) {
+                out.content = [{ ...first, text: enriched }, ...content.slice(1)];
             }
-            else {
-                // A notification has no id to answer — tear the pipe down instead.
-                void remote.close();
+        }
+    }
+    return out;
+}
+function applyPendingActiveSite(msg, pending) {
+    if (pending.size === 0 || msg === null || typeof msg !== 'object')
+        return msg;
+    const id = requestId(msg);
+    if (id === null)
+        return msg;
+    const active = pending.get(id);
+    if (active === undefined)
+        return msg;
+    pending.delete(id);
+    const result = msg.result;
+    if (result === null || typeof result !== 'object' || Array.isArray(result))
+        return msg;
+    return {
+        ...msg,
+        result: spliceActiveSite(result, active),
+    };
+}
+function readSiteId(args) {
+    const raw = args?.site_id;
+    return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
+}
+function extractSiteIdArg(toolName, args) {
+    if (GATEWAY_TOOL_NAMES.includes(toolName)) {
+        const inner = args?.arguments;
+        return readSiteId(inner !== null && typeof inner === 'object' ? inner : undefined);
+    }
+    return readSiteId(args);
+}
+function isGatewayDiscoveryCall(toolName, args) {
+    if (!GATEWAY_TOOL_NAMES.includes(toolName))
+        return false;
+    if (args === undefined)
+        return true;
+    return !('arguments' in args) && !('input' in args);
+}
+async function answerLocalToolCall(msg, callTool, local, errorLabel) {
+    const id = requestId(msg);
+    if (id === null)
+        return;
+    try {
+        const result = await callTool(msg.params.name, msg.params.arguments);
+        await local.send({ jsonrpc: '2.0', id, result });
+    }
+    catch (err) {
+        const message = errorMessage(err);
+        console.error(`[yt-builder-proxy] ${errorLabel} call failed:`, message);
+        await local
+            .send({
+            jsonrpc: '2.0',
+            id,
+            error: { code: -32000, message: `${errorLabel} error: ${message}` },
+        })
+            .catch((sendErr) => {
+            console.error(`[yt-builder-proxy] failed to deliver ${errorLabel.toLowerCase()} error frame:`, errorMessage(sendErr));
+        });
+    }
+}
+async function routeToolCallBySite(msg, siteRouter, local, remote, pendingHealth, hostPrompt, release) {
+    const explicit = extractSiteIdArg(msg.params.name, msg.params.arguments);
+    const effective = explicit ?? siteRouter.activeSiteId();
+    const active = isGatewayDiscoveryCall(msg.params.name, msg.params.arguments)
+        ? undefined
+        : activeSiteFromRouting(explicit, siteRouter.activeSiteId(), siteRouter.defaultSiteId);
+    if (explicit !== undefined) {
+        const refusal = siteRouter.substitutedRefusal(explicit);
+        if (refusal !== null) {
+            const refusedId = requestId(msg);
+            release(refusedId);
+            if (refusedId !== null) {
+                await local
+                    .send({ jsonrpc: '2.0', id: refusedId, result: refusal })
+                    .catch((sendErr) => {
+                    console.error('[yt-builder-proxy] failed to deliver substituted-registry refusal:', errorMessage(sendErr));
+                });
             }
+            return;
+        }
+    }
+    if (effective === null || effective === siteRouter.defaultSiteId) {
+        const forwardedId = requestId(msg);
+        if (active !== undefined && forwardedId !== null) {
+            rememberActiveSite(pendingHealth, forwardedId, active);
+        }
+        forwardToRemote(msg, remote, local, release);
+        return;
+    }
+    const id = requestId(msg);
+    const resolved = await siteRouter.resolve(effective);
+    if (!resolved.ok) {
+        release(id);
+        if (id !== null) {
+            await local
+                .send({ jsonrpc: '2.0', id, result: resolved.errorResult })
+                .catch((sendErr) => {
+                console.error('[yt-builder-proxy] failed to deliver site-routing error frame:', errorMessage(sendErr));
+            });
+        }
+        return;
+    }
+    try {
+        const result = await resolved.client.callTool({
+            name: msg.params.name,
+            arguments: msg.params.arguments,
         });
+        const answered = active !== undefined
+            ? spliceActiveSite(result, active)
+            : result;
+        const finished = await hostPrompt(id, answered);
+        if (id !== null) {
+            await local.send({ jsonrpc: '2.0', id, result: finished });
+        }
+    }
+    catch (err) {
+        const message = errorMessage(err);
+        console.error(`[yt-builder-proxy] site "${effective}" call failed:`, message);
+        release(id);
+        const routedUpstream = upstreamRpcError(message);
+        if (id !== null) {
+            await local
+                .send({
+                jsonrpc: '2.0',
+                id,
+                error: routedUpstream !== null
+                    ? { code: routedUpstream.code, message: `Site "${effective}": ${upstreamRpcErrorMessage(routedUpstream)}` }
+                    : {
+                        code: -32000,
+                        message: `Site "${effective}" call error: ${message}`
+                            + transportUncertaintyHint(true),
+                    },
+            })
+                .catch((sendErr) => {
+                console.error('[yt-builder-proxy] failed to deliver site-call error frame:', errorMessage(sendErr));
+            });
+        }
+    }
+}
+function forwardToRemote(msg, remote, local, release) {
+    remote.send(msg).catch((err) => {
+        const message = errorMessage(err);
+        const diag = diagnoseNetworkError(err);
+        const upstream = upstreamRpcError(message);
+        const uncertainty = upstream !== null ? '' : transportUncertaintyHint(isToolCallRequest(msg));
+        const hint = diag !== null ? `${diag.summary} Fix: ${diag.fix}${uncertainty}`
+            : upstream !== null ? ''
+                : `Check YTB_MCP_SITE_URL / YTB_MCP_BEARER_TOKEN.${uncertainty}`;
+        console.error('[yt-builder-proxy] upstream send failed:', message + (diag !== null ? `\n  → ${diag.fix}` : ''));
+        const id = requestId(msg);
+        release(id);
+        if (id !== null) {
+            const frame = {
+                jsonrpc: '2.0',
+                id,
+                error: upstream !== null
+                    ? { code: upstream.code, message: upstreamRpcErrorMessage(upstream) }
+                    : { code: -32000, message: `Proxy upstream error: ${message}. ${hint}` },
+            };
+            local.send(frame).catch((sendErr) => {
+                console.error('[yt-builder-proxy] failed to deliver error frame:', errorMessage(sendErr));
+            });
+        }
+        else {
+            void remote.close();
+        }
+    });
+}
+export function bridgeTransports(local, remote, opts = {}) {
+    const { instructions, shadow, sitesShadow, siteRouter } = opts;
+    const extraToolEntries = [
+        ...(shadow !== undefined ? [shadow.listEntry] : []),
+        ...(sitesShadow !== undefined ? sitesShadow.listEntries : []),
+    ];
+    const pendingHealth = new Map();
+    const pendingConfirm = new Map();
+    const prompter = new HostPrompter(local);
+    const release = (id) => releaseConfirmIntent(pendingConfirm, id);
+    const hostPrompt = async (id, result) => {
+        if (id === null)
+            return result;
+        const toolName = pendingConfirm.get(id);
+        if (toolName === undefined)
+            return result;
+        pendingConfirm.delete(id);
+        const payload = previewPayload(result);
+        if (!needsHostPrompt(payload))
+            return result;
+        const answer = await prompter.ask(promptFromPreview(payload, toolName));
+        return spliceHostPrompt(result, answer);
+    };
+    local.onmessage = (msg) => {
+        prompter.noteClientCapabilities(msg);
+        if (prompter.consumeResponse(msg))
+            return;
+        if (shadow !== undefined && isNamedToolCall(msg, [shadow.toolName])) {
+            void answerLocalToolCall(msg, (_name, args) => shadow.callTool(args), local, 'Shadow tool');
+            return;
+        }
+        if (sitesShadow !== undefined && isNamedToolCall(msg, sitesShadow.toolNames)) {
+            void answerLocalToolCall(msg, (name, args) => sitesShadow.callTool(name, args), local, 'Sites tool');
+            return;
+        }
+        if (isToolCallRequest(msg) && parksForHostPrompt(msg.params.arguments)) {
+            const id = requestId(msg);
+            if (id !== null)
+                rememberConfirmIntent(pendingConfirm, id, msg.params.name);
+        }
+        if (siteRouter !== undefined && isToolCallRequest(msg)) {
+            void routeToolCallBySite(msg, siteRouter, local, remote, pendingHealth, hostPrompt, release);
+            return;
+        }
+        forwardToRemote(msg, remote, local, release);
     };
     remote.onmessage = (msg) => {
-        // Normalise the WP-only double-wrap so the client sees the same shape it
-        // would from Joomla. Non-tools/call frames pass through by reference.
+        const oversize = oversizeToolsList(msg, TOOLS_LIST_WIRE_CAP_BYTES);
+        if (oversize !== null) {
+            const id = requestId(msg);
+            const reason = `The site's tool list is ${oversize.bytes} bytes over ${oversize.count} entries, `
+                + `above the ${TOOLS_LIST_WIRE_CAP_BYTES}-byte ceiling. Refusing the connection: `
+                + 'a partial list would silently remove tools. Check the plugin version on this site.';
+            console.error(`[yt-builder-proxy] ${reason}`);
+            if (id === null) {
+                void remote.close();
+                return;
+            }
+            void local
+                .send({ jsonrpc: '2.0', id, error: { code: -32603, message: reason } })
+                .catch((err) => {
+                console.error('[yt-builder-proxy] downstream send failed:', errorMessage(err));
+            })
+                .finally(() => {
+                void remote.close();
+            });
+            return;
+        }
         const normalized = normalizeProxyResponse(msg);
-        local.send(normalized).catch((err) => {
-            console.error('[yt-builder-proxy] downstream send failed:', errorMessage(err));
+        const enriched = injectShadowSurface(normalized, instructions, extraToolEntries);
+        const answered = applyPendingActiveSite(enriched, pendingHealth);
+        const deliver = (frame) => {
+            local.send(frame).catch((err) => {
+                console.error('[yt-builder-proxy] downstream send failed:', errorMessage(err));
+            });
+        };
+        const id = requestId(answered);
+        const parked = id !== null && pendingConfirm.has(id);
+        if (!parked) {
+            deliver(answered);
+            return;
+        }
+        const result = answered.result;
+        if (result === null || typeof result !== 'object' || Array.isArray(result)) {
+            pendingConfirm.delete(id);
+            deliver(answered);
+            return;
+        }
+        void hostPrompt(id, result).then((finished) => {
+            deliver({ ...answered, result: finished });
         });
     };
+    let abgeschaltet = false;
     local.onclose = () => {
+        if (abgeschaltet) {
+            return;
+        }
+        abgeschaltet = true;
         void remote.close();
     };
     remote.onclose = () => {
+        if (abgeschaltet) {
+            return;
+        }
+        abgeschaltet = true;
         void local.close();
     };
     local.onerror = (err) => {
@@ -172,84 +463,100 @@ export function bridgeTransports(local, remote) {
     remote.onerror = (err) => {
         console.error('[yt-builder-proxy] remote transport error:', err.message);
     };
+    return {
+        pendingHostPromptCount: () => pendingConfirm.size,
+    };
 }
-/**
- * Build the upstream `requestInit.headers` for proxy mode: the Bearer is
- * authoritative; corporate extra headers (customer gap #14) only fill gaps —
- * `Authorization` can NEVER be overwritten. Exported for unit tests.
- */
-export function buildProxyRequestHeaders(config) {
-    const base = { Authorization: `Bearer ${config.token}` };
-    return config.extraHeaders !== undefined && Object.keys(config.extraHeaders).length > 0
-        ? mergeExtraHeaders(base, config.extraHeaders)
-        : base;
-}
-/**
- * Resolve the upstream endpoint URL the proxy connects to, splicing in the U3
- * site-level HTTP Basic userinfo (`https://user:pass@host/…`) when configured so
- * the realm gets `Authorization: Basic …`. The Bearer rides the Authorization
- * header (see {@link buildProxyRequestHeaders}) — independent transport, never
- * clobbered. Returns the original URL unchanged when no site-Basic is set.
- * Exported for unit tests.
- */
-export function resolveProxyEndpointUrl(config) {
-    if (config.siteBasicUserinfo === undefined || config.siteBasicUserinfo === '') {
-        return config.endpointUrl;
-    }
-    return new URL(applyUserinfoToUrl(config.endpointUrl, config.siteBasicUserinfo));
-}
-/** Injection seam for tests — production builds the real SDK transports. */
+export { buildProxyRequestHeaders };
 function defaultTransports(config) {
-    const remote = new StreamableHTTPClientTransport(resolveProxyEndpointUrl(config), {
+    const remote = new StreamableHTTPClientTransport(config.endpointUrl, {
         requestInit: { headers: buildProxyRequestHeaders(config) },
+        fetch: createSessionRecoveryFetch(),
     });
     const local = new StdioServerTransport();
     return { local, remote };
 }
-/** Build the real transports + bridge them; resolves when EITHER side closes. */
 export async function runProxy(config, deps = {}) {
     const { local, remote } = (deps.makeTransports ?? defaultTransports)(config);
-    // Resolve the moment EITHER transport closes — never hang if the remote
-    // (upstream) drops first. Capture the bridge's own onclose handlers so the
-    // cross-teardown wiring still runs.
+    const shadow = deps.shadow ?? (await createShadowToolBridge());
+    const instructions = config.instructions ?? buildInstructions();
+    const multiSite = deps.multiSite
+        ?? (config.registry !== undefined
+            ? await createProxyMultiSite(config.registry, {
+                ...(config.extraHeaders !== undefined ? { extraHeaders: config.extraHeaders } : {}),
+                ...(config.siteBasicHeader !== undefined ? { siteBasicHeader: config.siteBasicHeader } : {}),
+            })
+            : undefined);
     const closed = new Promise((resolve) => {
-        bridgeTransports(local, remote);
+        bridgeTransports(local, remote, {
+            instructions,
+            shadow,
+            ...(multiSite !== undefined
+                ? { sitesShadow: multiSite.sitesShadow, siteRouter: multiSite.siteRouter }
+                : {}),
+        });
         const prevLocalClose = local.onclose;
         const prevRemoteClose = remote.onclose;
+        let zuerst = null;
         local.onclose = () => {
+            zuerst ??= 'local';
             prevLocalClose?.();
-            resolve();
+            resolve(zuerst);
         };
         remote.onclose = () => {
+            zuerst ??= 'remote';
             prevRemoteClose?.();
-            resolve();
+            resolve(zuerst);
         };
     });
-    // Start LOCAL (stdio) first so the listener is installed before any client
-    // message can race in; only then open the upstream connection.
     await local.start();
     await remote.start();
-    await closed;
+    return await closed;
 }
-/** Returns true if proxy mode handled the run; false → caller continues with fat. */
-export async function maybeRunProxy(env, deps = {}) {
-    const resolved = resolveMode(env);
-    if (resolved.mode !== 'proxy')
-        return false;
+export async function runBridge(env, deps = {}) {
+    let resolved;
+    try {
+        resolved = await resolveBridgeTarget(env);
+    }
+    catch (e) {
+        if (!(e instanceof ConfigError || e instanceof SitesFileError)) {
+            throw e;
+        }
+        const configProblem = configProblemFor(e);
+        const kind = configProblem === null ? 'starting unconfigured' : 'no site to connect to';
+        process.stderr.write(`[yt-builder-mcp] ${kind} — ${errorMessage(e)}\n`);
+        return { ran: false, configProblem };
+    }
     const run = deps.runProxy ?? runProxy;
-    // customer gap #14 — attach corporate extra headers (WAF / gateway secret) to
-    // every upstream request. parseExtraHeaders reads YTB_MCP_EXTRA_HEADERS.
+    const probe = deps.probeCompat ?? probeProxyCompatNotice;
     const { headers: extraHeaders } = parseExtraHeaders(env);
-    // U3 — a site-level HTTP Basic-Auth realm rides URL userinfo, not a header
-    // (the Bearer owns Authorization). parseSiteBasicAuth reads
-    // YTB_MCP_SITE_BASIC_AUTH; `null` when unset/malformed → no userinfo spliced.
-    const { userinfo: siteBasicUserinfo } = parseSiteBasicAuth(env);
-    await run({
+    const { header: siteBasicHeader } = parseSiteBasicAuth(env);
+    const closedBy = await run({
         endpointUrl: resolved.endpointUrl,
         token: resolved.token,
+        instructions: buildProxyInstructions(env, resolved.registry, await probe(resolved.registry, resolved.token, extraHeaders)),
+        registry: resolved.registry,
         ...(Object.keys(extraHeaders).length > 0 ? { extraHeaders } : {}),
-        ...(siteBasicUserinfo !== null ? { siteBasicUserinfo } : {}),
+        ...(siteBasicHeader !== null ? { siteBasicHeader } : {}),
     });
-    return true;
+    return { ran: true, closedBy: closedBy ?? 'local' };
+}
+async function probeProxyCompatNotice(registry, token, extraHeaders) {
+    try {
+        const id = registry?.defaultSiteId() ?? null;
+        if (registry === undefined || id === null)
+            return undefined;
+        const platform = await registry.platformFor(id);
+        const client = new RestClient({
+            platform,
+            bearerToken: token,
+            timeoutMs: PROXY_COMPAT_PROBE_TIMEOUT_MS,
+            ...(Object.keys(extraHeaders).length > 0 ? { extraHeaders } : {}),
+        });
+        return await probeCompatNotice(client, id);
+    }
+    catch {
+        return undefined;
+    }
 }
 //# sourceMappingURL=bridge.js.map