feat(image-gen): validate image references

[BeliefanX]

Summary

• Adds a small shared helper module for validating image-reference inputs before providers upload or forward them.
• Supports http(s) URLs, valid data:image/*;base64,... URLs, and local Hermes image-cache paths with size/type checks.
• Keeps validation independent from provider edit contracts and concrete provider implementations.

Relationship

• Layer 2 of the image-edit split: shared image-reference validation/helpers.
• Logical review order: feat(image-gen): add provider edit contract #26967 → feat(image-gen): validate image references #26968 → feat(image-gen): add OpenAI Codex image edit provider #40491 → feat(image-gen): add opt-in image_edit tool #40498.
• These PRs are intentionally related but not GitHub-stacked; each targets main so CI remains independent.
• This PR stays validation-only and excludes the provider contract, concrete providers, and tool registration.

Testing

• venv/bin/python -m py_compile agent/image_reference.py tests/agent/test_image_reference.py
• venv/bin/python -m pytest tests/agent/test_image_reference.py -q -o 'addopts='
• git diff --cached --check

[BeliefanX]

Addressed review feedback in the updated stack:

• Added encoded-length precheck for data URLs before base64 decoding, so oversized inputs fail before allocation/decoding.
• Switched local path validation to use a single opened file and header-only reads for MIME sniffing instead of reading the whole file.
• Added regression tests for oversized data URLs before decode, invalid base64 after precheck, and header-only local validation.
• Kept provider/tool behavior unchanged in this PR; it remains validation-only and inherits the PR1 CI baseline fixes.

[teknium1]

Thanks for isolating the validation logic and for addressing the encoded-length and header-only-read feedback.

Problems

• agent/image_reference.py:50 is not reached by the current image-generation path. tools/image_generation_tool.py:1343-1349 only normalizes reference strings before calling provider.generate(). Current providers still load references independently: OpenAI at plugins/image_gen/openai/__init__.py:282-284, xAI at plugins/image_gen/xai/__init__.py:140-151, and OpenRouter at plugins/image_gen/openrouter/__init__.py:99-111. Therefore this PR does not yet enforce its stated validation policy.
• Integration needs to cover provider-specific contracts. For example, OpenAI currently reads any non-denied local path at plugins/image_gen/openai/__init__.py:149-155, whereas Codex has independent local/data validation at plugins/image_gen/openai-codex/__init__.py:179-237.

Suggested changes

• Wire validation through a production dispatch/provider path and add dispatch-level tests proving rejected references never reach a provider.
• Reconcile this helper with the existing unified image resolver in tools/image_source.py:89-160 rather than leaving parallel validation semantics.

Automated hermes-sweeper review.

[teknium1]

This validator is not wired into the current image-generation path: tools/image_generation_tool.py:1343-1349 only normalizes strings before dispatch, and providers still load or forward references independently. Please integrate it at a production chokepoint (with dispatch-level coverage); otherwise the cache/type/size policy has no runtime effect.

[BeliefanX]

Addressed the hermes-sweeper findings in 00a658f:

• Validation now runs in the production dispatch path before provider calls, including fail-fast handling for unknown providers, unsupported image input, invalid schemes, and provider total-image limits.
• Local/data sources reuse tools/image_source.py with a bounded remaining-byte budget; HTTPS inputs stay as normalized URLs without eager download or reference reordering.
• Provider source-count capabilities now match their actual wire limits, so excess references fail instead of being silently truncated.
• Added handler-level regressions covering provider-not-called, zero-I/O failure paths, URL preservation/order, count limits, and bounded local/data materialization.

Focused verification: 174 tests passed; all required GitHub checks are green. Ready for re-review.

[BeliefanX]

Closing this stale implementation after reviewing it against current main. The image-input safety boundary remains valuable, but any future version should be rebuilt as a minimal handler-level pre-dispatch gate that reuses the current tools.image_source resolver and current provider contracts.