comfyui-mcp 0.52.2 → 0.52.3

package/dist/orchestrator/panel-tools.js

@@ -543,6 +543,11 @@ export const __panelToolsTestHooks = {
     setDeclineProbeTiming(timing) {
         declineProbeTimingOverride = timing;
     },
+    /** Inject a fake #1249 server-side /free so the frozen-tab settle can be
+     *  driven without real HTTP. null restores the live freeVramDirect. */
+    setFreeVramDirect(fn) {
+        freeVramDirectOverride = fn;
+    },
     /** Direct access to the #742 decline recheck loop so its hard-deadline
      *  guarantee (codex gate r2) can be unit-tested with a custom deadline. */
     probeDeclineRecovery,
@@ -1904,6 +1909,167 @@ async function settleExitSubgraphAfterAckTimeout(ctx, timedOut) {
     }
     return timedOut;
 }
+// ---- panel_free_vram: verifiable when the canvas tab is frozen (#1249) -----
+// `free_vram` is a purely SERVER-SIDE operation — the panel's handler is a plain
+// `POST /free` against the ComfyUI the tab fronts — yet the tool treated the
+// frozen tab's ACK as the only source of truth: a reply timeout left the caller
+// with "MUTATES … may have been applied" and no way to verify recovery. The
+// settle below takes the path the tab was only proxying: when the tab PROVABLY
+// fronts the orchestrator's local boot instance (the captureRebootHealthBase
+// gate — loopback, server-trusted, handshake-origin-matched), issue /free
+// DIRECTLY and read /system_stats around it.
+//
+// Why re-issuing is safe HERE and nowhere else on the timeout path: /free is
+// IDEMPOTENT. Unloading already-unloaded models and freeing an already-empty
+// cache is a no-op, so the copy the frozen tab may still execute when it wakes
+// cannot double-apply — the exact hazard the bridge's "do not blind-retry"
+// disclosure guards against for every other mutation does not exist for this
+// one command. This is a per-command exception, argued per command; it is NOT a
+// precedent for settling other mutations this way.
+/** Per-request bound for the direct /free + /system_stats round-trips, so a
+ *  wedged server degrades to the honest outcome-unknown instead of hanging the
+ *  tool call. ComfyUI applies /free synchronously before answering, so a large
+ *  unload can take seconds — 10s matches the bound probeComfyEndpoint callers
+ *  already pay on this same server. */
+const FREE_VRAM_DIRECT_TIMEOUT_MS = 10_000;
+/** GET `${base}/system_stats` and return its device VRAM counters, or null when
+ *  the read cannot answer (unreachable, non-2xx, non-ComfyUI body). Never
+ *  throws: an unreadable stat is "no numbers", never evidence in either
+ *  direction — the POST's own status is what certifies the free. */
+async function readVramDevices(base, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.max(1, timeoutMs));
+    timer.unref?.();
+    try {
+        const res = await comfyuiFetch(`${base}/system_stats`, {
+            signal: controller.signal,
+            redirect: "manual",
+        });
+        if (res.status < 200 || res.status >= 300)
+            return null;
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            return null; // 2xx but not JSON — up, but not a /system_stats we trust
+        }
+        if (!looksLikeSystemStats(body))
+            return null;
+        const devices = body.devices;
+        if (!Array.isArray(devices))
+            return null;
+        return devices.map((d) => {
+            const dev = (d ?? {});
+            const sample = {};
+            if (typeof dev.name === "string")
+                sample.name = dev.name;
+            if (typeof dev.vram_total === "number")
+                sample.vram_total = dev.vram_total;
+            if (typeof dev.vram_free === "number")
+                sample.vram_free = dev.vram_free;
+            return sample;
+        });
+    }
+    catch {
+        return null; // unreachable/timed out — no numbers to report
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Issue ComfyUI's /free DIRECTLY against a proven-local base and read the
+ *  VRAM counters around it. Never throws — every failure is a value, so the
+ *  settle can degrade to the honest outcome-unknown instead of masking the
+ *  original timeout behind a new error. */
+async function freeVramDirect(base) {
+    const before = await readVramDevices(base, FREE_VRAM_DIRECT_TIMEOUT_MS);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FREE_VRAM_DIRECT_TIMEOUT_MS);
+    timer.unref?.();
+    try {
+        const res = await comfyuiFetch(`${base}/free`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ unload_models: true, free_memory: true }),
+            signal: controller.signal,
+            redirect: "manual",
+        });
+        if (res.status < 200 || res.status >= 300) {
+            return { ok: false, reason: `POST ${base}/free answered HTTP ${res.status}` };
+        }
+    }
+    catch (err) {
+        const msg = controller.signal.aborted
+            ? `POST ${base}/free did not answer within ${FREE_VRAM_DIRECT_TIMEOUT_MS} ms`
+            : `POST ${base}/free failed: ${err instanceof Error ? err.message : String(err)}`;
+        return { ok: false, reason: msg };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const after = await readVramDevices(base, FREE_VRAM_DIRECT_TIMEOUT_MS);
+    return { ok: true, before, after };
+}
+/** Test injection for the direct server-side /free, so the settle can be
+ *  driven without real HTTP. null restores the live path. */
+let freeVramDirectOverride = null;
+/**
+ * After an ack timeout on `free_vram`, settle the outcome against the one
+ * channel a frozen tab cannot block: the ComfyUI server itself.
+ *
+ * Returns the timeout UNTOUCHED in every case where nothing was verified —
+ * no provable local server (remote/cloud tab, ambiguous origin, untrusted
+ * socket), or a direct /free that itself failed. #1473's rule: an unknown
+ * answer claims nothing in either direction, and the bridge's original
+ * outcome-unknown disclosure is already the honest verdict there.
+ */
+async function settleFreeVramAfterAckTimeout(ctx, timedOut) {
+    // The same gate the restart certification uses: null unless the tab PROVABLY
+    // fronts THIS orchestrator's local boot instance (loopback + server-trusted +
+    // handshake-origin match). Without that proof a direct /free could aim at a
+    // DIFFERENT server than the one the tab was asked to free — reporting that as
+    // this command's success would be the wrong-target success the gate exists to
+    // prevent, which is worse than the honest unknown being fixed.
+    const base = captureRebootHealthBase(ctx);
+    if (!base)
+        return timedOut;
+    const direct = await (freeVramDirectOverride ?? freeVramDirect)(base);
+    if (!direct.ok) {
+        // The tab never answered AND the server-side path failed. The outcome stays
+        // unknown — say so, and name what was tried, without claiming either way.
+        const text = timedOut.content?.find((c) => c.type === "text")?.text ?? "";
+        return {
+            ...timedOut,
+            content: [
+                {
+                    type: "text",
+                    text: `${text}\n\nThe server-side fallback also could not reach ComfyUI's /free ` +
+                        `(${direct.reason ?? "no detail"}), so whether VRAM was freed remains UNVERIFIED — ` +
+                        `check with get_system_stats (action:"health") once the server answers.`,
+                },
+            ],
+        };
+    }
+    const statsNote = direct.before != null && direct.after != null
+        ? "vram_before/vram_after are the server's own /system_stats counters around the free."
+        : "The /system_stats read around it did not answer, so no VRAM counters are reported — the 2xx from /free is the verification, not a measured delta.";
+    return ok({
+        freed: true,
+        unload_models: true,
+        free_memory: true,
+        acknowledged: false,
+        verified: "server-side",
+        via: `POST ${base}/free`,
+        ...(direct.before != null ? { vram_before: direct.before } : {}),
+        ...(direct.after != null ? { vram_after: direct.after } : {}),
+        note: `The panel tab never acknowledged (frozen or backgrounded), so the free was issued ` +
+            `DIRECTLY to the ComfyUI server this tab provably fronts — the same /free endpoint the ` +
+            `panel would have called — and the server confirmed it. /free is idempotent: if the tab's ` +
+            `queued copy still executes when the tab wakes, it is a no-op, so nothing was applied ` +
+            `twice. ${statsNote}`,
+    });
+}
 // ---- panel_install_node: accepted-but-never-enqueued (#1129) ---------------
 // #1143 fixed the pre-queue REFUSAL (403/404 → direct clone). This is the other
 // half of the same family: legacy Manager 3.x answers the install POST with
@@ -3860,7 +4026,7 @@ NOTE: an API-format load CAN re-mint the canvas workflow instance. If your next
         `Clear it with panel_set_workflow_target({mode:"current"}), which re-derives the fence ` +
         `from the live canvas, then retry. If the next command is not refused, nothing needs doing.`);
 }
-async function rebindWorkflowFence(ctx) {
+async function rebindWorkflowFence(ctx, opts) {
     const tabAtStart = ctx.tabId;
     let before = currentWorkflowFence(ctx);
     // `before` describes the tab we are ABOUT to compare against — but ctx.call can
@@ -3952,6 +4118,13 @@ async function rebindWorkflowFence(ctx) {
     // the stamp already matched without ever having read it.
     if (before.known && before.uuid === uuid)
         return { status: "already_current", uuid, before };
+    // #1646 — a READ-ONLY probe never moves the fence: the live canvas naming a
+    // DIFFERENT workflow is reported, not adopted. Only a deliberate rebind
+    // (panel_set_workflow_target, open/new) may replace the fence — a mismatch
+    // diagnosis that re-pointed the session on its own authority routed the
+    // caller's NEXT edits onto the very canvas the refusal named as the wrong one.
+    if (opts?.adopt === false)
+        return { status: "diverged", uuid, before };
     // refreshWorkflowUuid routes through the orchestrator's validator, which
     // re-checks reachability and the uuid's shape/origin binding. A `false` here is
     // a REFUSAL, not a no-op, so it gets its own status rather than being reported
@@ -4095,6 +4268,21 @@ panelGapNote = "") {
                         `(#803).`
                     : "";
     switch (r.status) {
+        case "diverged":
+            // #1646 — produced ONLY by a read-only probe (`adopt:false`), which the
+            // mismatch diagnosis uses; the deliberate rebinds this renderer serves
+            // never pass it. Handled anyway, because an unhandled union member would
+            // silently render as `undefined` — say exactly what happened if a future
+            // caller ever routes one here.
+            return {
+                binding: "not_recovered",
+                note: ` The live canvas is a DIFFERENT workflow instance (${r.uuid}) than this session's ` +
+                    `fence, and it was deliberately NOT adopted — a diagnosis must never re-point ` +
+                    `mutation routing on its own.` +
+                    (r.before.known && r.before.uuid ? ` The fence still names ${r.before.uuid}.` : "") +
+                    `\n\nWHAT TO DO: re-open the workflow you mean with panel_open_workflow, or re-target ` +
+                    `the live canvas deliberately by calling this tool with mode:"current".`,
+            };
         case "refreshed":
             return {
                 binding: okBinding,
@@ -6152,9 +6340,16 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
             // because nothing in the refusal distinguishes "the canvas really is a different
             // workflow" from "the identity flipped for a moment while you were building".
             //
-            // The fence is NOT weakened and nothing is auto-applied. This performs the same
-            // read-only re-derivation the documented recovery performs, then says which of the
-            // two states was found. One informed retry replaces fourteen blind ones.
+            // The fence is NOT weakened, nothing is auto-applied, and — #1646 — the
+            // probe is READ-ONLY. The first version of this check re-derived the fence
+            // onto the live canvas when the two genuinely differed ("AUTO-REBIND"), so
+            // every later mutation in the caller's sequence was silently re-pointed at
+            // the very canvas the refusal had just named as the wrong one — the exact
+            // corruption the fence exists to prevent, delivered as recovery. Now the
+            // check says which of the two states it found and the fence moves ONLY on
+            // an explicit rebind: panel_set_workflow_target({mode:"current"}) or a
+            // successful open. Until then every write stays refused against the target
+            // the caller actually named. One informed retry replaces fourteen blind ones.
             //
             // Safe to recommend a retry because a fence refusal is checked BEFORE the handler
             // runs — "Nothing was applied" is structural here, not an echoed claim.
@@ -6170,33 +6365,47 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
                 const stamped = /issued for workflow instance ([0-9a-f-]{36})/i.exec(err instanceof Error ? err.message : String(err))?.[1] ?? null;
                 let verdict;
                 try {
-                    const rebind = await rebindWorkflowFence(ctx);
+                    const probe = await rebindWorkflowFence(ctx, { adopt: false });
                     verdict =
-                        rebind.status === "already_current" && stamped && rebind.uuid === stamped
-                            ? `\n\nAUTO-REBIND: ATTEMPTED, and the live canvas now reports the SAME workflow ` +
-                                `instance this command carried (${stamped}) — nothing needed repairing. The ` +
-                                `mismatch was TRANSIENT: the identity flipped and settled back, which happens ` +
-                                `while a new unsaved workflow is still materialising. RETRY THIS EXACT CALL ONCE. ` +
-                                `Nothing was applied, so a retry cannot double-apply, and re-issuing the whole ` +
-                                `build would duplicate the work that already succeeded.`
-                            : rebind.status === "already_current"
-                                ? `\n\nAUTO-REBIND: ATTEMPTED; the fence already named the live canvas ` +
-                                    `(${rebind.uuid}), so it was not the stale side. Retry once — if it refuses ` +
+                        probe.status === "already_current" && stamped && probe.uuid === stamped
+                            ? `\n\nCHECKED: the live canvas now reports the SAME workflow instance this ` +
+                                `command carried (${stamped}), so the mismatch was TRANSIENT: the identity ` +
+                                `flipped and settled back, which happens while a new unsaved workflow is still ` +
+                                `materialising. RETRY THIS EXACT CALL ONCE. Nothing was applied, so a retry ` +
+                                `cannot double-apply, and re-issuing the whole build would duplicate the work ` +
+                                `that already succeeded.`
+                            : probe.status === "already_current"
+                                ? `\n\nCHECKED: the session's fence already names the live canvas ` +
+                                    `(${probe.uuid}), so it was not the stale side. Retry once — if it refuses ` +
                                     `again with the same pair, the two identities are genuinely disagreeing and ` +
                                     `panel_open_workflow is the way to settle which one you mean.`
-                                : rebind.status === "refreshed"
-                                    ? `\n\nAUTO-REBIND: ATTEMPTED and the fence was RE-DERIVED onto the live canvas ` +
-                                        `(now ${rebind.uuid}). Retry once. If you meant the EARLIER workflow, re-select ` +
-                                        `it with panel_open_workflow first — this session now points at the live one.`
-                                    : `\n\nAUTO-REBIND: ATTEMPTED and did NOT succeed (${rebind.status}), so the fence ` +
-                                        `is unchanged and a bare retry will fail the same way. Re-select the workflow ` +
-                                        `you mean with panel_open_workflow, then retry.`;
+                                : probe.status === "diverged"
+                                    ? `\n\nCHECKED, and this session was NOT re-pointed: the live canvas is a ` +
+                                        `DIFFERENT workflow (${probe.uuid}) than the one this command was issued ` +
+                                        `for${stamped ? ` (${stamped})` : ""}. The fence is unchanged, so later ` +
+                                        `edits in this sequence keep being refused rather than landing on the ` +
+                                        `wrong canvas. WHAT TO DO: to edit the workflow you issued for, bring it ` +
+                                        `back with panel_open_workflow; to follow the live canvas instead, ` +
+                                        `re-target deliberately with panel_set_workflow_target({mode:"current"}). ` +
+                                        `Either way the move is explicit — it is never made for you off a refused ` +
+                                        `mutation.`
+                                    : probe.status === "healed_by_panel"
+                                        ? `\n\nCHECKED, and the answer CHANGED while it was being read: the panel ` +
+                                            `re-advertised its identity and this session's fence moved to the live ` +
+                                            `canvas (${probe.uuid}) — through the panel's own repair, not this ` +
+                                            `check. If you meant the EARLIER workflow, re-select it with ` +
+                                            `panel_open_workflow before any further edits; they now target the live one.`
+                                        : `\n\nCHECKED, but the live canvas could not be established ` +
+                                            `(${probe.status}), so the fence is unchanged and a bare retry will fail ` +
+                                            `the same way. Re-select the workflow you mean with panel_open_workflow, ` +
+                                            `then retry.`;
                 }
-                catch (rebindErr) {
+                catch (probeErr) {
                     // Never let the diagnosis fail the call differently than it already failed.
                     verdict =
-                        `\n\nAUTO-REBIND: ATTEMPTED and threw, so the fence state is UNKNOWN — this refusal ` +
-                            `stands on its own terms. (${rebindErr instanceof Error ? rebindErr.message : String(rebindErr)})`;
+                        `\n\nCHECKED, and the check itself threw, so the live canvas is UNKNOWN — this ` +
+                            `refusal stands on its own terms and the fence is unchanged. ` +
+                            `(${probeErr instanceof Error ? probeErr.message : String(probeErr)})`;
                 }
                 return fail(`${name} was NOT applied — nothing changed. ${raw}${verdict}`);
             }
@@ -8596,7 +8805,7 @@ export function buildPanelToolDefs() {
                     : "") +
                 `Any values in this result are the canvas's actual state.`);
         }),
-        def("panel_run", "Queue the workflow the user has OPEN — exactly like them pressing Queue Prompt (current widget values, the live graph they can see). On success it confirms the run was queued; if ComfyUI REFUSES the prompt (validation failure on either channel — per-node node_errors OR a top-level error like a missing node type) it returns a FAILURE with that rejection detail, never a false 'queued'. Pass to_node_id to RUN ONLY ONE BRANCH ('run to node'): ComfyUI renders just that output node plus everything upstream of it and SKIPS every other output branch — handy for previewing or debugging part of a big graph without rendering the whole thing. to_node_id MUST be an OUTPUT node (SaveImage, PreviewImage, SaveVideo, …) — pick the one at the END of the branch you want; nodes are tagged is_output:true in panel_query_graph's detail rows. The output node may be NESTED inside a subgraph — just pass its id (resolved in the scope you're currently viewing, then anywhere in the workflow); the tool builds the nested execution path for you. Omit it to run the whole graph. DUPLICATE FENCE (#862): if a render this session cannot account for is already in flight (after a reconnect this is usually YOUR earlier render still running — the queue record does not survive a restart), the run is REFUSED before anything is queued and the in-flight prompt is named; inspect queue (action:'list') first, or pass allow_duplicate:true only to deliberately stack behind it. Use this so the render runs on THEIR canvas and they see the result.", {
+        def("panel_run", "Queue the workflow the user has OPEN — exactly like them pressing Queue Prompt (current widget values, the live graph they can see). On success it confirms the run was queued; if ComfyUI REFUSES the prompt (validation failure on either channel — per-node node_errors OR a top-level error like a missing node type) it returns a FAILURE with that rejection detail, never a false 'queued'. Pass to_node_id to RUN ONLY ONE BRANCH ('run to node'): ComfyUI renders just that output node plus everything upstream of it and SKIPS every other output branch — handy for previewing or debugging part of a big graph without rendering the whole thing. to_node_id MUST be an OUTPUT node (SaveImage, PreviewImage, SaveVideo, …) — pick the one at the END of the branch you want; nodes are tagged is_output:true in panel_query_graph's detail rows. The output node may be NESTED inside a subgraph — just pass its id (resolved in the scope you're currently viewing, then anywhere in the workflow); the tool builds the nested execution path for you. Omit it to run the whole graph. DUPLICATE FENCE (#862): if a render this session cannot account for is already in flight (after a reconnect this is usually YOUR earlier render still running — the queue record does not survive a restart), the run is REFUSED before anything is queued and the in-flight prompt is named; inspect queue (action:'list') first, then pass allow_duplicate:true once you have decided it is fine to run behind what is there — a scoped to_node_id preview after a reconnect is the ordinary case for it, a deliberate sweep/batch the other. Use this so the render runs on THEIR canvas and they see the result.", {
             batch_count: z
                 .number()
                 .int()
@@ -8612,7 +8821,7 @@ export function buildPanelToolDefs() {
             allow_duplicate: z
                 .boolean()
                 .optional()
-                .describe("Queue even when a render this session cannot account for is already in flight (default false). When work is in flight that this session has no record of queueing — e.g. YOUR OWN earlier render still running after a reconnect, whose record does not survive the restart — panel_run REFUSES to stack a duplicate and names the in-flight prompt instead. Pass true only to deliberately queue behind it (a sweep/batch)."),
+                .describe("Queue even when a render this session cannot account for is already in flight (default false). When work is in flight that this session has no record of queueing — e.g. YOUR OWN earlier render still running after a reconnect, whose record does not survive the restart — panel_run REFUSES to stack a duplicate and names the in-flight prompt instead. Pass true once you have LOOKED at what is in flight (queue action:'list') and decided it is fine to run behind it. After a reconnect that is the ordinary case, not an exotic one: you confirmed the in-flight job is your own earlier render or the user's, and you still want the next run — a scoped to_node_id preview, the next step of the task. Deliberately stacking a sweep/batch uses the same override."),
         }, async (args, ctx) => {
             // BACKPRESSURE: the agent can't see ComfyUI's queue, so re-queuing while a
             // render is already running silently stacks behind it (this is how a stuck
@@ -8678,9 +8887,12 @@ export function buildPanelToolDefs() {
                     `no prompt id) even YOUR OWN earlier render reads as unconfirmable, and queueing now ` +
                     `would stack a DUPLICATE behind it (#862). Nothing was queued. Inspect with queue ` +
                     `(action:"list"): if the in-flight job is the render you already started, wait for it ` +
-                    `and confirm the outcome with get_history instead of re-running it. If you genuinely ` +
-                    `intend to stack another render behind it (a deliberate sweep/batch), re-call panel_run ` +
-                    `with allow_duplicate:true. If the in-flight job is actually wedged, queue ` +
+                    `and confirm the outcome with get_history instead of re-running it. Once you HAVE ` +
+                    `looked and decided it is fine to run behind what is there, re-call panel_run with ` +
+                    `allow_duplicate:true — after a reconnect that is the ORDINARY case, not an exotic ` +
+                    `one: the in-flight job is your own earlier render or the user's, and you still want ` +
+                    `the next run (a scoped to_node_id preview, the next step of the task). Deliberately ` +
+                    `stacking a sweep/batch uses the same override. If the in-flight job is actually wedged, queue ` +
                     `(action:"cancel") with clear_pending:true interrupts it AND drops everything pending.`);
             }
             const runCmd = { cmd: "graph_run", batch_count: args.batch_count, to_node_id: args.to_node_id };
@@ -11582,7 +11794,17 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
                         ".") + argvNote + (preflightNote ? ` ${preflightNote}` : ""),
             });
         }),
-        def("panel_free_vram", "Unload all loaded models and free VRAM (ComfyUI /free). Use to unwedge a stuck/OOM ComfyUI when a cancel didn't free memory — before retrying or, last resort, restarting (panel_restart_comfyui). Does NOT restart ComfyUI; it just drops resident models and frees cached memory.", {}, async (_args, ctx) => ctx.call({ cmd: "free_vram" }, 15000)),
+        def("panel_free_vram", "Unload all loaded models and free VRAM (ComfyUI /free). Use to unwedge a stuck/OOM ComfyUI when a cancel didn't free memory — before retrying or, last resort, restarting (panel_restart_comfyui). Does NOT restart ComfyUI; it just drops resident models and frees cached memory. If the panel tab is frozen and cannot acknowledge, the free is instead issued DIRECTLY to the ComfyUI server and verified there (same /free, idempotent) whenever the tab provably fronts the local server — otherwise the outcome is reported unknown rather than claimed.", {}, async (_args, ctx) => {
+            const res = await ctx.call({ cmd: "free_vram" }, 15000);
+            // #1249 — ONLY a no-reply is settled server-side. An acked executor error
+            // (the panel's own "Failed to free VRAM: …") is a reply the bridge
+            // received and relayed; it already says what failed, and re-issuing from
+            // out here would fire a second mutation behind a verdict the caller was
+            // given. A tagged reply-timeout is the one case where nothing answered.
+            if (!isReplyTimeoutResult(res))
+                return res;
+            return settleFreeVramAfterAckTimeout(ctx, res);
+        }),
         def("panel_show_media", "Display one or more images or videos directly in the panel chat. Use this whenever the user asks to SEE or SHOW a file — a disk path you composited/downloaded/generated (absolute path on the orchestrator host) OR a ComfyUI output ref ({ filename, subfolder?, type? }). Items are rendered as media cards in the agent chat area; supply optional captions. Max 8 items per call. NEVER describe an image with emoji or text placeholders — call this tool instead.", {
             items: z
                 .array(z.object({