comfyui-mcp 0.28.0 → 0.30.0

package/dist/orchestrator/index.js

@@ -17,6 +17,7 @@ import { randomBytes } from "node:crypto";
 import readline from "node:readline";
 import { startUiBridge, isLoopbackBindHost } from "../services/ui-bridge.js";
 import { setupSecureBridge } from "../services/secure-bridge.js";
+import { startQuickTunnel } from "../services/tunnel.js";
 import { detectInstallMode } from "../services/self-update.js";
 import { SessionStore } from "./session-store.js";
 import { logger } from "../utils/logger.js";
@@ -24,7 +25,7 @@ import { PanelAgentManager, fetchSupportedModels, fetchSupportedCommands, isEffo
 import { createPanelMcpServer } from "./panel-tools.js";
 import { readUserMcpServers } from "../services/user-mcp-config.js";
 import { isForceRemoteFlagSet, isLoopbackHost, detectLocalComfyUIPath } from "../config.js";
-import { buildComfyuiMcpEnv, comfyuiSecretKeys, onComfyuiSecretsChanged, hydrateAgentSecretsIntoEnv, onAgentSecretsChanged, setAgentSecret, } from "../services/panel-secrets.js";
+import { buildComfyuiMcpEnv, comfyuiSecretKeys, onComfyuiSecretsChanged, hydrateAgentSecretsIntoEnv, onAgentSecretsChanged, setAgentSecret, setComfyuiSecret, isAllowedComfyuiSecretKey, } from "../services/panel-secrets.js";
 import { CodexBackend } from "./codex-backend.js";
 import { GeminiBackend, GEMINI_DEFAULT_MODEL } from "./gemini-backend.js";
 import { OllamaBackend } from "./ollama-backend.js";
@@ -34,15 +35,16 @@ import { readComfyuiCrashLog, formatCrashNote } from "../services/crash-log.js";
 import { QueueMonitor } from "../services/queue-monitor.js";
 import { unloadAllOllama, warmOllama, resolveOllamaHost } from "../services/ollama-vram.js";
 import { isLocalLmstudio, startLmstudioServer, unloadAllLmstudio, warmLmstudio, } from "../services/lmstudio-lifecycle.js";
+import { llamacppProps, llamacppToolsReady } from "../services/llamacpp-probe.js";
 import { getAgentSettings, setAgentSettings } from "../services/panel-settings.js";
 import { gatherEnvCapabilities, buildPanelSystemAppend, } from "../services/env-capabilities.js";
 const PANEL_SYSTEM_APPEND = `You are the autonomous assistant embedded directly in a ComfyUI sidebar panel. The person is working in ComfyUI and talks to you through that panel: their messages arrive as your prompts, and everything you write is shown to them in the panel chat. Write for that reader — lead with the result, keep replies short and concrete, and don't narrate routine internal steps.
 
-You can SEE and EDIT the workflow the user currently has open, via the panel_* tools (panel_get_graph, panel_add_node, panel_connect, panel_set_widget, panel_run, panel_get_errors, panel_save_workflow, …). STRONGLY PREFER building on their live canvas: read it with panel_get_graph first, add/wire/configure nodes with the panel_* tools, then panel_run to queue it — so the user watches the work happen and the result loads in their own workflow with full Ctrl+Z undo. Only fall back to the headless generate_image/enqueue_workflow tools when the user explicitly wants a one-off they don't need on their canvas, or when no panel tab is connected (a panel_* call will error if so). On a LARGE graph (a loaded pack/template with dozens of nodes), do NOT dump the whole thing with panel_get_graph and scan it — and NEVER shell out to grep/jq/python over a saved workflow file. To UNDERSTAND the graph, call panel_graph_outline FIRST: a compact, dependency-ordered TEXT map (nodes topologically sorted source→sink, each with its key widgets and ← inputs / → outputs wiring, plus a groups index) made for you to read top-to-bottom. To PINPOINT specific nodes, use panel_find_nodes: filter by type, title, input/output port, widget name, widget VALUE (e.g. a filename), is_output, or mode, or a free-text query across all of those — it returns each match's full summary plus why it matched. Reach for panel_get_graph's full JSON only when you need one node's exact slot/widget detail.
+You can SEE and EDIT the workflow the user currently has open, via the panel_* tools (panel_graph_outline, panel_query_graph, panel_add_node, panel_connect, panel_set_widget, panel_run, panel_get_errors, panel_save_workflow, …). STRONGLY PREFER building on their live canvas: read it first (panel_graph_outline, then panel_query_graph for specifics), add/wire/configure nodes with the panel_* tools, then panel_run to queue it — so the user watches the work happen and the result loads in their own workflow with full Ctrl+Z undo. Only fall back to the headless generate_image/enqueue_workflow tools when the user explicitly wants a one-off they don't need on their canvas, or when no panel tab is connected (a panel_* call will error if so). On a LARGE graph (a loaded pack/template with dozens of nodes), do NOT dump the whole thing and scan it — and NEVER shell out to grep/jq/python over a saved workflow file. To UNDERSTAND the graph, call panel_graph_outline FIRST: a compact, dependency-ordered TEXT map (nodes topologically sorted source→sink, each with its key widgets and ← inputs / → outputs wiring, plus a groups index) made for you to read top-to-bottom. To PINPOINT and INSPECT specific nodes, use panel_query_graph: filter by types/title/widget predicates ('cfg>7'), traverse upstream_of/downstream_of a node, aggregate with group_by:'type', and read ONE node's exact slot/widget detail with {ids:[id], fields:'detail'} — output is token-bounded so it can never flood your context. panel_find_nodes remains for free-text search across all fields.
 
 TRUST REPORTED MANUAL CHANGES. The user can edit the canvas BY HAND between your turns (bypass/mute a node, change a widget, rewire, add/remove nodes). When that happens, your turn opens with a "⟳ MANUAL CANVAS CHANGES since your last turn" block listing exactly what they changed. Treat that block as GROUND TRUTH about the current graph — it overrides what you remember from earlier in the conversation. Do NOT assume the graph still matches your last edit or your earlier reading; if the listed changes are substantial (or contradict a plan you were mid-execution on), re-read with panel_graph_outline before you act or draw conclusions. This is also how you learn the user already tried something (e.g. they bypassed a node and it worked) — believe it over your own prior reasoning.
 
-REFACTOR BIG GRAPHS INTO TOGGLEABLE SUBGRAPHS — don't reconstruct group membership by hand. panel_get_graph reports every group with its member node_ids (groups are geometric — they don't own nodes, so trust this list, not coordinates). To make a region readable and switchable as a UNIT (e.g. a "REPLACEMENT MODE" group), call panel_subgraph_group(group:<title or id>) — it wraps that group's nodes into one subgraph node in a single step (no need to gather node_ids yourself). Then toggle the whole region with panel_set_node_mode(<subgraph node id>, 'bypass' to turn it OFF / 'active' to turn it ON), and to compare variants queue it twice — panel_run with the subgraph active, then panel_set_node_mode to bypass and panel_run again. For an arbitrary node set that isn't a group, use panel_create_subgraph with explicit node_ids.
+REFACTOR BIG GRAPHS INTO TOGGLEABLE SUBGRAPHS — don't reconstruct group membership by hand. panel_query_graph reports every group with its member node_ids on each result's 'groups' (groups are geometric — they don't own nodes, so trust this list, not coordinates). To make a region readable and switchable as a UNIT (e.g. a "REPLACEMENT MODE" group), call panel_subgraph_group(group:<title or id>) — it wraps that group's nodes into one subgraph node in a single step (no need to gather node_ids yourself). Then toggle the whole region with panel_set_node_mode(<subgraph node id>, 'bypass' to turn it OFF / 'active' to turn it ON), and to compare variants queue it twice — panel_run with the subgraph active, then panel_set_node_mode to bypass and panel_run again. For an arbitrary node set that isn't a group, use panel_create_subgraph with explicit node_ids.
 
 If a workflow needs a custom node the user doesn't have, don't silently skip it — offer to install it. Use the BUILT-IN Manager tools: panel_search_nodes to find the pack, panel_install_node to install it, panel_node_queue_status to confirm it finished, then panel_restart_comfyui (tell the user first) to load it. NEVER restart while a generation is running or queued — a restart ABORTS the in-progress render (the tool refuses if ComfyUI is busy and tells you; wait for the queue to drain, or only force a restart if the user explicitly agrees to kill the running render). After the restart the panel reconnects and you resume automatically, so you can carry on with what you were building. Prefer these panel_* Manager tools over the headless install_custom_node/search_custom_nodes (which need a separate Manager setup).
 
@@ -50,11 +52,11 @@ CRASH RECOVERY — when a custom node BREAKS or CRASHED ComfyUI, fix it before g
 
 WEDGED RENDER / OOM / VRAM PINNED — when a generation is stuck or hits CUDA out-of-memory, or a cancel didn't actually free GPU memory (models still resident, VRAM pinned, the next run still OOMs), call panel_free_vram to UNLOAD all models and free VRAM before retrying — it does NOT restart ComfyUI, so it's the cheap first move. Escalation ladder: cancel the run → panel_free_vram (unload + free) → retry; only as a LAST RESORT panel_restart_comfyui (which refuses mid-render and guards the running generation). Reach for panel_free_vram before a restart whenever a cancel left memory pinned.
 
-CRITICAL — never destroy the user's work. When they ask for a "new workflow", a "fresh canvas", or to "start over for a new project", call panel_new_workflow (it opens a NEW TAB and leaves their current workflow intact). NEVER use panel_clear for that — panel_clear wipes the CURRENTLY OPEN graph and is ONLY for an explicit "clear/reset this canvas". You can manage tabs with panel_list_workflows / panel_open_workflow / panel_rename_workflow / panel_close_workflow, and group nodes with panel_select_nodes / panel_create_subgraph. To label a node by its purpose, use panel_set_node_title. To read or edit nodes INSIDE a subgraph, call panel_enter_subgraph(node_id) first — then panel_get_graph and the panel_* edit tools operate on the subgraph's inner nodes — and panel_exit_subgraph when you're done.
+CRITICAL — never destroy the user's work. When they ask for a "new workflow", a "fresh canvas", or to "start over for a new project", call panel_new_workflow (it opens a NEW TAB and leaves their current workflow intact). NEVER use panel_clear for that — panel_clear wipes the CURRENTLY OPEN graph and is ONLY for an explicit "clear/reset this canvas". You can manage tabs with panel_list_workflows / panel_open_workflow / panel_rename_workflow / panel_close_workflow, and group nodes with panel_select_nodes / panel_create_subgraph. To label a node by its purpose, use panel_set_node_title. To read or edit nodes INSIDE a subgraph, call panel_enter_subgraph(node_id) first — then panel_query_graph / panel_graph_outline and the panel_* edit tools operate on the subgraph's inner nodes — and panel_exit_subgraph when you're done.
 
-SUBGRAPH I/O — exposing interior nodes to the boundary. To wire an interior node to the subgraph's boundary from INSIDE a subgraph, do NOT panel_connect to a guessed rail node id — that's the rail and you'll get it wrong. Use panel_expose_subgraph_output(from_node_id, from_output) to expose an interior OUTPUT on the output rail (so the parent graph can wire the subgraph node's new output), and panel_expose_subgraph_input(to_node_id, to_input) to expose an interior INPUT on the input rail. Read panel_get_graph's \`rails\` field (present when viewing a subgraph) to see the current boundary slots — what's already exposed and what still needs it. To EXPAND/DISSOLVE a subgraph back into the parent graph (inline its inner nodes and rewire external links, removing the wrapper — the inverse of panel_create_subgraph), use panel_unpack_subgraph(node_id). All three are undoable with Ctrl+Z.
+SUBGRAPH I/O — exposing interior nodes to the boundary. To wire an interior node to the subgraph's boundary from INSIDE a subgraph, do NOT panel_connect to a guessed rail node id — that's the rail and you'll get it wrong. Use panel_expose_subgraph_output(from_node_id, from_output) to expose an interior OUTPUT on the output rail (so the parent graph can wire the subgraph node's new output), and panel_expose_subgraph_input(to_node_id, to_input) to expose an interior INPUT on the input rail. Read panel_query_graph's \`rails\` field (present when viewing a subgraph) to see the current boundary slots — what's already exposed and what still needs it. To EXPAND/DISSOLVE a subgraph back into the parent graph (inline its inner nodes and rewire external links, removing the wrapper — the inverse of panel_create_subgraph), use panel_unpack_subgraph(node_id). All three are undoable with Ctrl+Z.
 
-MERGE / COMPOSE WORKFLOWS — to bring nodes from ONE workflow into ANOTHER (combine two graphs, copy a section across tabs, reuse part of a saved workflow), use copy/paste: panel_open_workflow (the source) → panel_select_nodes (the section you want, or select all the nodes from panel_get_graph) → panel_copy_nodes → panel_open_workflow or panel_new_workflow (the destination) → panel_paste_nodes (returns the new node ids) → then wire and tidy them, applying the workflow-layout skill so the merged result is clean (no overlaps). The clipboard SURVIVES the workflow switch, so the copied nodes carry across tabs. Use connect_inputs only when you want the pasted nodes to auto-reconnect to matching existing nodes; default (false) drops a clean disconnected copy you wire yourself.
+MERGE / COMPOSE WORKFLOWS — to bring nodes from ONE workflow into ANOTHER (combine two graphs, copy a section across tabs, reuse part of a saved workflow), use copy/paste: panel_open_workflow (the source) → panel_select_nodes (the section you want, or select all the nodes from panel_query_graph {fields:'ids'}) → panel_copy_nodes → panel_open_workflow or panel_new_workflow (the destination) → panel_paste_nodes (returns the new node ids) → then wire and tidy them, applying the workflow-layout skill so the merged result is clean (no overlaps). The clipboard SURVIVES the workflow switch, so the copied nodes carry across tabs. Use connect_inputs only when you want the pasted nodes to auto-reconnect to matching existing nodes; default (false) drops a clean disconnected copy you wire yourself.
 
 REUSE SUBGRAPHS via the blueprint library — when the user builds a useful subgraph and wants to reuse it (now or in other workflows), SAVE it: panel_create_subgraph to group the nodes (if not already a subgraph), then panel_save_subgraph(node_id, name) publishes it to their library programmatically (no dialog). To drop a saved one into ANY workflow later, list them with panel_list_subgraphs and add with panel_add_subgraph(name). This is the durable way to reuse a building block across projects — distinct from copy/paste (a one-off merge of the current clipboard).
 
@@ -84,13 +86,13 @@ Adult / NSFW content is gated behind an explicit, persistent consent mode — qu
 
 SHOW / DISPLAY IMAGES AND VIDEOS — whenever the user asks to see, show, or display an image or video that you generated, composited, downloaded, or found — whether it is a file on disk (absolute path on the orchestrator host) or a ComfyUI output ref ({ filename, subfolder?, type? }) — call panel_show_media to render it as a media card directly in this chat. NEVER substitute emoji, text descriptions, or placeholder bullets for actual media; always call panel_show_media.
 
-INSPECT NODE MODES BEFORE YOU RUN. After loading a pack/template/workflow — and before any panel_run — call panel_get_graph and CHECK each node's mode. A node in 'bypass' is skipped (it just passes input through); a node in 'mute' does not execute and kills everything downstream. Packs and expert graphs ship with switches (a manual-prompt vs JSON/builder node, an rgthree Fast-Groups Bypasser/Muter, a prompt-source toggle) where the path you want is often BYPASSED/MUTED by default. NEVER assume a switch or route is active: if the path you intend to drive is bypassed/muted, enable it with panel_set_node_mode (set the wanted node 'active' and the unwanted one 'bypass'/'mute') BEFORE running. A wrong/stale mode is a top cause of renders that come out wrong.
+INSPECT NODE MODES BEFORE YOU RUN. After loading a pack/template/workflow — and before any panel_run — check node modes (panel_graph_outline marks [bypass]/[mute]; panel_query_graph detail rows carry mode). A node in 'bypass' is skipped (it just passes input through); a node in 'mute' does not execute and kills everything downstream. Packs and expert graphs ship with switches (a manual-prompt vs JSON/builder node, an rgthree Fast-Groups Bypasser/Muter, a prompt-source toggle) where the path you want is often BYPASSED/MUTED by default. NEVER assume a switch or route is active: if the path you intend to drive is bypassed/muted, enable it with panel_set_node_mode (set the wanted node 'active' and the unwanted one 'bypass'/'mute') BEFORE running. A wrong/stale mode is a top cause of renders that come out wrong.
 
 VERIFY THE OUTPUT MATCHES THE REQUEST. After a render completes, actually LOOK at the image/video the panel delivers and confirm it matches what was asked BEFORE you declare success or move to the next step. If it doesn't match, do NOT report progress — diagnose (wrong prompt path? a bypassed/muted builder or switch? wrong widget value?), fix it (often panel_set_node_mode or panel_set_widget), and rerun. Only claim something works once you've SEEN that it does — never report progress you haven't verified.
 
 AFTER PANEL_RUN — once you call panel_run to queue a render, you will be notified automatically with the output image(s)/video when it finishes. Do not poll get_queue, get_history, or list_output_images waiting for the result — just end your turn and the finished render will be delivered to you.
 
-DEBUG WRONG RENDERS BY INSPECTING INTERMEDIATE STEPS (run-to-node). When a final asset comes out WRONG — artifacts, wrong subject/pose/composition/color, blur, a ControlNet/IPAdapter/mask/LoRA not taking, a refiner or upscale stage degrading it — do NOT just re-roll the whole graph. LOCALIZE the fault: render only up to one stage and LOOK at what that stage produces. panel_run takes to_node_id to run ONE output branch (ComfyUI partial execution) — only that output node plus everything upstream of it renders, the rest is skipped, so it's fast and cheap, and the result is delivered to you automatically like any run. to_node_id MUST be an OUTPUT node (is_output:true in panel_get_graph). To inspect a point that ISN'T an output — a latent, a preprocessor/depth/pose map, a mask, an intermediate image — TAP it: add a PreviewImage on an IMAGE wire (or VAEDecode→PreviewImage on a LATENT, MaskToImage→PreviewImage on a MASK), panel_run(to_node_id=that preview), read the delivered image, then panel_remove_node the tap when done. Bisect upstream→downstream until you find the FIRST stage whose output is bad — that node (or its inputs/widgets) is what to fix, then run-to-node there again to confirm before a full run. For the full method (probe recipes, symptom→probe map) read the debug-render skill via read_skill. This is for renders that COMPLETE but look wrong; for runs that fail with an error/OOM/missing node, use the troubleshooting skill instead.
+DEBUG WRONG RENDERS BY INSPECTING INTERMEDIATE STEPS (run-to-node). When a final asset comes out WRONG — artifacts, wrong subject/pose/composition/color, blur, a ControlNet/IPAdapter/mask/LoRA not taking, a refiner or upscale stage degrading it — do NOT just re-roll the whole graph. LOCALIZE the fault: render only up to one stage and LOOK at what that stage produces. panel_run takes to_node_id to run ONE output branch (ComfyUI partial execution) — only that output node plus everything upstream of it renders, the rest is skipped, so it's fast and cheap, and the result is delivered to you automatically like any run. to_node_id MUST be an OUTPUT node (is_output:true in panel_query_graph detail rows). To inspect a point that ISN'T an output — a latent, a preprocessor/depth/pose map, a mask, an intermediate image — TAP it: add a PreviewImage on an IMAGE wire (or VAEDecode→PreviewImage on a LATENT, MaskToImage→PreviewImage on a MASK), panel_run(to_node_id=that preview), read the delivered image, then panel_remove_node the tap when done. Bisect upstream→downstream until you find the FIRST stage whose output is bad — that node (or its inputs/widgets) is what to fix, then run-to-node there again to confirm before a full run. For the full method (probe recipes, symptom→probe map) read the debug-render skill via read_skill. This is for renders that COMPLETE but look wrong; for runs that fail with an error/OOM/missing node, use the troubleshooting skill instead.
 
 CHAIN A STAGE'S OUTPUT INTO THE NEXT STAGE'S LOADER — when a multi-stage pipeline (e.g. Krea2 image → LTX video → WAN extend) needs one stage's OUTPUT fed into the next stage's loader (LoadImage / VHS_LoadVideo / LoadAudio), call stage_output_as_input with the output's { filename, subfolder?, type? } and drop the returned input filename into the loader's image/video/audio widget. (Or, for a file already on disk, upload_image / upload_video / upload_audio.) NEVER copy the output file into, or guess, a filesystem \`input/\` path: ComfyUI's input AND output directories may be CUSTOM (launched with --input-directory / --output-directory), so a guessed path makes LoadImage reject the file ("Invalid image file") and wastes the render. stage_output_as_input goes through the server API (/view → /upload/image), which resolves the real dirs correctly every time. VERIFY A VIDEO RENDER VIA THE FILESYSTEM, NOT /history — VHS_VideoCombine and similar video nodes write the .mp4 but frequently do NOT register an output in ComfyUI's /history (the prompt shows done with no output and no error), so do NOT conclude a clip "silently dropped" from get_history/get_job_status; confirm it with list_output_images (which now lists videos, each tagged kind:"video") by filename/prefix + fresh mtime, then chain it forward with stage_output_as_input.
 
@@ -129,7 +131,7 @@ const injectedQueueNotes = new Set();
  *  prepended to each headless-tab turn like the crash/queue notes, tells it to run
  *  headless and deliver the result ITSELF, in-turn. */
 const HEADLESS_DIRECTIVE = "[HEADLESS SESSION — no ComfyUI panel/canvas is connected] The panel_* live-canvas tools " +
-    "(panel_run, panel_get_graph, panel_set_widget, panel_add_node, …) are UNAVAILABLE here and will fail — " +
+    "(panel_run, panel_query_graph, panel_set_widget, panel_add_node, …) are UNAVAILABLE here and will fail — " +
     "do everything through the comfyui MCP tools (generate_image, or create_workflow + enqueue_workflow). " +
     "There is NO panel to auto-deliver a finished render, so you MUST deliver the result YOURSELF IN THIS SAME TURN: " +
     "enqueuing returns a prompt_id immediately, so wait for it with get_job_status(prompt_id) — poll it briefly until " +
@@ -584,6 +586,24 @@ export async function runPanelOrchestrator() {
     const lockPort = Number(process.env.COMFYUI_MCP_BRIDGE_PORT) || 9180;
     const lockPath = orchLockPath(lockPort);
     const bridge = startUiBridge(lockPort, bridgeToken, bridgeHost);
+    // On-demand phone pairing (the panel "Remote control" button). Off by default:
+    // the FIRST pair request lazily binds a SECOND, token-gated listener on all
+    // interfaces (so a phone can reach it), while the primary loopback bridge stays
+    // token-less. LAN mode returns a same-wifi ws:// URL; tunnel mode fronts the same
+    // token-gated listener with a cloudflared wss:// for anywhere access.
+    const pairPort = lockPort + 2; // avoid the panel_* HTTP-MCP port (lockPort + 1)
+    let pairToken = null;
+    let pairListenerStarted = false;
+    let pairTunnel = null;
+    const ensurePairListener = async () => {
+        if (!pairToken)
+            pairToken = randomBytes(24).toString("hex");
+        if (!pairListenerStarted) {
+            await bridge.addListener("0.0.0.0", pairPort, pairToken);
+            pairListenerStarted = true;
+        }
+        return pairToken;
+    };
     if (lanBridge) {
         // Ready-to-paste connection info: the panel's Settings → Advanced →
         // Bridge URL takes the full URL incl. ?token= verbatim.
@@ -853,6 +873,33 @@ export async function runPanelOrchestrator() {
     const LMSTUDIO_BASE_URL = (process.env.COMFYUI_MCP_LMSTUDIO_HOST ?? "http://127.0.0.1:1234/v1").replace(/[/]$/, "");
     let lmstudioModel = process.env.COMFYUI_MCP_LMSTUDIO_MODEL ?? persistedAgent.lmstudio?.model ?? "";
     const lmstudioDeps = () => ({ api: "openai", host: LMSTUDIO_BASE_URL });
+    // llama.cpp (issue #161) — llama-server's OpenAI-compatible /v1. No key, no
+    // login, ONE model fixed at launch (-m). Context is a LAUNCH flag (-c), and
+    // tool calling needs --jinja — both probed at connect (services/llamacpp-probe).
+    const LLAMACPP_BASE_URL = (process.env.COMFYUI_MCP_LLAMACPP_HOST ?? "http://127.0.0.1:8080/v1").replace(/[/]$/, "");
+    let llamacppModel = process.env.COMFYUI_MCP_LLAMACPP_MODEL ?? persistedAgent.llamacpp?.model ?? "";
+    const llamacppDeps = () => ({ api: "openai", host: LLAMACPP_BASE_URL });
+    // Custom OpenAI-compatible endpoint (issue #162) — the same openai dialect
+    // pointed anywhere the user says: vLLM, DeepSeek, Together, Azure, a box on
+    // the LAN… Base URL + model come from panel Settings (persisted) or env; the
+    // API key from the 0600 secrets store (COMFYUI_MCP_CUSTOM_API_KEY, set via
+    // the panel's masked "Set API key…" — many local endpoints need none). NO
+    // default URL on purpose: unconfigured degrades with an actionable ack
+    // instead of dialing a guess.
+    let customBaseUrl = (process.env.COMFYUI_MCP_CUSTOM_BASE_URL ?? persistedAgent.custom?.baseUrl ?? "").replace(/[/]$/, "");
+    let customModel = process.env.COMFYUI_MCP_CUSTOM_MODEL ?? persistedAgent.custom?.model ?? "";
+    // Key read FRESH each call (not a startup const) so a key set later via the
+    // panel — setAgentSecret hydrates it into env — applies on the next backend
+    // build without an orchestrator restart.
+    const customApiKey = () => process.env.COMFYUI_MCP_CUSTOM_API_KEY;
+    const customDeps = () => {
+        const key = customApiKey();
+        return {
+            api: "openai",
+            host: customBaseUrl,
+            ...(key ? { apiKey: key } : {}),
+        };
+    };
     // ── Per-tab backend (single-port multi-provider) ──────────────────────────
     // ONE orchestrator on ONE bridge port serves ALL providers; the panel picks a
     // provider per tab via the `hello`/`set_backend` handshake, instead of the node
@@ -862,7 +909,7 @@ export async function runPanelOrchestrator() {
     // provider (the panel replays the transcript to seed it) while a same-provider
     // reconnect RESUMES. `backendId`/`codexModel`/`geminiModel` above are the
     // DEFAULT + per-provider model config; the process is no longer pinned to one.
-    const KNOWN_BACKENDS = new Set(["claude", "codex", "gemini", "ollama", "openrouter", "lmstudio"]);
+    const KNOWN_BACKENDS = new Set(["claude", "codex", "gemini", "ollama", "openrouter", "lmstudio", "llamacpp", "custom"]);
     const defaultBackend = KNOWN_BACKENDS.has(backendId) ? backendId : "claude";
     const AGENT_KEY_SEP = "::";
     const tabBackends = new Map(); // panel tabId -> selected backend
@@ -1030,6 +1077,26 @@ export async function runPanelOrchestrator() {
                 ...lmstudioDeps(),
             });
         }
+        if (backend === "llamacpp") {
+            return new OllamaBackend({
+                cwd: comfyuiPath ?? process.cwd(),
+                model: llamacppModel,
+                systemAppend: panelSystemAppend,
+                comfyuiUrl,
+                mcpServers: makeHttpBackendMcpServers(panelTabId),
+                ...llamacppDeps(),
+            });
+        }
+        if (backend === "custom") {
+            return new OllamaBackend({
+                cwd: comfyuiPath ?? process.cwd(),
+                model: customModel,
+                systemAppend: panelSystemAppend,
+                comfyuiUrl,
+                mcpServers: makeHttpBackendMcpServers(panelTabId),
+                ...customDeps(),
+            });
+        }
         return undefined; // claude → built-in ClaudeBackend
     };
     logger.info(`[panel-orchestrator] single-port multi-provider: default backend=${defaultBackend}; ` +
@@ -1054,7 +1121,11 @@ export async function runPanelOrchestrator() {
                             ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: openrouterModel, ...openrouterDeps() })
                             : backend === "lmstudio"
                                 ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: lmstudioModel, ...lmstudioDeps() })
-                                : new GeminiBackend({ cwd: comfyuiPath ?? process.cwd(), model: geminiModel });
+                                : backend === "llamacpp"
+                                    ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: llamacppModel, ...llamacppDeps() })
+                                    : backend === "custom"
+                                        ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: customModel, ...customDeps() })
+                                        : new GeminiBackend({ cwd: comfyuiPath ?? process.cwd(), model: geminiModel });
             probeBackends.set(backend, pb);
         }
         return pb;
@@ -1274,16 +1345,20 @@ export async function runPanelOrchestrator() {
     // without a reconnect.
     const unsubscribeAgentSecrets = onAgentSecretsChanged(() => {
         hydrateAgentSecretsIntoEnv();
-        modelsByBackend.delete("openrouter");
-        const pb = probeBackends.get("openrouter");
-        if (pb?.close)
-            void pb.close().catch(() => { });
-        probeBackends.delete("openrouter");
+        // A key change can affect either keyed endpoint provider — drop both
+        // caches so the next probe carries the fresh credentials.
+        for (const b of ["openrouter", "custom"]) {
+            modelsByBackend.delete(b);
+            const pb = probeBackends.get(b);
+            if (pb?.close)
+                void pb.close().catch(() => { });
+            probeBackends.delete(b);
+        }
         for (const tabId of tabBackends.keys()) {
             pushReadiness(tabId);
             pushModels(tabId);
         }
-        logger.info("[panel-orchestrator] OpenRouter key saved → provider readiness + models refreshed");
+        logger.info("[panel-orchestrator] provider key saved → readiness + models refreshed");
     });
     // Debounce the connect ack: the panel re-sends `hello` on reconnect and on
     // workflow-title changes, which would otherwise stack duplicate greetings.
@@ -1322,14 +1397,31 @@ export async function runPanelOrchestrator() {
             p = probe.then((list) => {
                 if (!list.length)
                     modelsByBackend.delete(backend); // don't cache a failed probe
-                // LM Studio ships no sane hardcoded default (model ids are whatever the
-                // user downloaded) — adopt the server's first offering when unset.
+                // LM Studio / llama.cpp ship no sane hardcoded default (the model is
+                // whatever the user downloaded/launched) — adopt the server's first
+                // offering when unset. llama-server serves exactly one model, so this
+                // IS the model.
                 if (backend === "lmstudio" && !lmstudioModel && list.length) {
                     lmstudioModel = list[0].value ?? "";
                     if (lmstudioModel) {
                         logger.info(`[panel-orchestrator] lmstudio default model → ${lmstudioModel} (first served)`);
                     }
                 }
+                if (backend === "llamacpp" && !llamacppModel && list.length) {
+                    llamacppModel = list[0].value ?? "";
+                    if (llamacppModel) {
+                        logger.info(`[panel-orchestrator] llamacpp model → ${llamacppModel} (the server's loaded model)`);
+                    }
+                }
+                // Custom endpoint: same adoption — many self-hosted servers (vLLM,
+                // llama-server, TGI) serve exactly one model, so the first listed id
+                // is the sane default when the user hasn't named one.
+                if (backend === "custom" && !customModel && list.length) {
+                    customModel = list[0].value ?? "";
+                    if (customModel) {
+                        logger.info(`[panel-orchestrator] custom endpoint model → ${customModel} (first served)`);
+                    }
+                }
                 // User-curated preferred models (panel Settings → set_config) pin to the
                 // top of the ollama picker, ahead of the discovered catalog. Read fresh
                 // on every probe; set_config evicts the cache so edits apply live.
@@ -1366,6 +1458,10 @@ export async function runPanelOrchestrator() {
             return openrouterModel;
         if (backend === "lmstudio")
             return lmstudioModel || undefined;
+        if (backend === "llamacpp")
+            return llamacppModel || undefined;
+        if (backend === "custom")
+            return customModel || undefined;
         return model;
     }
     function pushModels(panelTabId) {
@@ -1419,8 +1515,29 @@ export async function runPanelOrchestrator() {
     // no CLI). The panel prefers this frame over its GET /backends probe.
     function pushReadiness(tabId) {
         try {
-            const { backends, any_ready } = allBackendReadiness(KNOWN_BACKENDS);
+            const { backends, any_ready } = allBackendReadiness(KNOWN_BACKENDS, {
+                customEndpointConfigured: !!customBaseUrl,
+            });
             bridge.push({ type: "backends", backends, any_ready }, tabId);
+            // llama.cpp reality check (async re-push): the binary is often unzipped
+            // anywhere (not on PATH), so static detection says "not installed" while
+            // a server is HAPPILY ANSWERING. A live endpoint beats a missing binary —
+            // probe it and, when it answers, re-push the frame with llamacpp ready.
+            const lc = backends.find((b) => b.backend === "llamacpp");
+            if (lc && !lc.ready) {
+                void fetch(`${LLAMACPP_BASE_URL.replace(/\/v1$/, "")}/health`, {
+                    signal: AbortSignal.timeout(1500),
+                })
+                    .then((r) => {
+                    if (!r.ok)
+                        return;
+                    lc.cli = true;
+                    lc.auth = true;
+                    lc.ready = true;
+                    bridge.push({ type: "backends", backends, any_ready: true }, tabId);
+                })
+                    .catch(() => { });
+            }
         }
         catch (err) {
             logger.warn(`[panel-orchestrator] readiness probe failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1495,6 +1612,8 @@ export async function runPanelOrchestrator() {
             const isOl = backend === "ollama";
             const isOr = backend === "openrouter";
             const isLs = backend === "lmstudio";
+            const isLc = backend === "llamacpp";
+            const isCu = backend === "custom";
             // TRUTHFUL "connected": only claim ready after PROVING the SELECTED backend
             // can run, by probing its model list. If the probe fails — the "connected
             // but dead" wedge — send a degraded ack so the panel shows the real state.
@@ -1512,6 +1631,18 @@ export async function runPanelOrchestrator() {
                 logger.warn(`[panel-orchestrator] tab ${panelTab.slice(0, 8)} connected (openrouter) but no API key — degraded ack`);
                 return;
             }
+            // Custom endpoint with no URL: don't dial a guess — degrade up front
+            // with the exact fix (mirrors the OpenRouter keyless guard above).
+            if (isCu && !customBaseUrl) {
+                bridge.push({
+                    type: "say",
+                    text: "⚠️ No endpoint configured — set the base URL in Settings → Custom endpoint (include the /v1, e.g. http://192.168.1.20:8000/v1 for vLLM, or a hosted provider's OpenAI-compatible URL), " +
+                        "plus “Set API key…” if the server needs one. Both apply immediately — then Connect again.",
+                }, panelTab);
+                bridge.push({ type: "ack", ok: false, kind: "degraded" }, panelTab);
+                logger.warn(`[panel-orchestrator] tab ${panelTab.slice(0, 8)} connected (custom) but no base URL — degraded ack`);
+                return;
+            }
             void (isLs && isLocalLmstudio(LMSTUDIO_BASE_URL)
                 ? startLmstudioServer(LMSTUDIO_BASE_URL).then(() => ensureModels(backend))
                 : ensureModels(backend))
@@ -1525,9 +1656,40 @@ export async function runPanelOrchestrator() {
                                 ? (ollamaModel ?? models[0].value ?? "Ollama")
                                 : isLs
                                     ? (lmstudioModel || (models[0].value ?? "LM Studio"))
-                                    : isOr
-                                        ? (openrouterModel ?? models[0].value ?? "OpenRouter")
-                                        : model;
+                                    : isLc
+                                        ? (llamacppModel || (models[0].value ?? "llama.cpp"))
+                                        : isCu
+                                            ? (customModel || (models[0].value ?? "Custom endpoint"))
+                                            : isOr
+                                                ? (openrouterModel ?? models[0].value ?? "OpenRouter")
+                                                : model;
+                    // llama.cpp launch gotchas (issue #161): a reachable server can still
+                    // be useless for us — tool calling needs --jinja (rejected requests),
+                    // and a launch-time -c under ~16K silently truncates the tool payload.
+                    // Probe both and degrade/warn with the exact fix instead of letting
+                    // the first real message fail cryptically.
+                    if (isLc) {
+                        const activeModel = llamacppModel || (models[0].value ?? "");
+                        void (async () => {
+                            const [tools, props] = await Promise.all([
+                                llamacppToolsReady(LLAMACPP_BASE_URL, activeModel),
+                                llamacppProps(LLAMACPP_BASE_URL),
+                            ]);
+                            if (tools === "no") {
+                                bridge.push({
+                                    type: "say",
+                                    text: "⚠️ Your llama-server is running WITHOUT `--jinja`, so tool calling is disabled — every agent action would fail. " +
+                                        "Restart it with tool support: `llama-server -m <model>.gguf --jinja -c 16384` (current builds enable jinja by default; older ones need the flag), then Disconnect → Connect.",
+                                }, panelTab);
+                            }
+                            else if (props.nCtx && props.nCtx < 16384) {
+                                bridge.push({
+                                    type: "say",
+                                    text: `ℹ️ Your llama-server context is ${props.nCtx} tokens (launch flag -c). The agent's tool payload wants ≥16384 — below that, long turns silently truncate. Consider restarting with \`-c 16384\` or higher.`,
+                                }, panelTab);
+                            }
+                        })();
+                    }
                     // Greet only on a FRESH session (a resume/reconnect already has the thread).
                     if (!resume) {
                         const readyText = isCx
@@ -1538,9 +1700,13 @@ export async function runPanelOrchestrator() {
                                     ? `🟢 comfyui-mcp agent ready — ${agentLabel} running locally via Ollama (no account, no API key). Small local models are slower and simpler than frontier ones — expect fewer frills. Ask away.`
                                     : isLs
                                         ? `🟢 comfyui-mcp agent ready — ${agentLabel} running locally via LM Studio (no account, no API key). Small local models are slower and simpler than frontier ones — expect fewer frills. Ask away.`
-                                        : isOr
-                                            ? `🟢 comfyui-mcp agent ready — ${agentLabel} via OpenRouter (hosted API, your OPENROUTER_API_KEY). Ask away.`
-                                            : `🟢 comfyui-mcp agent ready — ${agentLabel} on your Claude subscription. Ask away.`;
+                                        : isLc
+                                            ? `🟢 comfyui-mcp agent ready — ${agentLabel} running locally via llama.cpp (no account, no API key). Small local models are slower and simpler than frontier ones — expect fewer frills. Ask away.`
+                                            : isCu
+                                                ? `🟢 comfyui-mcp agent ready — ${agentLabel} via your custom endpoint (${customBaseUrl}). Ask away.`
+                                                : isOr
+                                                    ? `🟢 comfyui-mcp agent ready — ${agentLabel} via OpenRouter (hosted API, your OPENROUTER_API_KEY). Ask away.`
+                                                    : `🟢 comfyui-mcp agent ready — ${agentLabel} on your Claude subscription. Ask away.`;
                         bridge.push({ type: "say", text: readyText }, panelTab);
                     }
                     bridge.push({ type: "ack", ok: true, kind: "ready", agent: agentLabel, backend }, panelTab);
@@ -1552,10 +1718,14 @@ export async function runPanelOrchestrator() {
                         : isGm
                             ? "⚠️ The background agent isn't responding — the Gemini CLI couldn't start. Make sure the Gemini CLI is installed and signed in (run `gemini` once and complete the Google sign-in), then Disconnect → Connect to retry."
                             : isOl
-                                ? "⚠️ The background agent isn't responding — Ollama isn't reachable. Start it with `ollama serve` and pull our fine-tuned model (`ollama pull artokun/gemma4-comfyui-mcp:e4b` — gemma4 trained on the comfyui-mcp tool suite; `:e2b` for ~2 GB VRAM, `:12b` for ~8 GB), then Disconnect → Connect to retry."
+                                ? "⚠️ The background agent isn't responding — Ollama isn't reachable. Start it with `ollama serve` and pull our fine-tuned model (`ollama pull artokun/gemma4-comfyui-mcp:e4b` — gemma4 trained on the comfyui-mcp tool suite — arena-best local model; `:12b` for ~8 GB VRAM), then Disconnect → Connect to retry."
                                 : isLs
                                     ? `⚠️ The background agent isn't responding — LM Studio isn't reachable at ${LMSTUDIO_BASE_URL}. Open LM Studio → Developer → Start Server and load a tool-calling model (our gemma4-comfyui-mcp GGUFs from Hugging Face work great), or set COMFYUI_MCP_LMSTUDIO_HOST if it serves elsewhere — then Disconnect → Connect to retry.`
-                                    : "⚠️ The background agent isn't responding — the Claude Agent SDK couldn't start. Make sure you're signed in (run `claude` once), then Disconnect → Connect to retry.";
+                                    : isLc
+                                        ? `⚠️ The background agent isn't responding — llama-server isn't reachable at ${LLAMACPP_BASE_URL}. Start it with \`llama-server -m <model>.gguf -c 16384\` (our gemma4-comfyui-mcp GGUFs work great; add --jinja on older builds — required there for tool calling), or set COMFYUI_MCP_LLAMACPP_HOST — then Disconnect → Connect to retry.`
+                                        : isCu
+                                            ? `⚠️ The background agent isn't responding — your custom endpoint isn't answering at ${customBaseUrl}. Check the base URL in Settings → Custom endpoint (it must be OpenAI-compatible and include the /v1) and the API key if the server requires one — then Connect to retry.`
+                                            : "⚠️ The background agent isn't responding — the Claude Agent SDK couldn't start. Make sure you're signed in (run `claude` once), then Disconnect → Connect to retry.";
                     bridge.push({ type: "say", text: degradedText }, panelTab);
                     bridge.push({ type: "ack", ok: false, kind: "degraded" }, panelTab);
                     logger.warn(`[panel-orchestrator] tab ${panelTab.slice(0, 8)} connected (${backend}) but model probe empty — degraded ack`);
@@ -1654,6 +1824,18 @@ export async function runPanelOrchestrator() {
                     logger.info(`[panel-orchestrator] ollama config → model=${ollamaModel} api=${ollamaApi} host=${ollamaBaseUrl ?? "(default)"}`);
                 }
             }
+            const lccfg = event.llamacpp;
+            if (lccfg && typeof lccfg === "object") {
+                const o = lccfg;
+                if (typeof o.model === "string" && o.model.trim()) {
+                    const m = o.model.trim();
+                    if (!process.env.COMFYUI_MCP_LLAMACPP_MODEL)
+                        llamacppModel = m;
+                    setAgentSettings({ llamacpp: { model: m } });
+                    modelsByBackend.delete("llamacpp");
+                    logger.info(`[panel-orchestrator] llamacpp config → model=${llamacppModel}`);
+                }
+            }
             const lcfg = event.lmstudio;
             if (lcfg && typeof lcfg === "object") {
                 const o = lcfg;
@@ -1670,6 +1852,35 @@ export async function runPanelOrchestrator() {
                     logger.info(`[panel-orchestrator] lmstudio config → model=${lmstudioModel}`);
                 }
             }
+            // Custom endpoint (issue #162): base_url + model, both user-supplied.
+            // base_url accepts "" (clears the endpoint → provider flips unready);
+            // either change evicts the probe/model caches so the next connect dials
+            // the new target, and re-pushes readiness so the picker flips live.
+            const cucfg = event.custom;
+            if (cucfg && typeof cucfg === "object") {
+                const o = cucfg;
+                const patch = {};
+                if (typeof o.model === "string" && o.model.trim()) {
+                    patch.model = o.model.trim();
+                    if (!process.env.COMFYUI_MCP_CUSTOM_MODEL)
+                        customModel = patch.model;
+                }
+                if (typeof o.base_url === "string") {
+                    patch.baseUrl = o.base_url.trim().replace(/[/]$/, "");
+                    if (!process.env.COMFYUI_MCP_CUSTOM_BASE_URL)
+                        customBaseUrl = patch.baseUrl;
+                }
+                if (Object.keys(patch).length) {
+                    setAgentSettings({ custom: patch });
+                    const pb = probeBackends.get("custom");
+                    if (pb?.close)
+                        void pb.close().catch(() => { });
+                    probeBackends.delete("custom");
+                    modelsByBackend.delete("custom");
+                    pushReadiness(event.tab_id);
+                    logger.info(`[panel-orchestrator] custom endpoint config → model=${customModel || "(first served)"} host=${customBaseUrl || "(unset)"}`);
+                }
+            }
             if (ollamaChanged) {
                 modelsByBackend.delete("ollama");
                 pushModels(event.tab_id);
@@ -1677,13 +1888,16 @@ export async function runPanelOrchestrator() {
             bridge.push({ type: "ack", ok: true, kind: "config" }, event.tab_id);
             return;
         }
-        // Panel-initiated provider secret (Settings › "Set API key…") — NO agent, no
+        // Panel-initiated secret (Settings › "Set API key/token…") — NO agent, no
         // chat: the panel paints its own masked input and ships the value here
         // directly, over the same loopback/token-gated bridge the agent-initiated
-        // request_secret reply already rides. setAgentSecret enforces the allowlist
-        // (OPENROUTER_API_KEY), persists 0600, and hydrates process.env immediately,
-        // so the refreshed readiness frame flips the provider picker live — a user
-        // can enable OpenRouter before ANY backend is ready (no chicken-and-egg).
+        // request_secret reply already rides. Routed by allowlist: PROVIDER keys
+        // (OPENROUTER_API_KEY, COMFYUI_MCP_CUSTOM_API_KEY) → setAgentSecret, which
+        // persists 0600 and hydrates process.env immediately so the refreshed
+        // readiness frame flips the provider picker live; comfyui TOOL tokens
+        // (CivitAI/HuggingFace) → setComfyuiSecret, whose change event already
+        // re-injects the MCP child env + respawns on idle — so EVERY token button
+        // works agent-free with just the bridge connected (no chicken-and-egg).
         if (event.type === "set_secret" && event.tab_id) {
             const rawKey = event.key;
             const rawValue = event.value;
@@ -1693,8 +1907,11 @@ export async function runPanelOrchestrator() {
             try {
                 if (!value.trim())
                     throw new Error("No token entered — nothing was saved.");
-                setAgentSecret(key, value.trim());
-                logger.info(`[panel-orchestrator] provider secret set from panel Settings: ${key} (redacted)`);
+                if (isAllowedComfyuiSecretKey(key))
+                    setComfyuiSecret(key, value.trim());
+                else
+                    setAgentSecret(key, value.trim());
+                logger.info(`[panel-orchestrator] secret set from panel Settings: ${key} (redacted)`);
             }
             catch (err) {
                 error = err instanceof Error ? err.message : String(err);
@@ -1704,6 +1921,49 @@ export async function runPanelOrchestrator() {
                 pushReadiness(event.tab_id);
             return;
         }
+        // Phone pairing: mint a phone-reachable bridge URL for the panel's QR modal.
+        // `lan` → ws://<lan-ip>:<pairPort>/?token= (same wifi); `tunnel` → a cloudflared
+        // wss://…/?token= (anywhere). Both hit the on-demand token-gated pairing
+        // listener; async (tunnel startup can fail), so reply via a typed frame.
+        if (event.type === "pair" && event.tab_id) {
+            const mode = event.mode === "tunnel" ? "tunnel" : "lan";
+            const tabId = event.tab_id;
+            void (async () => {
+                const token = await ensurePairListener();
+                let url;
+                if (mode === "tunnel") {
+                    if (!pairTunnel) {
+                        const t = await startQuickTunnel(pairPort, "127.0.0.1");
+                        pairTunnel = { url: t.url, stop: t.stop };
+                        process.once("exit", () => {
+                            try {
+                                pairTunnel?.stop();
+                            }
+                            catch {
+                                /* best-effort */
+                            }
+                        });
+                    }
+                    const u = new URL(pairTunnel.url);
+                    u.protocol = "wss:";
+                    u.search = "";
+                    u.searchParams.set("token", token);
+                    url = u.toString();
+                }
+                else {
+                    const ip = firstLanIPv4();
+                    if (!ip) {
+                        throw new Error("No LAN network found — connect this machine to wifi/ethernet, or use the Internet (tunnel) option.");
+                    }
+                    url = `ws://${ip}:${pairPort}/?token=${token}`;
+                }
+                logger.info(`[panel-orchestrator] pairing URL minted (${mode})`);
+                bridge.push({ type: "pair_url", mode, url }, tabId);
+            })().catch((err) => {
+                bridge.push({ type: "pair_error", mode, error: err instanceof Error ? err.message : String(err) }, tabId);
+            });
+            return;
+        }
         // Model / effort picker: apply and confirm. Model switches live; an effort
         // change restarts the session (resumed) so the conversation carries over.
         if (event.type === "set_options" && event.tab_id) {