feat(image-gen): add OpenAI image edit provider

[BeliefanX]

Summary

• add OpenAI image edit support to the existing OpenAI image-generation provider
• implement the provider edit contract from feat(image-gen): add provider edit contract #26967 and reuse the image-reference validation helper from feat(image-gen): validate image references #26968
• keep the change provider-scoped; no default toolset, gateway, ACP, or unrelated provider changes are included

Relationship to #26967 / #26968

This PR is intentionally stacked on the clean image-edit foundation series:

Recommended merge order: #26967 → #26968 → #26969 → #21765. Please merge this PR after #26967 and #26968; after they land, I will rebase/refresh this branch onto main so the diff only shows the OpenAI provider delta.

1. feat(image-gen): add provider edit contract #26967: provider-level edit capability contract
2. feat(image-gen): validate image references #26968: reusable image reference validation helper
3. this PR: OpenAI provider implementation for image editing

Until the earlier PRs merge, GitHub will show their commits in this PR too. The provider-only delta in this PR is limited to:

• plugins/image_gen/openai/__init__.py
• tests/plugins/image_gen/test_openai_provider.py

Implementation

• adds OpenAIImageProvider.supports_edit() -> True
• adds OpenAIImageProvider.edit(...) using client.images.edit(...)
• validates source images through agent.image_reference.validate_image_reference(...)
• supports local/cache files and data URLs as SDK file inputs
• rejects HTTP(S) source references for edit requests because the OpenAI SDK expects file-like image inputs
• supports optional mask images, multi-image input lists, size/aspect-ratio resolution, quality tier/model resolution, and local caching of returned images

Testing

• python3 -m pytest tests/plugins/image_gen/test_openai_provider.py tests/agent/test_image_gen_provider_edit_contract.py tests/agent/test_image_reference.py -q -o 'addopts='
• python3 -m py_compile plugins/image_gen/openai/__init__.py tests/plugins/image_gen/test_openai_provider.py agent/image_gen_provider.py agent/image_reference.py
• git diff --check HEAD~1..HEAD

No live OpenAI API calls used; tests mock SDK request behavior.

[BeliefanX]

Addressed review feedback in the updated stack:

• Inherited the hardened PR2 reference validation changes.
• Cleaned up edit quality-tier resolution and added OpenAI edit error-path tests for missing dependency, API error, empty response data, and empty response item.
• The HTTP(S) reference rejection before the OpenAI call is intentional and remains covered by test; this avoids silently fetching remote URLs in the provider before there is an explicit SSRF/download policy.
• resolve_aspect_ratio already clamps invalid/empty aspect values via the base contract coverage.

[BeliefanX]

Refreshed the PR branch with a small OpenAI-Codex image stream fallback fix: if the Responses SDK final-response parser raises TypeError("'NoneType' object is not iterable") after streamed image events, the provider now preserves the image already collected from the stream instead of returning an API error. Added a regression test for that path.\n\nLocal checks run:\n- pytest -q tests/plugins/image_gen/test_openai_codex_provider.py -q\n- python -m py_compile plugins/image_gen/openai-codex/__init__.py tests/plugins/image_gen/test_openai_codex_provider.py

[BeliefanX]

Updated with an additional Codex image stream fallback: if the Responses stream iterator raises TypeError after yielding an image event, the provider now preserves that streamed image; iterator TypeError before any image still fails.\n\nValidation run locally:\n- pytest tests/plugins/image_gen/test_openai_codex_provider.py -q\n- python -m py_compile plugins/image_gen/openai-codex/init.py tests/plugins/image_gen/test_openai_codex_provider.py\n- git diff --check

[BeliefanX]

Closing this cumulative OpenAI API edit-provider branch in favor of the clean provider replacement #40491. The replacement keeps the provider work isolated from the contract/validation/tool layers and targets the current OpenAI Codex image-edit path.