vrex-flow-engine 0.2.0__tar.gz → 0.2.2__tar.gz

{vrex_flow_engine-0.2.0 → vrex_flow_engine-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vrex-flow-engine
-Version: 0.2.0
+Version: 0.2.2
 Summary: Launcher + supervisor and OpenAI-compatible image/video generation service (Vrex Flow Engine).
 Author: Vrex
 License: Proprietary
@@ -37,6 +37,11 @@ crash-restart), and renders a live status dashboard.
 uvx vrex-flow-engine start
 ```
 
+`uvx` ships with [uv](https://docs.astral.sh/uv/). If you get
+`uvx: command not found`, install uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`,
+or `brew install uv`) and re-run. No uv? `pipx run vrex-flow-engine start`, or
+`pip install --user vrex-flow-engine && flow-engine start`.
+
 First run prompts for the engine API key and the Cloudflare tunnel token (saved
 to `~/.vrex-flow/config.json`, chmod 600), then brings up the engine + tunnel.
 Ctrl-C stops both cleanly.
@@ -45,7 +50,7 @@ Ctrl-C stops both cleanly.
 
 | Command | What it does |
 |---|---|
-| `vrex-flow-engine start` | Run engine + tunnel with a live dashboard. `--no-tunnel` runs the engine only. |
+| `vrex-flow-engine start` | Run engine + tunnel with a live dashboard. `--no-tunnel` runs the engine only; `--tunnel-config <path>` drives an existing cloudflared config.yml (named tunnel) instead of a token. |
 | `vrex-flow-engine setup` | Store the engine key + tunnel token. |
 | `vrex-flow-engine doctor` | Check prerequisites and probe a running engine. |
 | `vrex-flow-engine serve` | Run just the engine in the foreground. |

{vrex_flow_engine-0.2.0 → vrex_flow_engine-0.2.2}/PYPI_README.md

@@ -13,6 +13,11 @@ crash-restart), and renders a live status dashboard.
 uvx vrex-flow-engine start
 ```
 
+`uvx` ships with [uv](https://docs.astral.sh/uv/). If you get
+`uvx: command not found`, install uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`,
+or `brew install uv`) and re-run. No uv? `pipx run vrex-flow-engine start`, or
+`pip install --user vrex-flow-engine && flow-engine start`.
+
 First run prompts for the engine API key and the Cloudflare tunnel token (saved
 to `~/.vrex-flow/config.json`, chmod 600), then brings up the engine + tunnel.
 Ctrl-C stops both cleanly.
@@ -21,7 +26,7 @@ Ctrl-C stops both cleanly.
 
 | Command | What it does |
 |---|---|
-| `vrex-flow-engine start` | Run engine + tunnel with a live dashboard. `--no-tunnel` runs the engine only. |
+| `vrex-flow-engine start` | Run engine + tunnel with a live dashboard. `--no-tunnel` runs the engine only; `--tunnel-config <path>` drives an existing cloudflared config.yml (named tunnel) instead of a token. |
 | `vrex-flow-engine setup` | Store the engine key + tunnel token. |
 | `vrex-flow-engine doctor` | Check prerequisites and probe a running engine. |
 | `vrex-flow-engine serve` | Run just the engine in the foreground. |

{vrex_flow_engine-0.2.0 → vrex_flow_engine-0.2.2}/flow_engine/bridge/flow_client.py

@@ -35,6 +35,13 @@ logger = logging.getLogger(__name__)
 # need to plumb it through from the extension on every call.
 _FLOW_API_KEY = "AIzaSyBtrm0o5ab1c-Ec8ZuLcGt3oJAA5VWt3pY"
 _FLOW_CREDITS_URL = "https://aisandbox-pa.googleapis.com/v1/credits"
+
+# Concrete paygate tiers Google returns that we accept as "resolved". Google
+# periodically introduces tiers (ONE=Pro, TWO=Ultra, TIER1P5="Tier 1.5"); an
+# unknown or `PAYGATE_TIER_UNSPECIFIED` value means the tier isn't resolved.
+# Single source of truth — flow_sdk imports this for its dispatch-time guard so
+# the two sites can never drift (a drift is what silently blocked TIER1P5).
+VALID_PAYGATE_TIERS = ("PAYGATE_TIER_ONE", "PAYGATE_TIER_TWO", "PAYGATE_TIER_TIER1P5")
 # Minimum gap between paygate-tier refreshes when the same Bearer token
 # is re-delivered. Tier rarely changes; 60 s is fine for AccountPanel
 # freshness and tames the credits-fetch storm an old extension can
@@ -182,9 +189,9 @@ class FlowClient:
             logger.warning("fetch_paygate_tier: response was not JSON")
             return False
         tier = data.get("userPaygateTier")
-        if tier not in ("PAYGATE_TIER_ONE", "PAYGATE_TIER_TWO"):
+        if tier not in VALID_PAYGATE_TIERS:
             logger.warning(
-                "fetch_paygate_tier: response missing userPaygateTier (got %r)",
+                "fetch_paygate_tier: unsupported userPaygateTier (got %r)",
                 tier,
             )
             return False

{vrex_flow_engine-0.2.0 → vrex_flow_engine-0.2.2}/flow_engine/bridge/flow_sdk.py

@@ -17,7 +17,7 @@ import time
 import uuid
 from typing import Any, Optional
 
-from flow_engine.bridge.flow_client import FlowClient
+from flow_engine.bridge.flow_client import FlowClient, VALID_PAYGATE_TIERS
 
 logger = logging.getLogger(__name__)
 
@@ -1465,7 +1465,8 @@ def _extract_project_id(resp: Any) -> Optional[str]:
         return None
 
 
-_VALID_TIERS = {"PAYGATE_TIER_ONE", "PAYGATE_TIER_TWO"}
+# Dispatch-time guard shares flow_client's single tier list (no drift).
+_VALID_TIERS = set(VALID_PAYGATE_TIERS)
 
 
 def _extract_uploaded_media_id(resp: Any) -> Optional[str]:

{vrex_flow_engine-0.2.0 → vrex_flow_engine-0.2.2}/flow_engine/cli/app.py

@@ -12,6 +12,7 @@ monorepo, `uvx --from 'git+ssh://…/multimodal.git#subdirectory=flow-engine' fl
 from __future__ import annotations
 
 import argparse
+import os
 import shutil
 import sys
 
@@ -39,10 +40,17 @@ def _run_wizard(cfg: FlowConfig) -> FlowConfig:
         "Engine API key" + (f" [dim]({mask(cfg.engine_api_key)})[/]" if cfg.has_engine_key else ""),
         password=True, default=cfg.engine_api_key, show_default=False,
     )
-    token = Prompt.ask(
-        "Cloudflare tunnel token" + (f" [dim]({mask(cfg.tunnel_token)})[/]" if cfg.has_tunnel_token else ""),
-        password=True, default=cfg.tunnel_token, show_default=False,
-    )
+    # Skip the token prompt when a tunnel config file is already configured — the
+    # config file carries its own credentials, so no token is needed.
+    if cfg.has_tunnel_config:
+        console.print(f"[dim]tunnel: using config {cfg.tunnel_config_path}[/]")
+        token = cfg.tunnel_token
+    else:
+        token = Prompt.ask(
+            "Cloudflare tunnel token" + (f" [dim]({mask(cfg.tunnel_token)})[/]" if cfg.has_tunnel_token else "")
+            + " [dim](blank if using --tunnel-config)[/]",
+            password=True, default=cfg.tunnel_token, show_default=False,
+        )
     port = Prompt.ask("HTTP port", default=str(cfg.http_port or DEFAULT_PORT))
     base = Prompt.ask("Public base URL", default=cfg.public_base_url or DEFAULT_PUBLIC_BASE_URL)
     cfg.engine_api_key = key.strip()
@@ -68,6 +76,8 @@ def _cmd_start(args: argparse.Namespace) -> int:
         cfg.engine_api_key = args.engine_key
     if args.tunnel_token:
         cfg.tunnel_token = args.tunnel_token
+    if args.tunnel_config:
+        cfg.tunnel_config_path = os.path.abspath(os.path.expanduser(args.tunnel_config))
     if args.port:
         cfg.http_port = args.port
     if args.public_url:
@@ -75,7 +85,8 @@ def _cmd_start(args: argparse.Namespace) -> int:
 
     with_tunnel = not args.no_tunnel
     # Fill gaps interactively unless told not to; then persist for next time.
-    needs = not cfg.has_engine_key or (with_tunnel and not cfg.has_tunnel_token)
+    # A tunnel config file satisfies the tunnel requirement in place of a token.
+    needs = not cfg.has_engine_key or (with_tunnel and not cfg.has_tunnel_auth)
     if needs and not args.non_interactive:
         cfg = _run_wizard(cfg)
         save_config(cfg)
@@ -107,7 +118,10 @@ def _cmd_doctor(_: argparse.Namespace) -> int:
     line(bool(shutil.which("cloudflared")), "cloudflared installed", shutil.which("cloudflared") or "missing")
     line(CONFIG_FILE.exists(), "config present", str(CONFIG_FILE))
     line(cfg.has_engine_key, "engine API key set", mask(cfg.engine_api_key))
-    line(cfg.has_tunnel_token, "tunnel token set", mask(cfg.tunnel_token))
+    if cfg.has_tunnel_config:
+        line(os.path.isfile(cfg.tunnel_config_path), "tunnel config file", cfg.tunnel_config_path)
+    else:
+        line(cfg.has_tunnel_token, "tunnel token set", mask(cfg.tunnel_token))
     h = health.probe_engine(cfg.http_port)
     if h:
         line(True, f"engine responding on :{cfg.http_port}",
@@ -124,6 +138,7 @@ def build_parser() -> argparse.ArgumentParser:
     ps = sub.add_parser("start", help="run engine + tunnel with a live dashboard")
     ps.add_argument("--engine-key", help="engine API key (overrides stored/env)")
     ps.add_argument("--tunnel-token", help="Cloudflare tunnel token (overrides stored/env)")
+    ps.add_argument("--tunnel-config", help="path to a cloudflared config.yml (named tunnel; used instead of a token)")
     ps.add_argument("--port", type=int, help=f"HTTP port (default {DEFAULT_PORT})")
     ps.add_argument("--public-url", help="public base URL")
     ps.add_argument("--no-tunnel", action="store_true", help="run the engine only (skip cloudflared)")

{vrex_flow_engine-0.2.0 → vrex_flow_engine-0.2.2}/flow_engine/cli/config.py

@@ -27,6 +27,10 @@ class FlowConfig:
 
     engine_api_key: str = ""
     tunnel_token: str = ""
+    # Alternative to a token: a cloudflared config file (named-tunnel with a
+    # credentials-file + local ingress). When set, the tunnel runs via
+    # `cloudflared tunnel --config <path> run` and no token is needed.
+    tunnel_config_path: str = ""
     http_port: int = DEFAULT_PORT
     public_base_url: str = DEFAULT_PUBLIC_BASE_URL
 
@@ -38,6 +42,15 @@ class FlowConfig:
     def has_tunnel_token(self) -> bool:
         return bool(self.tunnel_token.strip())
 
+    @property
+    def has_tunnel_config(self) -> bool:
+        return bool(self.tunnel_config_path.strip())
+
+    @property
+    def has_tunnel_auth(self) -> bool:
+        """Either a token or a config file is enough to run the tunnel."""
+        return self.has_tunnel_token or self.has_tunnel_config
+
 
 def load_config() -> FlowConfig:
     """Read the on-disk config, tolerating a missing file or unknown keys.
@@ -64,6 +77,7 @@ def save_config(cfg: FlowConfig) -> Path:
     payload = {
         "engine_api_key": cfg.engine_api_key,
         "tunnel_token": cfg.tunnel_token,
+        "tunnel_config_path": cfg.tunnel_config_path,
         "http_port": cfg.http_port,
         "public_base_url": cfg.public_base_url,
     }

{vrex_flow_engine-0.2.0 → vrex_flow_engine-0.2.2}/flow_engine/cli/supervisor.py

@@ -9,6 +9,7 @@ or SIGTERM stops both gracefully.
 """
 from __future__ import annotations
 
+import os
 import shutil
 import signal
 import socket
@@ -45,8 +46,11 @@ def preflight(cfg: FlowConfig, with_tunnel: bool) -> bool:
             "    other:  https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/"
         )
         ok = False
-    if with_tunnel and not cfg.has_tunnel_token:
-        console.print("[red]✗[/] no tunnel token — run [bold]flow-engine setup[/] (or pass --no-tunnel)")
+    if with_tunnel and cfg.has_tunnel_config and not os.path.isfile(cfg.tunnel_config_path):
+        console.print(f"[red]✗[/] tunnel config not found: {cfg.tunnel_config_path}")
+        ok = False
+    if with_tunnel and not cfg.has_tunnel_auth:
+        console.print("[red]✗[/] no tunnel token or --tunnel-config — run [bold]flow-engine setup[/] (or pass --no-tunnel)")
         ok = False
     if _port_in_use(cfg.http_port):
         console.print(f"[yellow]![/] port {cfg.http_port} already in use — the engine may fail to bind")
@@ -94,14 +98,23 @@ class Supervisor:
         )
 
     def _build_tunnel(self) -> ManagedProcess:
-        token = self.cfg.tunnel_token
-        argv = ["cloudflared", "--no-autoupdate", "tunnel", "run", "--token", token]
+        # A config file (named tunnel with local ingress) takes precedence over a
+        # token — it carries its own credentials-file + `flow.getvrex.com → :8101`
+        # ingress, which a token/remotely-managed run does not.
+        if self.cfg.has_tunnel_config:
+            path = self.cfg.tunnel_config_path
+            argv = ["cloudflared", "tunnel", "--config", path, "run"]
+            display = f"cloudflared tunnel --config {path} run"
+        else:
+            token = self.cfg.tunnel_token
+            argv = ["cloudflared", "--no-autoupdate", "tunnel", "run", "--token", token]
+            display = f"cloudflared --no-autoupdate tunnel run --token {mask(token)}"
         return ManagedProcess(
             "tunnel",
             argv,
             log_file=LOGS_DIR / "tunnel.log",
             on_line=self._on_line,
-            display=f"cloudflared --no-autoupdate tunnel run --token {mask(token)}",
+            display=display,
         )
 
     def _supervise(self, proc: ManagedProcess) -> None:

{vrex_flow_engine-0.2.0 → vrex_flow_engine-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vrex-flow-engine"
-version = "0.2.0"
+version = "0.2.2"
 description = "Launcher + supervisor and OpenAI-compatible image/video generation service (Vrex Flow Engine)."
 # Neutral public description (the in-repo README.md carries the full internal docs).
 readme = "PYPI_README.md"

{vrex_flow_engine-0.2.0 → vrex_flow_engine-0.2.2}/vrex_flow_engine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vrex-flow-engine
-Version: 0.2.0
+Version: 0.2.2
 Summary: Launcher + supervisor and OpenAI-compatible image/video generation service (Vrex Flow Engine).
 Author: Vrex
 License: Proprietary
@@ -37,6 +37,11 @@ crash-restart), and renders a live status dashboard.
 uvx vrex-flow-engine start
 ```
 
+`uvx` ships with [uv](https://docs.astral.sh/uv/). If you get
+`uvx: command not found`, install uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`,
+or `brew install uv`) and re-run. No uv? `pipx run vrex-flow-engine start`, or
+`pip install --user vrex-flow-engine && flow-engine start`.
+
 First run prompts for the engine API key and the Cloudflare tunnel token (saved
 to `~/.vrex-flow/config.json`, chmod 600), then brings up the engine + tunnel.
 Ctrl-C stops both cleanly.
@@ -45,7 +50,7 @@ Ctrl-C stops both cleanly.
 
 | Command | What it does |
 |---|---|
-| `vrex-flow-engine start` | Run engine + tunnel with a live dashboard. `--no-tunnel` runs the engine only. |
+| `vrex-flow-engine start` | Run engine + tunnel with a live dashboard. `--no-tunnel` runs the engine only; `--tunnel-config <path>` drives an existing cloudflared config.yml (named tunnel) instead of a token. |
 | `vrex-flow-engine setup` | Store the engine key + tunnel token. |
 | `vrex-flow-engine doctor` | Check prerequisites and probe a running engine. |
 | `vrex-flow-engine serve` | Run just the engine in the foreground. |

{vrex_flow_engine-0.2.0 → vrex_flow_engine-0.2.2}/vrex_flow_engine.egg-info/SOURCES.txt

@@ -1,5 +1,4 @@
 PYPI_README.md
-README.md
 pyproject.toml
 flow_engine/__init__.py
 flow_engine/catalog.py

vrex_flow_engine-0.2.0/README.md

@@ -1,259 +0,0 @@
-# flow-engine
-
-Host a **Google Flow browser-extension instance** and expose **OpenAI-compatible
-image/video generation endpoints** backed by Google Flow (labs.google).
-
-flow-engine drives a Chrome extension that borrows your authenticated Flow
-session (token + cookies + reCAPTCHA solving) and proxies Flow's private
-`aisandbox-pa.googleapis.com` calls, mapping the results onto familiar OpenAI
-request/response shapes. Python package `flow-engine`, import module
-`flow_engine`, console command `flow-engine` (subcommands: `start`, `serve`,
-`setup`, `doctor`).
-
-```
-OpenAI client ──HTTP :8101──> flow-engine ──WS :9223──> Chrome extension ──fetch──> Google Flow
-                               (this repo)               (extension/, in your browser)
-```
-
-In production the HTTP surface is published at `https://flow.getvrex.com`
-(a `cloudflared` tunnel → `127.0.0.1:8101`); the Next.js app reaches it via
-`FLOW_ENGINE_URL`. See "Expose to production" below.
-
-## Endpoints
-
-- `POST /v1/images/generations` — synchronous image (Nano Banana 2).
-- `POST /v1/videos/generations` + `GET /v1/videos/{id}` — async video job + poll (Veo 3.1 lite).
-- `GET /v1/videos/{id}/debug` — raw `{dispatch, last_poll}` Google payloads for a job (troubleshooting).
-- `POST /v1/flow/uploads` — image **or video** bytes → Flow media id (routes by mime).
-- `GET /v1/models` — model catalog (cached on disk, refresh with `?refresh=1`).
-- `GET /media/{id}` — cached generated bytes at a stable URL.
-- `GET /api/health` — liveness + extension-connected status (ungated).
-
-`/v1/*` and `/api/pool/status` require `Authorization: Bearer <FLOW_ENGINE_API_KEY>`.
-`/api/health` and `/media/{id}` are ungated.
-
-## Requirements
-
-- Python 3.10+
-- Google Chrome signed in to **labs.google** with a Flow tab open, and the
-  extension in `extension/` loaded (chrome://extensions → Load unpacked).
-- A Flow account (Pro or Ultra — the paygate tier is read from your session).
-- `cloudflared` (only for exposing to production).
-
-> The extension's `background.js` hardcodes `ws://127.0.0.1:9223` and
-> `http://127.0.0.1:8101/api/ext/callback`, so flow-engine defaults to those
-> ports. It therefore **cannot run alongside the legacy flowboard agent on
-> defaults** — change both the env vars and the extension URLs to run both.
-
-## Quickstart — one command
-
-`flow-engine start` is a supervisor: it stores your secrets, launches the engine
-**and** the Cloudflare tunnel as child processes, restarts either on crash, and
-renders a live status dashboard. Run it with [uv](https://docs.astral.sh/uv/)
-(the Python equivalent of `npx` — no manual venv):
-
-```bash
-# from the monorepo (until published to PyPI):
-uvx --from 'git+ssh://git@github.com/getvrex/multimodal.git#subdirectory=flow-engine' flow-engine start
-
-# once published: uvx flow-engine start
-```
-
-First run prompts for the **engine API key** (must match the value the Next.js
-app sends — `FLOW_ENGINE_API_KEY` on Vrex Multimodal / `.env.prd`) and the
-**Cloudflare tunnel token** (dashboard → Zero Trust → Networks → Tunnels → your
-tunnel → "run a connector"). Both are saved to `~/.vrex-flow/config.json` (0600)
-so later runs need no input. Then it brings up the engine + tunnel and shows:
-
-```
-🎬 Vrex Flow Engine   ● running   uptime 3m02s
-┌ engine ──────────────┐ ┌ tunnel ───────────────┐
-│ status     ● UP       │ │ status  ● connected    │
-│ extension  ● connected│ │ public  flow.getvrex.com│
-│ instances  1          │ │ →       127.0.0.1:8101  │
-└──────────────────────┘ └───────────────────────┘
-```
-
-The one thing the CLI can't automate: open a `labs.google/fx/tools/flow` tab in
-Chrome with the `extension/` loaded and signed into a Flow Pro/Ultra account.
-Until you do, the dashboard shows `extension ● OPEN A FLOW TAB`. Ctrl-C stops
-both processes cleanly.
-
-### CLI commands
-
-| Command | What it does |
-|---|---|
-| `flow-engine start` | Supervise engine + tunnel + live dashboard (the one-liner). `--no-tunnel` runs the engine only; `--non-interactive` fails instead of prompting. |
-| `flow-engine setup` | (Re)store the engine key + tunnel token in `~/.vrex-flow/config.json`. |
-| `flow-engine doctor` | Check prerequisites (python, cloudflared, config) and probe a running engine. |
-| `flow-engine serve` | Run just the engine in the foreground (for systemd / your own supervisor). |
-
-Secrets can also come from env (`FLOW_ENGINE_API_KEY`, `CLOUDFLARE_TUNNEL_TOKEN`)
-or flags (`--engine-key`, `--tunnel-token`) — flags > env > stored config.
-
-## Run manually (without the CLI)
-
-The engine reads config from the environment directly — **no `.env` auto-load**.
-`FLOW_ENGINE_API_KEY` is **required**; the server refuses to boot without it.
-
-```bash
-cd flow-engine
-python -m venv .venv && source .venv/bin/activate
-pip install -e .
-export FLOW_ENGINE_API_KEY=<shared-secret>     # must match the caller's key
-flow-engine serve                              # serves :8101 (HTTP) + :9223 (WS)
-# equivalent: python -m flow_engine.main
-```
-
-Load `extension/` in Chrome, open a `labs.google/fx/tools/flow` tab, then check:
-
-```bash
-curl localhost:8101/api/health
-# {"ok":true,"extension_connected":true,"instances":1}
-```
-
-`extension_connected:false` means no Flow tab/extension is bridged yet — open
-the tab and reload the extension.
-
-## Expose to production (Cloudflare Tunnel)
-
-The public origin `https://flow.getvrex.com` is a `cloudflared` tunnel to the
-local `:8101`. **`flow-engine start` runs this tunnel for you** (via the stored
-token), so normally you don't touch `cloudflared` directly. To run it standalone
-— e.g. the `serve` path — start the tunnel as a separate process on the same
-machine:
-
-```bash
-cloudflared tunnel run --token <your-tunnel-token>   # flow.getvrex.com → 127.0.0.1:8101
-# or, with a named-tunnel config file:
-cloudflared tunnel run --config cloudflared.yml
-```
-
-If `https://flow.getvrex.com` returns **HTTP 530 / `error code: 1033`**, the
-tunnel is down (Cloudflare has no active connection to the origin) — restart it
-(or `flow-engine start`). A `502`/`1016` instead means the tunnel is up but the
-engine on `:8101` is not — restart the engine.
-
-## Examples
-
-Image (`model` must be `NANO_BANANA_2`, or omit to force it):
-
-```bash
-curl localhost:8101/v1/images/generations \
-  -H "authorization: Bearer $FLOW_ENGINE_API_KEY" \
-  -H 'content-type: application/json' -d '{
-  "prompt": "a studio portrait, soft light", "n": 2,
-  "size": "1024x1024", "model": "NANO_BANANA_2"
-}'
-# {"created":..., "data":[{"url":"http://127.0.0.1:8101/media/<uuid>"}, ...]}
-```
-
-Video (`model` must be `veo_3_1_lite_low_priority`). Text-to-video:
-
-```bash
-JOB=$(curl -s localhost:8101/v1/videos/generations \
-  -H "authorization: Bearer $FLOW_ENGINE_API_KEY" \
-  -H 'content-type: application/json' -d '{
-    "prompt": "slow dolly in over a city at dusk",
-    "model": "veo_3_1_lite_low_priority", "seconds": 8, "size": "1280x720"
-  }' | jq -r .id)
-curl -s localhost:8101/v1/videos/$JOB \
-  -H "authorization: Bearer $FLOW_ENGINE_API_KEY"   # poll until status == "completed"
-```
-
-Image-to-video — pass the start frame inline; flow-engine uploads it for you:
-
-```bash
-curl localhost:8101/v1/videos/generations \
-  -H "authorization: Bearer $FLOW_ENGINE_API_KEY" \
-  -H 'content-type: application/json' -d "{
-    \"prompt\": \"the subject turns to camera\", \"model\": \"veo_3_1_lite_low_priority\",
-    \"start_images\": [\"$(base64 < frame.png)\"], \"size\": \"1280x720\"
-  }"
-```
-
-`start_images` / `ref_images` accept a data URL, an `http(s)` URL, or bare
-base64. Already have a Flow media id (e.g. from `/v1/flow/uploads`)? Pass it in
-`start_media_ids` / `ref_media_ids` instead — the two forms merge. Uploading a
-reference **video** (for v2v/edit/extend) works the same way via
-`/v1/flow/uploads -F file=@clip.mp4`, which returns a `"kind":"video"` media id.
-
-Extend or edit a clip you already generated — pass back the `media_id` you got
-and flow-engine resolves the rest (scene / workflow / frame count) from what it
-remembered this run:
-
-```bash
-# extend (continue a Veo clip — only Veo-generated videos can be extended)
-curl localhost:8101/v1/videos/generations \
-  -H "authorization: Bearer $FLOW_ENGINE_API_KEY" \
-  -H 'content-type: application/json' -d '{
-  "prompt": "a dog joins in", "mode": "extend",
-  "model": "veo_3_1_lite_low_priority", "source_media_id": "<prev media_id>"
-}'
-
-# edit (video-to-video rewrite)
-curl localhost:8101/v1/videos/generations \
-  -H "authorization: Bearer $FLOW_ENGINE_API_KEY" \
-  -H 'content-type: application/json' -d '{
-  "prompt": "add a green ball", "mode": "edit",
-  "model": "veo_3_1_lite_low_priority", "source_media_id": "<prev media_id>",
-  "source_seconds": 8
-}'
-```
-
-For a source flow-engine didn't generate this run (e.g. after a restart), pass
-`workflow_id` explicitly (extend resolves the scene from it; edit uses it
-directly) — plus `source_seconds` for edit so the frame range matches. The
-generation-context registry is in-memory, so it resets when the server restarts.
-
-## Configuration
-
-These configure the **engine** process (read from its environment). The
-`flow-engine start` launcher injects `FLOW_ENGINE_API_KEY` + ports for you from
-`~/.vrex-flow/config.json`; set these directly only for the manual `serve` path.
-All optional except the API key. Port/host/storage vars keep the `FLOWPROXY_`
-prefix for extension compatibility; the API key and pool size use the
-`FLOW_ENGINE_` / `FLOW_POOL_` names.
-
-| Env var | Default | Purpose |
-|---|---|---|
-| `FLOW_ENGINE_API_KEY` | — (**required**) | Bearer key gating `/v1/*`. Legacy `FLOWPROXY_API_KEY` still accepted. |
-| `FLOWPROXY_HTTP_PORT` | `8101` | HTTP surface (OpenAI endpoints + `/media` + callback). |
-| `FLOWPROXY_WS_HOST` | `127.0.0.1` | Extension WS bind — **must be loopback** (unauthenticated by design). |
-| `FLOWPROXY_EXT_WS_PORT` | `9223` | Extension WebSocket port. |
-| `FLOWPROXY_PUBLIC_BASE_URL` | `http://127.0.0.1:8101` | Base used to build absolute `/media` URLs returned to clients. |
-| `FLOW_POOL_CONCURRENCY` | `4` | Max concurrent in-flight Flow calls per instance (back-pressure, no 503). |
-| `FLOWPROXY_STORAGE` | `./storage` | Local byte cache dir. |
-| `FLOWPROXY_CATALOG_TTL` | `86400` | Model-catalog cache TTL (seconds). |
-| `VIDEO_POLL_MAX_CYCLES` / `VIDEO_POLL_INTERVAL_S` | `72` / `10` | Video poll budget (default 12 min). |
-
-## Layout
-
-```
-extension/            Chrome MV3 bridge (open a labs.google/fx/tools/flow tab)
-flow_engine/
-  bridge/             WS server + flow_client + flow_sdk (Flow API port)
-  media.py            DB-free media cache (registry + on-disk bytes)
-  jobs.py             in-memory job store + async video poller
-  session.py          readiness gate + default project + pool seam
-  catalog.py          model catalog (flow.projectInitialData), disk-cached
-  openai/             /v1/images, /v1/videos, /v1/flow/uploads, /v1/models
-  main.py             FastAPI app, /api/ext/callback, /media/{id}, lifespan
-  cli/                launcher: app (argparse), supervisor, dashboard,
-                      processes, health, config (~/.vrex-flow)
-```
-
-## Notes & caveats
-
-- **Single account.** One extension instance = one Google account = one tier.
-  Multi-tenant needs a browser-instance pool routed by API key — the
-  `session.get_bridge(api_key)` indirection is where that goes.
-- **Live Flow tab required.** Every dispatch solves an enterprise reCAPTCHA in
-  an open Flow tab; hosting needs a headful/virtual-display Chrome kept warm.
-- **Signed URLs expire.** flow-engine caches bytes locally and serves stable
-  `/media/{id}` URLs; workflow-mode video arrives as inline base64 MP4.
-- **Localhost WS is unauthenticated** by design — never bind it to a network
-  interface. Gate the HTTP `/v1/*` surface with `FLOW_ENGINE_API_KEY` when exposed.
-- **No `.env` auto-load.** The process reads `os.environ` directly — export vars
-  in the shell (or a wrapper/launchd unit), don't rely on a `.env` file.
-```