gflow-cli 0.25.0__tar.gz → 0.26.0__tar.gz

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.26.0] — 2026-07-06
+
+### Added
+
+- **Reference a generated image in `image i2i` by its Flow UUID (`gflow_generate_image`,
+  `reference_images`)**: pass a generated image's media UUID as a reference and gflow
+  attaches it by **selecting the already-existing asset in Flow's reference picker** —
+  it does **not** upload a duplicate copy (avoiding duplication is the preferred path).
+  The asset's tile is located by its media id in the thumbnail URL (robust to
+  display-name collisions), surfaced by a display-name search when it isn't already
+  visible, and attached in place. When the asset can't be located (e.g. it's in a
+  different project's picker), gflow falls back to uploading its on-disk local file. A
+  UUID that isn't in your catalog still attaches by media id (no error). Live-verified:
+  a generated image's UUID → i2i output that references it, with no duplicate upload.
+- **Generated images now record their Flow display name**: the display name is extracted
+  from the `batchGenerateImages` response's `workflows[]` array (previously ignored) and
+  persisted in the asset catalog — the searchable label the media picker shows, and what
+  the UUID-reference path searches by. (Original find and approach by **@C1ph3r404**,
+  #253/#255.)
+
 ## [0.25.0] — 2026-07-06
 
 ### Fixed

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.25.0
+Version: 0.26.0
 Summary: Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal.
 Project-URL: Homepage, https://github.com/ffroliva/gflow-cli
 Project-URL: Issues, https://github.com/ffroliva/gflow-cli/issues

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/docs/INDEX.md

@@ -117,7 +117,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
+**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
 **"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships.
 **"What was live-verified for the data layer (PR #58)?"** → [LIVE_VERIFICATION_data_layer](LIVE_VERIFICATION_data_layer.md) — 1 Imagen + 1 Veo credit on denon82, 6-layer ledger (file + magic + Pillow + DB rows + CLI round-trip + structlog)
 **"What was live-verified for the video-download feature (#29)?"** → [LIVE_VERIFICATION_video_download](LIVE_VERIFICATION_video_download.md)

gflow_cli-0.26.0/docs/LIVE_VERIFICATION_v0.26.0.md

@@ -0,0 +1,69 @@
+# Live Verification — v0.26.0
+
+Release date: 2026-07-06. Headline: **reference a generated image in `image i2i`
+by its Flow UUID**, attached by **selecting the already-existing asset** in Flow's
+reference picker rather than uploading a duplicate copy (the founder principle:
+avoid duplication). Plus generated images now record their Flow **display name**
+(the searchable picker label), extracted from the response's `workflows[]` array.
+
+Live run: 2026-07-06, headed Playwright, profile `ffroliva`, real Flow.
+
+## Scope
+
+| Change | Surface | Verdict |
+|---|---|---|
+| Image i2i UUID ref → **select existing asset** (no duplicate) | `mcp/tools.py`, `worker/daemon.py`, `api/image.py`, `api/transports/ui_automation*.py` | ✅ **Live e2e GREEN** |
+| Generated-image `display_name` from `workflows[]` | `api/dto.py`, `data/recorder.py` | ✅ Unit-tested (real captured sample); credited @C1ph3r404 |
+
+## Mechanism
+
+An `image i2i` `reference_images` entry that is a Flow media UUID is resolved at
+enqueue time (best-effort, never errors — an uncatalogued UUID still attaches by
+media id, PR #245) to the asset's `display_name` + on-disk `local_path`. The
+transport then **prefers selecting the existing asset in place**:
+
+1. Locate the tile by the **media UUID in its thumbnail URL** (`img[src*=<uuid>]`)
+   — robust to display-name collisions, needs no search term.
+2. If not already visible, **search the display name** to surface it, then re-locate
+   by UUID.
+3. Attach in place. (The image picker attaches on tile-click and auto-closes; the
+   code also handles the video-style explicit "Add to Prompt" include.)
+4. **Fallback — local upload** only when the asset can't be located (e.g. it lives
+   in a different project's picker) and a local file exists.
+
+## Live end-to-end result — GREEN
+
+`gflow_generate_image(prompt="the same rustic workshop wall, wider shot, more
+tools", reference_images=["60dcb880-…" (a generated image's UUID)],
+project="0f4e7eaa-…" (the asset's project), profile="ffroliva")` via the real
+stdio MCP server. 5-layer ledger:
+
+1. **Attach path**: structlog `ui_automation_video.image_ref_selected_existing`
+   fired — and **no** `image_ref_upload_fallback` / `image_uploaded` event. The
+   existing asset was selected; **no duplicate was uploaded**.
+2. **Wire**: the generation ran the `batchGenerateImages` route carrying the
+   reference `imageInput` — the ref reached the generation, not a plain t2i.
+3. **File**: exactly one output written, `bee1e8a9-…_1.jpg`, 893 KB.
+4. **Magic bytes**: `ff d8 ff e0` (valid JPEG); task `status: completed`.
+5. **User-confirmable artifact**: the output shows the **same** rustic workshop
+   wall and the "v0.25.0" sign as the referenced image, as a wider shot with more
+   tools — the i2i reference visibly took.
+
+### Pre-fix note
+
+The first live attempt selected the asset correctly but errored looking for a
+separate "Add to Prompt" button — the image picker attaches on tile-click and
+auto-closes (one step), unlike the video r2v picker. Fixed to treat an
+auto-closed dialog as success; the re-run above is GREEN. (A hung Chrome holding
+the profile's `SingletonLock` also caused two transient `launch_persistent_context`
+failures between runs — cleared by killing the process + removing the lock.)
+
+## Automated coverage
+
+- `_enrich_image_refs` unit tests (`tests/mcp/test_tools_helpers.py`): enriches a
+  catalogued ref with display_name + local_path; partial meta when no on-disk file;
+  uncatalogued UUID passes through with no error and no `ref_meta`.
+- `display_name` extraction tests (`tests/api/test_image_dto.py`) against the real
+  captured `06_batchGenerateImages.json` sample.
+- Full suite green (1994 passed; the one deselected `test_packaging` case is a
+  network-dependent sdist build, unrelated). `pyright src` 0 errors, ruff clean.

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/docs/MCP.md

@@ -45,7 +45,7 @@ Both Click CLI (`src/gflow_cli/cli.py`) and MCP Server (`src/gflow_cli/mcp/`) ar
 The server registers three protocol surfaces:
 
 ### Tools (Executable actions)
-* `gflow_generate_image(prompt, model, aspect, count, seed, reference_images, tools, profile, project)`: Triggers text-to-image / image-to-image (Imagen / Nano Banana). `reference_images` switches to i2i; `project` generates into an existing Flow project id (mirrors CLI `--project`).
+* `gflow_generate_image(prompt, model, aspect, count, seed, reference_images, tools, profile, project)`: Triggers text-to-image / image-to-image (Imagen / Nano Banana). `reference_images` switches to i2i and accepts **either a local file path or a generated image's Flow media UUID**. A UUID reference is attached by **selecting the already-existing asset in Flow's reference picker — no duplicate copy is uploaded** (locating the tile by the media id in its thumbnail URL, and searching the recorded display name to surface it when needed); gflow falls back to uploading the asset's on-disk local file only when it can't be located in place (e.g. it lives in a different project's picker). `project` generates into an existing Flow project id (mirrors CLI `--project`) — pass the reference's project to keep it selectable in place.
 * `gflow_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, tools, profile, project)`: Triggers vertical or landscape video generation (Veo). `mode` is `t2v`/`i2v`/`r2v`; `i2v` requires `initial_frame`, `r2v` requires `reference_images`; `project` generates into an existing Flow project id (mirrors CLI `--project`). `initial_frame`, `end_frame`, and `reference_images` each accept **either a local file path or the Flow image UUID of a generated asset** — pass a generated image's id straight in to chain image→video, and gflow attaches it for you (the UUID is resolved to the asset's already-on-disk local file and uploaded as the frame; no manual download/re-upload step). A UUID that isn't in your local asset catalog is rejected up front with a clear "Reference Not Found" error; a catalogued asset whose local file is no longer on disk gives a "Reference Not On Disk" error (re-generate it or pass a local path).
 * `gflow_list_projects(profile, limit)`: Queries SQLite catalog for recent generation folders.
 * `gflow_list_characters(profile)`: Lists Flow Character entities (requires an active browser session).

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.25.0"
+version = "0.26.0"
 description = "Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal."
 readme = "README.md"
 license = { file = "LICENSE" }

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/src/gflow_cli/__init__.py

@@ -1,3 +1,3 @@
 """gflow-cli — unofficial CLI for Google Flow."""
 
-__version__ = "0.25.0"
+__version__ = "0.26.0"

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/src/gflow_cli/api/dto.py

@@ -8,7 +8,7 @@ KeyErrors leak.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import TYPE_CHECKING, Any, Literal, cast
 
 if TYPE_CHECKING:
@@ -128,6 +128,10 @@ class GeneratedImage:
     fife_url: str  # CDN URL — usually expires after ~6 hours
     dimensions: tuple[int, int]  # (width, height)
     media_generation_id: str | None = None
+    # Flow-assigned display name (from the response's `workflows[]` array). This
+    # is the searchable label the media picker shows — recorded so a generated
+    # image can be referenced by name later. Original find by @C1ph3r404 (#253).
+    display_name: str | None = None
 
     @property
     def is_signed_url(self) -> bool:
@@ -172,8 +176,37 @@ class GeneratedImage:
         if not isinstance(media, list):
             msg = "unexpected batchGenerateImages response shape: media is not a list"
             raise ValueError(msg)
+        # Flow returns display names in a sibling `workflows[]` array keyed by
+        # workflow id (mirrors AssetInfo.from_upload_response). Build the lookup
+        # once and inject the name onto each parsed image. (Find by @C1ph3r404.)
+        workflow_names = cls._workflow_display_names(data.get("workflows"))
         items = cast("list[dict[str, Any]]", media)
-        return [cls.from_response_item(item) for item in items]
+        results: list[GeneratedImage] = []
+        for item in items:
+            img = cls.from_response_item(item)
+            name = workflow_names.get(img.workflow_id)
+            if name:
+                img = replace(img, display_name=name)
+            results.append(img)
+        return results
+
+    @staticmethod
+    def _workflow_display_names(workflows: object) -> dict[str, str]:
+        """Map workflow id → displayName from the response's ``workflows[]``."""
+        names: dict[str, str] = {}
+        if not isinstance(workflows, list):
+            return names
+        for w in cast("list[Any]", workflows):
+            if not isinstance(w, dict):
+                continue
+            entry = cast("dict[str, Any]", w)
+            w_id = entry.get("name")
+            metadata = entry.get("metadata")
+            if isinstance(w_id, str) and isinstance(metadata, dict):
+                display_name = cast("dict[str, Any]", metadata).get("displayName")
+                if isinstance(display_name, str) and display_name:
+                    names[w_id] = display_name
+        return names
 
 
 @dataclass(frozen=True)

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/src/gflow_cli/api/image.py

@@ -185,11 +185,20 @@ class ImageRef:
     """A reference image for I2I, identified by the upload's media UUID.
 
     The wire shape is the dict returned by :meth:`to_wire`. The UUID comes
-    from a prior ``/v1/flow/uploadImage`` call (see
-    ``samples/captured/01_upload_image.json``).
+    from a prior ``/v1/flow/uploadImage`` call OR a generated image's media id
+    (see ``samples/captured/01_upload_image.json``).
+
+    ``display_name`` and ``local_path`` are UI-automation-only hints (ignored by
+    :meth:`to_wire`): they let the transport attach the ref by **selecting the
+    already-existing Flow asset in the picker** — located by ``name`` (the media
+    UUID) in the tile's image URL, surfaced by ``display_name`` when a search is
+    needed — and preferred over re-uploading a duplicate. ``local_path`` is the
+    fallback file to upload only when the asset can't be located in place.
     """
 
     name: str
+    display_name: str = ""
+    local_path: str = ""
 
     def __post_init__(self) -> None:
         # Reject empty, whitespace-only, AND whitespace-padded UUIDs.

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/src/gflow_cli/api/transports/ui_automation.py

@@ -2110,6 +2110,16 @@ class UiAutomationTransport(VideoGenerationMixin):
         if request.ref_paths:
             await self._attach_references(page, list(request.ref_paths), out_dir=out_dir)
 
+        # Pre-generated image UUID refs: attach by selecting the EXISTING Flow
+        # asset in the reference picker (no duplicate upload — founder principle),
+        # falling back to uploading the local file only when it can't be located.
+        if request.refs:
+            await self._attach_image_uuid_refs(
+                page,
+                [(r.name, r.display_name, r.local_path) for r in request.refs],
+                out_dir=out_dir,
+            )
+
         # Entity references: attach locked CHARACTER entities via the Personagens
         # picker (inherited from the video transport). The entity must live in the
         # project we generate in (pass --project / project_id). Flow's JS then

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/src/gflow_cli/api/transports/ui_automation_video.py

@@ -1479,6 +1479,121 @@ class VideoGenerationMixin:
             )
             log.info("ui_automation_video.remote_reference_attached", display_name=name)
 
+    @staticmethod
+    def _existing_asset_tile(page: Page, media_id: str) -> Locator:
+        """Locate a picker tile for an already-existing asset by its media UUID.
+
+        The tile's thumbnail URL is ``media.getMediaUrlRedirect?name=<uuid>``, so
+        matching ``img[src*=<uuid>]`` selects the exact asset with no dependence
+        on a display name (robust to name collisions) and no search term.
+        """
+        return page.locator(f"[role='option']:has(img[src*='{media_id}'])").first
+
+    @staticmethod
+    async def _select_existing_asset(
+        page: Page,
+        media_id: str,
+        display_name: str,
+        *,
+        out_dir: Path | None,
+        dialog_timeout_s: float = REMOTE_PICKER_CLOSE_TIMEOUT_S,
+    ) -> bool:
+        """In the OPEN reference picker, select the already-existing Flow asset
+        identified by ``media_id`` (preferred over uploading a duplicate).
+
+        Locates the tile by the media UUID in its thumbnail URL; if it isn't
+        already visible, searches ``display_name`` to surface it, then re-locates
+        by UUID. Returns ``True`` once attached, ``False`` when the asset can't be
+        located (the caller then falls back to a local upload).
+        """
+        tile = VideoGenerationMixin._existing_asset_tile(page, media_id)
+        try:
+            await tile.wait_for(state="visible", timeout=4000)
+        except Exception:  # noqa: BLE001 - not-visible is an expected branch
+            if not display_name:
+                return False
+            search = page.locator(PICKER_SEARCH_INPUT)
+            # Human-like typing jitter to dodge WAF heuristics — not security.
+            await search.press_sequentially(display_name, delay=random.randint(10, 50))  # NOSONAR
+            await page.wait_for_timeout(800)
+            try:
+                await tile.wait_for(state="visible", timeout=6000)
+            except Exception:  # noqa: BLE001 - still not found -> caller uploads
+                return False
+
+        await tile.click()
+        await page.wait_for_timeout(400)
+
+        # The image reference picker attaches on tile-click and auto-closes the
+        # dialog (one step). The video r2v picker instead needs an explicit
+        # "Add to Prompt" include after selecting. Handle both: if the dialog
+        # already closed, the attach registered on click; otherwise resolve and
+        # click the locale-safe include button.
+        dialog = page.locator(DIALOG_ANY).last
+        try:
+            await dialog.wait_for(state="hidden", timeout=2500)
+            return True
+        except Exception:  # noqa: BLE001 - still open -> needs explicit include
+            pass
+
+        include = await VideoGenerationMixin._resolve_include_action(
+            page,
+            PICKER_INCLUDE_BUTTON,
+            _INCLUDE_BUTTON_TIER_NAMES,
+            surface="image_ref_include",
+            detail=f"image ref {media_id}",
+            out_dir=out_dir,
+            screenshot_name="image_ref_include_missing.png",
+        )
+        await include.click(timeout=3000)
+        await page.wait_for_timeout(600)
+        try:
+            await dialog.wait_for(state="hidden", timeout=dialog_timeout_s * 1000)
+        except Exception as e:
+            raise TransportTimeoutError(
+                f"image ref {media_id} picker dialog did not close after "
+                f"{dialog_timeout_s}s (the include action may not have registered)",
+            ) from e
+        return True
+
+    @staticmethod
+    async def _attach_image_uuid_refs(
+        page: Page,
+        refs: list[tuple[str, str, str]],
+        *,
+        out_dir: Path | None,
+    ) -> None:
+        """Attach pre-generated image UUID references for I2I.
+
+        Each ref is ``(media_id, display_name, local_path)``. **Prefers selecting
+        the already-existing Flow asset** in the picker (no duplicate upload —
+        the founder principle); uploads ``local_path`` only as a fallback when the
+        asset can't be located in place. Raises when neither is possible.
+        """
+        for media_id, display_name, local_path in refs:
+            add = page.locator(ADD_MEDIA_BUTTON).first
+            await add.wait_for(state="visible", timeout=8000)
+            await add.click()
+            await page.wait_for_timeout(800)
+
+            if await VideoGenerationMixin._select_existing_asset(
+                page, media_id, display_name, out_dir=out_dir
+            ):
+                log.info("ui_automation_video.image_ref_selected_existing", media_id=media_id)
+                continue
+
+            if local_path:
+                log.info("ui_automation_video.image_ref_upload_fallback", media_id=media_id)
+                await VideoGenerationMixin._upload_via_open_dialog(
+                    page, Path(local_path), log_label="image_ref", out_dir=out_dir
+                )
+                continue
+
+            raise TransportTimeoutError(
+                f"image ref {media_id!r} could not be selected in the picker and "
+                "has no local file to upload — re-generate it or pass a local path.",
+            )
+
     @staticmethod
     async def _scroll_picker_grid(page: Page, delta_px: int = PICKER_GRID_SCROLL_DELTA_PX) -> None:
         """Wheel-scroll the open resource picker down one step. The Tudo grid is

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/src/gflow_cli/data/recorder.py

@@ -245,6 +245,11 @@ class OperationRecorder:
         media_type = mimetypes.guess_type(saved_path.name)[0]
         asset_id = _new_id()
         width, height = image.dimensions
+        # Persist the Flow-assigned display name (when present) so a generated
+        # image can later be referenced by name — the picker's searchable label.
+        metadata: dict[str, str] = {"fife_url": image.fife_url}
+        if image.display_name:
+            metadata["display_name"] = image.display_name
         repo.upsert_asset(
             AssetRecord(
                 id=asset_id,
@@ -261,7 +266,7 @@ class OperationRecorder:
                 height=height,
                 duration_seconds=None,
                 seed=image.seed,
-                metadata_json=redact_metadata({"fife_url": image.fife_url}),
+                metadata_json=redact_metadata(metadata),
             ),
         )
         repo.link_operation_asset(op_id, asset_id, OperationAssetRole.OUTPUT, i)

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/src/gflow_cli/mcp/tools.py

@@ -386,28 +386,70 @@ def _resolve_ref_local_path(
 
 
 # Video task types whose media-id refs are resolved to local file paths and
-# attached via the local-upload path (#237 fix — see _resolve_ref_local_path).
-# Image task types attach remote refs by raw media id and MUST NOT be resolved
-# here — gating on that was the PR #245 image-i2i regression.
+# attached via the local-upload path (#237 fix — see _resolve_ref_local_path):
+# the video FRAME picker does not surface generated media, so there is no
+# existing tile to select. Image task types DO surface generated media in the
+# reference picker, so their refs are enriched (not rewritten) and attached by
+# selecting the existing asset — see _enrich_image_refs.
 _VIDEO_TASK_TYPES = frozenset({"t2v", "i2v", "r2v"})
 
 
+def _enrich_image_refs(
+    data_repo: DataRepository,
+    profile: str,
+    payload: dict[str, Any],
+) -> None:
+    """Annotate each media-id ref in an image ``payload`` with its Flow
+    ``display_name`` and on-disk ``local_path`` (best-effort), so the transport
+    can attach it by **selecting the already-existing Flow asset** in the
+    reference picker — the preferred path (no duplicate upload) — with the local
+    file as an upload fallback. Never errors: an uncatalogued UUID is still a
+    valid media id to attach in place (PR #245 — image refs pass through).
+    """
+    refs = payload.get("refs")
+    if not refs:
+        return
+    meta: dict[str, dict[str, str]] = {}
+    for ref in refs:
+        asset = data_repo.get_asset_by_any_id(profile, ref)
+        if asset is None:
+            continue
+        entry: dict[str, str] = {}
+        name = asset.metadata_json.get("display_name")
+        if isinstance(name, str) and name:
+            entry["display_name"] = name
+        for local_file in asset.local_files:
+            if (
+                local_file.storage_provider is None
+                and local_file.path is not None
+                and local_file.path.is_file()
+            ):
+                entry["local_path"] = str(local_file.path)
+                break
+        if entry:
+            meta[ref] = entry
+    if meta:
+        payload["ref_meta"] = meta
+
+
 def _resolve_payload_refs(
     data_repo: DataRepository,
     profile: str,
     payload: dict[str, Any],
     task_type: str,
 ) -> dict[str, Any] | None:
-    """Rewrite every media-id ref in ``payload`` to a local file path in place.
-
-    Only the video task types are resolved (image tasks attach remote refs by
-    raw media id and are left untouched — PR #245). For video, a start/end frame
-    ref becomes the local ``start_image``/``end_image`` path and r2v ``refs`` are
-    resolved and merged into ``reference_images`` — so the existing local-upload
-    attach runs and no (broken) picker name search is attempted. Returns an error
-    envelope on the first unresolvable UUID, else ``None``.
+    """Resolve media-id refs in ``payload`` in place, by task type.
+
+    Video task types: a start/end frame ref becomes the local
+    ``start_image``/``end_image`` path and r2v ``refs`` are merged into
+    ``reference_images`` (local-upload attach — the video frame picker doesn't
+    surface generated media). Image task types: refs are *enriched* with
+    display_name/local_path so the transport selects the existing asset in the
+    picker (see _enrich_image_refs). Returns an error envelope on the first
+    unresolvable VIDEO UUID, else ``None`` (image enrichment never errors).
     """
     if task_type not in _VIDEO_TASK_TYPES:
+        _enrich_image_refs(data_repo, profile, payload)
         return None
     if "refs" in payload:
         resolved_paths: list[str] = []

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/src/gflow_cli/worker/daemon.py

@@ -291,7 +291,19 @@ class FlowWorker:
         model_val = payload.get("model")
         model = ImageModel.from_cli(model_val) if model_val else ImageModel.NARWHAL
 
-        refs = tuple(ImageRef(r) for r in payload.get("refs", []))
+        # ref_meta (set by the MCP layer's _enrich_image_refs) carries the
+        # display_name + on-disk local_path per media-id ref, so the transport
+        # can select the EXISTING asset in the picker (preferred, no duplicate)
+        # and fall back to uploading local_path only if it can't be located.
+        ref_meta: dict[str, dict[str, str]] = payload.get("ref_meta", {})
+        refs = tuple(
+            ImageRef(
+                r,
+                display_name=ref_meta.get(r, {}).get("display_name", ""),
+                local_path=ref_meta.get(r, {}).get("local_path", ""),
+            )
+            for r in payload.get("refs", [])
+        )
         ref_paths = tuple(Path(p) for p in payload.get("ref_paths", []))
         # NOTE: the payload may carry "ref_names" (the MCP layer resolves them
         # for the video request); the image transport attaches remote refs by

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/tests/api/test_image_dto.py

@@ -68,6 +68,36 @@ class TestGeneratedImage:
         assert len(results) == 1
         assert results[0].seed == 646428
 
+    def test_from_response_dict_extracts_display_name_from_workflows(self) -> None:
+        """The Flow-assigned display name lives in the response's ``workflows[]``
+        array (keyed by workflow id), not in the media item — extract it onto
+        the GeneratedImage so the catalog records a searchable name. (Original
+        find by @C1ph3r404, PR #253.)"""
+        sample = _load("06_batchGenerateImages.json")
+        body = sample["response_body_parsed"]
+        results = GeneratedImage.from_response_dict(body)
+        assert results[0].display_name == "Warrior Zelda in dungeon"
+
+    def test_from_response_dict_display_name_none_when_no_workflows(self) -> None:
+        """A response without a matching workflow leaves display_name as None
+        (graceful — the field is optional)."""
+        item = {
+            "name": "m",
+            "workflowId": "w-1",
+            "image": {
+                "generatedImage": {
+                    "seed": "1",
+                    "prompt": "p",
+                    "modelNameType": "NARWHAL",
+                    "aspectRatio": "IMAGE_ASPECT_RATIO_PORTRAIT",
+                    "fifeUrl": "https://flow-content.google/image/x",
+                },
+                "dimensions": {"width": 1, "height": 1},
+            },
+        }
+        results = GeneratedImage.from_response_dict({"media": [item]})
+        assert results[0].display_name is None
+
     def test_parse_seeded_landscape_response(self) -> None:
         """Seeded I2I + 4:3 landscape capture parses to expected dimensions/aspect."""
         sample = _load("07_batchGenerateImages_seeded.json")

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/tests/mcp/test_tools_helpers.py

@@ -158,9 +158,10 @@ class _LocalFile:
 
 
 class _Asset:
-    def __init__(self, local_files, flow_media_id="m"):
+    def __init__(self, local_files, flow_media_id="m", metadata_json=None):
         self.local_files = list(local_files)
         self.flow_media_id = flow_media_id
+        self.metadata_json = metadata_json or {}
 
 
 class _FakeRepo:
@@ -264,9 +265,9 @@ def test_resolve_payload_refs_r2v_refs_merge_into_reference_images(tmp_path: Pat
     assert "ref_names" not in payload
 
 
-def test_resolve_payload_refs_leaves_image_refs_untouched() -> None:
-    """PR #245 review #1: only the video path is resolved. Image 'refs' (media-id
-    UUIDs) attach by id and must pass through untouched even for a missing UUID."""
+def test_resolve_payload_refs_image_uncatalogued_uuid_passes_through() -> None:
+    """PR #245: an image 'refs' UUID not in the local catalog must pass through
+    without error (still a valid media id to attach in place); video errors."""
     from gflow_cli.mcp.tools import _resolve_payload_refs
 
     repo = _FakeRepo(asset=None)  # UUID not in local catalog
@@ -274,9 +275,39 @@ def test_resolve_payload_refs_leaves_image_refs_untouched() -> None:
     # video task type: resolves (and would error on the missing UUID)
     err_video = _resolve_payload_refs(repo, "default", dict(payload), task_type="r2v")
     assert err_video is not None
-    # image task type: passes through untouched, no error
+    # image task type: passes through, no error, no ref_meta (nothing to enrich)
     p_image = dict(payload)
     err_image = _resolve_payload_refs(repo, "default", p_image, task_type="i2i")
     assert err_image is None
     assert p_image["refs"] == [_A_UUID]
     assert "reference_images" not in p_image
+    assert "ref_meta" not in p_image
+
+
+def test_resolve_payload_refs_image_enriches_found_ref(tmp_path: Path) -> None:
+    """An image 'refs' UUID that IS in the catalog is enriched with its
+    display_name and on-disk local_path (ref_meta) so the transport can select
+    the existing asset in the picker (prefer-existing), refs left in place."""
+    from gflow_cli.mcp.tools import _resolve_payload_refs
+
+    img = tmp_path / "gen.png"
+    img.write_bytes(b"\x89PNG\r\n\x1a\n")
+    repo = _FakeRepo(asset=_Asset([_LocalFile(img)], metadata_json={"display_name": "Cozy cabin"}))
+    payload = {"refs": [_A_UUID]}
+    err = _resolve_payload_refs(repo, "default", payload, task_type="i2i")
+    assert err is None
+    assert payload["refs"] == [_A_UUID]  # not rewritten
+    assert payload["ref_meta"] == {_A_UUID: {"display_name": "Cozy cabin", "local_path": str(img)}}
+
+
+def test_resolve_payload_refs_image_enrich_partial_meta_only() -> None:
+    """Enrichment records only what's available — a catalogued asset with no
+    on-disk file contributes just its display_name (picker-select still works;
+    no local-upload fallback for that ref)."""
+    from gflow_cli.mcp.tools import _resolve_payload_refs
+
+    repo = _FakeRepo(asset=_Asset([], metadata_json={"display_name": "Named but pruned"}))
+    payload = {"refs": [_A_UUID]}
+    err = _resolve_payload_refs(repo, "default", payload, task_type="i2i")
+    assert err is None
+    assert payload["ref_meta"] == {_A_UUID: {"display_name": "Named but pruned"}}

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/tests/mcp/test_tools_wired.py

@@ -51,6 +51,7 @@ class _FakeImage:
     aspect_ratio: str = "1:1"
     seed: int = 12345
     fife_url: str = "http://fake"
+    display_name: str | None = None  # mirrors GeneratedImage.display_name
 
 
 def _completed_video_result(media_id: str = "media-vid-wired") -> VideoResult:

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/tests/worker/test_daemon.py

@@ -25,6 +25,7 @@ class FakeGeneratedImage:
     aspect_ratio: str = "1:1"
     seed: int = 12345
     fife_url: str = "http://fake"
+    display_name: str | None = None  # mirrors GeneratedImage.display_name
 
 
 def _completed_video_result(media_id: str = "media-vid-123") -> VideoResult:

{gflow_cli-0.25.0 → gflow_cli-0.26.0}/uv.lock

@@ -787,7 +787,7 @@ wheels = [
 
 [[package]]
 name = "gflow-cli"
-version = "0.25.0"
+version = "0.26.0"
 source = { editable = "." }
 dependencies = [
     { name = "browser-cookie3" },