Epic: Gemini image output with workspace deliverables and portable session copies

[aheritier]

Purpose

Reliable Gemini image workflows across the Docker models gateway, direct Gemini API, and Vertex request surface, with workspace deliverables, portable session bytes, and manifest-authorized TUI rendering. This is Gemini-focused, not universal multimodal provider parity.

Configuration and request behavior

• Explicit output_capabilities.image true/false wins. Omitted, empty, or unset metadata uses exact provider-qualified models.dev output metadata; unknown or unavailable entries remain disabled. Model names are not capability evidence.
• Eligible ordinary Google calls request TEXT+IMAGE on gateway, direct API, and Vertex. Custom function tools and structured output are rejected before dispatch; Google Search, Maps, and code execution remain allowed. Utility calls bypass the guard and omit image response modalities.
• Audio/video input capability overrides and request-model filtering remain supported; this does not add universal upload or conversion support.
• The missing-image notice is phrase-based, with accepted negation/quotation/context false positives and wording false negatives. It is not NLP, has no retry, and does not predicate on output capability.

Generated-media lifecycle

• Complete media bytes accumulate internally; this is not progressive partial-image display or remote binary streaming.
• Every generated item is written inside the owning workspace. Relative nesting, MIME correction, atomic hard-link no-overwrite writes (unsupported filesystems fail safely), and partial success are retained. Absolute, traversal, home-relative, external, and symlink-escaping requests are redirected to a sanitized workspace basename with a bounded warning. There is no external generated-media write or confirmation flow.
• The manifest records owner, path, and workspace root before an optional complete portable blob is stored, without an application-level generated-media cap. Blob failure warns and preserves the workspace file. Session deletion removes manifest/blob rows, not workspace files.
• The root-kind migration remains for compatibility; old unknown or external rows fail closed. Every resolution rechecks the current manifest, so session deletion revokes references. All reads authorize against the manifest first, prefer blobs, and fall back only when the blob interface is absent or the blob is not found, and only to the owning workspace. Other blob errors fail closed.
• A blob can survive missing WorkingDir provenance and then uses the recorded relative display path, not a verified absolute path. Ordinary legacy file contents are not integrity-verified.
• Naming precedence is marker, exact one-image prompt filename, provider filename, then generated-N. Private markers are removed from visible and persisted text.
• TUI resolution happens off the Update path and preserves text beside media. Ordinary later model turns and compaction receive bounded metadata placeholders rather than generated bytes.

Transport and validation boundaries

• Payload-free keepalive filtering is a Docker gateway opt-in. Direct Gemini and Vertex retain upstream transport behavior.
• Deterministic fixtures cover request construction and guards. No new gateway/direct live reproduction was run for this draft; live Vertex remains deferred.
• Existing older real-catalog evidence may remain evidence of that earlier run, but is not presented as a new execution or an effective-config override.
• Database compatibility caution only: migrations happen in place, older binaries may not understand the upgraded schema, and compatibility tests use isolated disposable stores. No active database was read, copied, migrated, or mutated for this preparation.

Draft PRs

• feat(#3996): resolve and filter input media per request model #4016 — feat(Epic: Gemini image output with workspace deliverables and portable session copies #3996): resolve and filter input media per request model
• fix(#3996): diagnose Gemini requests and sanitize API failures #4017 — fix(Epic: Gemini image output with workspace deliverables and portable session copies #3996): diagnose Gemini requests and sanitize API failures
• feat(#3996): resolve image output capability from models.dev #4019 — feat(Epic: Gemini image output with workspace deliverables and portable session copies #3996): resolve image output capability from models.dev
• feat(#3996): guard image-output requests across Google surfaces #4020 — feat(Epic: Gemini image output with workspace deliverables and portable session copies #3996): guard image-output requests across Google surfaces
• fix(#3996): keep image-output models eligible for session titles #4021 — fix(Epic: Gemini image output with workspace deliverables and portable session copies #3996): keep image-output models eligible for session titles
• fix(#3996): filter gateway SSE keepalives and test image requests #4022 — fix(Epic: Gemini image output with workspace deliverables and portable session copies #3996): filter gateway SSE keepalives and test image requests
• feat(#3996): stream model-generated media deltas #4023 — feat(Epic: Gemini image output with workspace deliverables and portable session copies #3996): stream model-generated media deltas
• feat(#3996): add workspace media writes and session provenance #4024 — feat(Epic: Gemini image output with workspace deliverables and portable session copies #3996): add workspace media writes and session provenance
• feat(#3996): save generated media with no-resend placeholders #4025 — feat(Epic: Gemini image output with workspace deliverables and portable session copies #3996): save generated media with no-resend placeholders
• feat(#3996): keep generated media workspace-only with portable session copies #4026 — feat(Epic: Gemini image output with workspace deliverables and portable session copies #3996): keep generated media workspace-only with portable session copies
• feat(#3996): name generated media with private markers and prompt fallback #4027 — feat(Epic: Gemini image output with workspace deliverables and portable session copies #3996): name generated media with private markers and prompt fallback
• fix(#3996): leave reasoning headroom for Gemini session titles #4028 — fix(Epic: Gemini image output with workspace deliverables and portable session copies #3996): leave reasoning headroom for Gemini session titles
• feat(#3996): render generated images from manifest-gated portable blobs #4029 — feat(Epic: Gemini image output with workspace deliverables and portable session copies #3996): render generated images from manifest-gated portable blobs
• docs(#3996): describe portable generated media and Gemini output limits #4030 — docs(Epic: Gemini image output with workspace deliverables and portable session copies #3996): describe portable generated media and Gemini output limits

Validation status

All 31 commit cuts and all 14 PR boundaries passed build, test compilation and uncached owning-package tests. Every named fixture command ran nonzero top-level tests in every listed package. Final-head build, lint, full tests, uncached full suite, focused race tests and documentation checks passed.

Each PR body records its exact deterministic command and matching test counts. The final signed head passed the complete local validation gates. Remote CI is tracked on the linked PRs; live Vertex validation remains deferred, and no new paid-provider or active-database check was run.

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.