gflow-cli 0.19.0__tar.gz → 0.20.1__tar.gz

{gflow_cli-0.19.0 → gflow_cli-0.20.1}/.env.template

@@ -115,6 +115,12 @@
 # `patchright install chromium`. Unset to revert to the default playwright engine.
 # GFLOW_CLI_BROWSER_ENGINE=playwright
 
+# Try to force the Classic Flow UI mode for image generation by clicking the Agent toggle pill
+# if the page mounts in Agentic mode. This ensures deterministic aspect ratio controls.
+# If the page cannot be switched back to Classic, falls back to Agentic mode.
+# GFLOW_CLI_PREFER_CLASSIC=false
+
+
 # BCP-47 locale tag passed to Playwright's launch `locale=` parameter
 # (controls Accept-Language only — Chrome's UI language is forced to
 # en-US via the `--lang=en-US` launch arg regardless of this setting, so

{gflow_cli-0.19.0 → gflow_cli-0.20.1}/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.1] — 2026-06-16
+
+### Fixed
+
+- **Aspect ratio overrides in Agentic & Classic cohorts** ([#193](https://github.com/ffroliva/gflow-cli/issues/193)): Fixed a bug where aspect ratio settings were ignored under the pluggable `FlowUiDriver` strategies (both single and batch image generation paths).
+- **`GFLOW_CLI_PREFER_CLASSIC`** (or `prefer_classic` setting): Added a configuration setting to force the classic UI driver, allowing users to bypass the Agentic UI cohort if preferred.
+
+## [0.20.0] — 2026-06-15
+
+### Added
+
+- **Forced Agentic UI detection** (exit code 25): dynamically detects if the account's Flow editor page has been placed in Google Flow's new Agentic UI A/B cohort. Raises `FlowAgentUiError` and captures a diagnostic viewport screenshot (`debug_forced_agent_ui.png`) to exit cleanly and prevent CLI hangs.
+- **Pluggable Flow UI driver strategy** (`FlowUiDriver`): the UI-automation transport now probes the editor DOM **per generation** (the cohort flaps per page load) and binds a `ClassicFlowUiDriver` or `AgenticFlowUiDriver`, so the two cohorts' selectors never share code. Classic generation is unchanged.
+- **Agentic-cohort image generation** (validated live): when the editor is served the Agentic UI, `gflow image` drives it by encoding settings (count / aspect) into the conversational prompt directive and scraping generated assets directly from the DOM — **deduplicated by media UUID** — because the Agentic UI routes generation through a background Web Worker that defeats page-level network capture. Content-policy blocks (detected in alert/dialog regions) fail fast with `ContentPolicyError` (exit 5). Agentic **video** still raises `FlowAgentUiError` (exit 25) pending a validated scraping path.
+- **`GFLOW_CLI_FORCE_AGENT_UI`** (testing/diagnostic opt-in): forces the agentic composer by clicking the in-input "Agent" toggle after entering the editor, so the agentic path can be exercised deterministically regardless of the server-assigned A/B cohort (which has no client-readable flag). Unset by default — the cohort is auto-detected per generation. See `docs/AGENT_UI_E2E.md`.
+
 ## [0.19.0] — 2026-06-12
 
 ### Added
@@ -1549,7 +1565,9 @@ shell-script template that branches on these codes.
 
 First skeleton. Not functional end-to-end yet.
 
-[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.19.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.20.1...HEAD
+[0.20.1]: https://github.com/ffroliva/gflow-cli/compare/v0.20.0...v0.20.1
+[0.20.0]: https://github.com/ffroliva/gflow-cli/compare/v0.19.0...v0.20.0
 [0.19.0]: https://github.com/ffroliva/gflow-cli/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/ffroliva/gflow-cli/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/ffroliva/gflow-cli/compare/v0.16.0...v0.17.0

{gflow_cli-0.19.0 → gflow_cli-0.20.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.19.0
+Version: 0.20.1
 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.20.1/docs/AGENT_UI_E2E.md

@@ -0,0 +1,108 @@
+# Agentic UI — End-to-End Testing Runbook
+
+> How to **deterministically** drive and validate `gflow`'s **Agentic UI** image
+> path against live Google Flow. Companion to
+> [AGENT_UI_RECON.md](AGENT_UI_RECON.md) (the reverse-engineered wire/DOM spec)
+> and [LIVE_VERIFICATION_v0.20.0.md](LIVE_VERIFICATION_v0.20.0.md) (the shipped
+> evidence).
+
+## The problem, and the way in
+
+Google Flow serves the composer via a **server-assigned A/B cohort** that flaps
+per page load and has **no client-readable flag** — so the agentic UI cannot be
+*requested*. A naive "retry until the dice land agentic" e2e is unreliable (we
+observed 7 classic loads in a row).
+
+**The deterministic trigger:** the *classic* composer exposes an in-input
+**"Agent" toggle**. Clicking it switches the composer into the **same** agentic
+layout — confirmed live (`scripts/e2e/capture_agent_toggle.py`, 2026-06-14):
+
+| Signal | Before toggle | After toggle |
+|---|---|---|
+| `crop_*` media trigger | present | **gone** |
+| `tune` settings gear | absent | **present** |
+| Slate composer | present | present |
+
+So `tune` appears and `crop_*` disappears → `detect_ui_mode` then binds the
+agentic driver. An **`expand_content`** button opens the full agent side panel.
+
+## Repeatable procedure (deterministic)
+
+Set **`GFLOW_CLI_FORCE_AGENT_UI=1`** and the transport clicks the Agent toggle
+after entering the editor, forcing the agentic path on any load. The harness
+runs that and verifies the whole chain:
+
+```powershell
+# From repo root. Image generation is free — safe to run repeatedly.
+.\scripts\e2e\agentic_image_e2e.ps1 -Profile denon82 -Count 1
+.\scripts\e2e\agentic_image_e2e.ps1 -Profile denon82 -Count 3   # also exercises dedup
+```
+
+It PASSes only when all four hold (else it prints which stage failed):
+
+1. `agent_mode_forced activated=true` — the toggle flipped the composer to agentic;
+2. `ui_driver.bound mode=agentic` — the agentic driver was bound;
+3. exit 0;
+4. exactly `-Count` `.jpg` files written (scrape → dedup-by-UUID → download).
+
+Run it directly without the harness, too:
+
+```powershell
+$env:GFLOW_CLI_FORCE_AGENT_UI="1"
+uv run gflow image t2i "a ripe banana on a white plate" --profile denon82 --json
+```
+
+> `GFLOW_CLI_FORCE_AGENT_UI` is a **testing/diagnostic opt-in**, not a user
+> feature: it forces the agentic path even when the server served classic.
+> Leave it unset for normal use (the cohort is then auto-detected per
+> generation).
+
+## Validation result (2026-06-14, profile denon82)
+
+Forced-agentic runs validated the three assumptions that mocked tests cannot:
+
+- **`--count 1`** → exit 0, one **420 KB JPG**. Scrape found the asset, built the
+  full-res redirect URL, the `labs.google` download resolved with session
+  cookies, and the synthetic `GeneratedImage` fields (`workflow_id=""`, `seed=0`,
+  `dimensions=(0,0)`) flowed through the save path without error.
+- **`--count 3`** → exit 0, **3 distinct JPGs** for 3 distinct media UUIDs —
+  confirming dedup: the agentic UI's multiple `<img>` nodes per asset collapse to
+  the correct count.
+
+Classic remains unaffected: live `gflow image t2i` and `gflow video t2v` both
+succeed when the cohort/loads serve classic.
+
+## Knowledge extracted (this cost real e2e runs — keep it)
+
+Three render-timing / detection bugs were found **only** by live e2e (mocked
+tests passed throughout); each is now fixed with a regression test:
+
+1. **Cohort detection raced the render.** `get_ui_driver` probed instantly after
+   navigation and missed the agentic `tune` indicator (it appeared ~1.25 s
+   later), defaulting to classic → spurious `FlowAgentUiError` (exit 25). Fix:
+   `detect_ui_mode` polls (8 s window). Test: `test_detect_agentic_after_delayed_render`.
+2. **The force-toggle raced the render too.** `_force_agent_mode` probed for the
+   Agent toggle ~0.8 s after entering the editor, before the composer rendered →
+   `agent_toggle_not_found`, silently staying classic. Fix: `wait_for` the toggle
+   (8 s) before clicking.
+3. **Content-policy detection false-positived on static chrome.** Scanning the
+   whole `document.body` for "content policy" matched a benign page's footer/menu
+   link → every agentic generation died with a spurious `ContentPolicyError`
+   (exit 5) in ~6 s. Fix: scope the scan to `[role=alert]`/`[role=dialog]`/
+   `[aria-live=assertive]` regions only (a real block surfaces there; a
+   chat-message-only refusal is missed, which is the safe trade — a miss →
+   timeout beats a false positive that breaks every generation). Tests:
+   `test_await_images_raises_content_policy_on_explicit_text`,
+   `test_await_images_ignores_body_chrome_policy_text`.
+
+General lesson: **any agentic-composer probe must wait for the render** — instant
+DOM checks race Flow's deferred composer mount.
+
+## Still owed
+
+- A **captured positive content-policy refusal** in the agentic cohort, to widen
+  detection safely beyond alert/dialog regions (chat-message refusals are
+  currently missed → timeout). Trigger a disallowed prompt under
+  `GFLOW_CLI_FORCE_AGENT_UI=1` and capture how the refusal surfaces.
+- **Agentic video** — only the image path is validated; video stays on the
+  classic→`FlowAgentUiError` path pending a video scraping capture.

gflow_cli-0.20.1/docs/AGENT_UI_RECON.md

@@ -0,0 +1,192 @@
+# Agentic Flow UI — Recon Findings
+
+> Reverse-engineered 2026-06-14 via `gflow-agent-browser-spike` (CDP-attached
+> real Chrome, `agent-browser@0.27.0`) against the live Flow editor on two
+> Chrome profiles. Account-specific values (emails, project UUIDs) are redacted.
+> Relates to issues #183 (image `t2i` exit 23) and #174 (library-UI entity drop).
+
+## TL;DR
+
+- Flow runs a **server-side A/B cohort** that swaps the project composer between
+  the **classic** media UI and a new **agentic** UI (chat-style "Agent").
+- It is **volatile**: the *same* Chrome profile rendered the classic composer at
+  one point and the agentic composer later on the *same* project — confirming the
+  #174 flapping (denon82 reverting within 12h).
+- **gflow's own dedicated automation profiles DO land in the agentic cohort**
+  (not only the user's primary profile), so #183/#174 are reproducible through
+  gflow — the feature must handle it.
+- The cohort is **NOT discoverable from client-side state**: localStorage keys and
+  JS-visible cookies are byte-identical across both UIs, and the prime-suspect key
+  `FLOW_MAIN_PROMPT_BOX_STATE` holds only generation settings, not a mode flag.
+  → **Detection must be runtime DOM-based**; there is no pre-navigation cookie/flag
+  to read or flip.
+- `navigator.webdriver` is **`false`** under CDP-attached real Chrome.
+
+## How it was captured
+
+`gflow-agent-browser-spike` launches real Chrome with `--remote-debugging-port`
+on a chosen profile and drives `agent-browser` over CDP. JS is passed as
+**base64-wrapped `eval`** (`eval(atob('…'))`) — multi-line eval args get mangled
+through `npx`, so base64 is the reliable path (this also applies to
+`capture-agent-ui.ps1`, which must minify/encode its eval expressions). Capturing
+the user's **primary** profile required relaunching it with the debug flag (only
+applied on a fresh Chrome start, so all windows must be closed first), which
+triggered a one-time Google 2-Step Verification.
+
+## The two UIs — DOM signature
+
+| Signal | Classic | Agentic |
+|---|---|---|
+| `crop_*` inline aspect/mode trigger | **present** (`crop_9_16` etc.) | **absent** |
+| Agent pill (`/\bAgent\b/` + `div[role='textbox']`) | no | **yes** |
+| Chat ligatures `edit_square`, `thumb_up`, `thumb_down`, `flag` | no | **yes** |
+| Agentic ligatures `article_spark`, `apps_spark_2`, `tune` | no | **yes** |
+| "What do you want to create?" placeholder | no | **yes** |
+| Aspect / model / upscale controls | inline `crop_*` dropdown | moved into **"Agent settings"** (`tune`) |
+
+Agentic ligature inventory (captured): `accessibility_new, add, add_2,
+apps_spark_2, arrow_back, arrow_forward, arrow_forward_ios, article_spark, close,
+content_copy, dashboard, delete, edit_square, filter_list, flag, help, image,
+left_panel_close, menu, more_vert, movie, search, settings_2, thumb_down,
+thumb_up, tune, warning` — and **no `crop_*`**.
+
+## Gating mechanism (the cohort key)
+
+Captured on agentic profiles (both the user's primary and a gflow dedicated
+profile), the client-visible state is **identical**:
+
+- **localStorage keys**: `FLOW_MAIN_PROMPT_BOX_STATE`, `FLOW_QUICK_SEARCH_MODE`,
+  `_grecaptcha`, `glue.CookieNotificationBar`, `nextauth.message`.
+- **JS-visible cookies**: `EMAIL`, `_ga`, `_ga_X2GNH8R5NS` (any cohort cookie
+  would be `httpOnly`, i.e. invisible to JS — recoverable only from HAR request
+  headers, not yet captured).
+- **`FLOW_MAIN_PROMPT_BOX_STATE`** value (agentic):
+  `{"aspectRatio":"PORTRAIT","selectedImageModelFamily":"narwhal_display","selectedVideoModelFamily":"abra","imageOrVideoMode":"IMAGE","outputsPerPrompt":1,"selectedVideoDuration":4}`
+  — generation settings only, **no cohort/mode flag**.
+
+Because (a) the key set is identical across classic and agentic, (b) the one
+plausible key holds only settings, and (c) the same profile flaps between states,
+the cohort is concluded to be **server-assigned per page load**, not a readable
+client signal. Pre-navigation detection (read a cookie before driving) is **not
+viable**; runtime DOM classification is the only reliable detector.
+
+## Why the existing handling fails (#183)
+
+`_exit_agent_mode` (`ui_automation_video.py`) assumes the classic composer is
+recoverable and keys on `_media_panel_present` (the `crop_*` trigger). In the
+agentic cohort there is **no `crop_*`** at all (aspect moved into Agent settings),
+so the probe never recovers, the selector cascade exhausts, and the caller raises
+`UiSelectorDriftError` (exit 23). The recovery has nothing to recover *to*.
+
+## Recommendation for the feature plan
+
+1. **Detection = runtime DOM classification.** Agentic if *no `crop_*` mode
+   trigger* **and** (*Agent pill present* **or** *chat-panel ligatures present*).
+   This is what `classify_composer` / a refreshed `_exit_agent_mode` should key
+   on. Run it every generation — the cohort flaps, so no caching.
+2. **No pre-flight cookie/flag gate** — there is no client-readable cohort signal.
+3. **Response (decide in the feature plan, evidence now supports either):**
+   - **Detect + fail cleanly** with a typed `FlowAgentUiError` (own exit code) +
+     screenshot — low risk, immediately diagnosable. *Recommended first step.*
+   - **Drive the agentic surface** — type into the chat composer, set aspect/model
+     via the Agent-settings (`tune`) panel, handle the confirm-before-generating
+     gate. Larger; intermittently needed because the cohort flaps.
+
+## DOM scraping validation (2026-06-14, live capture)
+
+> Captured via `scripts/capture-media-scrape.ps1` (CDP-attached real Chrome,
+> profile `default`, agentic cohort confirmed: `crop=false, agentPill=true,
+> chatPanel=true`). One image generation, before/after media-DOM snapshot.
+> Artifact: `media-scrape-agentic-20260614-202739.json`.
+
+This resolves the open question blocking `AgenticFlowUiDriver.await_images`: **how do
+generated assets surface in the agentic DOM, and is count-delta scraping viable?**
+
+- **Assets render as plain remote `<img>` nodes.** After the generation: `blob=0`,
+  `data=0`, `canvas=0`, `background-image=0`. The full-res asset is a normal
+  `<img src="https://…">`. Count-delta DOM scraping **is viable** — network
+  interception is not (see HAR note below).
+- **The src is a same-origin tRPC redirect carrying a stable media id:**
+  ```
+  https://labs.google/fx/api/trpc/media.getMediaUrlRedirect?name=<uuid>[&mediaUrlType=MEDIA_URL_TYPE_THUMBNAIL]
+  ```
+  It 302-redirects to the CDN blob; same-origin (`labs.google`) means the session
+  cookies authorize the download. The `name=<uuid>` is the **stable backend media id**
+  — scraped assets correlate to media identity (usable for the batch ledger / dedup).
+- **Dedupe by `name=<uuid>`, NOT by `<img>` node count.** One generated asset surfaces
+  as **multiple** `<img>` nodes (canvas full-res + filmstrip thumbnail + chat preview,
+  each in bare and `&mediaUrlType=MEDIA_URL_TYPE_THUMBNAIL` variants). The single
+  capture produced **9 new `<img>` nodes for only 3 distinct assets** (~3× inflation).
+  `await_images` must extract the `name` query param and **count distinct UUIDs** — a
+  raw `initial_count + expected_count` node check would massively over-count.
+- **Page-level HAR captured 0 entries.** Confirms the Web-Worker delegation: the
+  `streamChat` + media requests bypass page-level network capture entirely. **DOM
+  scraping is the only viable capture path** in the agentic cohort.
+- **`flag` is NOT a content-policy signal.** The warn-symbol probe matched the `flag`
+  ligature 11× on a *successful* generation — `flag`/`thumb_up`/`thumb_down` are the
+  normal per-message chat affordances. Fail-fast detection must key on `warning` /
+  `error` / `block` or specific dialog/stream text, **never `flag`**. *(A deliberate
+  content-policy-refusal capture is still outstanding — no positive block sample yet.)*
+
+## Settings via prompt, not the `tune` popover (agentic acts MCP-like)
+
+The agentic composer behaves like a conversational agent: generation parameters that the
+classic UI exposes as discrete controls — **output count** (1 / 4 images), **video
+duration** (4/6/8/10 s), and likely **aspect ratio** and **model** — can be expressed in
+**natural language inside the prompt** (e.g. `Generate 4 images of <prompt> in 16:9`), and
+the agent resolves the selection itself.
+
+Implications for `AgenticFlowUiDriver`:
+- **`configure_settings` becomes optional.** Encoding settings as a directive prompt
+  avoids driving the fragile `tune` → Radix-popover dropdowns — the most drift-prone
+  surface on a volatile A/B UI. Prefer prompt-encoding; treat popover automation as a
+  fallback only if prompt-steering proves unreliable.
+- **The agent *interprets* the request → verify, don't trust.** It may produce a
+  different count or ignore a duration. This is precisely why scrape-and-dedup-by-UUID
+  is load-bearing: request N → poll until N distinct new media UUIDs → if the produced
+  count differs, raise a typed mismatch rather than silently returning the wrong set.
+- **Compose carefully** so settings directives aren't read as subject text (e.g. a
+  `Generate {n} image(s){aspect}: {prompt}` template).
+
+## Open follow-ups
+
+- **Content-policy block sample (outstanding):** capture a deliberate-refusal generation
+  in the agentic cohort to learn how a block surfaces (chat message vs. dialog vs.
+  symbol) — needed to design `await_images` fail-fast. The `flag` symbol is ruled out.
+
+## The Wire & API Endpoint (Resolved via Issue #183 Reporter)
+
+The network request logs from the agentic UI have been resolved. The new UX bypasses the direct media generation endpoints (such as `batchGenerateImages`) and routes all generation requests through Google's conversational flow creation agent.
+
+- **Endpoint**: `POST https://aisandbox-pa.googleapis.com/v1/flowCreationAgent:streamChat?alt=sse`
+- **Transport**: Server-Sent Events (SSE) stream, preceded by a CORS OPTIONS preflight.
+- **Request Payload Structure**:
+  ```json
+  {
+    "agentSessionId": "<uuid>",
+    "agentClientContext": {
+      "projectId": "projects/<projectUuid>",
+      "clientSessionId": ";<epochMillis>",
+      "recaptchaContext": {
+        "token": "<recaptcha_token>",
+        "applicationType": "RECAPTCHA_APPLICATION_TYPE_WEB"
+      },
+      "turnNumber": 2
+    },
+    "userMessage": {
+      "userPrompt": {
+        "parts": [
+          {
+            "text": "a red apple"
+          }
+        ]
+      }
+    }
+  }
+  ```
+
+### Why page-level CDP/Playwright instrumentation recorded 0 entries
+During local capture sessions, page-level request event listeners repeatedly recorded `0` API request entries. This occurred because the agentic UI delegates all `streamChat` network requests to a background **Web/Service Worker** target (`type: worker`). Worker-initiated requests completely bypass page-level network event registration in Playwright/CDP and require worker-level target attachments to capture.
+
+### Impact on issue #174 (referenceEntities)
+In the agentic UI, the prompt box is a conversational Slate.js editor. Because generation is driven by the conversation agent stream rather than direct REST inputs, staging library entities (e.g. characters) behaves differently. For the initial implementation phase, driving or injecting into `flowCreationAgent:streamChat` is out of scope. The recommended direction is **Runtime DOM detection + Fail Cleanly** with `FlowAgentUiError` (exit code 23) to prevent automation lockups while the cohort is active.

{gflow_cli-0.19.0 → gflow_cli-0.20.1}/docs/CONFIGURATION.md

@@ -200,6 +200,14 @@ GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
 **Reverting:** unset the variable (or set `playwright`) — the default path is byte-identical to a build without this feature, with no profile migration.
 **Security note:** the `patchright` extra ships a *patched Chromium driver* that handles your live Google session cookies; it is exact-pinned and treated as a security-review-required dependency. See [SECURITY.md § Dependencies](SECURITY.md).
 
+### `GFLOW_CLI_PREFER_CLASSIC`
+
+**What:** Try to force the Classic Flow UI mode for image generation by clicking the Agent toggle pill if the page mounts in Agentic mode.
+**Values:** `true` | `false`
+**Default:** `false`
+**Why use it:** The Agentic UI cohort (conversational chat) treats requested aspect ratios as a soft prompt hint, which can result in inconsistent aspect ratios (e.g. producing landscape when portrait 9:16 was requested). Exposing this setting allows callers to opt into switching the UI back to Classic mode where aspect ratios are enforced deterministically (via hard Flow crop controls).
+**Fallback:** If the page cannot be switched back to Classic (e.g., in a forced A/B cohort where the toggle is not available), the driver gracefully falls back to Agentic mode rather than blocking execution.
+
 ### `GFLOW_CLI_LOCALE`
 
 **What:** BCP-47 locale tag passed to Playwright's `launch_persistent_context(locale=...)` — controls the `Accept-Language` HTTP header only.

{gflow_cli-0.19.0 → gflow_cli-0.20.1}/docs/INDEX.md

@@ -35,6 +35,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[docs/CHARACTER.md](CHARACTER.md)** | Characters feature spec & system design: domain model, endpoint/cost matrix, sequence diagrams, JSON payloads (I/O), CLI surface, reuse via `referenceEntities` (#145) | Working on `gflow character`, reusing a character in generations, or understanding Flow's character wire protocol |
 | **[docs/MOVIE.md](MOVIE.md)** | `gflow movie` — multi-scene character-consistent films: manifest format, run lifecycle (browser stays open through generate→poll→download), entity-attach mechanism (Personagens right-click), resume/handoff, credits | Working on `gflow movie`, debugging scene generation, or understanding the character-entity attach + consistency model |
 | **[docs/IMAGE_UPSCALE_RECON.md](IMAGE_UPSCALE_RECON.md)** | `gflow image upscale` wire protocol: `upsampleImage` endpoint, full clientContext (projectId/sessionId/tool/userPaygateTier), reCAPTCHA action `IMAGE_GENERATION`, inline base64 response, 4K Ultra-gating, REST-is-dead proof | Working on `gflow image upscale`, debugging the 403/reCAPTCHA path, or understanding Flow's image-upscale wire protocol (#171) |
+| **[docs/AGENT_UI_RECON.md](AGENT_UI_RECON.md)** | Agentic Flow UI cohort: classic-vs-agentic DOM signature, server-side + volatile (flapping) A/B gating (no client-readable flag), why `_exit_agent_mode` fails, runtime-DOM-detection recommendation | Touching `_exit_agent_mode` / composer mode-switch, diagnosing exit 23 selector drift, or understanding Flow's agentic-UI A/B (#183/#174) |
 | **[tasks/lessons.md](../tasks/lessons.md)** | Running notebook of patterns + reviewer findings, dated and traced to commits | Starting a new phase; debugging "why did the council flag this?" |
 | **[skills/README.md](../skills/README.md)** | Installable agent skill docs (gflow-cli, predict, pr-council-review, scenario) — cross-tool portable Markdown consumed by Claude Code, Cursor, Codex, Gemini CLI, Aider, etc. | Any agent wanting to use gflow-cli correctly |
 | **[scripts/dev/skillopt/README.md](../scripts/dev/skillopt/README.md)** | SkillOpt mock harness — rollout→score loop for measuring and improving skill doc accuracy across multiple LLM providers | Measuring a skill edit's impact; comparing Claude vs GPT-4o vs Gemini on gflow tasks |
@@ -111,7 +112,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.19.0](LIVE_VERIFICATION_v0.19.0.md) (opt-in patchright engine: credit-free `image t2i` end-to-end under `GFLOW_CLI_BROWSER_ENGINE=patchright`, 5-layer ledger + missing-dep/invalid-enum/default-path checks; 403→200 premise documented as pending a hot profile). v0.14.0 / v0.15.0 / v0.15.1 shipped without a dedicated doc (CI + the v0.13.0 baseline). Prior: [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.20.1](LIVE_VERIFICATION_v0.20.1.md) (Aspect ratio overrides in Agentic & Classic cohorts; skipped honestly due to sandbox execution). Prior: [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.20.1/docs/LIVE_VERIFICATION_v0.20.0.md

@@ -0,0 +1,76 @@
+# Live verification — v0.20.0 (Agentic UI driver)
+
+> Hand-run against the real Google Flow editor on profile `denon82`. v0.20.0
+> ships the pluggable `FlowUiDriver` strategy and **Agentic-cohort image
+> generation**. The agentic cohort is server-assigned and cannot be forced from
+> the client, so the deterministic trigger `GFLOW_CLI_FORCE_AGENT_UI=1` (clicks
+> the in-input "Agent" toggle) is used to exercise the agentic path. Image
+> generation is credit-free.
+
+## Environment
+
+| | |
+|---|---|
+| Branch | `feature/agentic-ui-driver` → `develop` (PR [#189](https://github.com/ffroliva/gflow-cli/pull/189)) |
+| Version | `0.19.0` working tree (pre-v0.20.0 bump) |
+| Profile | `denon82` (real-browser Chrome) |
+| Profile dir | `C:\Users\ffrol\AppData\Local\ffroliva\gflow-cli\profile_denon82` |
+| Date | 2026-06-14 |
+| Transport | `ui_automation` |
+| Engine | `playwright` |
+
+## How to reproduce
+
+```pwsh
+$env:PYTHONUTF8=1
+# Classic cohort (auto-detected):
+uv run gflow image t2i "a red apple on a rustic wooden table" --profile denon82 --aspect 16:9 --json
+uv run gflow video t2v "a golden sunset over calm ocean waves" --profile denon82 --aspect 16:9 --duration 4 --json
+
+# Agentic cohort, forced deterministically (clicks the Agent toggle):
+$env:GFLOW_CLI_FORCE_AGENT_UI="1"
+uv run gflow image t2i "a single ripe banana on a white plate" --profile denon82 --aspect 16:9 --json
+uv run gflow image t2i "three colorful macarons on a marble surface" --profile denon82 --count 3 --json
+
+# Deterministic harness (verifies forced→agentic→scrape→download, asserts file count):
+.\scripts\e2e\agentic_image_e2e.ps1 -Profile denon82 -Count 3
+```
+
+## Evidence ledger (5-layer)
+
+Each run: **file written** + **magic bytes (JPEG/MP4)** + **dimensions/size** +
+**structlog invariants** + **user-confirmable artifact (media UUID + path)**.
+
+| # | Path | Cohort | Result | Media UUID(s) | Bytes | Key structlog invariants |
+|---|---|---|---|---|---|---|
+| 1 | image t2i (classic) | classic | exit 0, 1 JPG | `f3e529ca…` | 647 KB | `ui_driver.bound mode=classic`; `crop_16_9` matched; `batchGenerateImages` 200 captured |
+| 2 | video t2v (classic) | classic | exit 0, 1 MP4 | `433a92d5…` | 6.33 MB | `video_mode_entered`; `poll_terminal STATUS_SUCCESSFUL`; `video_saved` |
+| 3 | image t2i (forced agentic, count 1) | agentic | exit 0, 1 JPG | `3722b716…` | 420 KB | `agent_mode_forced activated=true`; `ui_driver.bound mode=agentic`; full-res `getMediaUrlRedirect` URL |
+| 4 | image t2i (forced agentic, count 3) | agentic | exit 0, **3 distinct** JPGs | `0bfb4127…`, `2f5c5f9e…`, `cd8f4781…` | 596 / 590 / 629 KB | `mode=agentic`; **dedup**: multiple `<img>` nodes → 3 distinct media UUIDs |
+
+## What this proves
+
+- **Classic path unaffected** by the driver refactor (rows 1–2): image + video
+  generate and download end-to-end through the new `ClassicFlowUiDriver`.
+- **Agentic image generation works end-to-end** (rows 3–4): the Agent toggle
+  flips the composer to agentic, the agentic driver encodes settings into the
+  prompt, types into the Slate composer, **scrapes** the generated assets from
+  the DOM (page-level network capture is dead in this cohort — Web-Worker
+  delegated), **deduplicates by media UUID**, and downloads via the same-origin
+  `labs.google/.../getMediaUrlRedirect` redirect (allow-listed for download).
+- **Synthetic `GeneratedImage` fields** (`seed=0`, `workflow_id=""`,
+  `dimensions=(0,0)`) flow through the save/report path without error.
+
+## Not verified this cycle (recorded honestly)
+
+- **A natural (non-forced) agentic load end-to-end:** the cohort flapped to
+  classic during the windows tested; the forced path exercises identical driver
+  code, but a naturally-served agentic load was not captured generating.
+- **A positive content-policy refusal in the agentic cohort:** detection is
+  scoped to alert/dialog regions pending a captured sample (a chat-message-only
+  refusal currently misses → timeout). See `docs/AGENT_UI_E2E.md`.
+- **Agentic video:** out of scope — raises `FlowAgentUiError` (exit 25) pending a
+  video scraping capture.
+
+See [docs/AGENT_UI_E2E.md](AGENT_UI_E2E.md) for the repeatable procedure and the
+three render-race / detection bugs this live testing surfaced and fixed.

gflow_cli-0.20.1/docs/LIVE_VERIFICATION_v0.20.1.md

@@ -0,0 +1,19 @@
+# Live Verification — v0.20.1
+
+Feature under test:
+- **Aspect ratio overrides in Agentic & Classic cohorts** ([#193](https://github.com/ffroliva/gflow-cli/issues/193)).
+- **`GFLOW_CLI_PREFER_CLASSIC`** config option (`prefer_classic` setting).
+
+## Live Verification Status
+
+Live verification was **not run this cycle** (skipped honestly per the release protocol).
+
+### Reason
+The release prep was executed in an automated agent sandbox environment where live Google Flow credentials (`GFLOW_LIVE` and `GFLOW_CLI_E2E_PROFILE`) are not configured.
+
+### Local Verification
+To ensure no regressions, the following local verification checks were executed:
+1. **Local Test Suite**: 1,765 local tests passed successfully (`pytest -m "not e2e and not live and not smoke"`).
+2. **Type Checking**: `pyright src` completed with 0 errors and 0 warnings.
+3. **Lint & Formatting**: `ruff check` and `ruff format --check` passed successfully with no violations.
+4. **Repository Hygiene**: `check_repo_hygiene.py` and `check_doc_links.py` resolved all files and links with no violations.

{gflow_cli-0.19.0 → gflow_cli-0.20.1}/pyproject.toml

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

gflow_cli-0.20.1/scripts/dev/analyze_agent_ui_capture.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+r"""Offline analyzer for gflow-agent-browser-spike captures.
+
+Reads the sandbox's agentui-capture-*.json files, classifies each composer
+state, redacts + fingerprints the gating signals, diffs them across runs
+(account / locale / engine), and emits a consolidated, redacted findings JSON.
+No browser driving — pure file processing. Raw captures stay in the sandbox.
+
+Usage:
+    .venv\Scripts\python.exe scripts\dev\analyze_agent_ui_capture.py \
+        path\to\agentui-capture-ffroliva-en-*.json \
+        path\to\agentui-capture-denon82-pt-*.json --out findings.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+
+class ComposerState(StrEnum):
+    CLASSIC_MEDIA = "classic_media"
+    AGENT_OVER_CLASSIC = "agent_over_classic"
+    FORCED_AGENT = "forced_agent"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class ComposerSignals:
+    crop_present: bool
+    agent_pill_present: bool
+    agent_chat_panel_present: bool
+    crop_recoverable: bool | None  # None = recovery not attempted
+
+
+def classify_composer(s: ComposerSignals) -> ComposerState:
+    if s.crop_present:
+        return ComposerState.CLASSIC_MEDIA
+    if not (s.agent_pill_present or s.agent_chat_panel_present):
+        return ComposerState.UNKNOWN
+    if s.crop_recoverable is True:
+        return ComposerState.AGENT_OVER_CLASSIC
+    if s.crop_recoverable is False:
+        return ComposerState.FORCED_AGENT
+    return ComposerState.UNKNOWN
+
+
+def _sha8(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()[:8] if value else ""
+
+
+def fingerprint_map(kv: dict[str, Any]) -> dict[str, str]:
+    """Reduce a {key: value} map (localStorage etc.) to {key: sha8(value)} —
+    lets us diff by presence + value-hash without persisting secrets."""
+    return {k: _sha8(str(v)) for k, v in kv.items()}
+
+
+def diff_signal_sets(a: dict[str, str], b: dict[str, str]) -> dict[str, list[str]]:
+    ka, kb = set(a), set(b)
+    return {
+        "onlyInA": sorted(ka - kb),
+        "onlyInB": sorted(kb - ka),
+        "changed": sorted(k for k in ka & kb if a[k] != b[k]),
+    }
+
+
+def load_capture(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _signals_from_capture(capture: dict[str, Any]) -> ComposerSignals:
+    s = capture.get("signals", {})
+    rec = s.get("cropRecoverable")
+    return ComposerSignals(
+        crop_present=bool(s.get("cropPresent")),
+        agent_pill_present=bool(s.get("agentPill")),
+        agent_chat_panel_present=bool(s.get("chatPanel")),
+        crop_recoverable=None if rec is None else bool(rec),
+    )
+
+
+def summarize_capture(capture: dict[str, Any]) -> dict[str, Any]:
+    gating = capture.get("gating", {})
+    return {
+        "key": f"{capture.get('profile')}/{capture.get('locale')}",
+        "profile": capture.get("profile"),
+        "locale": capture.get("locale"),
+        "engine": capture.get("engine"),
+        "navigatorWebdriver": capture.get("navigatorWebdriver"),
+        "state": classify_composer(_signals_from_capture(capture)).value,
+        "localStorageFp": fingerprint_map(gating.get("localStorage", {})),
+        "sessionStorageFp": fingerprint_map(gating.get("sessionStorage", {})),
+        "cookieNames": sorted(gating.get("documentCookieNames", [])),
+        "nextDataPagePropKeys": sorted(gating.get("nextDataPagePropKeys", [])),
+    }
+
+
+def build_findings(summaries: list[dict[str, Any]]) -> dict[str, Any]:
+    """Consolidate per-run summaries; diff the first agentic run against the
+    first classic run to surface candidate gating signals."""
+    states = {s["key"]: s["state"] for s in summaries}
+    agentic = next(
+        (s for s in summaries if s["state"] in ("forced_agent", "agent_over_classic")), None
+    )
+    classic = next((s for s in summaries if s["state"] == "classic_media"), None)
+    out: dict[str, Any] = {"runs": summaries, "states": states}
+    if agentic and classic:
+        out["localStorageDiff"] = diff_signal_sets(
+            agentic["localStorageFp"], classic["localStorageFp"]
+        )
+        out["sessionStorageDiff"] = diff_signal_sets(
+            agentic["sessionStorageFp"], classic["sessionStorageFp"]
+        )
+        out["cookieNameDiff"] = diff_signal_sets(
+            {k: "1" for k in agentic["cookieNames"]}, {k: "1" for k in classic["cookieNames"]}
+        )
+        out["nextDataKeyDiff"] = diff_signal_sets(
+            {k: "1" for k in agentic["nextDataPagePropKeys"]},
+            {k: "1" for k in classic["nextDataPagePropKeys"]},
+        )
+    else:
+        out["note"] = "need at least one agentic and one classic capture to diff gating signals"
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Analyze agentic-UI captures")
+    p.add_argument("captures", nargs="+", help="paths to agentui-capture-*.json")
+    p.add_argument("--out", default=None)
+    args = p.parse_args(argv)
+    summaries = [summarize_capture(load_capture(Path(c))) for c in args.captures]
+    findings = build_findings(summaries)
+    text = json.dumps(findings, indent=2)
+    if args.out:
+        Path(args.out).write_text(text, encoding="utf-8")
+    print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())