comfy-draftsman 0.15.0__py3-none-any.whl

comfy_draftsman/__init__.py

@@ -0,0 +1,3 @@
+"""comfy-draftsman: MCP server that drafts readable, annotated ComfyUI workflows."""
+
+__version__ = "0.15.0"

comfy_draftsman/comfy/catalog.py

@@ -0,0 +1,254 @@
+"""Compact search and summaries over ComfyUI's object_info document.
+
+object_info is multi-megabyte (combo inputs embed every model filename on the
+instance), so agents must never receive it raw. Search returns lightweight
+descriptors; node_summary returns one node's schema with giant combo lists
+truncated.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..graph import widgets as w
+
+MAX_COMBO_CHOICES = 24
+MAX_TOOLTIP_CHARS = 160  # tooltips are rarely needed to wire a node correctly
+MAX_TRIGGER_TAGS = 15
+
+# An autogrow container can declare up to 50 synthesized slot names. The names
+# are a visible arithmetic pattern ("image0".."image49"), so a few plus the
+# count and the last name convey it - listing all 50 is pure repetition.
+_AUTOGROW_NAMES_SHOWN = 6
+
+
+def metadata_digest(meta: dict[str, Any], max_tags: int = MAX_TRIGGER_TAGS) -> dict[str, Any]:
+    """Trim a safetensors __metadata__ dict to what matters for USING the model:
+    base-model/architecture keys and the top training tags by frequency (a
+    LoRA's trigger words live in ss_tag_frequency). Raw headers can be tens of
+    KB of per-image tag counts - never return them whole."""
+    out: dict[str, Any] = {}
+    for key in (
+        "ss_base_model_version",
+        "ss_sd_model_name",
+        "modelspec.architecture",
+        "modelspec.title",
+        "ss_network_module",
+        "ss_network_dim",
+        "ss_network_alpha",
+        "ss_output_name",
+        "ss_resolution",
+    ):
+        if meta.get(key):
+            out[key] = meta[key]
+    freq_raw = meta.get("ss_tag_frequency")
+    if freq_raw:
+        try:
+            data = json.loads(freq_raw) if isinstance(freq_raw, str) else freq_raw
+            counts: dict[str, int] = {}
+            for tags in data.values():  # {dataset_name: {tag: count}}
+                if isinstance(tags, dict):
+                    for tag, n in tags.items():
+                        counts[tag.strip()] = counts.get(tag.strip(), 0) + int(n)
+            top = sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))[:max_tags]
+            out["top_training_tags"] = [f"{tag} ({n})" for tag, n in top]
+        except (ValueError, TypeError, AttributeError):
+            pass
+    if not out:
+        out["note"] = (
+            "no recognizable training metadata; raw keys: "
+            + ", ".join(sorted(meta)[:20])
+        )
+    return out
+
+
+def search_nodes(
+    object_info: dict[str, Any],
+    query: str,
+    category: str | None = None,
+    limit: int = 25,
+) -> list[dict[str, Any]]:
+    """Case-insensitive substring search over class name, display name, description."""
+    q = query.lower().strip()
+    hits: list[tuple[int, dict[str, Any]]] = []
+    for class_type, schema in object_info.items():
+        cat = schema.get("category", "") or ""
+        if category and category.lower() not in cat.lower():
+            continue
+        display = schema.get("display_name", "") or ""
+        description = schema.get("description", "") or ""
+        haystacks = (class_type.lower(), display.lower(), description.lower())
+        if q:
+            if q in haystacks[0]:
+                rank = 0
+            elif q in haystacks[1]:
+                rank = 1
+            elif q in haystacks[2]:
+                rank = 2
+            else:
+                continue
+        else:
+            rank = 3
+        hits.append(
+            (
+                rank,
+                {
+                    "class_type": class_type,
+                    "display_name": display,
+                    "description": description[:120],
+                    "category": cat,
+                    "output_node": bool(schema.get("output_node")),
+                },
+            )
+        )
+    hits.sort(key=lambda pair: (pair[0], pair[1]["class_type"]))
+    return [h for _, h in hits[:limit]]
+
+
+def _sub_widget_descriptors(parent: str, option: dict[str, Any]) -> list[dict[str, Any]]:
+    """Describe the conditional sub-widgets a dynamic-combo option reveals, with
+    their dotted set_widget names (e.g. 'output.normalization')."""
+    descriptors: list[dict[str, Any]] = []
+    inputs = (option or {}).get("inputs", {}) or {}
+    for section in ("required", "optional"):
+        for name, spec in (inputs.get(section) or {}).items():
+            if not w.is_widget_input(spec):
+                continue
+            opts = spec[1] if isinstance(spec, list | tuple) and len(spec) > 1 and isinstance(spec[1], dict) else {}
+            kind = spec[0]
+            desc: dict[str, Any] = {"name": f"{parent}.{name}"}
+            if w.is_dynamic_combo(spec):
+                desc["type"] = "COMBO"
+                desc["dynamic_combo"] = True
+                desc["choices"] = [o.get("key") for o in w.dynamic_options(spec)]
+                desc["default"] = w.dynamic_default_key(spec)
+            elif isinstance(kind, list):
+                desc["type"] = "COMBO"
+                desc["choices"] = kind[:MAX_COMBO_CHOICES]
+            elif kind == "COMBO":
+                desc["type"] = "COMBO"
+                desc["choices"] = opts.get("options", [])[:MAX_COMBO_CHOICES]
+            else:
+                desc["type"] = str(kind)
+            if "default" in opts:
+                desc["default"] = opts["default"]
+            descriptors.append(desc)
+    return descriptors
+
+
+def _apply_choices(
+    entry: dict[str, Any],
+    options: list[Any],
+    choices_filter: str,
+    max_choices: int,
+) -> None:
+    """Attach a combo's choices to an input entry, filtered and capped. When the
+    list is cut, say how to see the rest (agents can't guess hidden entries)."""
+    total = len(options)
+    if choices_filter:
+        needle = choices_filter.lower()
+        options = [o for o in options if needle in str(o).lower()]
+    cap = max_choices if max_choices > 0 else MAX_COMBO_CHOICES
+    entry["choices"] = options[:cap]
+    if choices_filter:
+        entry["choices_matched"] = len(options)
+        entry["choices_total"] = total
+    if len(options) > cap:
+        entry["choices_truncated"] = len(options)
+        entry["choices_hint"] = (
+            f"showing {cap} of {len(options)}; re-call get_node_info with "
+            "choices_filter='substring' or a larger max_choices"
+        )
+
+
+def node_summary(
+    object_info: dict[str, Any],
+    class_type: str,
+    choices_filter: str = "",
+    max_choices: int = 0,
+) -> dict[str, Any]:
+    """One node's full slot schema, sized for an agent to wire it correctly.
+
+    choices_filter / max_choices control combo-choice listing: filter is a
+    case-insensitive substring over every combo input's choices; max_choices
+    raises the per-combo cap (default MAX_COMBO_CHOICES)."""
+    schema = object_info[class_type]
+    inputs = []
+    for section in ("required", "optional"):
+        for name, spec in schema.get("input", {}).get(section, {}).items():
+            entry: dict[str, Any] = {
+                "name": name,
+                "required": section == "required",
+                "widget": w.is_widget_input(spec),
+            }
+            kind = spec[0] if isinstance(spec, list | tuple) and spec else "*"
+            opts = spec[1] if isinstance(spec, list | tuple) and len(spec) > 1 and isinstance(spec[1], dict) else {}
+            if isinstance(kind, list):
+                entry["type"] = "COMBO"
+                _apply_choices(entry, kind, choices_filter, max_choices)
+            elif kind == "COMBO":
+                entry["type"] = "COMBO"
+                _apply_choices(entry, opts.get("options", []), choices_filter, max_choices)
+            elif (autogrow := w.autogrow_template(spec)) is not None:
+                # A growing socket list, not a socket. `/object_info` names only
+                # this container, so without expanding it here the real slot
+                # names are undiscoverable and `connect` has nothing to aim at -
+                # and the prefix isn't derivable from the marker ("images" ->
+                # "image0"). Names are capped like every other list this server
+                # returns; `max` is up to 50 and repeating it per node is cost
+                # for nothing once the pattern is visible.
+                item = autogrow["item_spec"]
+                entry["type"] = str(
+                    item[0] if isinstance(item, list | tuple) and item else "*"
+                )
+                names = autogrow["names"]
+                entry["autogrow"] = True
+                entry["connect_to"] = [
+                    f"{name}.{n}" for n in names[:_AUTOGROW_NAMES_SHOWN]
+                ]
+                entry["slot_count"] = len(names)
+                entry["min_connected"] = autogrow["min"]
+                entry["hint"] = (
+                    f"a growing socket list, not a socket: connect to "
+                    f"'{name}.{names[0]}'..'{name}.{names[-1]}' "
+                    f"({len(names)} slots, at least {autogrow['min']} required, "
+                    "gaps allowed) - never to "
+                    f"'{name}' itself"
+                )
+            elif w.is_dynamic_combo(spec):
+                # a V3 dynamic combo: the main value is one of the option keys,
+                # and the selected key reveals dotted sub-widgets. Surface both
+                # so the agent can set_widget them (main first, then subs).
+                entry["type"] = "COMBO"
+                entry["dynamic_combo"] = True
+                entry["choices"] = [o.get("key") for o in w.dynamic_options(spec)]
+                entry["default"] = w.dynamic_default_key(spec)
+                entry["options"] = {
+                    o.get("key"): _sub_widget_descriptors(name, o)
+                    for o in w.dynamic_options(spec)
+                }
+            else:
+                entry["type"] = str(kind)
+            for key in ("default", "min", "max", "tooltip", "control_after_generate", "step"):
+                if key in opts:
+                    entry[key] = opts[key]
+            if isinstance(entry.get("tooltip"), str) and len(entry["tooltip"]) > MAX_TOOLTIP_CHARS:
+                entry["tooltip"] = entry["tooltip"][:MAX_TOOLTIP_CHARS] + "…"
+            if entry["widget"] and w.has_control_slot(name, spec):
+                entry["control_slot"] = f"{name}__control_after_generate"
+            inputs.append(entry)
+    out_names = schema.get("output_name") or []
+    outputs = [
+        {"name": str(out_names[i]) if i < len(out_names) else str(t), "type": str(t)}
+        for i, t in enumerate(schema.get("output") or [])
+    ]
+    return {
+        "class_type": class_type,
+        "display_name": schema.get("display_name", class_type),
+        "description": (schema.get("description") or "")[:300],
+        "category": schema.get("category", ""),
+        "output_node": bool(schema.get("output_node")),
+        "inputs": inputs,
+        "outputs": outputs,
+    }

comfy_draftsman/comfy/client.py

@@ -0,0 +1,413 @@
+"""Async HTTP client for a local ComfyUI instance.
+
+Endpoint shapes verified against ComfyUI 0.27.0 (July 2026):
+- GET  /system_stats            -> {"system": {...}, "devices": [...]}
+- GET  /object_info             -> {class_type: schema, ...}  (~2.5 MB; cached here)
+- GET  /models                  -> [folder, ...]
+- GET  /models/{folder}         -> [filename, ...]
+- GET  /templates/index.json    -> [{"moduleName", "templates": [...]}, ...]
+- GET  /templates/{name}.json   -> UI-format workflow JSON (schema 0.4)
+- POST /prompt                  -> {"prompt_id", "number"} | 400 {"error", "node_errors"}
+- GET  /history/{prompt_id}     -> {prompt_id: {...}}
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import uuid
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+import websockets
+
+from ..config import Config
+
+
+class ComfyValidationError(Exception):
+    """ComfyUI rejected a prompt at validation time."""
+
+    def __init__(self, error: dict[str, Any], node_errors: dict[str, Any]):
+        self.error = error
+        self.node_errors = node_errors
+        message = error.get("message", "prompt validation failed")
+        super().__init__(f"{message}; node_errors={list(node_errors)}")
+
+
+class ComfyConnectionError(Exception):
+    """Couldn't reach the ComfyUI instance at all - down, wrong URL, or blocked.
+
+    Distinct from ComfyValidationError (reached it, prompt rejected): a raw httpx
+    ConnectError/timeout is opaque to an agent, so we turn it into an actionable
+    message naming the URL and the likely fixes."""
+
+
+class ComfyClient:
+    def __init__(self, config: Config):
+        self._config = config
+        self.base_url = config.comfyui_url
+        self.client_id = uuid.uuid4().hex
+        self._http = httpx.AsyncClient(base_url=self.base_url, timeout=config.request_timeout)
+        self._object_info: dict[str, Any] | None = None
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def _send(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """Issue a request, converting a failure-to-connect into a clear error.
+
+        Only transport-level failures (can't connect, DNS, connect timeout) become
+        ComfyConnectionError; an HTTP response - even a 4xx/5xx - is returned for
+        the caller's own raise_for_status/status handling."""
+        try:
+            return await self._http.request(method, path, **kwargs)
+        except httpx.RequestError as e:
+            raise ComfyConnectionError(
+                f"can't reach ComfyUI at {self.base_url}: {type(e).__name__}. "
+                "Is ComfyUI running and is COMFYUI_URL correct? A remote instance "
+                "must be started with --listen and reachable from this host."
+            ) from e
+
+    async def _get_json(self, path: str) -> Any:
+        response = await self._send("GET", path)
+        response.raise_for_status()
+        return response.json()
+
+    async def get_system_stats(self) -> dict[str, Any]:
+        return await self._get_json("/system_stats")
+
+    async def get_object_info(self, refresh: bool = False) -> dict[str, Any]:
+        if self._object_info is None or refresh:
+            self._object_info = await self._get_json("/object_info")
+        return self._object_info
+
+    async def list_model_folders(self) -> list[str]:
+        return await self._get_json("/models")
+
+    async def list_models(self, folder: str) -> list[str]:
+        return await self._get_json(f"/models/{quote(folder, safe='')}")
+
+    async def get_model_metadata(self, folder: str, filename: str) -> dict[str, Any]:
+        """Embedded safetensors __metadata__ via /view_metadata. ComfyUI 404s
+        for missing files, non-.safetensors, and headers without metadata."""
+        clean = filename.replace("\\", "/")
+        if clean.startswith("/") or ".." in clean.split("/"):
+            raise ValueError(f"invalid filename: {filename!r}")
+        response = await self._send(
+            "GET", f"/view_metadata/{quote(folder, safe='')}", params={"filename": filename}
+        )
+        if response.status_code == 404:
+            raise FileNotFoundError(filename)
+        response.raise_for_status()
+        return response.json()
+
+    async def get_template_index(self) -> list[dict[str, Any]]:
+        return await self._get_json("/templates/index.json")
+
+    async def get_template_workflow(self, name: str) -> dict[str, Any]:
+        clean = name.replace("\\", "/")
+        if clean.startswith("/") or ".." in clean.split("/"):
+            raise ValueError(f"invalid template name: {name!r}")
+        return await self._get_json(f"/templates/{name}.json")
+
+    async def queue_prompt(
+        self,
+        api_prompt: dict[str, Any],
+        extra_data: dict[str, Any] | None = None,
+        client_id: str | None = None,
+        front: bool = False,
+    ) -> dict[str, Any]:
+        # client_id override: non-blocking runs queue under the ProgressTracker's
+        # id so ITS socket receives the per-prompt events (ComfyUI routes them
+        # to the queuing client's socket only).
+        payload: dict[str, Any] = {"prompt": api_prompt, "client_id": client_id or self.client_id}
+        if front:
+            # run next after the current job finishes; pending jobs stay queued
+            payload["front"] = True
+        if extra_data:
+            payload["extra_data"] = extra_data
+        response = await self._send("POST", "/prompt", json=payload)
+        if response.status_code == 400:
+            body = response.json()
+            raise ComfyValidationError(body.get("error", {}), body.get("node_errors", {}))
+        response.raise_for_status()
+        return response.json()
+
+    async def get_history(self, prompt_id: str) -> dict[str, Any]:
+        history = await self._get_json(f"/history/{prompt_id}")
+        return history.get(prompt_id, {})
+
+    async def get_queue(self) -> dict[str, Any]:
+        return await self._get_json("/queue")
+
+    async def interrupt(self) -> None:
+        response = await self._send("POST", "/interrupt")
+        response.raise_for_status()
+
+    async def clear_queue(self) -> None:
+        response = await self._send("POST", "/queue", json={"clear": True})
+        response.raise_for_status()
+
+    async def delete_queue_items(self, prompt_ids: list[str]) -> None:
+        response = await self._send("POST", "/queue", json={"delete": prompt_ids})
+        response.raise_for_status()
+
+    async def free(self, unload_models: bool = False, free_memory: bool = True) -> None:
+        response = await self._send(
+            "POST", "/free", json={"unload_models": unload_models, "free_memory": free_memory}
+        )
+        response.raise_for_status()
+
+    async def upload_image(
+        self,
+        data: bytes,
+        name: str,
+        subfolder: str = "",
+        overwrite: bool = False,
+        image_type: str = "input",
+    ) -> dict[str, Any]:
+        """POST /upload/image -> {"name", "subfolder", "type"}."""
+        form: dict[str, str] = {"type": image_type, "overwrite": "true" if overwrite else "false"}
+        if subfolder:
+            form["subfolder"] = subfolder
+        response = await self._send(
+            "POST", "/upload/image", files={"image": (name, data)}, data=form
+        )
+        response.raise_for_status()
+        return response.json()
+
+    async def upload_mask(
+        self,
+        data: bytes,
+        name: str,
+        original_ref: dict[str, Any],
+        subfolder: str = "",
+        overwrite: bool = False,
+    ) -> dict[str, Any]:
+        """POST /upload/mask; original_ref names the image the mask belongs to."""
+        form: dict[str, str] = {
+            "type": "input",
+            "overwrite": "true" if overwrite else "false",
+            "original_ref": json.dumps(original_ref),
+        }
+        if subfolder:
+            form["subfolder"] = subfolder
+        response = await self._send(
+            "POST", "/upload/mask", files={"image": (name, data)}, data=form
+        )
+        response.raise_for_status()
+        return response.json()
+
+    @staticmethod
+    def _workflow_userdata_path(name: str) -> str:
+        """Relative userdata path for a workflow browser file, refusing traversal."""
+        clean = name.replace("\\", "/").strip("/")
+        if not clean or ".." in clean.split("/"):
+            raise ValueError(f"invalid workflow name: {name!r}")
+        filename = clean if clean.endswith(".json") else f"{clean}.json"
+        return f"workflows/{filename}"
+
+    async def list_userdata_workflows(self) -> list[str]:
+        """Workflow files in ComfyUI's workflow browser (userdata), incl. subdirs."""
+        response = await self._send(
+            "GET", "/api/userdata", params={"dir": "workflows", "recurse": "true", "split": "false"}
+        )
+        if response.status_code == 404:  # no workflows dir yet on a fresh instance
+            return []
+        response.raise_for_status()
+        return [p.replace("\\", "/") for p in response.json()]
+
+    async def get_userdata_workflow(self, name: str) -> dict[str, Any]:
+        """Load one workflow browser file by name (with or without .json).
+
+        Raises FileNotFoundError if it doesn't exist, ValueError on a name that
+        would escape the workflows directory.
+        """
+        path = self._workflow_userdata_path(name)
+        response = await self._send("GET", f"/api/userdata/{quote(path, safe='')}")
+        if response.status_code == 404:
+            raise FileNotFoundError(name)
+        response.raise_for_status()
+        return response.json()
+
+    async def save_userdata_workflow(
+        self, name: str, document: dict[str, Any], overwrite: bool = False
+    ) -> str:
+        """Save a UI-format workflow into ComfyUI's workflow browser (userdata API).
+
+        With overwrite=False (default) ComfyUI answers 409 if the file exists,
+        surfaced here as FileExistsError so callers can pick another name.
+        """
+        filename = name if name.endswith(".json") else f"{name}.json"
+        response = await self._send(
+            "POST",
+            f"/api/userdata/{quote(f'workflows/{filename}', safe='')}",
+            params={"overwrite": "true" if overwrite else "false"},
+            json=document,
+        )
+        if response.status_code == 409:
+            raise FileExistsError(filename)
+        response.raise_for_status()
+        return filename
+
+    #: output keys holding {filename, subfolder, type} FILE refs - the only ones
+    #: /view can fetch and _relocate_outputs can move.
+    FILE_OUTPUT_KEYS = ("images", "gifs", "videos", "audio")
+
+    #: non-file keys that carry no information for the caller: `animated` is a
+    #: per-image bool list the frontend uses to pick a player.
+    _DATA_KEYS_IGNORED = frozenset({"animated"})
+
+    # A node can return anything JSON-serializable, and some return a lot (an
+    # entire generated prompt, a batch's worth of paths). These are explicitly
+    # requested run results rather than a recurring summary, so the budget is
+    # generous - but it is still a budget.
+    _DATA_VALUE_CHARS = 1200
+    _DATA_TOTAL_CHARS = 5000
+
+    @staticmethod
+    def _collect_outputs(history: dict[str, Any]) -> list[dict[str, Any]]:
+        """FILE outputs only, flattened to relocatable {filename, subfolder, type}
+        refs. Non-file return values go through _collect_data_outputs."""
+        outputs: list[dict[str, Any]] = []
+        for node_id, node_output in (history.get("outputs") or {}).items():
+            for key in ComfyClient.FILE_OUTPUT_KEYS:
+                for item in node_output.get(key, []) or []:
+                    outputs.append({**item, "node_id": node_id, "kind": key})
+        return outputs
+
+    @classmethod
+    def _collect_data_outputs(cls, history: dict[str, Any]) -> dict[str, Any]:
+        """Every NON-file value an output node returned, keyed by node id.
+
+        Output nodes are free to return anything in their `ui` dict, and plenty
+        do: ShowText-style nodes return `text`, and save nodes commonly return the
+        paths they wrote (`filenames`, `path`, `saved_count`). Harvesting only the
+        four file keys meant those results were silently dropped - a workflow whose
+        product was a generated string, or whose save node reported where it wrote,
+        looked like it produced nothing at all.
+
+        Values are truncated per item and the whole payload is budgeted; a `note`
+        records anything cut so a short value is never mistaken for the full one.
+        """
+        collected: dict[str, Any] = {}
+        used = 0
+        truncated: list[str] = []
+        for node_id, node_output in (history.get("outputs") or {}).items():
+            if not isinstance(node_output, dict):
+                continue
+            for key, value in node_output.items():
+                if key in cls.FILE_OUTPUT_KEYS or key in cls._DATA_KEYS_IGNORED:
+                    continue
+                rendered = value if isinstance(value, str) else json.dumps(value, default=str)
+                # over-long values degrade to a clipped STRING; anything within
+                # budget keeps its original shape (list/dict/number)
+                kept: Any = value
+                if len(rendered) > cls._DATA_VALUE_CHARS:
+                    kept = rendered[: cls._DATA_VALUE_CHARS] + "…"
+                    truncated.append(f"{node_id}.{key}")
+                cost = len(kept) if isinstance(kept, str) else len(rendered)
+                if used + cost > cls._DATA_TOTAL_CHARS:
+                    truncated.append(f"{node_id}.{key} (omitted)")
+                    continue
+                used += cost
+                collected.setdefault(str(node_id), {})[key] = kept
+        if truncated:
+            collected["note"] = (
+                "clipped to keep the response bounded: " + ", ".join(truncated[:10])
+            )
+        return collected
+
+    def _ws_url(self, client_id: str | None = None) -> str:
+        scheme = "wss" if self.base_url.startswith("https") else "ws"
+        host = self.base_url.split("://", 1)[1]
+        return f"{scheme}://{host}/ws?clientId={client_id or self.client_id}"
+
+    async def run_and_wait(
+        self,
+        api_prompt: dict[str, Any],
+        timeout: float = 600.0,
+        extra_data: dict[str, Any] | None = None,
+        front: bool = False,
+    ) -> dict[str, Any]:
+        """Queue a prompt and wait for completion via the /ws event stream.
+
+        Returns {"status", "prompt_id", "outputs" (image/video/audio files from
+        history), "error"?}.
+        """
+        async with websockets.connect(self._ws_url(), max_size=32 * 1024 * 1024) as ws:
+            queued = await self.queue_prompt(api_prompt, extra_data=extra_data, front=front)
+            prompt_id = queued["prompt_id"]
+            # ComfyUI accepts a prompt (HTTP 200 + prompt_id) yet still returns
+            # node_errors for nodes it rejected at validation, executing only the
+            # rest of the graph. Capture them so a partial run isn't reported as a
+            # clean success with mysteriously-empty outputs.
+            partial_node_errors = queued.get("node_errors") or {}
+            error: dict[str, Any] | None = None
+            async with asyncio.timeout(timeout):
+                while True:
+                    frame = await ws.recv()
+                    if isinstance(frame, bytes):  # preview image frames
+                        continue
+                    event = json.loads(frame)
+                    data = event.get("data", {})
+                    if data.get("prompt_id") not in (None, prompt_id):
+                        continue
+                    kind = event.get("type")
+                    if kind == "execution_error":
+                        error = data
+                        break
+                    if kind == "execution_interrupted":
+                        error = {"exception_message": "interrupted"}
+                        break
+                    finished = kind == "execution_success" or (
+                        kind == "executing" and data.get("node") is None
+                    )
+                    if finished and data.get("prompt_id") == prompt_id:
+                        break
+        # /history can lag the execution_success event by a beat; on a clean run
+        # with no outputs yet, re-poll briefly before trusting an empty list.
+        outputs: list[dict[str, Any]] = []
+        data_outputs: dict[str, Any] = {}
+        for attempt in range(5):
+            history = await self.get_history(prompt_id)
+            outputs = self._collect_outputs(history)
+            data_outputs = self._collect_data_outputs(history)
+            if (
+                outputs
+                or data_outputs
+                or error
+                or history.get("status", {}).get("completed") is False
+            ):
+                break
+            if attempt < 4:
+                await asyncio.sleep(0.2 * (attempt + 1))
+        result: dict[str, Any] = {
+            "status": "error" if error else "success",
+            "prompt_id": prompt_id,
+            "outputs": outputs,
+        }
+        if data_outputs:
+            # non-file return values (generated text, written paths, counts) -
+            # omitted entirely when empty so the common case costs nothing
+            result["data_outputs"] = data_outputs
+        if error:
+            result["error"] = {
+                "node_id": error.get("node_id"),
+                "node_type": error.get("node_type"),
+                "message": error.get("exception_message"),
+                "type": error.get("exception_type"),
+            }
+        if partial_node_errors:
+            result["node_errors"] = partial_node_errors
+        return result
+
+    async def fetch_output(self, item: dict[str, Any]) -> bytes:
+        response = await self._send("GET", "/view", params={
+            "filename": item.get("filename", ""),
+            "subfolder": item.get("subfolder", ""),
+            "type": item.get("type", "output"),
+        })
+        response.raise_for_status()
+        return response.content