Flow-Agent Extension HTTP/SSE Bridge Implementation Plan

For AI Agents & Developers: Required sub-skills: use superpowers:subagent-driven-development or superpowers:executing-plans to execute or review tasks step by step. Use markdown checkboxes (- [x] / - [ ]) to track progress.

Working Directory: Repository root (flow-agent / flow-extension)

Goal: Transform the communication between the Flow-Agent browser extension and the local Python backend from strictly relying on WebSocket (ws://127.0.0.1:8001/ws) to an HTTP-first bidirectional bridge (HTTP polling + optional SSE), ensuring stable connectivity across fingerprint browsers like Hubstudio, AdsPower, and standard Google Chrome.

Architecture: Maintain the existing message model ("backend sends command -> extension executes on Google Flow -> extension returns results"), while upgrading the transport layer:

Registration: Extension proactively sends POST /api/ext/hello to register its session and report the captured flowKey (token).
Command Dispatch: Extension polls GET /api/ext/poll every 1–2 seconds to pull queued execution commands.
Result Callback: Extension posts results back to POST /api/ext/callback.
SSE Downlink (Optional): Low-latency push via GET /api/ext/events.
WebSocket Fallback: WebSocket (/ws) is preserved as a fallback for maximum backwards compatibility.

Tech Stack: Chrome MV3 Extension (background.js), FastAPI, flow_engine/bridge.py, flow_engine/http_bridge.py, pytest, chrome.alarms / fetch.

Repository Layout

flow-agent/
├── .github/workflows/build.yml     # CI/CD and multi-platform build workflow
├── README.md
├── flow-agent/                     # Python Backend & CLI
│   ├── flow_engine/                # Core execution & bridge logic
│   │   ├── bridge.py               # Main bidirectional bridge router
│   │   ├── http_bridge.py          # In-memory HTTP session registry & command queue
│   │   ├── config.py               # Environment configuration & defaults
│   │   ├── media_store.py          # Media persistence & caching
│   │   └── upload.py               # Asset upload utilities
│   ├── flow_server/                # FastAPI application & endpoints
│   │   ├── app.py                  # FastAPI app factory
│   │   ├── api.py                  # API server bootstrap
│   │   ├── state.py                # Server state & lifecycle management
│   │   └── routes/                 # Modular API route handlers
│   │       ├── system.py           # Extension transport (/api/ext/*), /health, credits
│   │       ├── generation.py       # Flow video/image generation endpoints
│   │       ├── chat.py             # OpenAI-compatible chat completions
│   │       └── media.py            # Media file serving
│   ├── tests/                      # Pytest suite
│   │   ├── test_http_bridge.py     # HTTP registry unit tests
│   │   └── test_ext_http_api.py    # FastAPI extension endpoint tests
│   ├── pyproject.toml
│   └── main.py
├── flow-extension/                 # Chrome MV3 Extension
│   ├── background.js               # Service worker handling HTTP/WS bridge & polling
│   ├── manifest.json               # Extension manifest (MV3)
│   ├── content.js                  # Content script for token sniffing & DOM interaction
│   ├── injected.js                 # Network interception script
│   ├── popup.html / popup.js       # Extension status popup UI
│   └── config.js                   # Client-side configuration
├── docs/superpowers/plans/         # Engineering design & implementation plans
└── README.md                       # Documentation

Background & Technical Constraints

Previous Link Architecture

Backend flow serve listens on http://127.0.0.1:8001.
Extension establishes a connection to ws://127.0.0.1:8001/ws.
Backend sends commands via WebSocket: api_request, trpc_request, upload_video, solve_captcha, get_status, open_flow_tab, refresh_flow_tab.