Epic: Let Gemini generate, save, and view images safely in the workspace

[aheritier]

Purpose

Reliable Gemini image/media workflows across the Gateway and direct Gemini API, with safe generated-image delivery into the workspace and a usable TUI experience.

This is an incremental Gemini-focused release, not a promise of universal multimodal parity across every provider.

User-visible workflows

• Gateway: an owner-declared image-capable model can request text + image output on the declared gateway route; SSE keepalive frames are ignored before GenAI parsing, and incompatible output-capability configuration is rejected with actionable diagnostics.
• Direct Gemini API: the same declared image-output workflow works on the direct Gemini surface. Direct Gemini API was manually validated.
• Vertex: unit-test coverage exercises the Vertex request/response and generated-media paths. Vertex live validation is deferred by owner approval for this series (it is not represented as live-provider validation).
• Generated images: streamed media deltas are materialized into the configured workspace, recorded in the session manifest, and shown inline in the TUI when the manifest authorizes resolution. Generated media is not resent as conversation history.
• Naming and paths: explicit [media-file:] response markers are supported; a single unnamed image can fall back to an explicit user-prompt filename. Names and metadata are UTF-8-safe, sanitized, bounded, and collision-safe. Workspace escapes require explicit user confirmation; failures are classified into safe, user-visible reasons.

Configuration

Image generation is opt-in and owner-declared through model output_capabilities.image. Per-model/media capability overrides control whether a requested modality is allowed. The configuration remains the authority for image-output eligibility; runtime request guards prevent incompatible Gemini requests rather than silently attempting them. Workspace media storage and lifecycle are documented, including the absolute WorkingDir provenance recorded for local creation paths.

Technical architecture and guarantees

• Shared chat/runtime media-delta handling streams generated media without coupling the TUI to provider wire formats.
• Gateway and direct transports request declared modalities and classify malformed/unsupported Gemini 400 responses into safe, actionable diagnostics.
• A workspace media writer performs atomic, collision-safe writes and cleanup; permissions, missing parents, and mid-write cleanup are covered by tests.
• A session manifest is the trust anchor for generated-media resolution. The TUI resolves only manifest-authorized paths.
• Path handling sanitizes and bounds generated metadata, preserves workspace provenance, and gates workspace escapes behind confirmation.

Compatibility limits

• This release covers the LLM Gateway and direct Gemini API workflows. Vertex is covered by unit tests only for this series; live Vertex validation is explicitly deferred with owner approval.
• Image output requires an owner-declared output_capabilities.image; models/routes without that declaration are rejected or remain text-only.
• Unsupported input audio/video modalities are not expanded by this epic and must not be silently treated as supported. Broader provider capability parity, uploads, and generalized attachment coverage remain outside this task.
• Existing non-image provider behavior and older configuration compatibility are preserved; no universal generated-media contract is implied.

Validation evidence

• Unit tests cover Gemini request shaping/diagnostics, gateway SSE keepalive handling, Vertex paths, media streaming/materialization, atomic workspace writes, naming/path safety, manifest-gated TUI resolution, and no-resend history behavior.
• Direct Gemini API image generation was manually validated.
• Vertex live validation is deferred by owner approval for this series.
• The 14 changes are published as a 14-PR stacked draft series for review, based at the current main branch; the unapplied Adopt a conflict-resistant strategy for session DB migrations from parallel branches #3968 branch is excluded.

Coming next ....

• Additional provider implementations and cross-provider multimodal capability parity.
• Generalized uploads/attachment-source work.
• Audio/video input expansion, long-term media retention/garbage collection policy, and non-TUI presentation surfaces.