fix: forward reference images through Codex and native FAL image generation

[jplew]

What does this PR do?

Adds end-to-end reference_images forwarding for both major Hermes image-generation paths covered by this branch:

1. Plugin-backed Codex / GPT Image
2. Native FAL image generation

Before this change, Hermes could accept reference_images at the tool layer, but backend handling was incomplete:

• the Codex/plugin path needed explicit forwarding and image-input shaping
• the native FAL path dropped refs and stayed on prompt-only generation

After this change:

• reference_images are accepted by image_generate
• plugin-backed Codex can forward refs into the image-editing request path
• native FAL normalizes refs into FAL-compatible image_urls
• native FAL switches to edit endpoints when refs are present
• invalid/unsupported ref inputs fail clearly instead of silently degrading

This was tested specifically against:

• OpenAI Codex / GPT Image 2
• FAL Nano Banana Pro
• FAL Nano Banana 2

Related Issue

Closes #21562

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• tools/image_generation_tool.py

  • add reference_images support to image_generate_tool(...)
  • forward reference_images from _handle_image_generate(...)
  • pass refs through plugin dispatch so plugin-backed providers can receive them
  • add _normalize_fal_reference_images(...)
  • accept remote URLs, data:image/... URLs, and local file paths
  • convert local files to data URLs for FAL submission
  • add native FAL edit routing for reference-image requests
  • switch Nano Banana models to edit endpoints when refs are present:
    • fal-ai/nano-banana-pro/edit
    • fal-ai/nano-banana-2/edit
  • add validation for invalid refs and max-reference limits

• plugins/image_gen/openai-codex/__init__.py

  • forward reference images through the Codex-backed GPT Image request path
  • shape image-edit inputs so refs are actually supplied to the backend rather than remaining prompt-only

• tests/tools/test_image_generation.py

  • add Nano Banana 2 aspect-ratio coverage
  • verify Nano Banana models do not receive unsupported image_size
  • update schema expectation to include reference_images
  • add tests for FAL reference-image normalization
  • add tests confirming edit-endpoint routing and image_urls forwarding

• tests/tools/test_image_generation_tool_reference_images.py

  • add focused tests for reference-image passthrough behavior

• tests/plugins/image_gen/test_openai_codex_provider.py

  • add/update Codex provider coverage for reference-image forwarding

How to Test

1. Run:

   python -m pytest tests/tools/test_image_generation.py tests/tools/test_image_generation_tool_reference_images.py tests/plugins/image_gen/test_openai_codex_provider.py -q

2. Configure Hermes to use either:

   • a Codex-backed GPT Image provider, or
   • a native FAL Nano Banana model

3. Submit an image-edit request with:

   • base scene as reference image 1
   • replacement face/headshot as reference image 2
   • a prompt telling Hermes to preserve the first image and only change the face

4. Confirm the backend receives real image refs and the result preserves composition while changing identity.

Runtime Verification

This branch was validated with focused tests and with live runtime verification on native FAL/Nano Banana Pro using two references.

The live Hermes session confirmed that:

• the tool call included reference_images
• the FAL-backed path succeeded
• the resulting image plausibly preserved the original scene while changing face identity

Checklist

Code

• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Ubuntu Linux

Documentation & Housekeeping

• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

[alt-glitch]

Competing PRs: #15308, #21463, and #18805 also implement reference_images forwarding for image generation. This PR adds FAL native edit-endpoint routing on top of the Codex plugin path.

[jplew]

I updated the PR to reconcile it with main's recent adoption of httpx+SSE architecture

[jplew]

fixed on another PR