comfyui-mcp 0.48.22 → 0.48.24

package/README.md

@@ -16,7 +16,7 @@ Works on **macOS**, **Linux**, and **Windows**. Auto-detects your ComfyUI instal
 
 **Stuck or have a question? [Join the Discord](https://discord.gg/cW9arBhzCu)** — help, model tips, and release announcements.
 
-**182 MCP tools** | **35 AI skills** (Flux · WAN · LTX 2.3 video · Qwen · Z-Image · Ideogram 4 · ERNIE · ANIMA · model registry · Civitai · node authoring · launch/perf flags) | **55 installer packs** | **11 slash commands** | **4 autonomous agents** | **3 hooks**
+**182 MCP tools** | **36 AI skills** (Flux · WAN · LTX 2.3 video · Qwen · Z-Image · Ideogram 4 · ERNIE · ANIMA · model registry · Civitai · node authoring · launch/perf flags) | **55 installer packs** | **11 slash commands** | **4 autonomous agents** | **3 hooks**
 
 The plugin ships **expert skills that grow with every release** — model-specific generation guides with curated download URLs, workflow recipes, troubleshooting, and custom-node authoring — so Claude knows the right sampler, CFG, resolution, and model files for each architecture without trial and error.
 

package/dist/orchestrator/index.js

@@ -26,7 +26,7 @@ import { uploadImageHttp, resetClient } from "../comfyui/client.js";
 import { logger } from "../utils/logger.js";
 import { PanelAgentManager, fetchSupportedModels, fetchSupportedCommands, isEffort, } from "./panel-agent.js";
 import { promptText } from "./error-text.js";
-import { createPanelMcpServer } from "./panel-tools.js";
+import { createPanelMcpServer, makePanelToolCtx, resolvePinTarget } from "./panel-tools.js";
 import { optionsAckFrame, optionsErrorAckFrame, optionsRequestMeta, } from "./options-ack.js";
 import { readUserMcpServers } from "../services/user-mcp-config.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -85,7 +85,7 @@ REPORT OUR OWN BUGS (we're in beta — bias HARD toward filing) — distinct fro
 
 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.
 
-WORKFLOW TARGETING — by default your panel_* graph edits follow whichever workflow tab the user is currently viewing. If the user wants you to work on a DIFFERENT open workflow while they browse another tab, call panel_set_workflow_target(mode:"pinned", path:<from panel_list_workflows>) to pin edits to that workflow; panel_get_workflow_target shows the current binding. Set mode:"current" to follow the user's active tab again. Pinning does NOT switch what the user sees — it only routes your graph tools. When pinned, still use panel_open_workflow only when you intentionally want to switch the user's view.
+WORKFLOW TARGETING — by default your panel_* graph edits follow whichever workflow tab the user is currently viewing. The panel can only read or edit the workflow currently IN VIEW, so to work on a specific open workflow, make it the active canvas first with panel_open_workflow, then call panel_set_workflow_target(mode:"pinned", path:<from panel_list_workflows>) to bind your edits to it; panel_get_workflow_target shows the current binding. Pinning to a background (open but not active) workflow is REJECTED at pin time — it cannot route edits to a tab that isn't in view. A pin does NOT switch what the user sees; it binds your edits to that workflow so that if the user later switches away, your next graph call fails loudly instead of silently editing the wrong graph. Set mode:"current" to follow the user's active tab again.
 
 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.
 
@@ -216,11 +216,16 @@ function formatQueueNote(rep) {
             `clear_pending:true; if it reports the job still wedged, restart_comfyui / panel_restart_comfyui. ` +
             `Do NOT queue another run on top.`);
     }
-    if (rep.backlog) {
+    // A plain backlog (depth > 1) is NOT evidence of a wedge — deliberately queuing
+    // a batch is a normal workflow. Suppress the note entirely when the in-flight
+    // work is this session's own recent jobs, and when it isn't, report it NEUTRALLY
+    // (no false "you likely queued behind a stuck job" diagnosis, no destructive
+    // clear_pending as the headline). A genuinely stalled job is handled above (#559).
+    if (rep.backlog && !rep.selfAttributed) {
         const pending = Math.max(0, rep.queueDepth - 1);
-        return (`⚠️ ComfyUI queue backlog: ${rep.queueDepth} tasks in flight (1 running + ${pending} pending). ` +
-            `You likely queued behind a slow/stuck job. Check get_queue; use cancel_job with clear_pending:true to ` +
-            `reset before re-queuing rather than stacking another run.`);
+        return (`ℹ️ ComfyUI queue: ${rep.queueDepth} tasks in flight (1 running + ${pending} pending) that this session ` +
+            `didn't queue. This is only a problem if the running one is stuck — inspect with get_queue. ` +
+            `cancel_queued_job drops a single pending item; cancel_job with clear_pending:true resets everything.`);
     }
     return null;
 }
@@ -1244,7 +1249,20 @@ export async function runPanelOrchestrator() {
     // race) can label itself correctly instead of showing the pre-init default.
     const resolvedModelByTab = new Map();
     const headlessTabs = new Set(); // tabs with no ComfyUI canvas (mobile/remote) — deliver renders in-turn
+    // #570: for an UNSAVED workflow the panel tab id is an ephemeral tmp:<uuid>,
+    // regenerated on every reload, so the tab-keyed session store can't survive an
+    // orchestrator restart that also reloads the panel. Map each such tab to a STABLE
+    // resume key (origin + title + backend) computed at hello, so onSession can also
+    // persist under it and a reloaded tab can resume it. tmp: tabs only.
+    const tabStableKey = new Map();
     const workflowTargets = new WorkflowTargetStore();
+    // Monotonic per-tab sequence for set_workflow_target events. A pinned target is
+    // validated asynchronously (resolvePinTarget queries workflow_list), so a later event
+    // (another pin, or a synchronous mode:"current") can arrive before the async pin
+    // commits. Each event bumps the tab's sequence; a pinned resolution only commits/acks if
+    // its captured sequence is still the latest — otherwise a stale pin would clobber the
+    // user's newer selection (codex race).
+    const workflowTargetSeq = new Map();
     const backendForTab = (panelTabId) => tabBackends.get(panelTabId) ?? defaultBackend;
     const agentKeyFor = (panelTabId) => panelTabId + AGENT_KEY_SEP + backendForTab(panelTabId);
     // A panel tab id never contains "::"; backend names never do — so split on the
@@ -1687,6 +1705,10 @@ export async function runPanelOrchestrator() {
                 COMFYUI_URL: comfyuiUrl,
                 // Where download_model writes live progress for the panel tray.
                 COMFYUI_MCP_PROGRESS_DIR: progressDir,
+                // Self-scope this tab's downloads so the orchestrator can wake EXACTLY
+                // this tab's agent when a download settles (#547) — the child stamps its
+                // own COMFYUI_MCP_TAB into each progress row, mirroring COMFYUI_MCP_BLIND.
+                ...(panelTab ? { COMFYUI_MCP_TAB: panelTab } : {}),
                 // Local mode → enables download_model, apply_manifest (installer packs),
                 // and model scans so the agent installs the right way instead of curl.
                 ...(comfyuiPath ? { COMFYUI_PATH: comfyuiPath } : forceRemoteEnv()),
@@ -1733,6 +1755,12 @@ export async function runPanelOrchestrator() {
         // Report the SDK session id so the panel can persist it and resume on reload.
         onSession: (key, sessionId, model) => {
             const panelTab = panelTabOf(key);
+            // #570: also persist under the tab's STABLE resume key (unsaved workflows),
+            // so a panel reload that regenerates the tmp:<uuid> can still resume this
+            // conversation. The manager already persisted under the exact tab key.
+            const skey = tabStableKey.get(panelTab);
+            if (skey)
+                sessionStore.setStable(skey, sessionId, panelTab);
             bridge.push({ type: "session", session_id: sessionId }, panelTab);
             bridge.broadcastTabList(); // a session started/changed → refresh mirror pickers
             // #376: the ready banner was sent at hello with the PRE-init default model.
@@ -2326,6 +2354,12 @@ export async function runPanelOrchestrator() {
                 tabBackends.delete(migratedFrom);
                 headlessTabs.delete(migratedFrom);
                 workflowTargets.clear(migratedFrom);
+                // Invalidate any in-flight set_workflow_target(pinned) resolution captured under
+                // the retired id: dropping its sequence makes isCurrent() false, so a late async
+                // pin can no longer write a stale target / emit a late ack that the bridge's
+                // migration map would deliver to the new tab (codex race, tab-id migration edge).
+                workflowTargetSeq.delete(migratedFrom);
+                tabStableKey.delete(migratedFrom); // recomputed for the new id below (#570)
             }
             // Blind content mode rides the hello (issue #90) so the FIRST agent spawn
             // already carries the right tool-server env. A CHANGE against a live
@@ -2371,6 +2405,53 @@ export async function runPanelOrchestrator() {
             const resume = typeof event.resume === "string" ? event.resume : undefined;
             if (resume && (!prev || prev === backend))
                 manager.setResume(key, resume);
+            // #570: an UNSAVED workflow's tab id is an ephemeral tmp:<uuid>, regenerated
+            // on every panel reload — so on an orchestrator restart that also reloads the
+            // panel, the tab returns under a never-stored id and forgets everything
+            // (neither our tab-keyed store nor the panel's tab-keyed hello.resume can hit).
+            // Anchor a STABLE resume key on what DOES survive that tab's reload — the
+            // ComfyUI origin + workflow title + backend — and seed it as a fallback.
+            // Saved workflows (wf:<path>) already key stably, so this is tmp:-only.
+            if (panelTab.startsWith("tmp:")) {
+                const origin = (typeof helloUrl === "string" && helloUrl.trim() ? helloUrl.trim() : undefined) ??
+                    bridge.tabOrigin(panelTab) ??
+                    "";
+                const title = typeof event.title === "string" ? event.title : "";
+                const skey = `tmp::${origin}::${title}::${backend}`;
+                tabStableKey.set(panelTab, skey);
+                // Seed the resume fallback ONLY when the panel supplied none and no live
+                // agent owns the key. spawn() prefers the exact-tab store hit over this
+                // pendingResume, so the precise path is never overridden — this only
+                // rescues the churned tmp: id. setResume() no-ops if a live agent exists.
+                //
+                // COLLISION GUARD: origin+title+backend is NOT unique — two unsaved tabs
+                // with the same (default) title collide. Seed only when THIS tab is the sole
+                // connected holder of the key, so a fresh sibling tab can never resume
+                // another CONCURRENTLY-live unsaved tab's conversation (the cross-tab hijack
+                // the migration path also refuses; setStable poisons a key the moment two
+                // live tabs write distinct sessions to it). When ambiguous we surface fresh —
+                // a lost resume is a mild miss; resuming the WRONG conversation is not.
+                //
+                // The SEQUENTIAL same-title case (tab A closed, a later tab B opens with the
+                // same origin+title+backend) intentionally resumes A: by the only identity
+                // that survives a reload — the workflow identity the issue itself names as the
+                // key — B *is* the same workspace. This is bounded by the GC TTL (an abandoned
+                // session ages out) and always yields to the exact-tab store and the panel's
+                // own hello.resume. A truly-unique panel per-instance id (referenced in #568/
+                // #570's thread) would let us tighten even this — a clean future upgrade.
+                if (!resume && !manager.hasLiveAgent(key) && sessionStore.get(key) === undefined) {
+                    let sameKeyTabs = 0;
+                    for (const t of bridge.tabs()) {
+                        if (tabStableKey.get(t.tab_id) === skey)
+                            sameKeyTabs += 1;
+                    }
+                    if (sameKeyTabs <= 1) {
+                        const stableSid = sessionStore.getStable(skey);
+                        if (stableSid)
+                            manager.setResume(key, stableSid);
+                    }
+                }
+            }
             // Live model list for the picker; SDK slash commands are Claude-only.
             pushModels(panelTab);
             // Truthful provider readiness (this machine runs the agents), so the
@@ -2607,10 +2688,48 @@ export async function runPanelOrchestrator() {
                 bridge.push({ type: "ack", ok: false, kind: "workflow_target", message: "path required when pinning" }, panelTab);
                 return;
             }
-            const target = workflowTargets.set(panelTab, { mode, path, filename });
-            bridge.push({ type: "ack", ok: true, kind: "workflow_target", target }, panelTab);
-            bridge.push({ type: "workflow_target", target }, panelTab);
-            logger.info(`[panel-orchestrator] tab ${panelTab.slice(0, 8)} workflow target → ${target.mode}${target.path ? ` (${target.path})` : ""}`);
+            // Every target event bumps the tab's sequence so a later selection always wins over
+            // an in-flight (async) pin resolution.
+            const seq = (workflowTargetSeq.get(panelTab) ?? 0) + 1;
+            workflowTargetSeq.set(panelTab, seq);
+            const isCurrent = () => workflowTargetSeq.get(panelTab) === seq;
+            const ackTarget = (t) => {
+                bridge.push({ type: "ack", ok: true, kind: "workflow_target", target: t }, panelTab);
+                bridge.push({ type: "workflow_target", target: t }, panelTab);
+                logger.info(`[panel-orchestrator] tab ${panelTab.slice(0, 8)} workflow target → ${t.mode}${t.path ? ` (${t.path})` : ""}`);
+            };
+            // A PINNED target must clear the SAME validation as the MCP tool
+            // (panel_set_workflow_target) — otherwise this panel-driven event path would be a
+            // bypass that re-admits #556/#571 (background pin) and #259 (not-open pin). Resolve
+            // async through the shared helper, failing at pin time before the store is written.
+            if (mode === "pinned") {
+                void (async () => {
+                    const ctx = makePanelToolCtx(bridge, panelTab, workflowTargets);
+                    const res = await resolvePinTarget(ctx, String(path), filename);
+                    // Superseded by a newer target event while we were validating — drop silently
+                    // (no write, no late ack) so the newer selection is never clobbered.
+                    if (!isCurrent())
+                        return;
+                    if (!res.ok) {
+                        bridge.push({ type: "ack", ok: false, kind: "workflow_target", message: res.error }, panelTab);
+                        return;
+                    }
+                    ackTarget(workflowTargets.set(panelTab, { mode: "pinned", path: res.pinPath, filename: res.pinFilename }));
+                })().catch((err) => {
+                    if (!isCurrent())
+                        return;
+                    bridge.push({
+                        type: "ack",
+                        ok: false,
+                        kind: "workflow_target",
+                        message: `Could not pin workflow: ${err instanceof Error ? err.message : String(err)}`,
+                    }, panelTab);
+                });
+                return;
+            }
+            // mode === "current" — no target to validate; follow the active tab. Writes
+            // synchronously and is the latest sequence, so it wins over any in-flight pin.
+            ackTarget(workflowTargets.set(panelTab, { mode, path, filename }));
             return;
         }
         // Live panel config: render-stall threshold, plus the user's agent-model
@@ -3067,6 +3186,12 @@ export async function runPanelOrchestrator() {
             // reset() is synchronous (map cleared now), so no concurrent send() can
             // spawn an agent before we report the cleared session.
             manager.reset(agentKeyFor(tabId));
+            // reset() clears the exact-tab store; the stable resume index (#570) is the
+            // manager's blind spot, so drop it here too — a deliberate NEW chat must not
+            // be resurrected by the unsaved-workflow fallback on the next reload.
+            const sk = tabStableKey.get(tabId);
+            if (sk)
+                sessionStore.clearStable(sk);
             bridge.push({ type: "session", session_id: null }, tabId);
             bridge.push({ type: "ack", ok: true, kind: "new_session" }, tabId);
             bridge.broadcastTabList(); // session cleared → mirror pickers' green dot off
@@ -3309,6 +3434,37 @@ export async function runPanelOrchestrator() {
     // a downloading row that stops updating for 60s is treated as a dead writer.
     const DOWNLOAD_LINGER_MS = 8000;
     const downloadRemoveAt = new Map();
+    // Download-completion agent events (#547). A finished render already wakes the
+    // agent (manager.injectEvent kind:"executed"); a finished DOWNLOAD had no
+    // equivalent, so a "download then use the model" task stalled until the user
+    // poked it. We observe the SAME first-terminal transition the tray-prune timer
+    // uses and inject a completion event to the tab's agent — but COALESCED: an
+    // apply_manifest that pulls many files would otherwise fire one turn per file,
+    // so completions accumulate per agent for a short window and flush as ONE event.
+    const DOWNLOAD_DONE_DEBOUNCE_MS = 1500;
+    // agentKey → { download identity → {name, terminal status} } accumulated since
+    // the last flush, plus the epoch-ms deadline (extended by each new completion)
+    // at which we emit. Keyed by download IDENTITY (row.id), not display name, so
+    // two distinct downloads sharing a filename in one batch don't overwrite each
+    // other and hide a failure (codex).
+    const downloadDonePending = new Map();
+    // Resolve which agent to wake for a settled download row: the stamped tab's
+    // agent when it's still live; else the SINGLE live agent (pre-fix/in-process
+    // rows carry no tab, AND a tab-id migration/backend change can leave the
+    // stamped tab's key no longer resolving to the live agent — codex); else none —
+    // never fan out to unrelated tabs (#547).
+    const resolveDownloadAgentKey = (row) => {
+        const tab = typeof row.tab === "string" ? row.tab.trim() : "";
+        if (tab) {
+            const key = agentKeyFor(tab);
+            if (manager.hasLiveAgent(key))
+                return key;
+            // Stamped tab's agent is gone (migration/backend switch) — fall through to
+            // the single-live-agent fallback rather than silently dropping the event.
+        }
+        const live = manager.liveKeys();
+        return live.length === 1 ? live[0] : null;
+    };
     /** Boolean URL probe with a timeout — readiness checks for pending pod connects. */
     const probeOk = async (url, timeoutMs = 8_000) => {
         const ctl = new AbortController();
@@ -3417,6 +3573,19 @@ export async function runPanelOrchestrator() {
                 const due = downloadRemoveAt.get(full);
                 if (due == null) {
                     downloadRemoveAt.set(full, now + DOWNLOAD_LINGER_MS); // start the linger
+                    // FIRST terminal observation of this download (due was unset) — the
+                    // exact once-per-download moment. Wake the tab's agent with the result
+                    // (#547), coalesced via downloadDonePending so a many-file manifest is
+                    // one turn, not N.
+                    const key = resolveDownloadAgentKey(row);
+                    if (key && manager.hasLiveAgent(key)) {
+                        const bucket = downloadDonePending.get(key) ??
+                            { downloads: new Map(), flushAt: 0 };
+                        const idKey = String(row.id ?? full);
+                        bucket.downloads.set(idKey, { name: String(row.name ?? row.id ?? "model"), status: String(status) });
+                        bucket.flushAt = now + DOWNLOAD_DONE_DEBOUNCE_MS;
+                        downloadDonePending.set(key, bucket);
+                    }
                 }
                 else if (now >= due) {
                     try {
@@ -3450,6 +3619,16 @@ export async function runPanelOrchestrator() {
             lastDownloadSnapshot = snapshot;
             bridge.push({ type: "download_progress", downloads }); // broadcast to all tabs
         }
+        // Flush any download-completion buckets whose debounce window has elapsed —
+        // ONE agent event per tab per batch of settled downloads (#547). Runs every
+        // tick (700ms) so a flush always fires shortly after the last file settles.
+        for (const [key, bucket] of [...downloadDonePending]) {
+            if (now < bucket.flushAt)
+                continue;
+            downloadDonePending.delete(key);
+            const settled = [...bucket.downloads.values()];
+            manager.injectEvent(key, { kind: "download_done", downloads: settled });
+        }
         // MCP-child control channel (#269): runpod_* tools that ran in spawned
         // agent children ask the orchestrator to retarget / watch / unwatch /
         // auto-connect here — through the SAME applyComfyuiUrl fan-out as a panel