comfyui-mcp 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -6,6 +6,18 @@ All notable changes to this project are documented here. This project adheres to
 
 ## Unreleased
 
+### Fixed
+
+- **Docker build hang on rate-limited CI (e.g. Glama)** — `npm ci` in the
+  Dockerfile no longer runs the `cloudflared` postinstall, which fetches a
+  ~40 MB binary from GitHub releases over an `https.get()` call with no
+  timeout. On networks where GitHub rate-limits (or otherwise stalls)
+  unauthenticated requests, that fetch hung indefinitely and blocked image
+  builds. Install scripts are now skipped with `--ignore-scripts` and the
+  two native deps we actually need (`better-sqlite3`, `sharp`) are rebuilt
+  explicitly. The runtime tunnel helper already downloads the cloudflared
+  binary lazily on first use, so no functionality is lost.
+
 ### Added
 
 - **`get_job_status` cloud-mode coverage** — when `COMFYUI_API_KEY` is set,

package/Dockerfile

@@ -18,11 +18,22 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       python3 make g++ \
   && rm -rf /var/lib/apt/lists/*
 
-# Install against the lockfile. scripts/ is needed because our (safe) postinstall
-# runs during install; copying it first keeps the dependency layer cacheable.
+# Install against the lockfile. scripts/ is copied first so the dep layer stays
+# cacheable when only src/ changes.
+#
+# We pass --ignore-scripts to skip ALL install hooks, then explicitly rebuild
+# the native deps we actually need. Why: the optional `cloudflared` package's
+# postinstall downloads a ~40 MB binary from GitHub releases over an
+# https.get() call with no timeout. On rate-limited CI networks (notably
+# Glama's build sandbox) that request hangs indefinitely and the whole image
+# build stalls. The runtime tunnel helper in src/services/tunnel.ts already
+# downloads the binary lazily on first use, so dropping the install-time
+# fetch is safe. better-sqlite3 + sharp still need their `install` scripts
+# to fetch / build their native bindings, hence the explicit rebuild.
 COPY package.json package-lock.json ./
 COPY scripts ./scripts
-RUN npm ci
+RUN npm ci --ignore-scripts \
+  && npm rebuild better-sqlite3 sharp
 
 # Compile TypeScript -> dist/
 COPY tsconfig.json ./

package/design/embedded-agent-panel.md

@@ -103,13 +103,42 @@ A Node HTTP server on `localhost:PORT`:
 
 ## 6. Build order
 0. **v2 authoring skill** (enabler — write the extension correctly).
-1. **Tunnel helper** — port `tunnel-manager` into our server (`startQuickTunnel(port) → url`), behind a flag.
-2. **AI SDK chat endpoint** — `/api/chat` with one server-side tool (`generate_image`) end-to-end.
-3. **Sidebar skeleton** — `defineSidebarTab` + `useChat` hitting the tunnel; render stream.
+1. **Tunnel helper** — port `tunnel-manager` into our server (`startQuickTunnel(port) → url`), behind a flag. ✅ done (`src/services/tunnel.ts`).
+2. **AI SDK chat endpoint** — `/api/chat` with one server-side tool (`generate_image`) end-to-end. ✅ done (`src/experimental/{agent-poc,chat-handler}.ts`).
+3. **Sidebar skeleton** — sidebar tab + chat UI hitting the tunnel; render stream. ✅ done **as a v1 extension** (see §7).
 4. **Live edit** — one client-side tool (`set_widget_value`) applied via `WidgetHandle`; prove the loop.
 5. **Wire comfyui-mcp** as the server-side tool surface (MCP client); expand client-side graph tools.
 6. **Provider switch** (Claude/Codex/Gemini) + connection/key UX + polish into a shippable node pack.
 
+## 7. Panel implementation status — v1 now, v2 later
+
+`@comfyorg/extension-api` (the v2 package the rest of this doc assumes) is **not yet on npm** as of 2026-06 — PRs #12142–#12145 are still in review and there is no published ETA. We therefore shipped the panel against the **v1 extension API** that every existing ComfyUI extension uses today, and tagged every v1-specific call site `// TODO(v2):` for the upgrade.
+
+What lives in the repo now:
+
+- `web/extensions/comfyui-mcp-agent-panel/comfyui-mcp-agent-panel.js` — single-file drop-in extension. Vanilla DOM (no framework, no bundler). Registers via `window.app.registerExtension(...)` and mounts a sidebar tab via `app.extensionManager.registerSidebarTab({...})`.
+- `web/extensions/comfyui-mcp-agent-panel/README.md` — install + connection-config instructions; explains backend URL / bearer token settings (stored in `localStorage`).
+- `src/experimental/ui-message-stream-parser.ts` + matching vitest suite — the AI SDK UI message stream consumer (text-start/delta/end, tool-input-available, tool-output-available, finish). The panel JS inlines a byte-equivalent copy of this parser since it ships unbundled.
+
+The panel currently implements:
+
+- **Connection UX** — paste tunnel URL + bearer token, persisted under `comfyui-mcp.agent-panel.*` localStorage keys.
+- **Chat stream** — POSTs `{ messages: UIMessage[] }` to `<backendUrl>/api/chat`, parses the SSE stream, and renders streaming assistant text plus tool cards for `generate_image` (the POC server-side tool).
+- **Abort on unmount** — the panel cancels any in-flight `fetch` on `destroy()`.
+
+### Migration to v2 (when the package ships)
+
+| v1 (today) | v2 (after `@comfyorg/extension-api` is on npm) |
+|------------|-------------------------------------------------|
+| `window.app.registerExtension({ name, setup })` | `defineExtension({ name, setup() { ... } })` |
+| `app.extensionManager.registerSidebarTab({ id, title, icon, type:'custom', render, destroy })` | `defineSidebarTab({ id, title, icon, type:'custom', render, destroy })` |
+| Inlined `parseUiMessageStream` JS in the panel | Real ESM import from `src/experimental/...` once a build step enters the picture |
+| Read `window.app` at module scope | Pure `import` from `@comfyorg/extension-api`; no globals |
+
+Cross-reference for the full pattern map: `plugin/skills/comfyui-frontend-extensions/references/migrate-v1-to-v2.md`.
+
+Step 4 (live graph edits) is **deferred until v2** unless we decide it's worth writing v1-shim wrappers around `LiteGraph` directly — the v2 `WidgetHandle.setValue` path is much cleaner and the POC works end-to-end without it.
+
 ## References
 - Ungate (MIT): https://github.com/orchidfiles/ungate — clone at `~/code/ungate`.
 - `cloudflared` npm: https://www.npmjs.com/package/cloudflared

package/dist/experimental/ui-message-stream-parser.d.ts

@@ -0,0 +1,21 @@
+export interface UiMessageStreamChunk {
+    type: string;
+    [k: string]: unknown;
+}
+export interface ParseResult {
+    chunks: UiMessageStreamChunk[];
+    /** Unterminated trailing fragment; pass to the next call. */
+    remainder: string;
+    /** Whether the `[DONE]` sentinel was seen. */
+    done: boolean;
+}
+/**
+ * Parse a slice of an AI SDK UI message stream. Stateless — the caller owns
+ * the remainder buffer.
+ *
+ * Frame grammar: events are separated by `\n\n`; each event is one or more
+ * `data: <payload>` lines. The terminator is the literal `[DONE]`. We
+ * tolerate `\r\n\n` and stray blank lines.
+ */
+export declare function parseUiMessageStream(buffer: string): ParseResult;
+//# sourceMappingURL=ui-message-stream-parser.d.ts.map

package/dist/experimental/ui-message-stream-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-message-stream-parser.d.ts","sourceRoot":"","sources":["../../src/experimental/ui-message-stream-parser.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IAIb,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CA2ChE"}

package/dist/experimental/ui-message-stream-parser.js

@@ -0,0 +1,73 @@
+// ---------------------------------------------------------------------------
+// AI SDK UI Message Stream Protocol — consumer-side parser.
+//
+// `POST /api/chat` returns a Server-Sent Events stream whose every `data:`
+// frame is a JSON-encoded `UIMessageChunk` (the AI SDK v6 UI message stream
+// protocol — see `node_modules/ai/dist/index.d.ts` for the full union). The
+// terminator frame is the literal `data: [DONE]`.
+//
+// This module provides a single pure function that turns an arbitrary slice of
+// the raw text body (i.e. however much arrived in the latest `reader.read()`)
+// into:
+//   - a list of decoded chunk objects, and
+//   - a `remainder` string (an unterminated partial event) the caller must
+//     prepend to the NEXT slice before re-invoking.
+//
+// Keeping the parser pure (no state, no DOM, no fetch) makes it cheap to test
+// against canned byte streams in vitest. The exact same logic is *also*
+// inlined into the browser-side panel (web/extensions/...) because that file
+// is dropped directly into ComfyUI's `web/extensions/` directory with no
+// bundler; the two implementations are kept byte-equivalent.
+// ---------------------------------------------------------------------------
+/**
+ * Parse a slice of an AI SDK UI message stream. Stateless — the caller owns
+ * the remainder buffer.
+ *
+ * Frame grammar: events are separated by `\n\n`; each event is one or more
+ * `data: <payload>` lines. The terminator is the literal `[DONE]`. We
+ * tolerate `\r\n\n` and stray blank lines.
+ */
+export function parseUiMessageStream(buffer) {
+    const chunks = [];
+    let done = false;
+    // Normalize line endings so the split below works regardless of transport.
+    const normalized = buffer.replace(/\r\n/g, "\n");
+    // Split on the blank-line frame boundary. The trailing element is whatever
+    // is *after* the last `\n\n` — i.e. an unterminated frame in progress.
+    const parts = normalized.split("\n\n");
+    const remainder = parts.pop() ?? "";
+    for (const frame of parts) {
+        // A frame can contain multiple `data:` lines (SSE spec joins them with
+        // `\n`). In practice AI SDK emits a single line per frame, but we honor
+        // the spec to keep the parser interoperable.
+        const dataLines = [];
+        for (const line of frame.split("\n")) {
+            if (!line.startsWith("data:"))
+                continue;
+            // Strip `data:` then a single optional leading space (per SSE spec).
+            let payload = line.slice(5);
+            if (payload.startsWith(" "))
+                payload = payload.slice(1);
+            dataLines.push(payload);
+        }
+        if (dataLines.length === 0)
+            continue;
+        const payload = dataLines.join("\n");
+        if (payload === "[DONE]") {
+            done = true;
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(payload);
+            if (parsed && typeof parsed === "object" && typeof parsed.type === "string") {
+                chunks.push(parsed);
+            }
+        }
+        catch {
+            // Malformed frame — skip silently. The AI SDK never emits invalid
+            // JSON; this is just defensive for non-conforming proxies.
+        }
+    }
+    return { chunks, remainder, done };
+}
+//# sourceMappingURL=ui-message-stream-parser.js.map

package/dist/experimental/ui-message-stream-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-message-stream-parser.js","sourceRoot":"","sources":["../../src/experimental/ui-message-stream-parser.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4DAA4D;AAC5D,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,4EAA4E;AAC5E,kDAAkD;AAClD,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,QAAQ;AACR,2CAA2C;AAC3C,2EAA2E;AAC3E,oDAAoD;AACpD,EAAE;AACF,8EAA8E;AAC9E,wEAAwE;AACxE,6EAA6E;AAC7E,yEAAyE;AACzE,6DAA6D;AAC7D,8EAA8E;AAkB9E;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,IAAI,IAAI,GAAG,KAAK,CAAC;IAEjB,2EAA2E;IAC3E,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAEjD,2EAA2E;IAC3E,uEAAuE;IACvE,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;IAEpC,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,uEAAuE;QACvE,wEAAwE;QACxE,6CAA6C;QAC7C,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;gBAAE,SAAS;YACxC,qEAAqE;YACrE,IAAI,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC5B,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACxD,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACrC,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAErC,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;YACzB,IAAI,GAAG,IAAI,CAAC;YACZ,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAyB,CAAC;YAC3D,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC5E,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;YAClE,2DAA2D;QAC7D,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AACrC,CAAC"}

package/infra/cloudflare/README.md

@@ -0,0 +1,75 @@
+# Cloudflare Worker — docs proxy
+
+Worker that proxies `https://comfyui-mcp.artokun.io/docs*` to the Mintlify
+deployment at `artokun.mintlify.dev`. Bare-root requests 302 to `/docs`;
+anything else on the host returns 404 (this host is docs-only).
+
+- Worker source: `docs-proxy.js`
+- Wrangler config: `wrangler.jsonc`
+- Production URL: <https://comfyui-mcp.artokun.io/docs>
+- Mintlify origin: <https://artokun.mintlify.dev/docs>
+
+## Prerequisites (must all be true for the public URL to work)
+
+1. **DNS record** — `comfyui-mcp` AAAA/A or CNAME record exists on the
+   `artokun.io` zone in Cloudflare, **with the proxy (orange cloud) enabled**.
+   Without this record the Worker route never fires and clients get NXDOMAIN /
+   `curl: (6) Could not resolve host`.
+2. **Worker deployed** — `comfyui-mcp-docs-proxy` is deployed on the account
+   matching `account_id` in `wrangler.jsonc`.
+3. **Worker route attached** — `comfyui-mcp.artokun.io/*` on `artokun.io` zone
+   (declared in `wrangler.jsonc`, applied at deploy time).
+4. **Mintlify custom domain** — Mintlify project has
+   `comfyui-mcp.artokun.io/docs` configured so generated asset/link URLs use
+   the `/docs` prefix.
+
+## Deploy
+
+```bash
+cd infra/cloudflare
+npx wrangler deploy
+```
+
+Wrangler must be authenticated against the Cloudflare account that owns the
+`artokun.io` zone (account id `208c358f58d75a3fc684695473f431dd`). Verify with
+`wrangler whoami` — if it shows a different account, run
+`wrangler logout && wrangler login` and pick the right account in the OAuth
+flow.
+
+## Recovery: `comfyui-mcp.artokun.io` returns NXDOMAIN
+
+Symptoms:
+
+```text
+$ curl -I https://comfyui-mcp.artokun.io/docs
+curl: (6) Could not resolve host: comfyui-mcp.artokun.io
+$ dig comfyui-mcp.artokun.io @drake.ns.cloudflare.com +short   # empty
+```
+
+Cause: the DNS record for the `comfyui-mcp` subdomain has been deleted from
+the `artokun.io` zone, or its proxy was disabled and the underlying target
+is unreachable. The Worker can be deployed and the route attached, but
+without the DNS record the hostname has no IP.
+
+Fix (Cloudflare dashboard):
+
+1. Dashboard → `artokun.io` zone → **DNS → Records**.
+2. Add a record:
+   - Type: `AAAA`
+   - Name: `comfyui-mcp`
+   - IPv6 address: `100::` (RFC 6666 discard prefix — value is irrelevant
+     because the request never leaves Cloudflare; the Worker route intercepts
+     it). An `A 192.0.2.1` placeholder works equally well.
+   - **Proxy status: Proxied (orange cloud)** — this is mandatory.
+   - TTL: Auto.
+3. Save. Propagation on Cloudflare's own resolvers is near-instant.
+4. Verify:
+
+   ```bash
+   dig comfyui-mcp.artokun.io @drake.ns.cloudflare.com +short   # should now return Cloudflare IPs
+   curl -I https://comfyui-mcp.artokun.io/docs                  # HTTP/2 200
+   curl -I https://comfyui-mcp.artokun.io/                      # HTTP/2 302 → /docs
+   ```
+
+If `curl` returns 404 from a Cloudflare server, the DNS is fixed but the
+Worker route is missing — re-run `wrangler deploy`.

package/llms-install.md

@@ -0,0 +1,139 @@
+# comfyui-mcp — Install Guide for AI Agents
+
+This document tells an AI agent (Cline, Claude Code, Cursor, etc.) how to
+install and configure **comfyui-mcp** in one shot. It is a focused subset of
+the project [README](./README.md) — see that file for full documentation.
+
+## What you are installing
+
+An MCP server that lets the user's AI assistant drive
+[ComfyUI](https://github.com/comfyanonymous/ComfyUI): generate images, run and
+author workflows, manage models and custom nodes, and control the server.
+**86 MCP tools** across the categories shown in
+[docs/tools/](https://comfyui-mcp.artokun.io/docs/tools/image-generation).
+
+## Prerequisites
+
+- **Node.js ≥ 22.** Confirm with `node --version`; install via
+  [nodejs.org](https://nodejs.org/) or `nvm` if missing.
+- The package is published to npm as **`comfyui-mcp`** and runs via `npx` — no
+  global install required.
+- The server needs a ComfyUI to talk to. **Three options**, pick one with the
+  user (ask if unclear):
+
+  1. **Local ComfyUI** — the user is running ComfyUI on the same machine. The
+     server auto-detects the install path and port (8188 → 8000 fallback). No
+     extra config needed.
+  2. **Remote ComfyUI** — the user runs ComfyUI on a different host
+     (RunPod, VPS, LAN box). Pass `--comfyui-url <url>` or set
+     `COMFYUI_URL` env. When the host is non-loopback, local-FS auto-detection
+     is suppressed.
+  3. **Comfy Cloud** — the user has a [cloud.comfy.org](https://cloud.comfy.org)
+     API key. Set `COMFYUI_API_KEY` env. The server routes HTTP primitives to
+     the cloud; local-only tools throw `CLOUD_UNSUPPORTED`.
+
+## Add to the MCP client config
+
+### Claude Code / Claude Desktop (`~/.claude/settings.json`)
+
+**Local ComfyUI** (most common):
+
+```json
+{
+  "mcpServers": {
+    "comfyui": {
+      "command": "npx",
+      "args": ["-y", "comfyui-mcp"]
+    }
+  }
+}
+```
+
+**Remote ComfyUI:**
+
+```json
+{
+  "mcpServers": {
+    "comfyui": {
+      "command": "npx",
+      "args": ["-y", "comfyui-mcp", "--comfyui-url", "https://my-comfy.example.com"]
+    }
+  }
+}
+```
+
+**Comfy Cloud:**
+
+```json
+{
+  "mcpServers": {
+    "comfyui": {
+      "command": "npx",
+      "args": ["-y", "comfyui-mcp"],
+      "env": {
+        "COMFYUI_API_KEY": "<ask the user for their cloud.comfy.org key>"
+      }
+    }
+  }
+}
+```
+
+### Cline / Cursor / generic MCP
+
+Use the same `command` + `args` shape (Cline expects `command` + `args` in
+its `cline_mcp_settings.json`; Cursor expects similar in its MCP settings
+panel).
+
+## Optional environment variables
+
+Set in the `env` block above. None are required for the local-default flow.
+
+- `COMFYUI_HOST` / `COMFYUI_PORT` — override host/port (defaults: auto-detect)
+- `COMFYUI_PATH` — explicit ComfyUI install path (auto-detected on Mac / Linux
+  / Windows when unset)
+- `COMFYUI_DOWNLOAD_CACHE_DIR` — model download cache (default
+  `~/.comfyui-mcp/cache`)
+- `COMFYUI_LRU_CACHE_SIZE_GB` — cap the cache; `0` disables eviction
+- `CIVITAI_API_TOKEN`, `HUGGINGFACE_TOKEN`, `GITHUB_TOKEN` — for gated
+  downloads and higher API rate limits
+- `REGISTRY_ACCESS_TOKEN` — Comfy Registry API key for `publish_custom_node`
+- `COMFY_API_KEY` — comfy.org API key for hosted partner nodes (different
+  from `COMFYUI_API_KEY`, which is for Comfy Cloud)
+- `COMFYUI_CLOUD_URL` — override the Comfy Cloud endpoint
+  (default `https://cloud.comfy.org`)
+
+Full reference: [docs/configuration](https://comfyui-mcp.artokun.io/docs/configuration).
+
+## Verify
+
+After updating the settings file, **restart the MCP client** (Claude Code: run
+`/mcp` to reconnect; Cline: toggle the server). Then ask the assistant:
+
+> What ComfyUI tools do you have?
+
+It should list ~86 tools across generation, workflow execution/authoring,
+models, custom nodes, etc. If the user wants a quick smoke test, ask:
+
+> Generate a 1024×1024 image of a red apple on a wooden table.
+
+That exercises the `generate_image` tool end-to-end (auto-selects a local
+checkpoint or uses defaults; returns an `asset_id` you can `view_image` to
+see).
+
+## Common issues
+
+- **"ComfyUI not detected on ports 8188, 8000"** — ComfyUI isn't running. Tell
+  the user to start it (Desktop app or `python main.py`).
+- **`CLOUD_UNSUPPORTED` errors** — `COMFYUI_API_KEY` is set, so the server is
+  in cloud mode and a local-only tool was called. Either unset the key (to
+  use a local install) or stick to cloud-compatible tools.
+- **Empty model lists** — `extra_model_paths.yaml` is misconfigured. Run
+  `health_check` for a diagnostic.
+
+## License + repo
+
+- **License:** [MIT](./LICENSE)
+- **Repo:** https://github.com/artokun/comfyui-mcp
+- **npm:** https://www.npmjs.com/package/comfyui-mcp
+- **Docs:** https://comfyui-mcp.artokun.io/docs
+- **Issues:** https://github.com/artokun/comfyui-mcp/issues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comfyui-mcp",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "mcpName": "io.github.artokun/comfyui-mcp",
   "description": "MCP server for ComfyUI — workflow execution, visualization, composition, registry, and skill generation",
   "homepage": "https://comfyui-mcp.artokun.io/docs",

package/web/extensions/comfyui-mcp-agent-panel/README.md

@@ -0,0 +1,97 @@
+# comfyui-mcp Agent Panel — v1 ComfyUI extension
+
+A drop-in sidebar tab for ComfyUI that hosts a chat UI talking to the
+[experimental agent backend](../../../src/experimental/agent-poc.ts) shipped
+with `comfyui-mcp`. This is the **v1 implementation** — built against today's
+`app.registerExtension(...)` API. It will be ported to the v2
+`@comfyorg/extension-api` package the moment that ships
+(Comfy-Org PRs #12142–#12145); v1-specific call sites are tagged
+`// TODO(v2):` in the source.
+
+## Install
+
+1. Copy **`comfyui-mcp-agent-panel.js`** (single file, no dependencies) into
+   one of these locations — ComfyUI auto-loads any `.js` it finds inside them:
+   - `<ComfyUI>/web/extensions/comfyui-mcp-agent-panel.js`, or
+   - `<ComfyUI>/custom_nodes/<your-pack>/web/comfyui-mcp-agent-panel.js`.
+2. Hard-reload the ComfyUI page (`Cmd/Ctrl+Shift+R`).
+3. A new **Agent** tab (chat icon) appears in the left sidebar.
+
+The README and this directory layout exist for repo hygiene only — ComfyUI
+does **not** consume the README.
+
+## Start the backend
+
+In a separate terminal at the repo root:
+
+```bash
+COMFYUI_MCP_AGENT_POC=1 \
+  COMFYUI_MCP_AGENT_TUNNEL=1 \
+  ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY
+  npm run dev:agent-poc
+```
+
+The server prints two values you need:
+
+- `chat server listening on http://127.0.0.1:8765/api/chat` — the local URL,
+  fine if ComfyUI runs on the same machine over `http://`.
+- `public URL: https://<random>.trycloudflare.com` — required if ComfyUI is
+  served over HTTPS or on a remote host (browser mixed-content would block a
+  plain-`localhost` POST otherwise).
+- `session token: <hex>` — the bearer token.
+
+## Configure the panel
+
+Open the **Agent** tab → **Connection** section, then paste:
+
+- **Backend URL** — `https://<random>.trycloudflare.com` (or
+  `http://localhost:8765` for same-machine HTTP setups).
+- **Bearer token** — the hex string from the server stdout.
+
+Click **Save** (or just hit **Send** — the panel persists the live input
+values whenever a request is dispatched, so explicit Save is optional).
+Both values persist in `window.localStorage` under
+`comfyui-mcp.agent-panel.backendUrl` / `comfyui-mcp.agent-panel.token`.
+
+> **Backend URL forms accepted.** The panel normalizes `…/`, `…/api`, and
+> `…/api/chat` suffixes — paste whatever the server logged.
+
+> **Security:** the bearer token can spend on your provider API keys.
+> `localStorage` is per-origin readable by every script on the ComfyUI page —
+> rotate the token (restart the POC) if you suspect leakage.
+
+## What it can do (POC scope)
+
+- Stream chat replies from the configured provider (Claude / Codex / Gemini —
+  picked server-side via `src/experimental/provider-registry.ts`).
+- Surface a tool card whenever the model calls the POC `generate_image` tool;
+  the backend stubs the actual ComfyUI workflow execution and returns a
+  placeholder result.
+
+Live graph edits (`set_widget_value`, `add_node`, etc.) are **not yet** wired
+— that's step 4 in `design/embedded-agent-panel.md` and depends on either
+the v2 `extension-api` `WidgetHandle` surface or our own v1 shims around
+`LiteGraph`.
+
+## Files
+
+- `comfyui-mcp-agent-panel.js` — the entire extension (one file, no build).
+- `README.md` — this file.
+
+The SSE parser embedded in the panel JS is byte-equivalent to
+`src/experimental/ui-message-stream-parser.ts` (which has vitest coverage at
+`src/__tests__/experimental/ui-message-stream-parser.test.ts`). Keep them in
+sync if you change either.
+
+## V1 → V2 migration plan
+
+When `@comfyorg/extension-api` lands on npm:
+
+| v1 (this file) | v2 |
+|----------------|----|
+| `window.app.registerExtension({ name, setup })` | `defineExtension({ name, setup() {} })` |
+| `app.extensionManager.registerSidebarTab({ id, title, icon, type:'custom', render, destroy })` | `defineSidebarTab({ id, title, icon, type:'custom', render, destroy })` |
+| Embedded `parseUiMessageStream` JS | `import { parseUiMessageStream } from '...'` (a real bundler enters the picture) |
+
+See `plugin/skills/comfyui-frontend-extensions/references/migrate-v1-to-v2.md`
+for the full mapping.

package/web/extensions/comfyui-mcp-agent-panel/comfyui-mcp-agent-panel.js

@@ -0,0 +1,604 @@
+// =============================================================================
+// comfyui-mcp Agent Panel — v1 ComfyUI frontend extension.
+//
+// Registers a sidebar tab inside ComfyUI that hosts a chat UI talking to our
+// experimental backend (src/experimental/agent-poc.ts). Drop this single file
+// into ComfyUI's `web/extensions/` directory (or the user's
+// `ComfyUI/custom_nodes/<pack>/web/` dir) and reload the page.
+//
+// Wire format: the backend's `POST /api/chat` returns an AI SDK v6 UI Message
+// Stream (Server-Sent Events). We parse `text-start`/`text-delta`/`text-end`
+// to append streaming text, and `tool-input-available` /
+// `tool-output-available` to render a tool card.
+//
+// Settings (panel UI; persisted via window.localStorage under
+// `comfyui-mcp.agent-panel.*`):
+//   - `backendUrl`  — public URL the panel POSTs to (e.g. the cloudflared
+//                     trycloudflare.com URL or `http://localhost:8765`).
+//   - `token`       — bearer token printed on the server's stdout.
+// Both are required before the first message can be sent.
+//
+// SECURITY NOTE: localStorage is per-origin readable by any script on the
+// ComfyUI page. The bearer token grants spend on the user's provider keys —
+// don't share workflow JSON containing it, and rotate it (restart the POC) if
+// you suspect leakage.
+//
+// V1→V2 MIGRATION: this file uses `window.app.registerExtension(...)` (v1) and
+// `app.extensionManager.registerSidebarTab(...)`. When the v2 npm package
+// `@comfyorg/extension-api` (PRs #12142–#12145) ships, the equivalent calls
+// are `defineExtension({ setup() { ... } })` + `defineSidebarTab({ id, title,
+// type: 'custom', icon, render, destroy })`. Every v1-specific call below is
+// marked `// TODO(v2):` — see
+// `plugin/skills/comfyui-frontend-extensions/references/migrate-v1-to-v2.md`.
+// =============================================================================
+
+// ---------------------------------------------------------------------------
+// AI SDK UI Message Stream parser. Kept byte-equivalent to the TS module at
+// `src/experimental/ui-message-stream-parser.ts` (which has vitest coverage).
+// We can't import that TS module here because this file is loaded directly
+// by ComfyUI's browser with no bundler.
+// ---------------------------------------------------------------------------
+function parseUiMessageStream(buffer) {
+  const chunks = [];
+  let done = false;
+  const normalized = buffer.replace(/\r\n/g, "\n");
+  const parts = normalized.split("\n\n");
+  const remainder = parts.pop() ?? "";
+
+  for (const frame of parts) {
+    const dataLines = [];
+    for (const line of frame.split("\n")) {
+      if (!line.startsWith("data:")) continue;
+      let payload = line.slice(5);
+      if (payload.startsWith(" ")) payload = payload.slice(1);
+      dataLines.push(payload);
+    }
+    if (dataLines.length === 0) continue;
+    const payload = dataLines.join("\n");
+    if (payload === "[DONE]") {
+      done = true;
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(payload);
+      if (parsed && typeof parsed === "object" && typeof parsed.type === "string") {
+        chunks.push(parsed);
+      }
+    } catch {
+      // ignore malformed frames
+    }
+  }
+  return { chunks, remainder, done };
+}
+
+// ---------------------------------------------------------------------------
+// localStorage-backed settings (small, sync, plenty for the POC).
+// ---------------------------------------------------------------------------
+const STORAGE_KEY_BACKEND = "comfyui-mcp.agent-panel.backendUrl";
+const STORAGE_KEY_TOKEN = "comfyui-mcp.agent-panel.token";
+
+function loadSettings() {
+  try {
+    return {
+      backendUrl: window.localStorage.getItem(STORAGE_KEY_BACKEND) ?? "",
+      token: window.localStorage.getItem(STORAGE_KEY_TOKEN) ?? "",
+    };
+  } catch {
+    return { backendUrl: "", token: "" };
+  }
+}
+
+function saveSettings(s) {
+  try {
+    window.localStorage.setItem(STORAGE_KEY_BACKEND, s.backendUrl ?? "");
+    window.localStorage.setItem(STORAGE_KEY_TOKEN, s.token ?? "");
+  } catch {
+    // localStorage may be unavailable in private/locked-down browsers; the
+    // panel just becomes session-scoped in that case.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tiny id helper for UIMessage ids. The AI SDK accepts any unique string.
+// ---------------------------------------------------------------------------
+function uid() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) return crypto.randomUUID();
+  return `m_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Build the panel DOM. Returns { root, destroy } so the host can mount/unmount.
+// ---------------------------------------------------------------------------
+function buildPanel() {
+  const root = document.createElement("div");
+  root.className = "comfyui-mcp-agent-panel";
+  root.style.cssText = `
+    display: flex; flex-direction: column; height: 100%;
+    padding: 8px; gap: 8px; box-sizing: border-box;
+    font: 13px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    color: var(--input-text, #ddd); background: var(--comfy-menu-bg, #222);
+  `;
+
+  // ---- Settings strip ------------------------------------------------------
+  const settingsBox = document.createElement("details");
+  settingsBox.style.cssText = "border: 1px solid #444; border-radius: 4px; padding: 6px;";
+  const settingsSummary = document.createElement("summary");
+  settingsSummary.textContent = "Connection";
+  settingsSummary.style.cssText = "cursor: pointer; user-select: none; font-weight: 600;";
+  settingsBox.appendChild(settingsSummary);
+
+  const settings = loadSettings();
+  settingsBox.open = !settings.backendUrl || !settings.token;
+
+  const makeRow = (labelText, type, value, placeholder) => {
+    const row = document.createElement("div");
+    row.style.cssText = "display: flex; flex-direction: column; gap: 2px; margin-top: 6px;";
+    const label = document.createElement("label");
+    label.textContent = labelText;
+    label.style.cssText = "font-size: 11px; opacity: 0.7;";
+    const input = document.createElement("input");
+    input.type = type;
+    input.value = value;
+    input.placeholder = placeholder;
+    input.style.cssText = `
+      width: 100%; padding: 4px 6px; border: 1px solid #555; border-radius: 3px;
+      background: var(--comfy-input-bg, #181818); color: inherit; box-sizing: border-box;
+    `;
+    row.append(label, input);
+    return { row, input };
+  };
+
+  const { row: urlRow, input: urlInput } = makeRow(
+    "Backend URL",
+    "url",
+    settings.backendUrl,
+    "https://<random>.trycloudflare.com",
+  );
+  const { row: tokenRow, input: tokenInput } = makeRow(
+    "Bearer token",
+    "password",
+    settings.token,
+    "from server stdout: 'session token: ...'",
+  );
+
+  const saveBtn = document.createElement("button");
+  saveBtn.type = "button";
+  saveBtn.textContent = "Save";
+  saveBtn.style.cssText =
+    "margin-top: 8px; padding: 4px 10px; cursor: pointer; align-self: flex-start;";
+  saveBtn.addEventListener("click", () => {
+    saveSettings({
+      backendUrl: urlInput.value.trim(),
+      token: tokenInput.value.trim(),
+    });
+    appendSystem("Connection saved.");
+    settingsBox.open = false;
+  });
+
+  settingsBox.append(urlRow, tokenRow, saveBtn);
+  root.appendChild(settingsBox);
+
+  // ---- Message log ---------------------------------------------------------
+  const log = document.createElement("div");
+  log.style.cssText = `
+    flex: 1 1 auto; overflow-y: auto; padding: 6px;
+    border: 1px solid #444; border-radius: 4px;
+    display: flex; flex-direction: column; gap: 6px;
+  `;
+  root.appendChild(log);
+
+  // ---- Input row -----------------------------------------------------------
+  const form = document.createElement("form");
+  form.style.cssText = "display: flex; gap: 6px;";
+  const input = document.createElement("textarea");
+  input.placeholder = "Ask the agent... (Enter to send, Shift+Enter for newline)";
+  input.rows = 2;
+  input.style.cssText = `
+    flex: 1; padding: 6px; border: 1px solid #555; border-radius: 3px;
+    background: var(--comfy-input-bg, #181818); color: inherit; resize: vertical;
+    font: inherit;
+  `;
+  const sendBtn = document.createElement("button");
+  sendBtn.type = "submit";
+  sendBtn.textContent = "Send";
+  sendBtn.style.cssText = "padding: 6px 12px; cursor: pointer;";
+  form.append(input, sendBtn);
+  root.appendChild(form);
+
+  // ---- DOM helpers ---------------------------------------------------------
+  const messages = []; // UIMessage[] for /api/chat history.
+
+  function makeBubble(role) {
+    const bubble = document.createElement("div");
+    bubble.style.cssText = `
+      padding: 6px 8px; border-radius: 4px; max-width: 95%;
+      white-space: pre-wrap; word-wrap: break-word;
+    `;
+    if (role === "user") {
+      bubble.style.background = "#2a4d6e";
+      bubble.style.alignSelf = "flex-end";
+    } else if (role === "system") {
+      bubble.style.background = "#3a3a3a";
+      bubble.style.fontStyle = "italic";
+      bubble.style.opacity = "0.8";
+      bubble.style.alignSelf = "center";
+      bubble.style.fontSize = "11px";
+    } else {
+      bubble.style.background = "#333";
+      bubble.style.alignSelf = "flex-start";
+    }
+    log.appendChild(bubble);
+    log.scrollTop = log.scrollHeight;
+    return bubble;
+  }
+
+  function appendUser(text) {
+    const bubble = makeBubble("user");
+    bubble.textContent = text;
+  }
+
+  function appendSystem(text) {
+    const bubble = makeBubble("system");
+    bubble.textContent = text;
+  }
+
+  function appendAssistantStub() {
+    const bubble = makeBubble("assistant");
+    bubble.dataset.role = "assistant";
+    return bubble;
+  }
+
+  function appendToolCard({ toolCallId, toolName, input: toolInput, output }) {
+    const card = document.createElement("div");
+    card.style.cssText = `
+      align-self: flex-start; padding: 6px 8px; border-radius: 4px;
+      background: #2c2c2c; border-left: 3px solid #6aa84f;
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px;
+      max-width: 95%; white-space: pre-wrap; word-wrap: break-word;
+    `;
+    const head = document.createElement("div");
+    head.style.cssText = "font-weight: 600; margin-bottom: 4px;";
+    head.textContent = `tool ${toolName ?? "?"} (${toolCallId.slice(0, 8)}…)`;
+    card.appendChild(head);
+    if (toolInput !== undefined) {
+      const inDiv = document.createElement("div");
+      inDiv.textContent = `input: ${safeStringify(toolInput)}`;
+      card.appendChild(inDiv);
+    }
+    if (output !== undefined) {
+      const outDiv = document.createElement("div");
+      outDiv.style.opacity = "0.85";
+      outDiv.textContent = `output: ${safeStringify(output)}`;
+      card.appendChild(outDiv);
+    }
+    log.appendChild(card);
+    log.scrollTop = log.scrollHeight;
+    return card;
+  }
+
+  function safeStringify(v) {
+    try {
+      return JSON.stringify(v);
+    } catch {
+      return String(v);
+    }
+  }
+
+  // ---- Send pipeline -------------------------------------------------------
+  let inFlight = null; // AbortController for the current request.
+
+  /** Read the live connection settings, preferring the form inputs over storage
+   *  so that a user who types into Connection and hits Send (without clicking
+   *  Save first) gets the expected behavior — and we silently persist the
+   *  values they implicitly approved by sending. */
+  function readConnection() {
+    const liveUrl = urlInput.value.trim();
+    const liveToken = tokenInput.value.trim();
+    const stored = loadSettings();
+    const backendUrl = liveUrl || stored.backendUrl;
+    const token = liveToken || stored.token;
+    if (
+      backendUrl &&
+      token &&
+      (backendUrl !== stored.backendUrl || token !== stored.token)
+    ) {
+      saveSettings({ backendUrl, token });
+    }
+    return { backendUrl, token };
+  }
+
+  /** Normalize a user-pasted backend URL into a `/api/chat` endpoint.
+   *  Accepts forms like:
+   *    https://abc.trycloudflare.com
+   *    https://abc.trycloudflare.com/
+   *    https://abc.trycloudflare.com/api
+   *    https://abc.trycloudflare.com/api/chat
+   *  and returns the canonical `<origin>/api/chat`. */
+  function toChatUrl(raw) {
+    // Strip whitespace + trailing slashes.
+    let s = raw.trim().replace(/\/+$/, "");
+    // Strip a trailing `/api/chat` or `/api` segment if the user copied either.
+    s = s.replace(/\/api\/chat$/i, "").replace(/\/api$/i, "");
+    return s + "/api/chat";
+  }
+
+  async function sendMessage(text) {
+    const { backendUrl, token } = readConnection();
+    if (!backendUrl || !token) {
+      appendSystem("Set the backend URL and bearer token in the Connection section first.");
+      settingsBox.open = true;
+      return;
+    }
+
+    const userMsg = {
+      id: uid(),
+      role: "user",
+      parts: [{ type: "text", text }],
+    };
+    messages.push(userMsg);
+    appendUser(text);
+
+    sendBtn.disabled = true;
+    input.disabled = true;
+    const assistantBubble = appendAssistantStub();
+    let assistantText = "";
+    // Track open tool calls so we can fill in their output when it arrives,
+    // AND so the assistant message we persist to history includes the
+    // dynamic-tool parts the model actually emitted (otherwise multi-turn
+    // tool conversations lose the tool context — the model can't see what
+    // it called or got back on the next turn).
+    const toolCards = new Map();
+    const toolParts = new Map(); // toolCallId -> dynamic-tool UIMessagePart
+
+    // Single chunk-dispatcher; closes over the per-request mutable state.
+    // Declared as a `const` so its binding is unambiguously available before
+    // the read loop runs (block-scoped function decls in `try` are spec-fuzzy
+    // across engines and strict mode).
+    const processChunk = (chunk) => {
+      switch (chunk.type) {
+        case "text-start":
+          // Nothing to render; bubble is already in place.
+          break;
+        case "text-delta":
+          if (typeof chunk.delta === "string") {
+            assistantText += chunk.delta;
+            assistantBubble.textContent = assistantText;
+            log.scrollTop = log.scrollHeight;
+          }
+          break;
+        case "text-end":
+          break;
+        case "tool-input-available": {
+          const id = String(chunk.toolCallId ?? uid());
+          const toolName = String(chunk.toolName ?? "");
+          const card = appendToolCard({
+            toolCallId: id,
+            toolName,
+            input: chunk.input,
+          });
+          toolCards.set(id, card);
+          // Build the assistant-message part so a follow-up turn can see
+          // this call. Mirrors the AI SDK's DynamicToolUIPart shape.
+          toolParts.set(id, {
+            type: "dynamic-tool",
+            toolName,
+            toolCallId: id,
+            state: "input-available",
+            input: chunk.input,
+          });
+          break;
+        }
+        case "tool-output-available": {
+          // The backend POC `generate_image` tool resolves server-side and
+          // the result rides this chunk. We just surface the payload in
+          // the corresponding card (or open a new one if we missed the
+          // input event for some reason). This is the "one tool-execution
+          // path end-to-end" required by the build order.
+          const id = String(chunk.toolCallId ?? uid());
+          let card = toolCards.get(id);
+          if (!card) {
+            card = appendToolCard({ toolCallId: id, toolName: "(tool)" });
+            toolCards.set(id, card);
+          }
+          const outDiv = document.createElement("div");
+          outDiv.style.opacity = "0.85";
+          outDiv.textContent = `output: ${safeStringify(chunk.output)}`;
+          card.appendChild(outDiv);
+          log.scrollTop = log.scrollHeight;
+          // Promote the persisted part to output-available so multi-turn
+          // history carries the tool result back to the model.
+          const prior = toolParts.get(id) ?? {
+            type: "dynamic-tool",
+            toolName: "(tool)",
+            toolCallId: id,
+          };
+          toolParts.set(id, {
+            ...prior,
+            state: "output-available",
+            output: chunk.output,
+          });
+          break;
+        }
+        case "tool-output-error": {
+          const id = String(chunk.toolCallId ?? uid());
+          const card = toolCards.get(id);
+          const errDiv = document.createElement("div");
+          errDiv.style.color = "#f08";
+          errDiv.textContent = `error: ${chunk.errorText ?? "tool failed"}`;
+          (card ?? appendToolCard({ toolCallId: id, toolName: "(tool)" })).appendChild(
+            errDiv,
+          );
+          const prior = toolParts.get(id) ?? {
+            type: "dynamic-tool",
+            toolName: "(tool)",
+            toolCallId: id,
+          };
+          toolParts.set(id, {
+            ...prior,
+            state: "output-error",
+            errorText: String(chunk.errorText ?? "tool failed"),
+          });
+          break;
+        }
+        case "error":
+          assistantBubble.textContent = String(chunk.errorText ?? "stream error");
+          assistantBubble.style.background = "#5a2828";
+          break;
+        case "finish":
+          // Loop exits on `[DONE]`.
+          break;
+        default:
+          // Unknown chunk types (data-*, reasoning-*, etc.) are silently
+          // ignored for the POC.
+          break;
+      }
+    };
+
+    inFlight = new AbortController();
+    try {
+      const res = await fetch(toChatUrl(backendUrl), {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ messages }),
+        signal: inFlight.signal,
+      });
+
+      if (!res.ok || !res.body) {
+        const errText = await res.text().catch(() => "");
+        assistantBubble.textContent = `Error ${res.status}: ${errText || res.statusText}`;
+        assistantBubble.style.background = "#5a2828";
+        return;
+      }
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let streamDone = false;
+
+      while (!streamDone) {
+        const { value, done } = await reader.read();
+        if (done) {
+          // Flush any pending multi-byte UTF-8 bytes the decoder is buffering
+          // (a final TCP read could split a multi-byte char in half; without
+          // this flush the trailing bytes are silently dropped).
+          buffer += decoder.decode();
+          const tail = parseUiMessageStream(buffer);
+          buffer = tail.remainder;
+          if (tail.done) streamDone = true;
+          for (const chunk of tail.chunks) processChunk(chunk);
+          break;
+        }
+        buffer += decoder.decode(value, { stream: true });
+        const result = parseUiMessageStream(buffer);
+        buffer = result.remainder;
+        if (result.done) streamDone = true;
+
+        for (const chunk of result.chunks) processChunk(chunk);
+      }
+
+      // Persist the assistant message so subsequent turns include it. We
+      // record any tool parts FIRST (matching the AI SDK's typical part
+      // order — tool invocations precede the final text summary) and only
+      // emit a message if the model produced any content this turn.
+      const parts = [];
+      for (const part of toolParts.values()) parts.push(part);
+      if (assistantText) parts.push({ type: "text", text: assistantText });
+      if (parts.length > 0) {
+        messages.push({ id: uid(), role: "assistant", parts });
+      }
+    } catch (err) {
+      if (err && err.name === "AbortError") {
+        assistantBubble.textContent += "\n[aborted]";
+      } else {
+        const msg = err && err.message ? err.message : String(err);
+        assistantBubble.textContent = `Request failed: ${msg}`;
+        assistantBubble.style.background = "#5a2828";
+      }
+    } finally {
+      inFlight = null;
+      sendBtn.disabled = false;
+      input.disabled = false;
+      input.focus();
+    }
+  }
+
+  form.addEventListener("submit", (ev) => {
+    ev.preventDefault();
+    const text = input.value.trim();
+    if (!text || inFlight) return;
+    input.value = "";
+    void sendMessage(text);
+  });
+
+  input.addEventListener("keydown", (ev) => {
+    // Enter sends; Shift+Enter inserts a newline.
+    if (ev.key === "Enter" && !ev.shiftKey) {
+      ev.preventDefault();
+      form.requestSubmit();
+    }
+  });
+
+  return {
+    root,
+    destroy() {
+      try {
+        inFlight?.abort();
+      } catch {}
+      root.remove();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// v1 registration. We reach for `window.app` lazily — at module-eval time
+// `app` may not yet be on `window`, but `registerExtension` itself queues.
+// ---------------------------------------------------------------------------
+const app = window.app ?? globalThis.app;
+if (!app || typeof app.registerExtension !== "function") {
+  console.error(
+    "[comfyui-mcp] window.app.registerExtension is unavailable. " +
+      "This extension targets the v1 ComfyUI frontend API.",
+  );
+} else {
+  // TODO(v2): replace with `defineExtension({ name, setup() {...} })`.
+  app.registerExtension({
+    name: "comfyui-mcp.agent-panel",
+    async setup() {
+      const tabId = "comfyui-mcp.agent";
+      let mounted = null; // { root, destroy }
+
+      const tabSpec = {
+        id: tabId,
+        title: "Agent",
+        // ComfyUI ships PrimeIcons; `pi-comments` is the closest "chat" glyph.
+        icon: "pi pi-comments",
+        tooltip: "comfyui-mcp Agent",
+        type: "custom",
+        render: (container) => {
+          if (mounted) mounted.destroy();
+          mounted = buildPanel();
+          container.appendChild(mounted.root);
+        },
+        destroy: () => {
+          mounted?.destroy();
+          mounted = null;
+        },
+      };
+
+      // TODO(v2): replace with `defineSidebarTab({ id, title, type: 'custom',
+      // icon, render, destroy })` imported from '@comfyorg/extension-api'.
+      const mgr = app.extensionManager;
+      if (mgr && typeof mgr.registerSidebarTab === "function") {
+        mgr.registerSidebarTab(tabSpec);
+      } else {
+        console.error(
+          "[comfyui-mcp] app.extensionManager.registerSidebarTab is unavailable; " +
+            "the agent panel cannot mount. Update ComfyUI to a version that exposes the extension manager.",
+        );
+      }
+    },
+  });
+}