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
JavaScript
// 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