UNPKG

comfyui-mcp

Version:

Local-first, agent-native control plane for ComfyUI — MCP server + autonomous sidebar agent that drives your live graph in natural language on ANY LLM: Claude/ChatGPT/Gemini on your subscription (no API key), free local models via Ollama (fully offline),

1,031 lines • 51.4 kB
// UI bridge: a loopback WebSocket server the comfyui-mcp-panel pack connects
// to. The panel orchestrator calls `send(cmd)` and awaits the panel's
// rid-correlated reply — a background Claude agent drives the live ComfyUI
// graph over this bridge, with zero LLM API keys.
//
// MULTI-TAB: each ComfyUI browser tab holds its own connection, identified by
// a per-tab session id the panel sends in its `hello` frame (plus the open
// workflow's title, so the agent can tell tabs apart). Commands route by:
// explicit tab_id → the only connected tab → the tab the user most recently
// typed in → error listing connected tabs. Workflows are per-tab in ComfyUI,
// so there is no cross-tab state sync — just per-tab routing.
//
// Wire design ported from node-lab's mcp/bridge.ts (same author): every
// request is `{ rid, cmd, ...args }`; the panel replies `{ rid, ok, result }`
// or `{ rid, ok: false, error }`. Frames WITHOUT a rid are panel-initiated
// events (`hello`, `user_message`) and flow to `onPanelMessage`.
import { randomUUID, timingSafeEqual } from "node:crypto";
import { WebSocketServer, WebSocket } from "ws";
import { logger } from "../utils/logger.js";
export const DEFAULT_BRIDGE_PORT = 9101;
/** Panel build that first implements the full graph_* / ui_* bridge command set.
 *  Reports of "Unknown command <x>" come from panels older than this. */
export const MIN_PANEL_VERSION_FOR_BRIDGE_COMMANDS = "0.11.4";
/**
 * A panel replies `{ ok: false, error: 'Unknown command "<cmd>"' }` when the
 * orchestrator dispatches a bridge command the (older) panel doesn't register —
 * graph_query, ui_render, graph_serialize, graph_view_nodes_in_viewport, etc. all
 * shipped in the panel at 0.11.4. Detect that raw dispatch error and rewrite it
 * into an actionable "update your panel" message instead of surfacing the opaque
 * internal command name to the agent/user. Returns null when `error` is anything
 * else (a genuine command failure), so the happy/normal-error path is untouched.
 */
export function makeUnknownCommandError(error, panelVersion) {
    // Match the panel's exact shape: `Unknown command "graph_query"` (quotes
    // optional/variable). ANCHORED at the start of the (trimmed) message so an
    // unrelated error that merely QUOTES an unknown-command phrase somewhere in its
    // text is never rewritten — only the panel dispatcher's own reply, which is
    // exactly this string. Case-insensitive, tolerant of straight or smart quotes.
    const m = /^unknown command\s*["“']?([\w.-]+)["”']?/i.exec(error.trim());
    if (!m)
        return null;
    const cmd = m[1];
    const detected = panelVersion ? ` (detected ${panelVersion})` : "";
    return new Error(`This ComfyUI-MCP panel is too old for "${cmd}"${detected} — update the ComfyUI-MCP panel ` +
        `to ≥${MIN_PANEL_VERSION_FOR_BRIDGE_COMMANDS} (ComfyUI Manager → update comfyui-mcp panel), then reconnect.`);
}
/**
 * Frame `type`s that are safe to MIRROR to a tab's viewers — genuine shared-session
 * activity a remote-control phone should see. This is an ALLOWLIST (default-deny):
 * a `cid`-based denylist leaked cid-less correlated replies (pair_url, secret_saved,
 * OAuth acks, and history replies to a no-cid request). Anything not listed here —
 * acks, model/backend config, pairing/secret frames, correlated replies — stays with
 * the primary and the ONE socket that asked. New frame types are non-mirroring until
 * explicitly added, so a future secret-bearing frame can't leak by default.
 */
const MIRROR_SAFE_FRAME_TYPES = new Set([
    "say",
    "stream",
    "thinking",
    "echo",
    "turn",
    "turn_anchor",
    "session",
    "agent_status",
    "action",
    "download_progress",
]);
export class UiBridge {
    /** Max EADDRINUSE retries before degrading to "panel unavailable". */
    static MAX_BIND_ATTEMPTS = 5;
    /** Backoff base; delays are 200, 400, 800, 1600, 3200ms (~6.2s total). */
    static BIND_RETRY_BASE_MS = 200;
    /** WebSocket keepalive: ping every 25s so a proxied connection (the cloudflared
     *  tunnel behind a secure wss:// bridge) is never idle long enough for Cloudflare
     *  to reap it (~100s idle timeout) during a long, quiet agent turn. Harmless on
     *  loopback. */
    static HEARTBEAT_MS = 25_000;
    /** Terminate a socket only after this many consecutive missed pongs (~50s of
     *  silence) — lenient enough that a briefly-backgrounded/throttled tab isn't
     *  falsely dropped, strict enough to reap a silently-dead tunnel connection. */
    static MAX_MISSED_PONGS = 2;
    wss = null;
    /** Extra always-token-gated listeners — the on-demand phone-pairing bind (LAN
     *  and/or a loopback port a cloudflared tunnel fronts). Their connections route
     *  through the same tab/rid logic as the primary bridge; the primary loopback
     *  listener stays token-less so the local browser panel is unaffected. */
    extraServers = [];
    conns = new Map(); // tabId -> connection (canvas-owning primary)
    /** Mobile "mirror" viewers subscribed to a tab's live output (remote control):
     *  push()-path frames for a tabId fan out to these IN ADDITION to the primary,
     *  so a phone sees the desktop tab's agent activity/renders. They NEVER receive
     *  canvas send()-commands (owner-only) and their own correlated replies are
     *  socket-scoped. Keyed by the mirrored (primary) tabId. Empty in the normal
     *  case → zero effect on existing panel behavior. */
    subscribers = new Map();
    /** A mirroring viewer's socket → the desktop tab it drives. While attached, the
     *  viewer's INBOUND events (user_message, interrupt, new_session, …) are routed
     *  to THIS tab's shared session instead of the viewer's own — that's what makes
     *  it remote control rather than a passive view. Cleared on detach/disconnect. */
    mirrorViewers = new Map();
    /** Injected by the orchestrator: does this tabId have a live agent session?
     *  (SessionStore/PanelAgentManager live there.) Flags desktopTabs() for the
     *  mobile mirror picker's green "session attached" dot. */
    hasSessionPredicate = null;
    /**
     * Tab-id migrations (oldTabId → newTabId). When a panel socket re-hellos under
     * a NEW tab id (e.g. after a panel update that changed the id scheme from
     * random UUID to deterministic tmp:/wf: prefixed ids), the old id is mapped to
     * the new one so agent sessions that were bound to the old id can still resolve
     * their target via resolveTarget — the session self-heals instead of throwing
     * "no connected tab with id …" on every panel_* call.
     */
    tabMigrations = new Map();
    /** Per-tab "mailbox" of undeliverable render deliveries (show_media), buffered
     *  while a client is OFFLINE and flushed on reconnect — so a finished render is
     *  never lost when the mobile app is backgrounded/killed mid-render. Keyed by a
     *  STABLE tab id (the phone persists one). In-memory: survives disconnect ⇄
     *  reconnect within an orchestrator run, not a full orchestrator restart.
     *  Bounded per tab + TTL'd. */
    mailbox = new Map();
    static MAILBOX_MAX = 30;
    static MAILBOX_TTL_MS = 24 * 60 * 60 * 1000;
    /** Tab ids that ever connected as a headless (mobile/remote) client — kept so
     *  `isHeadless` stays true across a disconnect (see isHeadless). */
    headlessSeen = new Set();
    seenTabs = new Set(); // tabIds ever announced — dedup connect logs across reconnect churn
    /** Frames pushed at a tab with NO live connection, buffered for replay when that
     *  tab re-hellos. Per-workflow sessions re-target ONE socket between workflow tab
     *  ids, so a backgrounded workflow's agent output would otherwise be dropped on
     *  the floor and its finished turn lost to the user. Complements the send()-path
     *  `mailbox` (which buffers show_media command deliveries): this one buffers
     *  push()-path frames (agent turn output). Bounded per tab. */
    missedFrames = new Map();
    static MAX_MISSED_FRAMES = 100;
    pending = new Map();
    portInUse = false;
    bindRetryTimer = null;
    heartbeatTimer = null;
    /** Consecutive missed pongs per socket — reset to 0 on each pong. */
    missedPongs = new WeakMap();
    port;
    /** When set, connections MUST present `?token=<token>` on the WS upgrade
     *  (constant-time compared). Used for the secure `wss://` bridge exposed over a
     *  cloudflared tunnel, where the endpoint is publicly reachable. null in the
     *  default loopback-only mode (no auth needed — not reachable off-box). */
    token;
    /** Bind host. Default loopback; a LAN/all-interfaces bind (0.0.0.0, a LAN IP)
     *  is allowed ONLY together with a token — panel #54: browsers on OTHER
     *  machines reaching a 24/7 server-side orchestrator. */
    host;
    /** Tab the user most recently typed in — the default command target. */
    lastActiveTabId = null;
    /** Resolves true once the port is bound, false if binding ultimately fails. */
    readyPromise = null;
    readyResolve = null;
    /** Called for panel-initiated frames (no rid): user messages, hellos. */
    onPanelMessage = null;
    constructor(port = DEFAULT_BRIDGE_PORT, token = null, host = "127.0.0.1") {
        this.port = port;
        this.token = token;
        this.host = host;
        if (!isLoopbackBindHost(host) && !token) {
            // The bridge drives the live canvas + agent; exposing it beyond loopback
            // without auth is never acceptable — refuse loudly at construction.
            throw new Error(`UiBridge: refusing to bind the panel bridge on non-loopback host "${host}" without a token. ` +
                `Set COMFYUI_MCP_BRIDGE_TOKEN (or let the orchestrator generate one).`);
        }
    }
    /** Constant-time token check for the WS upgrade. Always true when no token is
     *  configured (loopback mode). Length-mismatch short-circuits before the
     *  timing-safe compare (which requires equal-length buffers). */
    tokenOk(provided) {
        if (!this.token)
            return true;
        const a = Buffer.from(provided);
        const b = Buffer.from(this.token);
        return a.length === b.length && timingSafeEqual(a, b);
    }
    start() {
        this.portInUse = false;
        this.readyPromise = new Promise((resolve) => {
            this.readyResolve = resolve;
        });
        this.attemptListen(0);
    }
    /**
     * WebSocket keepalive. Every HEARTBEAT_MS, ping each live socket so a proxied
     * connection (cloudflared tunnel) never sits idle long enough for Cloudflare to
     * reap it during a long, quiet agent turn — the root cause of "intermittent
     * connection and drops" on the secure wss:// bridge. A socket that misses
     * MAX_MISSED_PONGS pings in a row is treated as dead and terminated so the panel
     * reconnects onto a clean socket. The timer is unref'd so it never keeps the
     * process alive on its own.
     */
    startHeartbeat() {
        if (this.heartbeatTimer)
            return;
        this.heartbeatTimer = setInterval(() => {
            // Ping the primary listener AND any pairing listeners — a phone on a LAN or
            // tunnel bind needs the same idle-keepalive the browser panel gets.
            const servers = [this.wss, ...this.extraServers].filter((s) => s !== null);
            for (const server of servers) {
                for (const sock of server.clients) {
                    const missed = this.missedPongs.get(sock) ?? 0;
                    if (missed >= UiBridge.MAX_MISSED_PONGS) {
                        try {
                            sock.terminate();
                        }
                        catch {
                            // already gone
                        }
                        continue;
                    }
                    this.missedPongs.set(sock, missed + 1);
                    try {
                        sock.ping();
                    }
                    catch {
                        // socket mid-close — the next tick's terminate/close handler cleans up
                    }
                }
            }
        }, UiBridge.HEARTBEAT_MS);
        this.heartbeatTimer.unref?.();
    }
    /**
     * Resolves true once the bridge port is bound, false if it ultimately can't
     * bind (port held by another process). Lets a caller that *must* own the port
     * — the panel orchestrator — fail loudly instead of running uselessly.
     */
    whenReady() {
        return this.readyPromise ?? Promise.resolve(this.wss !== null);
    }
    /**
     * Bind the loopback bridge port, retrying briefly on EADDRINUSE. A fast
     * `/mcp` reconnect can race the previous session's bridge before the OS has
     * released the port; rather than degrade immediately we back off and retry,
     * so the common restart case self-heals. Non-blocking — this never delays
     * MCP stdio startup, which is what matters for the client's init timeout.
     */
    attemptListen(attempt) {
        // Loopback by default — this drives the user's live editor. Two ways it can
        // be reachable off-box, BOTH token-gated on the WS upgrade:
        //   • secure mode: loopback bind fronted by a cloudflared wss:// tunnel
        //   • LAN mode (panel #54): a non-loopback bind host, for a 24/7 server-side
        //     orchestrator; the constructor enforces token-with-non-loopback.
        const wss = new WebSocketServer({
            port: this.port,
            host: this.host,
            verifyClient: this.token
                ? (info, cb) => {
                    let provided = "";
                    try {
                        provided =
                            new URL(info.req.url ?? "/", "http://127.0.0.1").searchParams.get("token") ?? "";
                    }
                    catch {
                        provided = "";
                    }
                    if (this.tokenOk(provided))
                        return cb(true);
                    logger.warn("[ui-bridge] rejected a bridge connection with a missing/invalid token");
                    cb(false, 401, "Unauthorized");
                }
                : undefined,
        });
        wss.on("listening", () => {
            this.portInUse = false;
            this.wss = wss;
            logger.info(`[ui-bridge] listening on ws://${this.host}:${this.port}${this.token ? " (token-gated)" : ""}`);
            this.startHeartbeat();
            this.readyResolve?.(true);
            this.readyResolve = null;
        });
        wss.on("error", (err) => {
            if (err.code === "EADDRINUSE") {
                // Discard this server; a fresh one is created per retry.
                try {
                    wss.close();
                }
                catch {
                    // Nothing bound to clean up.
                }
                if (attempt < UiBridge.MAX_BIND_ATTEMPTS) {
                    const delay = UiBridge.BIND_RETRY_BASE_MS * 2 ** attempt;
                    logger.warn(`[ui-bridge] port ${this.port} in use — a previous session may still be releasing it; retrying in ${delay}ms (attempt ${attempt + 1}/${UiBridge.MAX_BIND_ATTEMPTS})`);
                    this.bindRetryTimer = setTimeout(() => {
                        this.bindRetryTimer = null;
                        this.attemptListen(attempt + 1);
                    }, delay);
                    return;
                }
                this.portInUse = true;
                logger.warn(`[ui-bridge] port ${this.port} still in use after ${UiBridge.MAX_BIND_ATTEMPTS} attempts — another comfyui-mcp session likely owns the panel. This session's MCP tools still work, but panel_* commands are unavailable until that session exits.`);
                this.readyResolve?.(false);
                this.readyResolve = null;
            }
            else if (this.wss) {
                // We had successfully bound (listening) and the server errored AFTER
                // startup — the port/bridge is gone and can't recover in-process. Exit so
                // the panel pack respawns a CLEAN orchestrator instead of leaving a zombie
                // (process alive, bridge dead → panel can't reconnect). This was a root
                // cause of "the panel agent will no longer reconnect."
                logger.error(`[ui-bridge] fatal: server error after startup (${err.message}) — exiting so a fresh orchestrator can take over`);
                this.wss = null;
                process.exit(1);
            }
            else {
                logger.error(`[ui-bridge] server error: ${err.message}`);
                // Never reached "listening" — unblock any whenReady() waiter.
                this.readyResolve?.(false);
                this.readyResolve = null;
            }
        });
        wss.on("connection", (sock) => {
            // Keepalive bookkeeping for the SERVER-LEVEL heartbeat loop, which only
            // iterates real wss.clients (relay-mediated shim connections aren't real
            // sockets bound by this server, so they're intentionally excluded — see
            // relay-client.ts / the relay README for why that's believed low-risk).
            this.missedPongs.set(sock, 0);
            sock.on("pong", () => this.missedPongs.set(sock, 0));
            this.handleConnection(sock);
        });
    }
    /**
     * Attach a non-loopback panel connection — used by the relay client
     * (relay-client.ts) to feed a relay-multiplexed panel-tab connection into the
     * exact same hello/rid/tab-routing logic a direct loopback socket gets. From
     * here on the relay shim is indistinguishable from a real connection.
     */
    attachRelayConnection(sock) {
        this.handleConnection(sock);
    }
    /**
     * Open a SECOND, ALWAYS token-gated listener on `host:port` and route its
     * connections through the same tab/rid logic as the primary bridge. Used by the
     * on-demand "pair a phone" flow: a `0.0.0.0` bind so a phone can reach it over
     * the LAN, and/or a loopback port a cloudflared quick-tunnel fronts. The primary
     * loopback listener stays token-less, so the local browser panel is untouched.
     * Resolves once bound; rejects if the port can't be bound. Idempotent-ish: the
     * caller is responsible for not re-binding the same port.
     */
    addListener(host, port, token) {
        return new Promise((resolve, reject) => {
            let settled = false;
            const wss = new WebSocketServer({
                port,
                host,
                verifyClient: (info, cb) => {
                    let provided = "";
                    try {
                        provided =
                            new URL(info.req.url ?? "/", "http://127.0.0.1").searchParams.get("token") ?? "";
                    }
                    catch {
                        provided = "";
                    }
                    const a = Buffer.from(provided);
                    const b = Buffer.from(token);
                    if (a.length === b.length && timingSafeEqual(a, b))
                        return cb(true);
                    logger.warn("[ui-bridge] pairing listener rejected a connection with a missing/invalid token");
                    cb(false, 401, "Unauthorized");
                },
            });
            wss.on("connection", (sock) => {
                this.missedPongs.set(sock, 0);
                sock.on("pong", () => this.missedPongs.set(sock, 0));
                this.handleConnection(sock);
            });
            wss.on("listening", () => {
                settled = true;
                this.extraServers.push(wss);
                logger.info(`[ui-bridge] pairing listener on ws://${host}:${port} (token-gated)`);
                resolve();
            });
            wss.on("error", (err) => {
                if (!settled) {
                    settled = true;
                    try {
                        wss.close();
                    }
                    catch {
                        // nothing bound
                    }
                    reject(err);
                }
                else {
                    logger.warn(`[ui-bridge] pairing listener error: ${err.message}`);
                }
            });
        });
    }
    handleConnection(sock) {
        // The connection is anonymous until its hello frame names a tab id.
        let tabId = null;
        // A socket's KIND (canvas-owning panel vs headless viewer) is pinned on its
        // FIRST hello and is authoritative thereafter. The `headless` flag on later
        // hellos is client-controlled, so a headless viewer could otherwise flip it to
        // `false` to pass the same-kind takeover check and seize a desktop tab's id.
        let socketHeadless = null;
        sock.on("message", (buf) => {
            const raw = String(buf);
            let msg;
            try {
                msg = JSON.parse(raw);
            }
            catch {
                logger.warn("[ui-bridge] dropping malformed frame from panel");
                return;
            }
            // Hello: register (or refresh) this connection under its tab id.
            if (msg.type === "hello" && typeof msg.tab_id === "string") {
                // SECURITY (codex review): migrated_from is a SERVER-stamped field. A
                // client-supplied value would let any tab rebind another tab's agent —
                // scrub it unconditionally before the migration check below may re-add it.
                delete msg.migrated_from;
                // A single socket may RE-HELLO under a new tab id when the user switches
                // ComfyUI workflow tabs (per-workflow sessions). Drop this socket's PRIOR
                // tab mapping so a background agent's push() to the old tab can't leak into
                // the newly-targeted view (frames carry no tab_id — the socket is the tab).
                if (tabId && tabId !== msg.tab_id && this.conns.get(tabId)?.sock === sock) {
                    // PATH-COMPRESS the migration map: the reported field failure chains
                    // ids (random UUID → tmp:<uuid> → wf:<hash>). A single-hop lookup on
                    // the ORIGINAL id would land on the dead intermediate — rewrite every
                    // entry pointing at the id being retired so any historical id resolves
                    // to the LIVE tab in one step, and the map never grows chains. Entries
                    // are SOCKET-SCOPED (codex review): wf:<hash> ids are deterministic and
                    // recur across reconnects, so a migration must only ever route to the
                    // socket that created it — compression too stays within this socket.
                    for (const [from, entry] of this.tabMigrations) {
                        if (entry.to === tabId && entry.sock === sock) {
                            this.tabMigrations.set(from, { to: msg.tab_id, sock });
                        }
                    }
                    this.tabMigrations.set(tabId, { to: msg.tab_id, sock });
                    // Authoritative migration signal for the orchestrator (same-socket
                    // re-hello — the ONLY safe rebind trigger; title matching is not).
                    msg.migrated_from = tabId;
                    this.conns.delete(tabId);
                    // Move mirror subscribers to the migrated tab id so viewers keep this
                    // tab's live feed across a same-socket re-hello.
                    const migSubs = this.subscribers.get(tabId);
                    if (migSubs) {
                        this.subscribers.delete(tabId);
                        const dest = this.subscribers.get(msg.tab_id) ?? new Set();
                        for (const s of migSubs)
                            dest.add(s);
                        this.subscribers.set(msg.tab_id, dest);
                    }
                    // Re-point any viewers driving the OLD id at the new one so their input
                    // keeps reaching this tab's session across the re-hello.
                    for (const [s, drivenTab] of this.mirrorViewers) {
                        if (drivenTab === tabId)
                            this.mirrorViewers.set(s, msg.tab_id);
                    }
                }
                tabId = msg.tab_id;
                // Pin the socket's kind on its first hello; ignore any later flip so the
                // takeover guard below can't be bypassed with a forged `headless` value.
                if (socketHeadless === null) {
                    socketHeadless = msg.headless === true;
                }
                const incomingHeadless = socketHeadless;
                const existing = this.conns.get(tabId);
                if (existing && existing.sock !== sock) {
                    // SECURITY: a viewer must not hello-hijack another client's tab id. The
                    // reconnect-supersede path evicts the current holder, so without this a
                    // headless phone could re-hello under a DESKTOP's id, kill its socket, and
                    // register as that tab — bypassing attach_tab's authoritative stamping and
                    // driving the tab it never attached to. Only same-kind reconnects (a real
                    // reload: desktop→desktop, phone→phone) may supersede. Cross-kind is refused.
                    if (existing.headless !== incomingHeadless) {
                        logger.warn(`[ui-bridge] refused cross-kind hello takeover of tab ${tabId.slice(0, 8)} ` +
                            `(existing headless=${existing.headless}, incoming headless=${incomingHeadless})`);
                        try {
                            sock.close();
                        }
                        catch {
                            // Already gone.
                        }
                        return;
                    }
                    // Same tab reconnected (reload) — supersede the stale socket.
                    try {
                        existing.sock.close();
                    }
                    catch {
                        // Already gone.
                    }
                }
                this.conns.set(tabId, {
                    sock,
                    tabId,
                    title: typeof msg.title === "string" && msg.title ? msg.title : "untitled",
                    connectedAt: existing?.connectedAt ?? new Date().toISOString(),
                    headless: incomingHeadless,
                    panelVersion: typeof msg.panel_version === "string"
                        ? (msg.panel_version || undefined)
                        : existing?.panelVersion,
                });
                if (incomingHeadless)
                    this.headlessSeen.add(tabId);
                this.broadcastTabList(); // a tab connected/reconnected — refresh mirror pickers
                // Log a real connect ONCE per tab id. A reconnect/ping-pong loop (a new
                // socket every couple seconds — e.g. two browser contexts sharing one tab
                // id) would otherwise spam this; dedup by tab id so churn stays at debug.
                if (!this.seenTabs.has(tabId)) {
                    this.seenTabs.add(tabId);
                    logger.info(`[ui-bridge] panel tab connected: ${tabId.slice(0, 8)} (“${this.conns.get(tabId)?.title}”) — ${this.conns.size} tab(s) total`);
                }
                else {
                    logger.debug(`[ui-bridge] tab ${tabId.slice(0, 8)} (re)hello`);
                }
                // Replay anything this tab's agent produced while the tab had no live
                // connection (its socket was re-helloed to another workflow). The panel
                // swaps to this workflow's thread synchronously before these frames can be
                // processed, so they render + record into the RIGHT conversation.
                const missed = this.missedFrames.get(tabId);
                if (missed?.length) {
                    this.missedFrames.delete(tabId);
                    for (const f of missed) {
                        try {
                            sock.send(JSON.stringify(f));
                        }
                        catch {
                            break; // socket died mid-flush — frames stay lost, next turn recovers
                        }
                    }
                    logger.debug(`[ui-bridge] replayed ${missed.length} missed frame(s) to tab ${tabId.slice(0, 8)}`);
                }
                // Deliver anything that finished while this tab was away.
                this.flushMailbox(tabId);
                this.onPanelMessage?.(msg);
                return;
            }
            const rid = typeof msg.rid === "string" ? msg.rid : undefined;
            if (rid) {
                const p = this.pending.get(rid);
                if (!p)
                    return; // late reply for a timed-out command
                clearTimeout(p.timer);
                this.pending.delete(rid);
                if (msg.ok) {
                    p.resolve(msg.result);
                }
                else {
                    p.reject(new Error(String(msg.error ?? "panel reported an error")));
                }
                return;
            }
            // Lightweight title update — keep the tab's title fresh
            // WITHOUT re-greeting. The panel sends this on title mutations instead of
            // a full hello, so a graph build / run progress doesn't spam greetings.
            if (msg.type === "title" && tabId) {
                const conn = this.conns.get(tabId);
                if (conn && typeof msg.title === "string" && msg.title)
                    conn.title = msg.title;
                this.broadcastTabList(); // a title changed — refresh mirror pickers
                return;
            }
            // Desktop-tab mirroring (mobile remote control). Handled HERE (we hold the
            // requesting socket) so the replies are socket-scoped — never fanned out to
            // other viewers or the primary. Additive: unknown to the desktop panel.
            if (msg.type === "list_tabs") {
                try {
                    sock.send(JSON.stringify({ type: "tab_list", cid: msg.cid, tabs: this.desktopTabs() }));
                }
                catch {
                    /* socket died — the caller times out */
                }
                return;
            }
            if (msg.type === "attach_tab" && typeof msg.target_tab_id === "string") {
                const target = msg.target_tab_id;
                // Only allow mirroring a real, non-headless desktop tab — reject stale ids
                // and prevent subscribing to another headless (mobile) client.
                const valid = this.conns.has(target) && !this.headlessSeen.has(target);
                if (valid) {
                    // A viewer mirrors ONE tab at a time — drop any prior subscription first so
                    // re-attaching (A→B) doesn't keep streaming A's activity alongside B's.
                    for (const [tid, s] of this.subscribers) {
                        if (s.delete(sock) && s.size === 0)
                            this.subscribers.delete(tid);
                    }
                    let set = this.subscribers.get(target);
                    if (!set) {
                        set = new Set();
                        this.subscribers.set(target, set);
                    }
                    set.add(sock);
                    // Route this viewer's inbound events to the mirrored tab (remote control).
                    this.mirrorViewers.set(sock, target);
                }
                try {
                    sock.send(JSON.stringify({
                        type: "tab_attached",
                        cid: msg.cid,
                        tab_id: target,
                        ok: valid,
                        ...(valid ? {} : { error: "no such desktop tab" }),
                    }));
                }
                catch {
                    /* socket died */
                }
                return;
            }
            if (msg.type === "detach_tab") {
                for (const [tid, set] of this.subscribers) {
                    if (set.delete(sock) && set.size === 0)
                        this.subscribers.delete(tid);
                }
                this.mirrorViewers.delete(sock); // stop routing its input to the mirrored tab
                return;
            }
            // Panel-initiated event. Stamp the tab and track activity. A mirroring viewer
            // (phone attached to a desktop tab) DRIVES that tab's shared session, so its
            // events route to the mirrored tab id — not the viewer's own — which is what
            // turns the mirror into remote control. Stamping is server-authoritative here
            // (it overwrites any client-supplied tab_id), so a viewer can't target a tab
            // it hasn't attached to.
            if (typeof msg.type === "string") {
                const effectiveTab = this.mirrorViewers.get(sock) ?? tabId;
                if (effectiveTab) {
                    msg.tab_id = effectiveTab;
                    msg.title = this.conns.get(effectiveTab)?.title;
                    if (msg.type === "user_message")
                        this.lastActiveTabId = effectiveTab;
                }
                this.onPanelMessage?.(msg);
            }
        });
        sock.on("close", () => {
            // Prune this socket's migration aliases — they can only ever route to
            // this socket (socket-scoped), so they're inert once it dies. Keeps the
            // map bounded over long-lived orchestrators (codex review).
            for (const [from, entry] of this.tabMigrations) {
                if (entry.sock === sock)
                    this.tabMigrations.delete(from);
            }
            // Drop this socket from any mirror subscriptions (it was a viewer).
            for (const [tid, set] of this.subscribers) {
                if (set.delete(sock) && set.size === 0)
                    this.subscribers.delete(tid);
            }
            this.mirrorViewers.delete(sock);
            let wasPrimary = false;
            if (tabId && this.conns.get(tabId)?.sock === sock) {
                wasPrimary = true;
                this.conns.delete(tabId);
                if (this.lastActiveTabId === tabId)
                    this.lastActiveTabId = null;
                // The mirrored desktop tab is gone — detach its viewers so their input
                // reverts to their OWN session instead of routing into a dead id (and its
                // output isn't silently buffered forever). They can re-attach if it returns.
                for (const [s, drivenTab] of this.mirrorViewers) {
                    if (drivenTab === tabId)
                        this.mirrorViewers.delete(s);
                }
                this.subscribers.delete(tabId);
                logger.info(`[ui-bridge] panel tab disconnected: ${tabId.slice(0, 8)} — ${this.conns.size} tab(s) remain`);
            }
            if (wasPrimary)
                this.broadcastTabList(); // a desktop tab left — refresh pickers
            // Reject any in-flight commands that were bound to this socket.
            for (const [rid, p] of this.pending) {
                if (p.sock === sock) {
                    clearTimeout(p.timer);
                    p.reject(new Error("panel tab disconnected mid-command"));
                    this.pending.delete(rid);
                }
            }
        });
    }
    connected() {
        return this.conns.size > 0;
    }
    /** Would a command bound to this EXACT tabId reach a live tab right now?
     *  (Exact id, an unambiguous prefix, or a live same-socket migration alias —
     *  the same acceptance `resolveTarget` uses, but as a boolean and never
     *  throwing.) The orchestrator uses this to tell an orphaned session from a
     *  healthy one before deciding whether to self-heal via a rebind. */
    canReach(tabId) {
        try {
            this.resolveTarget(tabId);
            return true;
        }
        catch {
            return false;
        }
    }
    /** The id of the tab a NO-tabId command would target right now: the sole
     *  connection, else the last active tab. Throws the SAME clear errors as the
     *  no-tabId `send` path when it can't pick a single one (none connected, or
     *  2+ with no last-active). This is the EXPLICIT resolution the orchestrator
     *  invokes at a user/agent-initiated rebind moment — it deliberately does NOT
     *  weaken `resolveTarget`, so multi-tab routing stays conservative. */
    resolveActiveTabId() {
        return this.resolveTarget().tabId;
    }
    /** True when the tab advertised itself as a canvas-less (mobile/remote) client
     *  in its `hello`. Unknown tabs → false. */
    isHeadless(tabId) {
        // Sticky: a tab that EVER connected headless stays "headless" even while
        // offline, so a render finishing during a disconnect is byte-inlined (not a
        // bytes-less viewRef) and is renderable when the mailbox flushes to the phone.
        return this.conns.get(tabId)?.headless === true || this.headlessSeen.has(tabId);
    }
    /** All currently connected tabs, most recent hello last. */
    tabs() {
        return Array.from(this.conns.values()).map((c) => ({
            tab_id: c.tabId,
            title: c.title,
            connected_at: c.connectedAt,
        }));
    }
    status() {
        if (this.portInUse) {
            return `port ${this.port} is held by another comfyui-mcp session — close that session (or whatever owns the port) and reconnect`;
        }
        if (this.conns.size === 0) {
            return "no panel connected — open ComfyUI with the comfyui-mcp-panel pack installed and check the Agent sidebar tab";
        }
        const lines = this.tabs().map((t) => `- tab ${t.tab_id.slice(0, 8)} “${t.title}”${t.tab_id === this.lastActiveTabId ? " (last active)" : ""}`);
        return `${this.conns.size} panel tab(s) connected:\n${lines.join("\n")}`;
    }
    /** Resolve which tab a command should go to. */
    resolveTarget(tabId) {
        if (tabId) {
            // Accept full ids or unambiguous prefixes (status shows 8-char ids).
            const exact = this.conns.get(tabId);
            if (exact)
                return exact;
            const prefixed = Array.from(this.conns.values()).filter((c) => c.tabId.startsWith(tabId));
            // Tab-id migration fallback — checked AFTER prefix matching (codex
            // review: a stale alias must never shadow a legitimately connected
            // prefix match), and only honored when the live connection is STILL the
            // socket that created the migration (wf:<hash> ids recur — an unrelated
            // later tab reusing the id must not inherit someone else's alias).
            if (prefixed.length === 0) {
                const migrated = this.tabMigrations.get(tabId);
                if (migrated) {
                    const target = this.conns.get(migrated.to);
                    if (target && target.sock === migrated.sock)
                        return target;
                }
            }
            if (prefixed.length === 1)
                return prefixed[0];
            throw new Error(prefixed.length > 1
                ? `tab_id "${tabId}" is ambiguous — matches ${prefixed.length} tabs`
                : `no connected tab with id "${tabId}". Connected: ${this.tabs()
                    .map((t) => `${t.tab_id.slice(0, 8)} (“${t.title}”)`)
                    .join(", ") || "none"}`);
        }
        if (this.conns.size === 1) {
            return this.conns.values().next().value;
        }
        if (this.lastActiveTabId && this.conns.has(this.lastActiveTabId)) {
            return this.conns.get(this.lastActiveTabId);
        }
        if (this.conns.size === 0) {
            throw new Error(`Panel not reachable: ${this.status()}`);
        }
        throw new Error(`Multiple panel tabs are connected and none is "last active" — pass tab_id. ${this.status()}`);
    }
    /** Deliveries worth mailboxing when the target is offline (a finished render),
     *  vs. interactive canvas ops that should just fail. */
    static isMailboxable(cmd) {
        return cmd.cmd === "show_media";
    }
    storeMailbox(tabId, cmd) {
        const box = this.mailbox.get(tabId) ?? [];
        box.push({ cmd, ts: Date.now() });
        while (box.length > UiBridge.MAILBOX_MAX)
            box.shift();
        this.mailbox.set(tabId, box);
        logger.info(`[ui-bridge] mailboxed "${cmd.cmd}" for offline tab ${tabId.slice(0, 8)} (${box.length} queued)`);
    }
    /** Deliver any buffered render frames to a tab that just (re)connected, plus a
     *  `mailbox_flush` summary so the client can notify "N renders finished while
     *  you were away". Expired items (past TTL) are dropped. */
    flushMailbox(tabId) {
        const box = this.mailbox.get(tabId);
        if (!box || box.length === 0)
            return;
        this.mailbox.delete(tabId);
        const conn = this.conns.get(tabId);
        if (!conn)
            return;
        const now = Date.now();
        const fresh = box.filter((m) => now - m.ts <= UiBridge.MAILBOX_TTL_MS);
        for (const m of fresh) {
            try {
                conn.sock.send(JSON.stringify({ rid: randomUUID(), ...m.cmd, mailbox: true }));
            }
            catch {
                // socket raced closed; drop
            }
        }
        if (fresh.length > 0) {
            try {
                conn.sock.send(JSON.stringify({ type: "mailbox_flush", count: fresh.length }));
            }
            catch {
                /* best-effort */
            }
            logger.info(`[ui-bridge] flushed ${fresh.length} mailboxed frame(s) to reconnected tab ${tabId.slice(0, 8)}`);
        }
    }
    send(cmd, opts = {}) {
        const timeoutMs = opts.timeoutMs ?? 6000;
        let conn;
        try {
            conn = this.resolveTarget(opts.tabId);
        }
        catch (err) {
            // Offline target: buffer a finished-render delivery for reconnect instead of
            // failing, so the agent's "here's your image" isn't lost while the phone is away.
            if (opts.tabId && UiBridge.isMailboxable(cmd)) {
                this.storeMailbox(opts.tabId, cmd);
                return Promise.resolve({ ok: true, mailboxed: true });
            }
            return Promise.reject(err instanceof Error ? err : new Error(String(err)));
        }
        if (conn.sock.readyState !== WebSocket.OPEN) {
            if (opts.tabId && UiBridge.isMailboxable(cmd)) {
                this.storeMailbox(opts.tabId, cmd);
                return Promise.resolve({ ok: true, mailboxed: true });
            }
            return Promise.reject(new Error(`Panel tab ${conn.tabId.slice(0, 8)} is not open`));
        }
        const rid = randomUUID();
        return new Promise((resolve, reject) => {
            // Rewrite an old-panel "Unknown command" rejection into an actionable
            // update-your-panel message (see makeUnknownCommandError). Applied to the
            // reply-error path only; the happy path and genuine command errors are
            // passed through untouched.
            const rejectMapped = (err) => {
                const friendly = makeUnknownCommandError(err.message, conn.panelVersion);
                reject(friendly ?? err);
            };
            const timer = setTimeout(() => {
                this.pending.delete(rid);
                reject(new Error(`Panel tab ${conn.tabId.slice(0, 8)} did not reply to "${cmd.cmd}" within ${timeoutMs} ms — the ComfyUI tab may be backgrounded or frozen`));
            }, timeoutMs);
            const pending = {
                resolve,
                reject: rejectMapped,
                timer,
                sock: conn.sock,
            };
            this.pending.set(rid, pending);
            try {
                conn.sock.send(JSON.stringify({ rid, ...cmd }));
            }
            catch (err) {
                clearTimeout(timer);
                this.pending.delete(rid);
                reject(err instanceof Error ? err : new Error(String(err)));
            }
        });
    }
    /** Push a fire-and-forget frame. Targeted when tabId given, else broadcast.
     *  Truly fire-and-forget: if the target tab has gone, this no-ops (returns 0)
     *  rather than throwing — a throw here becomes an unhandled rejection in the
     *  async push call sites and would crash the orchestrator. */
    /** Inject the "does this tab have a live session?" predicate (SessionStore lives
     *  in the orchestrator). */
    setHasSessionPredicate(fn) {
        this.hasSessionPredicate = fn;
    }
    /** The open DESKTOP tabs (non-headless primaries) for the mobile mirror picker. */
    desktopTabs() {
        const out = [];
        for (const [tabId, conn] of this.conns) {
            if (this.headlessSeen.has(tabId))
                continue; // skip mobile/remote viewers
            out.push({
                tab_id: tabId,
                title: conn.title ?? "",
                has_session: this.hasSessionPredicate ? this.hasSessionPredicate(tabId) : false,
            });
        }
        return out;
    }
    /** Push the current desktop-tab list to every mirror subscriber — call when the
     *  connected-tab set or a session's live state changes so phones stay in sync. */
    broadcastTabList() {
        if (this.subscribers.size === 0)
            return;
        const frame = JSON.stringify({ type: "tab_list", tabs: this.desktopTabs() });
        const seen = new Set();
        for (const set of this.subscribers.values()) {
            for (const sock of set) {
                if (seen.has(sock) || sock.readyState !== WebSocket.OPEN)
                    continue;
                seen.add(sock);
                try {
                    sock.send(frame);
                }
                catch {
                    /* socket mid-disconnect — drop */
                }
            }
        }
    }
    push(frame, tabId) {
        let sent = 0;
        let targets;
        if (tabId) {
            try {
                targets = [this.resolveTarget(tabId)];
            }
            catch {
                // Tab not connected (e.g. the user switched to another workflow and the
                // shared socket re-helloed under that workflow's id). Buffer for replay on
                // this tab's next hello, so a backgrounded agent's turn isn't lost.
                const q = this.missedFrames.get(tabId) ?? [];
                q.push(frame);
                if (q.length > UiBridge.MAX_MISSED_FRAMES)
                    q.splice(0, q.length - UiBridge.MAX_MISSED_FRAMES);
                this.missedFrames.set(tabId, q);
                return 0;
            }
        }
        else {
            targets = Array.from(this.conns.values());
        }
        const payload = JSON.stringify(frame);
        for (const conn of targets) {
            if (conn.sock.readyState !== WebSocket.OPEN)
                continue;
            try {
                conn.sock.send(payload);
                sent += 1;
            }
            catch {
                // Tab mid-disconnect — drop.
            }
        }
        // Mirror fan-out: also deliver a tab-scoped frame to any phones mirroring this
        // tab (remote control). No-op when nothing is subscribed → existing panel
        // behavior unchanged. The primary is already in `targets`, so skip it here.
        // ONLY shared-session activity frames mirror (allowlist, default-deny) — this
        // is what keeps correlated/secret frames (acks, pair_url, secret_saved, OAuth,
        // history replies, tool_result) with the ONE socket that asked.
        if (tabId && typeof frame.type === "string" && MIRROR_SAFE_FRAME_TYPES.has(frame.type)) {
            // Look subscribers up under the RESOLVED (canonical) tab id: after a
            // migration, agents keep pushing under a tab's ORIGINAL id while its
            // subscribers moved to the new id, so `targets[0]` (the resolved primary)
            // holds the id the viewers are actually keyed under.
            const canonicalId = targets.length === 1 ? targets[0].tabId : tabId;
            const subs = this.subscribers.get(canonicalId);
            if (subs) {
                const primarySock = targets[0]?.sock;
                for (const sock of subs) {
                    if (sock === primarySock || sock.readyState !== WebSocket.OPEN)
                        continue;
                    try {
                        sock.send(payload);
                        sent += 1;
                    }
                    catch {
                        /* viewer mid-disconnect — drop */
                    }
                }
            }
        }
        return sent;
    }
    async stop() {
        if (this.bindRetryTimer) {
            clearTimeout(this.bindRetryTimer);
            this.bindRetryTimer = null;
        }
        if (this.heartbeatTimer) {
            clearInterval(this.heartbeatTimer);
            this.heartbeatTimer = null;
        }
        for (const [rid, p] of this.pending) {
            clearTimeout(p.timer);
            p.reject(new Error("bridge stopped"));
            this.pending.delete(rid);
        }
        for (const conn of this.conns.values()) {
            try {
                conn.sock.close();
            }
            catch {
                // Already gone.
            }
        }
        this.conns.clear();
        for (const s of this.extraServers.splice(0)) {
            try {
                s.close();
            }
            catch {
                // already gone
            }
        }
        await new Promise((resolve) => {
            if (!this.wss)
                return resolve();
            this.wss.close(() => resolve());
        });
        this.wss = null;
    }
}
/** Bind-host classification for the guard above. `0.0.0.0`/`::` are exposure
 *  (all interfaces), so they are NOT loopback for this purpose. */
export function isLoopbackBindHost(host) {
    const h = host.trim().toLowerCase();
    return h === "127.0.0.1" || h === "localhost" || h === "::1";
}
// Module-level singleton (the last bridge started in this process).
let bridgeInstance = null;
export function startUiBridge(port, token, host) {
    if (!bridgeInstance) {
        bridgeInstance = new UiBridge(port ??
            (Number(process.env.COMFYUI_MCP_BRIDGE_PORT) || DEFAULT_BRIDGE_PORT), token ?? null, host ?? "127.0.0.1");
        bridgeInstance.start();
    }
    return bridgeInstance;
}
export function getUiBridge() {
    return bridgeInstance;
}
//# sourceMappingURL=ui-bridge.js.map