feat(tools): add reference_images support to image generation tool

[apipoj]

What does this PR do?

Adds an optional reference_images parameter to the image_generate tool schema and dispatch pipeline, enabling plugin providers that support reference-based generation (e.g., OpenAI gpt-image-2 with reference images) to receive image paths/URLs for style or likeness guidance.

Also fixes a compatibility issue where MCP clients (notably Codex ACP) wrap all tool arguments in a single kwargs parameter, causing dispatch failures. The _normalize_tool_kwargs helper unwraps common shapes before handle_function_call.

Related Issue

No existing issue — discovered and implemented during local plugin development.

Type of Change

• ✨ New feature (non-breaking change that adds functionality)
• ✅ Tests (adding or improving test coverage)

Changes Made

• tools/image_generation_tool.py — Add reference_images parameter to tool schema, handler, and plugin dispatch. Built-in FAL path rejects reference_images with a clear error directing users to configure a compatible plugin provider.
• agent/transports/hermes_tools_mcp_server.py — Add _normalize_tool_kwargs() helper to unwrap MCP client kwargs wrapping (Codex ACP sends {"kwargs": "{\"prompt\": ...}"} or {"kwargs": {"kwargs": {...}}}).
• tests/tools/test_image_generation.py — Add 3 tests: schema exposure, plugin dispatch with reference images, FAL rejection of reference images.

How to Test

1. Run the test suite: pytest tests/tools/test_image_generation.py -v (57/57 pass)
2. Configure a plugin provider that accepts reference_images (e.g., openai-codex-ref)
3. Call image_generate with reference_images: ["/path/to/ref.jpg"] — should dispatch to the plugin
4. Without a plugin provider, calling with reference_images returns a clear error suggesting image_gen.provider configuration

Checklist

Code

• I have read the Contributing Guide
• My commit messages follow Conventional Commits (feat(tools):, etc.)
• I searched for existing PRs to make sure this is not a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I have run pytest tests/ -q and all tests pass
• I have added tests for my changes
• I have tested on my platform: macOS 15 (Sequoia)

Documentation and Housekeeping

• I have updated tool descriptions/schemas if I changed tool behavior
• N/A — no config keys added
• N/A — no architecture changes

[teknium1]

Thanks for identifying both the reference-image and Codex MCP paths.

Problems

• The image-generation part is already superseded by c02192f (#48705). Current main exposes the unified image_url / reference_image_urls contract in tools/image_generation_tool.py:1207-1228, forwards it at :1513-1550, and has routing/dispatch coverage in tests/tools/test_image_generation_image_to_image.py:145-178 and :260-316.
• The proposed _normalize_tool_kwargs() goes beyond MCP-wrapper unwrapping: its key:value parsing and raw-string-to-prompt fallback reconstruct malformed arguments for every exposed tool. That should not be merged as a model-output repair path.
• The MCP root issue needs a narrower fix: current main computes params_schema at agent/transports/hermes_tools_mcp_server.py:154-155 but does not pass it to mcp.add_tool() at :174-181. Normalizing after FastMCP dispatch does not make the MCP tool schema authoritative.

Suggested changes

• Salvage only a focused MCP fix: register the pinned MCP SDK's supported JSON-schema argument surface and add transport tests for observed wrapper payloads. Do not reintroduce the obsolete reference_images API.
• Restrict any compatibility unwrapping to validated wrapper objects/JSON; remove heuristic line parsing and raw-prompt inference.

Automated hermes-sweeper review.

[teknium1]

This normalizes after FastMCP has already exposed the callable shape, while current main computes params_schema but never passes it into mcp.add_tool(). Please fix and test schema registration at that boundary instead of adding a generic post-dispatch repair path.

[teknium1]

Do not infer prompt from arbitrary malformed tool arguments here. This handler serves every tool in EXPOSED_TOOLS, so raw-string fallback is a new model-output reconstruction path rather than validated MCP wrapper unwrapping.

[GottZ]

This was generated by AI during triage.

Summary

Two PRs address reference-image input for image generation: #25677 adds a single local-file argument directly to the built-in FAL path, while #30148 adds a multi-image plugin contract plus unrelated MCP argument normalization. The reference-image work in both is now superseded by #48705, and #30148's remaining MCP change repairs malformed arguments after dispatch rather than registering the authoritative schema at the FastMCP boundary.

Related pull requests

• #25677 [closed] related — (+49/-1) — closed duplicate: Adds reference_image_path validation and forwards one local path as the FAL image argument, but it duplicates the established #21562 workstream and was explicitly closed after the contributor identified #18805 and related implementations; it remains relevant as an earlier direct-FAL variant.
• #30148 related — (+128/-6) — narrow before merge: Its reference_images plugin dispatch is superseded by #48705's unified image_url / reference_image_urls contract, while _normalize_tool_kwargs() broadly reconstructs malformed arguments for every MCP tool instead of making the registered MCP schema authoritative. Consistent with the keep_open review on #30148, retain it only if rewritten as the requested focused FastMCP schema-registration fix with transport-level coverage; the current diff should not merge.

Duplicates

#25677 and the image-generation portion of #30148 substantially duplicate the same reference-image capability, which is now implemented by #48705; #30148 additionally contains a distinct MCP transport change.

Suggested consolidation

Do not merge either current diff: keep #25677 closed as a duplicate, and keep #30148 open only for a focused rewrite that removes the superseded image changes and replaces global argument repair with authoritative FastMCP schema registration plus transport-level tests. If that rewrite is not pursued, #30148 can also be closed as superseded by #48705 for its image portion and unsuitable as written for the MCP portion.

Cross-PR triage: Reviewed 2 pull requests and 0 issues in this complex. Each diff was read against this issue; Assessment working set: 15 kB of PR diffs, 4 kB of issue/PR text, 3 kB of discussion (4 comments), 0 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.