vrex-flow-engine 0.2.0__py3-none-any.whl

flow_engine/bridge/ws_server.py

@@ -0,0 +1,84 @@
+"""Standalone WebSocket server on :9223 for the Chrome extension bridge.
+
+Kept separate from the FastAPI :8101 app to match flowkit's pattern — the
+extension's `background.js` connects to `ws://127.0.0.1:9223` only.
+
+Multi-instance protocol: the extension MUST send a ``register_instance``
+message as its FIRST message before any other traffic. The server registers
+(or retrieves) the PoolInstance for that account_id and binds the WS to it.
+All subsequent messages are routed to that instance's FlowClient.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+
+import websockets
+
+from flow_engine.config import EXTENSION_WS_PORT, WS_HOST
+from flow_engine.pool import pool
+
+logger = logging.getLogger(__name__)
+
+
+async def _handler(websocket) -> None:
+    # First message must be register_instance; close 1008 on protocol violation.
+    try:
+        raw = await asyncio.wait_for(websocket.recv(), timeout=10.0)
+        data = json.loads(raw)
+    except Exception:
+        await websocket.close(1008, "expected register_instance as first message")
+        return
+
+    if data.get("type") != "register_instance":
+        await websocket.close(1008, "first message must be register_instance")
+        return
+
+    account_id = data.get("accountId")
+    if not isinstance(account_id, str) or not account_id:
+        await websocket.close(1008, "accountId required in register_instance")
+        return
+
+    instance = pool.register(account_id)
+    instance.client.set_extension(websocket)
+    logger.info(
+        "instance %s connected from %s",
+        account_id,
+        getattr(websocket, "remote_address", "?"),
+    )
+
+    # Hand the extension the per-instance callback secret.
+    try:
+        await websocket.send(
+            json.dumps(
+                {"type": "callback_secret", "secret": instance.client.callback_secret}
+            )
+        )
+    except Exception:  # noqa: BLE001
+        logger.exception("failed to send callback_secret to %s", account_id)
+
+    try:
+        async for raw in websocket:
+            try:
+                msg = json.loads(raw)
+            except json.JSONDecodeError:
+                logger.warning("invalid JSON from extension %s", account_id)
+                continue
+            try:
+                await instance.client.handle_message(msg)
+            except Exception:  # noqa: BLE001
+                logger.exception("error handling message from %s", account_id)
+    except websockets.ConnectionClosed:
+        pass
+    finally:
+        instance.client.clear_extension()
+        logger.info("instance %s disconnected", account_id)
+
+
+async def run_ws_server() -> None:
+    async with websockets.serve(_handler, WS_HOST, EXTENSION_WS_PORT):
+        logger.info(
+            "WebSocket server listening on ws://%s:%d", WS_HOST, EXTENSION_WS_PORT
+        )
+        await asyncio.Future()  # run forever

flow_engine/catalog.py

@@ -0,0 +1,332 @@
+"""Dynamic model catalog, sourced from Flow's ``flow.projectInitialData``.
+
+Instead of hardcoding model keys (which Google rotates), flow_engine fetches the
+live ``modelConfig`` once and resolves the exact ``videoModelKey`` for a given
+(family, mode, aspect, duration) against the user's service tier — picking the
+variant whose ``creditMapping[tier]`` is actually a number (available), not
+``"UNAVAILABLE"``.
+
+Mode is read from each usage's ``requirements`` (data-driven), not the key
+string:
+  REFERENCES → r2v · END_IMAGE → interpolation · START_IMAGE → i2v ·
+  EXTENSION → extension · UPSAMPLE* → upsample · VIDEO_EDIT → edit · else t2v
+
+Cached process-wide; call ``refresh()`` (or hit /v1/models?refresh=1) to reload.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+from flow_engine.bridge.flow_sdk import (
+    VIDEO_EDIT_URL,
+    VIDEO_EXTEND_URL,
+    VIDEO_I2V_URL,
+    VIDEO_R2V_URL,
+    VIDEO_T2V_URL,
+    FlowSDK,
+)
+from flow_engine.config import CATALOG_TTL_S, STORAGE_DIR
+
+logger = logging.getLogger(__name__)
+
+_CACHE_FILE = STORAGE_DIR / "catalog.json"
+
+# Endpoints we can actually dispatch today (body shapes verified). interpolation
+# / upsample still need a captured request before we wire them — resolve()
+# returns endpoint=None for those so callers 400 clearly.
+_MODE_ENDPOINTS: dict[str, str] = {
+    "t2v": VIDEO_T2V_URL,
+    "i2v": VIDEO_I2V_URL,
+    "r2v": VIDEO_R2V_URL,
+    "extension": VIDEO_EXTEND_URL,
+    "edit": VIDEO_EDIT_URL,
+}
+
+
+class _Catalog:
+    def __init__(self) -> None:
+        self._loaded_at: Optional[float] = None
+        self._raw_model_config: dict[str, Any] = {}
+        self._video_families: list[dict[str, Any]] = []
+        self._image_families: list[dict[str, Any]] = []
+        self._audio_voices: list[dict[str, Any]] = []
+        self._service_tier: Optional[str] = None
+        self._lock = asyncio.Lock()
+
+    @property
+    def loaded(self) -> bool:
+        return self._loaded_at is not None
+
+    def _fresh(self) -> bool:
+        return (
+            self._loaded_at is not None
+            and (time.time() - self._loaded_at) < CATALOG_TTL_S
+        )
+
+    @property
+    def service_tier(self) -> Optional[str]:
+        return self._service_tier
+
+    async def ensure_loaded(
+        self, sdk: FlowSDK, project_id: str, *, force: bool = False
+    ) -> Optional[str]:
+        """Load the catalog if the in-memory copy is missing/stale. Tries the
+        on-disk cache before hitting Flow's heavy projectInitialData call;
+        refreshes only once per ``CATALOG_TTL_S`` (default 1 day). Returns an
+        error string on failure, else None."""
+        if self._fresh() and not force:
+            return None
+        async with self._lock:
+            if self._fresh() and not force:
+                return None
+            # On-disk cache (survives restarts) — use if still within TTL.
+            if not force and self._load_from_disk():
+                return None
+            result = await sdk.get_project_initial_data(project_id)
+            if result.get("error"):
+                return str(result["error"])[:200]
+            self._apply(result.get("data") or {})
+            self._loaded_at = time.time()
+            self._save_to_disk()
+            logger.info(
+                "catalog fetched from Flow: %d video families, %d image "
+                "families, %d voices, tier=%s",
+                len(self._video_families), len(self._image_families),
+                len(self._audio_voices), self._service_tier,
+            )
+            return None
+
+    # Families exposed via /v1/models and accepted at dispatch time.
+    # Requests for any other family are rejected at the handler level (HTTP 400).
+    _ALLOWED_VIDEO_FAMILIES: frozenset[str] = frozenset({"veo_3_1_lite_low_priority"})
+    _ALLOWED_IMAGE_FAMILIES: frozenset[str] = frozenset({"NANO_BANANA_2"})
+
+    def _apply(self, data: dict[str, Any]) -> None:
+        mc = data.get("modelConfig") or {}
+        self._raw_model_config = mc
+        # Filter to pinned families immediately so /v1/models only surfaces them.
+        all_video = mc.get("videoModelFamilies") or []
+        all_image = mc.get("imageModelFamilies") or []
+        self._video_families = [
+            f for f in all_video if f.get("id") in self._ALLOWED_VIDEO_FAMILIES
+        ]
+        self._image_families = [
+            f for f in all_image if f.get("id") in self._ALLOWED_IMAGE_FAMILIES
+        ]
+        self._service_tier = (data.get("userData") or {}).get("serviceTier")
+        contents = data.get("projectContents") or {}
+        self._audio_voices = [
+            {
+                "id": v.get("mediaId"),
+                "name": (v.get("media") or {}).get("audio", {})
+                .get("generatedAudio", {}).get("name")
+                or v.get("workflowDisplayName"),
+                "description": (v.get("media") or {}).get("audio", {})
+                .get("generatedAudio", {}).get("description"),
+            }
+            for v in (contents.get("externalReferenceMedia") or [])
+            if v.get("mediaType") == "AUDIO" and v.get("mediaId")
+        ]
+
+    def _load_from_disk(self) -> bool:
+        """Populate from the on-disk cache when present and within TTL."""
+        try:
+            blob = json.loads(_CACHE_FILE.read_text())
+        except (OSError, ValueError):
+            return False
+        fetched_at = blob.get("fetched_at")
+        if not isinstance(fetched_at, (int, float)):
+            return False
+        if (time.time() - fetched_at) >= CATALOG_TTL_S:
+            return False
+        all_video = blob.get("video_families") or []
+        all_image = blob.get("image_families") or []
+        self._video_families = [
+            f for f in all_video if f.get("id") in self._ALLOWED_VIDEO_FAMILIES
+        ]
+        self._image_families = [
+            f for f in all_image if f.get("id") in self._ALLOWED_IMAGE_FAMILIES
+        ]
+        self._audio_voices = blob.get("audio_voices") or []
+        self._service_tier = blob.get("service_tier")
+        self._loaded_at = fetched_at
+        logger.info(
+            "catalog loaded from disk cache (age %ds): %d video families",
+            int(time.time() - fetched_at), len(self._video_families),
+        )
+        return True
+
+    def _save_to_disk(self) -> None:
+        blob = {
+            "fetched_at": self._loaded_at,
+            "service_tier": self._service_tier,
+            "video_families": self._video_families,
+            "image_families": self._image_families,
+            "audio_voices": self._audio_voices,
+        }
+        try:
+            _CACHE_FILE.write_text(json.dumps(blob))
+        except OSError as exc:
+            logger.warning("could not persist catalog cache: %s", exc)
+
+    # ── resolution ─────────────────────────────────────────────────────────
+    @staticmethod
+    def _usage_mode(usage: dict[str, Any]) -> str:
+        reqs: set[str] = set()
+        for combo in usage.get("requirements") or []:
+            for r in combo:
+                reqs.add(r)
+        if any("UPSAMPLE" in r for r in reqs):
+            return "upsample"
+        if "VIDEO_REQUIREMENT_VIDEO_EDIT" in reqs:
+            return "edit"
+        if "VIDEO_REQUIREMENT_EXTENSION" in reqs:
+            return "extension"
+        if "VIDEO_REQUIREMENT_REFERENCES" in reqs:
+            return "r2v"
+        if "VIDEO_REQUIREMENT_END_IMAGE" in reqs:
+            return "interpolation"
+        if "VIDEO_REQUIREMENT_START_IMAGE" in reqs:
+            return "i2v"
+        if "VIDEO_REQUIREMENT_TEXT" in reqs:
+            return "t2v"
+        return "unknown"
+
+    @staticmethod
+    def _cost(usage: dict[str, Any], tier: Optional[str]) -> Optional[int]:
+        cm = usage.get("creditMapping") or {}
+        entry = cm.get(tier or "") or {}
+        cost = entry.get("cost")
+        return cost if isinstance(cost, int) else None
+
+    @staticmethod
+    def _aspect_short(aspect: str) -> str:
+        return "PORTRAIT" if "PORTRAIT" in (aspect or "") else "LANDSCAPE"
+
+    def _family(self, family_id: str) -> Optional[dict[str, Any]]:
+        for fam in self._video_families:
+            if fam.get("id") == family_id:
+                return fam
+        return None
+
+    def resolve_video(
+        self,
+        family_id: str,
+        mode: str,
+        aspect: str,
+        duration: Optional[int],
+        service_tier: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Resolve a concrete dispatch config for the selection.
+
+        Returns ``{key, endpoint, mode, video_length, max_image_inputs,
+        max_audio_references, outputs_audio, credits}`` or ``{error}``.
+        """
+        tier = service_tier or self._service_tier
+        fam = self._family(family_id)
+        if fam is None:
+            return {"error": f"unknown_video_model_family_{family_id}"}
+        aspect_short = self._aspect_short(aspect)
+
+        cands = [
+            u for u in (fam.get("usages") or [])
+            if self._usage_mode(u) == mode
+            and aspect_short in (u.get("supportedAspectRatios") or [])
+        ]
+        if not cands:
+            return {
+                "error": f"{family_id}_has_no_{mode}_usage_for_{aspect_short}"
+            }
+        if duration is not None:
+            dur = [u for u in cands if u.get("videoLengthSeconds") == duration]
+            cands = dur or cands
+        # Prefer the variant available to this tier (cost is a number).
+        avail = [u for u in cands if self._cost(u, tier) is not None]
+        pick = (avail or cands)[0]
+
+        endpoint = _MODE_ENDPOINTS.get(mode)
+        if endpoint is None:
+            return {
+                "error": (
+                    f"mode_{mode}_not_dispatchable_yet "
+                    f"(resolved key {pick.get('key')!r}; endpoint not captured)"
+                ),
+                "key": pick.get("key"),
+                "mode": mode,
+            }
+        spec = pick.get("inputSpec") or {}
+        return {
+            "key": pick.get("key"),
+            "endpoint": endpoint,
+            "mode": mode,
+            "video_length": pick.get("videoLengthSeconds"),
+            "max_image_inputs": pick.get("maxImageInputs"),
+            "max_audio_references": spec.get("maxAudioReferences"),
+            "outputs_audio": pick.get("outputsAudio"),
+            "credits": self._cost(pick, tier),
+        }
+
+    # ── catalog views (for /v1/models) ─────────────────────────────────────
+    def video_models_api(self, service_tier: Optional[str] = None) -> list[dict]:
+        tier = service_tier or self._service_tier
+        out: list[dict[str, Any]] = []
+        for fam in self._video_families:
+            usages = fam.get("usages") or []
+            modes: dict[str, dict[str, Any]] = {}
+            for u in usages:
+                mode = self._usage_mode(u)
+                cost = self._cost(u, tier)
+                if cost is None:
+                    continue  # not available to this tier
+                m = modes.setdefault(
+                    mode,
+                    {"mode": mode, "durations": set(), "aspects": set(),
+                     "dispatchable": mode in _MODE_ENDPOINTS, "credits": cost},
+                )
+                if u.get("videoLengthSeconds"):
+                    m["durations"].add(u["videoLengthSeconds"])
+                for a in u.get("supportedAspectRatios") or []:
+                    m["aspects"].add(a)
+                m["credits"] = min(m["credits"], cost)
+            if not modes:
+                continue
+            out.append({
+                "id": fam.get("id"),
+                "object": "model",
+                "kind": "video",
+                "display_name": fam.get("displayName"),
+                "owned_by": "google-flow",
+                "modes": [
+                    {**v, "durations": sorted(v["durations"]),
+                     "aspects": sorted(v["aspects"])}
+                    for v in modes.values()
+                ],
+            })
+        return out
+
+    def image_models_api(self, service_tier: Optional[str] = None) -> list[dict]:
+        tier = service_tier or self._service_tier
+        out: list[dict[str, Any]] = []
+        for fam in self._image_families:
+            usages = fam.get("usages") or []
+            keys = [u.get("key") for u in usages if u.get("key")]
+            out.append({
+                "id": fam.get("id"),
+                "object": "model",
+                "kind": "image",
+                "display_name": fam.get("displayName"),
+                "owned_by": "google-flow",
+                "keys": keys,
+            })
+        return out
+
+    def audio_voices(self) -> list[dict[str, Any]]:
+        return list(self._audio_voices)
+
+
+catalog = _Catalog()

flow_engine/cli/__init__.py

@@ -0,0 +1 @@
+"""flow-engine launcher CLI: setup wizard + supervisor + live dashboard."""

flow_engine/cli/app.py

@@ -0,0 +1,149 @@
+"""flow-engine CLI entrypoint.
+
+Commands:
+  start   supervise the engine + Cloudflare tunnel with a live dashboard (the one-liner)
+  serve   run just the engine (foreground uvicorn) — for systemd / a custom supervisor
+  setup   interactive wizard to store the engine key + tunnel token (~/.vrex-flow)
+  doctor  check prerequisites and probe a running engine
+
+Distributed Python-native: `uvx flow-engine start` (once published) or, from the
+monorepo, `uvx --from 'git+ssh://…/multimodal.git#subdirectory=flow-engine' flow-engine start`.
+"""
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+
+from rich.console import Console
+from rich.prompt import Prompt
+
+from . import health
+from .config import (
+    CONFIG_FILE,
+    DEFAULT_PORT,
+    DEFAULT_PUBLIC_BASE_URL,
+    FlowConfig,
+    load_config,
+    mask,
+    save_config,
+)
+
+console = Console()
+
+
+def _run_wizard(cfg: FlowConfig) -> FlowConfig:
+    """Prompt for the secrets/ports, keeping existing values as defaults."""
+    console.print("[bold]Vrex Flow Engine — setup[/]  (stored at ~/.vrex-flow/config.json, chmod 600)\n")
+    key = Prompt.ask(
+        "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,
+    )
+    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()
+    cfg.tunnel_token = token.strip()
+    cfg.http_port = int(port)
+    cfg.public_base_url = base.strip()
+    return cfg
+
+
+def _cmd_setup(_: argparse.Namespace) -> int:
+    cfg = _run_wizard(load_config())
+    path = save_config(cfg)
+    console.print(f"\n[green]✓[/] saved to [bold]{path}[/]")
+    return 0
+
+
+def _cmd_start(args: argparse.Namespace) -> int:
+    from .supervisor import Supervisor, preflight
+
+    cfg = load_config()
+    # CLI flags override stored/env values (non-interactive hosts).
+    if args.engine_key:
+        cfg.engine_api_key = args.engine_key
+    if args.tunnel_token:
+        cfg.tunnel_token = args.tunnel_token
+    if args.port:
+        cfg.http_port = args.port
+    if args.public_url:
+        cfg.public_base_url = args.public_url
+
+    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)
+    if needs and not args.non_interactive:
+        cfg = _run_wizard(cfg)
+        save_config(cfg)
+
+    if not preflight(cfg, with_tunnel):
+        return 1
+    return Supervisor(cfg, with_tunnel=with_tunnel).run()
+
+
+def _cmd_serve(_: argparse.Namespace) -> int:
+    # Raw engine only (what `start` spawns as a child, and what systemd would use).
+    from flow_engine.main import main as serve_main
+
+    serve_main()
+    return 0
+
+
+def _cmd_doctor(_: argparse.Namespace) -> int:
+    cfg = load_config()
+    ok = True
+
+    def line(good: bool, label: str, detail: str = "") -> None:
+        nonlocal ok
+        ok = ok and good
+        mark = "[green]✓[/]" if good else "[red]✗[/]"
+        console.print(f"{mark} {label}" + (f"  [dim]{detail}[/]" if detail else ""))
+
+    line(sys.version_info >= (3, 10), "python ≥ 3.10", sys.version.split()[0])
+    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))
+    h = health.probe_engine(cfg.http_port)
+    if h:
+        line(True, f"engine responding on :{cfg.http_port}",
+             f"extension_connected={h.get('extension_connected')} instances={h.get('instances')}")
+    else:
+        console.print(f"[dim]·[/] engine not running on :{cfg.http_port} (start it with [bold]flow-engine start[/])")
+    return 0 if ok else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="flow-engine", description="Vrex Flow Engine launcher + supervisor")
+    sub = p.add_subparsers(dest="command")
+
+    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("--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)")
+    ps.add_argument("--non-interactive", action="store_true", help="fail instead of prompting for missing secrets")
+    ps.set_defaults(func=_cmd_start)
+
+    sub.add_parser("serve", help="run just the engine (foreground uvicorn)").set_defaults(func=_cmd_serve)
+    sub.add_parser("setup", help="store engine key + tunnel token").set_defaults(func=_cmd_setup)
+    sub.add_parser("doctor", help="check prerequisites + probe a running engine").set_defaults(func=_cmd_doctor)
+    return p
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    if not getattr(args, "command", None):
+        parser.print_help()
+        raise SystemExit(0)
+    raise SystemExit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

flow_engine/cli/config.py

@@ -0,0 +1,81 @@
+"""Persistent CLI config for the flow-engine supervisor.
+
+Stores the engine API key + Cloudflare tunnel token (both secrets) plus the
+HTTP port and public base URL in ``~/.vrex-flow/config.json`` (chmod 0600).
+The running engine itself does NOT read this file — the supervisor injects the
+key into the child process env — so this is purely the launcher's own state.
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass, fields
+from pathlib import Path
+
+CONFIG_DIR = Path(os.getenv("VREX_FLOW_HOME") or (Path.home() / ".vrex-flow"))
+CONFIG_FILE = CONFIG_DIR / "config.json"
+LOGS_DIR = CONFIG_DIR / "logs"
+
+DEFAULT_PORT = 8101
+DEFAULT_PUBLIC_BASE_URL = "https://flow.getvrex.com"
+
+
+@dataclass
+class FlowConfig:
+    """Launcher state. `engine_api_key` + `tunnel_token` are secrets."""
+
+    engine_api_key: str = ""
+    tunnel_token: str = ""
+    http_port: int = DEFAULT_PORT
+    public_base_url: str = DEFAULT_PUBLIC_BASE_URL
+
+    @property
+    def has_engine_key(self) -> bool:
+        return bool(self.engine_api_key.strip())
+
+    @property
+    def has_tunnel_token(self) -> bool:
+        return bool(self.tunnel_token.strip())
+
+
+def load_config() -> FlowConfig:
+    """Read the on-disk config, tolerating a missing file or unknown keys.
+    Env vars FLOW_ENGINE_API_KEY / CLOUDFLARE_TUNNEL_TOKEN override the file so a
+    non-interactive host can inject secrets without writing them to disk."""
+    cfg = FlowConfig()
+    if CONFIG_FILE.exists():
+        known = {f.name for f in fields(FlowConfig)}
+        data = json.loads(CONFIG_FILE.read_text())
+        cfg = FlowConfig(**{k: v for k, v in data.items() if k in known})
+    env_key = os.getenv("FLOW_ENGINE_API_KEY")
+    env_token = os.getenv("CLOUDFLARE_TUNNEL_TOKEN") or os.getenv("TUNNEL_TOKEN")
+    if env_key:
+        cfg.engine_api_key = env_key
+    if env_token:
+        cfg.tunnel_token = env_token
+    return cfg
+
+
+def save_config(cfg: FlowConfig) -> Path:
+    """Persist the config as 0600 (it holds secrets). Returns the file path."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    LOGS_DIR.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "engine_api_key": cfg.engine_api_key,
+        "tunnel_token": cfg.tunnel_token,
+        "http_port": cfg.http_port,
+        "public_base_url": cfg.public_base_url,
+    }
+    # Write then tighten perms — never leave a world-readable window on secrets.
+    CONFIG_FILE.write_text(json.dumps(payload, indent=2) + "\n")
+    os.chmod(CONFIG_FILE, stat.S_IRUSR | stat.S_IWUSR)  # 0600
+    return CONFIG_FILE
+
+
+def mask(secret: str) -> str:
+    """Render a secret for display: keep a short prefix, hide the rest."""
+    s = (secret or "").strip()
+    if not s:
+        return "(unset)"
+    return f"{s[:6]}…{s[-2:]}" if len(s) > 10 else "•" * len(s)