---

description: "The model-facing image and video generation tool (images_generate) over ctx.comfyImagesController: how deployments mount it and what the model sees when it submits a ComfyUI workflow." kind: "package-reference"

@deepseek-ai/dsh-tool-images

English | 中文

Summary

dsh-tool-images gives the model one images_generate tool that submits a workflow from the connected ComfyUI controller's catalog and reports the files, workflow, and model it used. Choose it when an agent should produce an image or a short video without driving ComfyUI call by call: reading graphs, staging files, and polling a CLI. Each workflow's own canvas, steps, and batch are the defaults, with the caller's overrides inside fixed bounds. An unreachable server or an unavailable workflow fails with a message naming what is available. A run outlasting defaultWaitSeconds reports as still running.

Table of Contents

• Use this package
• Understand the implementation
• Model Experience
• Known Limitations and Deferred Work
• Dev Note

---

Use this package

Load the package where the tool registry and the ComfyUI controller are both mounted; it adds images_generate to the model's toolset.

When to choose it

Choose this package when the model should create media rather than read it. The tool submits through the same controller the Images panel uses, so the catalog the model chooses from is the catalog the panel displays, and a workflow added to the server is available to both without further configuration.

Minimal configuration

- name: '@deepseek-ai/dsh-tools'
- name: '@deepseek-ai/dsh-api-comfyui-controller'
- name: '@deepseek-ai/dsh-tool-images'

Field	Default	Meaning
defaultWaitSeconds	120	How long a submission waits for its render before reporting it as still running
maxWaitSeconds	600	Upper bound on a caller's wait_seconds argument
inheritedTools	Unrestricted	Optional allowlist of other providers' tools, including session-local tools. This plugin's media tools remain available. Follows provider installation and removal. Missing optional providers contribute no tool. Excluded tools are hidden and cannot execute in this scope.
chatImageEdits	false	Shadow an installed edit_image with prompt, optional exact source_attachment_id or ordered source_attachment_ids, and optional configured workflow. Prompt-only edits use the latest user attachments, otherwise the newest conversation image, including generated results. Omit workflow for the provider's automatic compatible selection. Canvas and filesystem selectors are unavailable in this scope; other agents retain the original tool.
referenceSearch	false	Add public image reference search and import; requires web and attachments services.
referenceSearchResults	6	Maximum source pages and returned image candidates, from 1 to 20.
referenceTimeoutMs	20000	Per-request reference search and download deadline.
referencePageBytes	1000000	Maximum source-page or Commons response bytes.
referenceCommonsEndpoint	https://commons.wikimedia.org/w/api.php	Public MediaWiki image search endpoint.
referenceCommonsFallback	true	Search Commons if configured web search yields no page previews.

The tool requires the tools and comfyImagesController services, so a composition that omits either leaves the row pending rather than registering a tool that cannot run.

Using images_generate

Call it with a prompt and, when a particular style or capability is wanted, the workflow id from the catalog.

images_generate({ prompt: 'a hedgehog in a tiny party hat, early digital camera flash', workflow: 'saved:Klein.json' })

size, steps, seed, and batch override the chosen workflow's own settings; wait_seconds bounds how long the call waits. Width and height must be 64 to 4096, steps 1 to 150, and batch 1 to 8.

Failures and recovery

With referenceSearch, content_search_images uses configured web search to discover source-page OpenGraph or Twitter previews. It is not a dedicated image-search engine. Commons can be selected explicitly and provides a public fallback; its results may not contain an exact fictional costume or brand asset. content_import_reference downloads a selected PNG, JPEG, WebP or GIF through anonymous, bounded public HTTP transport, validates it through the attachment store, and returns visible pixels, an exact attachment ID and the source page. External text and images are reference material, not instructions. Imports send no browser cookies; oversized images and non-public destinations fail. For multi-reference edits, supply the customer photo first and the imported reference next; the image provider must support the ordered references or reject the request.

An unreachable server fails naming its address. An unknown or unavailable workflow fails listing the ids that are available, so the model can retry with a real one. A render that has not finished when the wait expires returns status: 'running' with the prompt id, and its result appears in the conversation's history when it completes.

---

Understand the implementation

Video-only mode (videoOnly: true) registers content_video_workflows, content_generate_video, content_video_status and content_assemble_video alongside the profile image provider. Creation accepts an available saved video workflow, stages one conversation image when requested, and returns actual output URLs or a running prompt ID. Poll status instead of resubmitting. duration_seconds and frame_rate override supported scene timing; segments_json supplies Director prompt segments. Without timing overrides, the saved graph's duration and frame rate apply.

With production: true, content_project reads and saves conversation-scoped briefs and ordered storyboards. Each save requires the latest revision number and creates an immutable revision; concurrent saves cannot overwrite each other. projectDirectory defaults to .arya/content-projects under the user's home directory; maxProjectBytes defaults to 65536 bytes per complete revision. A project stores scene prompts, durations, workflow selections, references and actual generation receipts. Reading an earlier revision permits restoring it through a new save; saving a storyboard does not generate its scenes.

content_assemble_video combines exact retained output references in the requested order, with optional trims, crossfades and selectable captions. It returns the finished film URL only after encoding succeeds. Configure the controller's local FFmpeg support before using assembly. Existing generated clips remain unchanged; uploaded video staging, automatic video understanding, narration synthesis and soundtrack replacement are not provided.

Implementation internals — click to expand

Design philosophy

• The catalog is the contract. The tool chooses from the entries the controller reports and takes each workflow's own settings as the defaults, and with no workflow named prefers the deployment's built-in standard before any saved graph, so adding or retiring a workflow on the server changes what the model can ask for without a code change.
• The result names what happened. Every reply carries the workflow label and the model label actually used, because a rendered image is not evidence of which model made it.
• The controller owns submission. Argument validation, graph conversion, HTTP, history projection, and cancellation stay in the service; this package builds a request and reads the outcome.

Source map

File	Role
src/index.ts	Plugin entry: config schema, catalog-driven workflow choice, request building, polling, tool registration

---

Model Experience

Tool definition

What the model sees

The images_generate schema — prompt required, plus optional workflow, negative_prompt, size, steps, seed, batch, and wait_seconds — and its description, which states that a workflow id comes from the Images catalog and that a reference edit or an image-to-video request is not accepted.

Token effect

A fixed schema cost per request while the tool is registered.

KV Cache effect

Prefix-stable while the definition is unchanged; a plugin lifecycle change may invalidate reuse from the first changed token.

Completed run

What the model sees

status, the promptId, the workflow label, the model label, and the media filenames the run produced.

Token effect

Fixed fields plus one line per produced file, resent until compaction.

KV Cache effect

Append-only; the result follows the reusable request prefix.

Unfinished or failed run

What the model sees

A render that outlasts the wait reports status: 'running' with its prompt id. An unreachable server, an unknown workflow, or an out-of-bounds argument fails with a message naming the address, the available ids, or the accepted range.

Token effect

Only the retained result adds tokens.

KV Cache effect

Append-only; the result follows the reusable request prefix.

Known Limitations and Deferred Work

• No source image or source video — the tool stages neither, so a reference edit and a graph that processes a source video are refused with the reason rather than failing inside ComfyUI. Text-to-video needs no source and stays available. Reference edits and image-to-video stay in the Images panel, which supplies one.
• No result card — the tool's host render is text; a Web card derived from the result metadata is not implemented.
• Waiting is bounded by configuration — a render longer than maxWaitSeconds returns running rather than holding the call open; the caller must read the conversation history for the finished file.
• Recorded storyboard behavior — snapshots/session/content-project replays the production tool through the shipped headless profile without a model or renderer. ComfyUI submission, polling, reference staging and film assembly have owning tool, Loader and real encoder tests; GPU rendering requires downloaded models.

Dev Note

Working context for maintainers — click to expand

This Dev Note is working context for maintainers and is explicitly non-authoritative.

Future: a reference argument

A reference argument that stages a workspace image into ComfyUI's input directory would let the model reach the edit and image-to-video workflows the catalog already reports. It needs the staging step the controller does not yet expose, so it stays out of this version.