infinicode 2.8.23 → 2.8.25

package/packages/robopark/scheduler/preview_agent.py

@@ -1,782 +1,1011 @@
-#!/usr/bin/env python3
-"""
-RoboPark Preview Agent — runs on each robot/satellite Pi.
-
-Polls the scheduler for an active operator preview request. When active,
-opens the selected camera + microphone and publishes them to the returned
-LiveKit room. When the preview expires or is stopped, the agent leaves the
-room and releases the hardware.
-
-Also runs a small local HTTP listener for RoboVisionAI_PI's motion webhook
-(POST /api/motion/webhook target — see RoboVisionAI_PI's app_pi_clean.py).
-On a motion event it calls the scheduler's presence-triggered
-POST /api/devices/{id}/request-session and publishes into the returned room
-using the same LiveKitPublisher as the operator preview — this is the
-"scene detection" trigger point the scheduler's request-session docstring
-describes; RoboVisionAI_PI supplies the detection, this agent supplies the
-bridge to an actual session.
-
-Configuration (env / ~/.robopark/preview_agent.json):
-  SCHEDULER_URL          base URL of the RoboPark scheduler
-  ROBOT_ID               robot identity in the scheduler (defaults to hostname)
-  DEVICE_TOKEN           long-lived device token (after enrollment)
-  ENROLLMENT_TOKEN       one-time enrollment token (device token will be saved)
-  VIDEO_DEVICE           camera path/index/name (e.g. /dev/video0, 0, "PiCamera")
-  AUDIO_DEVICE           microphone name/index or "default"
-  VIDEO_WIDTH / HEIGHT   capture resolution (default 640x480)
-  VIDEO_FPS              capture fps (default 15)
-  POLL_INTERVAL          seconds between scheduler polls (default 3)
-  HEARTBEAT_INTERVAL     seconds between device heartbeats (default 30)
-  VISION_WEBHOOK_PORT    local port for the RoboVision motion webhook (default 5057, 0 disables)
-  VISION_TRIGGER_COOLDOWN  min seconds between motion-triggered sessions (default 20)
-  VISION_SESSION_SECONDS   how long a motion-triggered session holds the publisher (default 90)
-"""
-from __future__ import annotations
-
-import argparse
-import asyncio
-import json
-import logging
-import os
-import signal
-import sys
-import threading
-import time
-from dataclasses import dataclass
-from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
-from pathlib import Path
-from typing import Optional
-
-import httpx
-
-logger = logging.getLogger("robopark.preview_agent")
-
-CONFIG_DIR = Path.home() / ".robopark"
-CONFIG_FILE = CONFIG_DIR / "preview_agent.json"
-TOKEN_FILE = CONFIG_DIR / "device_token"
-
-DEFAULT_VIDEO_WIDTH = 640
-DEFAULT_VIDEO_HEIGHT = 480
-DEFAULT_FPS = 15
-DEFAULT_POLL_INTERVAL = 3.0
-DEFAULT_HEARTBEAT_INTERVAL = 30.0
-DEFAULT_VISION_WEBHOOK_PORT = 5057
-DEFAULT_VISION_TRIGGER_COOLDOWN = 20.0
-DEFAULT_VISION_SESSION_SECONDS = 90.0
-
-
-def _load_config() -> dict:
-    cfg: dict = {}
-    if CONFIG_FILE.exists():
-        try:
-            cfg = json.loads(CONFIG_FILE.read_text(encoding="utf8"))
-        except Exception as e:
-            logger.warning(f"failed to read {CONFIG_FILE}: {e}")
-    return cfg
-
-
-def _save_config(cfg: dict) -> None:
-    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
-    CONFIG_FILE.write_text(json.dumps(cfg, indent=2), encoding="utf8")
-
-
-def _load_token() -> Optional[str]:
-    if TOKEN_FILE.exists():
-        return TOKEN_FILE.read_text(encoding="utf8").strip() or None
-    return None
-
-
-def _save_token(token: str) -> None:
-    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
-    TOKEN_FILE.write_text(token, encoding="utf8")
-    os.chmod(TOKEN_FILE, 0o600)
-
-
-async def _enroll(scheduler_url: str, enrollment_token: str, robot_id: str) -> str:
-    """Enroll this Pi with the scheduler and return the device token."""
-    import socket
-    payload = {
-        "enrollment_token": enrollment_token,
-        "name": robot_id,
-        "lan_ip": _get_lan_ip(),
-    }
-    async with httpx.AsyncClient() as client:
-        r = await client.post(
-            f"{scheduler_url.rstrip('/')}/api/devices/enroll",
-            json=payload,
-            timeout=30.0,
-        )
-        r.raise_for_status()
-        data = r.json()
-    device_token = data.get("device_token")
-    if not device_token:
-        raise RuntimeError("enrollment did not return a device_token")
-    _save_token(device_token)
-    cfg = _load_config()
-    cfg["device_id"] = data.get("device_id")
-    cfg["scheduler_url"] = data.get("scheduler_url", scheduler_url)
-    _save_config(cfg)
-    logger.info(f"enrolled as device {data.get('device_id')}")
-    return device_token
-
-
-def _get_lan_ip() -> Optional[str]:
-    try:
-        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
-        s.settimeout(0.5)
-        s.connect(("10.255.255.255", 1))
-        ip = s.getsockname()[0]
-        s.close()
-        return ip
-    except Exception:
-        return None
-
-
-async def _send_heartbeat(scheduler_url: str, device_id: str, token: str) -> None:
-    try:
-        async with httpx.AsyncClient() as client:
-            await client.post(
-                f"{scheduler_url.rstrip('/')}/api/devices/{device_id}/heartbeat",
-                json={"status": "online", "ip": _get_lan_ip()},
-                headers={"Authorization": f"Bearer {token}"},
-                timeout=10.0,
-            )
-    except Exception as e:
-        logger.debug(f"heartbeat failed: {e}")
-
-
-@dataclass
-class PreviewState:
-    active: bool = False
-    url: Optional[str] = None
-    token: Optional[str] = None
-    room: Optional[str] = None
-
-
-class PreviewAgent:
-    def __init__(self, cfg: dict):
-        self.scheduler_url = cfg.get("scheduler_url", os.getenv("SCHEDULER_URL", "http://localhost:8080"))
-        self.robot_id = cfg.get("robot_id", os.getenv("ROBOT_ID", _hostname()))
-        self.device_token: Optional[str] = cfg.get("device_token") or os.getenv("DEVICE_TOKEN") or _load_token()
-        self.device_id: Optional[str] = cfg.get("device_id")
-        self.enrollment_token: Optional[str] = cfg.get("enrollment_token")
-        self.video_device = cfg.get("video_device", os.getenv("VIDEO_DEVICE", "auto"))
-        self.audio_device = cfg.get("audio_device", os.getenv("AUDIO_DEVICE", "default"))
-        self.width = int(cfg.get("video_width", os.getenv("VIDEO_WIDTH", DEFAULT_VIDEO_WIDTH)))
-        self.height = int(cfg.get("video_height", os.getenv("VIDEO_HEIGHT", DEFAULT_VIDEO_HEIGHT)))
-        self.fps = int(cfg.get("video_fps", os.getenv("VIDEO_FPS", DEFAULT_FPS)))
-        self.poll_interval = float(cfg.get("poll_interval", os.getenv("POLL_INTERVAL", DEFAULT_POLL_INTERVAL)))
-        self.heartbeat_interval = float(cfg.get("heartbeat_interval", os.getenv("HEARTBEAT_INTERVAL", DEFAULT_HEARTBEAT_INTERVAL)))
-        self.vision_webhook_port = int(cfg.get("vision_webhook_port", os.getenv("VISION_WEBHOOK_PORT", DEFAULT_VISION_WEBHOOK_PORT)))
-        self.vision_trigger_cooldown = float(cfg.get("vision_trigger_cooldown", os.getenv("VISION_TRIGGER_COOLDOWN", DEFAULT_VISION_TRIGGER_COOLDOWN)))
-        self.vision_session_seconds = float(cfg.get("vision_session_seconds", os.getenv("VISION_SESSION_SECONDS", DEFAULT_VISION_SESSION_SECONDS)))
-
-        self._shutdown = asyncio.Event()
-        self._task: Optional[asyncio.Task] = None
-        self._session: Optional[httpx.AsyncClient] = None
-        self._current_state: PreviewState = PreviewState()
-        self._publisher: Optional["LiveKitPublisher"] = None
-        self._loop: Optional[asyncio.AbstractEventLoop] = None
-        self._vision_server: Optional[ThreadingHTTPServer] = None
-        self._last_vision_trigger: float = 0.0
-        self._vision_active_until: float = 0.0
-
-    async def run(self) -> None:
-        enrollment_token = os.getenv("ENROLLMENT_TOKEN") or self.enrollment_token
-        if not self.device_token and enrollment_token:
-            self.device_token = await _enroll(self.scheduler_url, enrollment_token, self.robot_id)
-
-        if not self.device_token:
-            logger.error("no DEVICE_TOKEN and no ENROLLMENT_TOKEN; cannot poll scheduler")
-            sys.exit(1)
-
-        self._session = httpx.AsyncClient()
-
-        # Must come after self._session exists — _resolve_device_id() guards
-        # on it and silently no-ops otherwise. On a fresh enroll (no cached
-        # device_id in ~/.robopark/preview_agent.json) that made this ALWAYS
-        # no-op, so device_id never resolved and preview/agent polling fell
-        # back to robot_id (the display name) instead of the real device_id
-        # for the entire session — the same id-mismatch bug fixed elsewhere,
-        # recurring here only on a first-ever enroll.
-        if not self.device_id:
-            await self._resolve_device_id()
-
-        self._loop = asyncio.get_running_loop()
-        self._start_vision_webhook_server()
-
-        tasks = [
-            asyncio.create_task(self._poll_loop()),
-            asyncio.create_task(self._heartbeat_loop()),
-        ]
-        await self._shutdown.wait()
-        for t in tasks:
-            t.cancel()
-            try:
-                await t
-            except asyncio.CancelledError:
-                pass
-        if self._vision_server:
-            self._vision_server.shutdown()
-        await self._stop_publisher()
-        await self._session.aclose()
-
-    async def _resolve_device_id(self) -> None:
-        """Look up our device_id from the scheduler using the token."""
-        if not self._session or not self.device_token:
-            return
-        try:
-            r = await self._session.get(
-                f"{self.scheduler_url.rstrip('/')}/api/devices",
-                headers={"Authorization": f"Bearer {self.device_token}"},
-                timeout=10.0,
-            )
-            r.raise_for_status()
-            for d in r.json():
-                if d.get("name") == self.robot_id:
-                    self.device_id = d.get("id")
-                    cfg = _load_config()
-                    cfg["device_id"] = self.device_id
-                    _save_config(cfg)
-                    return
-        except Exception as e:
-            logger.warning(f"could not resolve device_id: {e}")
-
-    async def _poll_loop(self) -> None:
-        while not self._shutdown.is_set():
-            try:
-                if time.time() >= self._vision_active_until:
-                    # A motion-triggered session (if any) has ended its lease —
-                    # let the operator-preview poll reconcile the publisher again.
-                    if self._vision_active_until:
-                        self._vision_active_until = 0.0
-                        await self._stop_publisher()
-                        self._current_state = PreviewState()
-                    state = await self._fetch_preview_state()
-                    await self._apply_state(state)
-                # else: a vision-triggered session currently owns the publisher —
-                # don't let the (unrelated) operator-preview state tear it down.
-            except Exception as e:
-                logger.warning(f"poll error: {e}")
-            try:
-                await asyncio.wait_for(self._shutdown.wait(), timeout=self.poll_interval)
-            except asyncio.TimeoutError:
-                pass
-
-    async def _heartbeat_loop(self) -> None:
-        while not self._shutdown.is_set():
-            if self.device_id and self.device_token:
-                await _send_heartbeat(self.scheduler_url, self.device_id, self.device_token)
-            try:
-                await asyncio.wait_for(self._shutdown.wait(), timeout=self.heartbeat_interval)
-            except asyncio.TimeoutError:
-                pass
-
-    async def _fetch_preview_state(self) -> PreviewState:
-        if not self._session or not self.device_token:
-            return PreviewState()
-        r = await self._session.get(
-            f"{self.scheduler_url.rstrip('/')}/api/robots/{self.device_id or self.robot_id}/preview/agent",
-            headers={"Authorization": f"Bearer {self.device_token}"},
-            timeout=10.0,
-        )
-        r.raise_for_status()
-        data = r.json()
-        if not data.get("active"):
-            return PreviewState()
-        return PreviewState(
-            active=True,
-            url=data.get("url"),
-            token=data.get("token"),
-            room=data.get("room"),
-        )
-
-    async def _apply_state(self, state: PreviewState) -> None:
-        same = (
-            state.active == self._current_state.active
-            and state.room == self._current_state.room
-            and state.token == self._current_state.token
-            and state.url == self._current_state.url
-        )
-        if same:
-            return
-        self._current_state = state
-        if not state.active:
-            await self._stop_publisher()
-            return
-        await self._start_publisher(state)
-
-    async def _start_publisher(self, state: PreviewState) -> None:
-        await self._stop_publisher()
-        if not state.url or not state.token or not state.room:
-            return
-        try:
-            pub = LiveKitPublisher(state.url, state.token, state.room, self)
-            await pub.start()
-            self._publisher = pub
-            logger.info(f"joined preview room {state.room}")
-        except Exception as e:
-            logger.error(f"failed to start publisher: {e}")
-
-    async def _stop_publisher(self) -> None:
-        if self._publisher:
-            try:
-                await self._publisher.stop()
-            except Exception as e:
-                logger.warning(f"publisher stop error: {e}")
-            self._publisher = None
-
-    # ---- vision (RoboVisionAI_PI motion webhook) -> presence-triggered session ----
-
-    def _start_vision_webhook_server(self) -> None:
-        if not self.vision_webhook_port:
-            return
-        agent = self
-
-        class Handler(BaseHTTPRequestHandler):
-            def log_message(self, fmt, *a):  # noqa: A002 — quiet by default
-                logger.debug("vision webhook: " + fmt, *a)
-
-            def do_POST(self):  # noqa: N802 — http.server's required method name
-                try:
-                    length = int(self.headers.get("Content-Length", 0))
-                    body = self.rfile.read(length) if length else b"{}"
-                    payload = json.loads(body or b"{}")
-                except Exception as e:
-                    self.send_response(400)
-                    self.end_headers()
-                    self.wfile.write(str(e).encode())
-                    return
-                self.send_response(200)
-                self.end_headers()
-                self.wfile.write(b'{"ok":true}')
-                if agent._loop:
-                    asyncio.run_coroutine_threadsafe(agent._on_vision_motion(payload), agent._loop)
-
-            def do_GET(self):  # noqa: N802
-                self.send_response(200)
-                self.end_headers()
-                self.wfile.write(b'{"status":"ok","listening_for":"robovision motion webhook"}')
-
-        try:
-            self._vision_server = ThreadingHTTPServer(("0.0.0.0", self.vision_webhook_port), Handler)
-            thread = threading.Thread(target=self._vision_server.serve_forever, daemon=True)
-            thread.start()
-            logger.info(
-                f"vision webhook listening on :{self.vision_webhook_port} — "
-                f"point RoboVisionAI_PI's POST /api/motion/webhook at "
-                f"http://<this-host>:{self.vision_webhook_port}/"
-            )
-        except Exception as e:
-            logger.error(f"could not start vision webhook server: {e}")
-            self._vision_server = None
-
-    async def _on_vision_motion(self, payload: dict) -> None:
-        now = time.time()
-        if now - self._last_vision_trigger < self.vision_trigger_cooldown:
-            logger.debug("vision trigger suppressed (cooldown)")
-            return
-        self._last_vision_trigger = now
-        if not self.device_id or not self.device_token or not self._session:
-            logger.warning("vision motion event received but not enrolled yet — ignoring")
-            return
-        logger.info("motion detected by RoboVisionAI_PI — requesting a session")
-        try:
-            r = await self._session.post(
-                f"{self.scheduler_url.rstrip('/')}/api/devices/{self.device_id}/request-session",
-                headers={"Authorization": f"Bearer {self.device_token}"},
-                timeout=10.0,
-            )
-            r.raise_for_status()
-            data = r.json()
-        except Exception as e:
-            logger.error(f"request-session failed: {e}")
-            return
-        state = PreviewState(
-            active=True,
-            url=data.get("server_url"),
-            token=data.get("token"),
-            room=data.get("room_name"),
-        )
-        self._vision_active_until = time.time() + self.vision_session_seconds
-        self._current_state = state
-        await self._start_publisher(state)
-        session_id = data.get("session_id")
-        if session_id and self._session:
-            try:
-                await self._session.post(
-                    f"{self.scheduler_url.rstrip('/')}/api/sessions/{session_id}/joined",
-                    headers={"Authorization": f"Bearer {self.device_token}"},
-                    timeout=10.0,
-                )
-            except Exception as e:
-                logger.debug(f"could not mark session joined: {e}")
-
-    def shutdown(self) -> None:
-        self._shutdown.set()
-
-
-class LiveKitPublisher:
-    """Encapsulates LiveKit room connection, camera capture and mic capture."""
-
-    def __init__(self, url: str, token: str, room_name: str, agent: PreviewAgent):
-        from livekit import rtc
-        self.url = url
-        self.token = token
-        self.room_name = room_name
-        self.agent = agent
-        self.rtc = rtc
-        self.room: Optional[rtc.Room] = None
-        self.video_source: Optional[rtc.VideoSource] = None
-        self.video_track: Optional[rtc.LocalVideoTrack] = None
-        self.audio_source: Optional[rtc.AudioSource] = None
-        self.audio_track: Optional[rtc.LocalAudioTrack] = None
-        self._stop_event = asyncio.Event()
-        self._tasks: list[asyncio.Task] = []
-        self._capture: Optional["VideoCapture"] = None
-
-    async def start(self) -> None:
-        self.room = self.rtc.Room()
-        await self.room.connect(self.url, self.token)
-
-        # Video
-        self.video_source = self.rtc.VideoSource(self.agent.width, self.agent.height)
-        self.video_track = self.rtc.LocalVideoTrack.create_video_track("camera", self.video_source)
-        vopts = self.rtc.TrackPublishOptions()
-        vopts.source = self.rtc.TrackSource.SOURCE_CAMERA
-        await self.room.local_participant.publish_track(self.video_track, vopts)
-
-        # Audio
-        self.audio_source = self.rtc.AudioSource(48000, 1)
-        self.audio_track = self.rtc.LocalAudioTrack.create_audio_track("microphone", self.audio_source)
-        aopts = self.rtc.TrackPublishOptions()
-        aopts.source = self.rtc.TrackSource.SOURCE_MICROPHONE
-        await self.room.local_participant.publish_track(self.audio_track, aopts)
-
-        self._capture = create_video_capture(self.agent.video_device, self.agent.width, self.agent.height, self.agent.fps)
-        if self._capture:
-            self._tasks.append(asyncio.create_task(self._video_loop()))
-        if has_audio():
-            self._tasks.append(asyncio.create_task(self._audio_loop()))
-
-    async def stop(self) -> None:
-        self._stop_event.set()
-        for t in self._tasks:
-            t.cancel()
-            try:
-                await t
-            except asyncio.CancelledError:
-                pass
-        self._tasks.clear()
-        if self._capture:
-            self._capture.stop()
-            self._capture = None
-        if self.room:
-            await self.room.disconnect()
-            self.room = None
-
-    async def _video_loop(self) -> None:
-        assert self._capture is not None and self.video_source is not None
-        frame_interval = 1.0 / self.agent.fps
-        while not self._stop_event.is_set():
-            start = time.monotonic()
-            frame = self._capture.read()
-            if frame is not None:
-                self.video_source.capture_frame(frame)
-            elapsed = time.monotonic() - start
-            sleep_for = frame_interval - elapsed
-            if sleep_for > 0:
-                try:
-                    await asyncio.wait_for(self._stop_event.wait(), timeout=sleep_for)
-                except asyncio.TimeoutError:
-                    pass
-
-    async def _audio_loop(self) -> None:
-        assert self.audio_source is not None
-        mic = create_audio_capture(self.agent.audio_device)
-        if mic is None:
-            return
-        frame_duration = 0.02  # 20ms
-        samples_per_frame = int(48000 * frame_duration)
-        while not self._stop_event.is_set():
-            frame = mic.read(samples_per_frame)
-            if frame is not None:
-                self.audio_source.capture_frame(frame)
-            try:
-                await asyncio.wait_for(self._stop_event.wait(), timeout=frame_duration)
-            except asyncio.TimeoutError:
-                pass
-
-
-# -----------------------------------------------------------------------------
-# Video capture abstraction: V4L2/USB via OpenCV, or picamera2 on Pi.
-# -----------------------------------------------------------------------------
-
-class VideoCapture:
-    def read(self) -> Optional["rtc.VideoFrame"]:
-        raise NotImplementedError
-
-    def stop(self) -> None:
-        raise NotImplementedError
-
-
-class OpencvVideoCapture(VideoCapture):
-    def __init__(self, device: int | str, width: int, height: int, fps: int):
-        import cv2
-        self.cv2 = cv2
-        if isinstance(device, str) and device.startswith("/dev/video"):
-            device = int(device.replace("/dev/video", ""))
-        self.cap = cv2.VideoCapture(device)
-        self.cap.set(cv2.CAP_PROP_FRAME_WIDTH, width)
-        self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, height)
-        self.cap.set(cv2.CAP_PROP_FPS, fps)
-        self._ensure_frame()
-
-    def _ensure_frame(self):
-        ok, _ = self.cap.read()
-        if not ok:
-            raise RuntimeError("cannot read from camera")
-
-    def read(self):
-        from livekit import rtc
-        ok, bgr = self.cap.read()
-        if not ok or bgr is None:
-            return None
-        return rtc.VideoFrame(
-            width=bgr.shape[1],
-            height=bgr.shape[0],
-            type=rtc.VideoBufferType.BGR,
-            data=bgr.tobytes(),
-        )
-
-    def stop(self):
-        self.cap.release()
-
-
-class Picamera2Capture(VideoCapture):
-    def __init__(self, width: int, height: int, fps: int):
-        from picamera2 import Picamera2
-        self.picam = Picamera2()
-        config = self.picam.create_video_configuration(
-            main={"format": "RGB888", "size": (width, height)},
-            controls={"FrameRate": fps},
-        )
-        self.picam.configure(config)
-        self.picam.start()
-        self.width = width
-        self.height = height
-
-    def read(self):
-        from livekit import rtc
-        arr = self.picam.capture_array()
-        if arr is None:
-            return None
-        return rtc.VideoFrame(
-            width=self.width,
-            height=self.height,
-            type=rtc.VideoBufferType.RGB,
-            data=arr.tobytes(),
-        )
-
-    def stop(self):
-        try:
-            self.picam.stop()
-        except Exception:
-            pass
-
-
-def create_video_capture(device: str, width: int, height: int, fps: int) -> Optional[VideoCapture]:
-    if device.lower() in ("none", "", "false", "null"):
-        return None
-    try:
-        from livekit import rtc
-        _ = rtc.VideoSource
-    except Exception as e:
-        logger.error(f"livekit python sdk not installed: {e}")
-        return None
-
-    # Auto-detect: prefer first V4L2 device, fall back to picamera2 if available.
-    if device.lower() in ("auto", "default", "first"):
-        for i in range(4):
-            try:
-                cap = OpencvVideoCapture(i, width, height, fps)
-                logger.info(f"auto-selected USB camera /dev/video{i}")
-                return cap
-            except Exception:
-                continue
-        try:
-            cap = Picamera2Capture(width, height, fps)
-            logger.info("auto-selected Pi Camera")
-            return cap
-        except Exception:
-            pass
-        logger.error("no camera found (tried V4L2 and picamera2)")
-        return None
-
-    if device.lower() in ("picamera", "picamera2", "pi", "rpi"):
-        return Picamera2Capture(width, height, fps)
-
-    # Treat as V4L2 index or path
-    return OpencvVideoCapture(device, width, height, fps)
-
-
-# -----------------------------------------------------------------------------
-# Audio capture abstraction: PyAudio or sounddevice -> LiveKit AudioFrame.
-# -----------------------------------------------------------------------------
-
-class AudioCapture:
-    def read(self, samples_per_frame: int) -> Optional["rtc.AudioFrame"]:
-        raise NotImplementedError
-
-    def stop(self) -> None:
-        raise NotImplementedError
-
-
-class PyAudioCapture(AudioCapture):
-    def __init__(self, device: str | int | None):
-        import pyaudio
-        self.pa = pyaudio.PyAudio()
-        self.device_index = self._resolve_device(device)
-        self.buffer = bytearray()
-        self.stream = self.pa.open(
-            format=pyaudio.paInt16,
-            channels=1,
-            rate=48000,
-            input=True,
-            input_device_index=self.device_index,
-            frames_per_buffer=960,
-            stream_callback=self._callback,
-        )
-        self.stream.start_stream()
-
-    def _resolve_device(self, device: str | int | None) -> Optional[int]:
-        if device is None or device == "default":
-            return None
-        if isinstance(device, int):
-            return device
-        # Try exact name match
-        for i in range(self.pa.get_device_count()):
-            info = self.pa.get_device_info_by_index(i)
-            if info.get("maxInputChannels", 0) > 0 and device.lower() in str(info.get("name", "")).lower():
-                return i
-        return None
-
-    def _callback(self, in_data, frame_count, time_info, status):
-        self.buffer.extend(in_data)
-        return (None, pyaudio.paContinue)
-
-    def read(self, samples_per_frame: int):
-        from livekit import rtc
-        bytes_needed = samples_per_frame * 2  # int16 mono
-        while len(self.buffer) < bytes_needed:
-            time.sleep(0.005)
-        chunk = bytes(self.buffer[:bytes_needed])
-        self.buffer = self.buffer[bytes_needed:]
-        return rtc.AudioFrame(
-            data=chunk,
-            sample_rate=48000,
-            num_channels=1,
-            samples_per_channel=samples_per_frame,
-        )
-
-    def stop(self):
-        if self.stream:
-            self.stream.stop_stream()
-            self.stream.close()
-        self.pa.terminate()
-
-
-def has_audio() -> bool:
-    try:
-        import pyaudio  # noqa: F401
-        return True
-    except Exception:
-        return False
-
-
-def create_audio_capture(device: str) -> Optional[AudioCapture]:
-    if device.lower() in ("none", "", "false", "null"):
-        return None
-    try:
-        import pyaudio  # noqa: F401
-        return PyAudioCapture(device if device != "default" else None)
-    except Exception as e:
-        logger.warning(f"pyaudio not available: {e}")
-        return None
-
-
-def _hostname() -> str:
-    import socket
-    return socket.gethostname().split(".")[0]
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="RoboPark preview agent")
-    parser.add_argument("--scheduler-url", default=os.getenv("SCHEDULER_URL", "http://localhost:8080"))
-    parser.add_argument("--robot-id", default=os.getenv("ROBOT_ID", _hostname()))
-    parser.add_argument("--device-token", default=os.getenv("DEVICE_TOKEN"))
-    parser.add_argument("--enrollment-token", default=os.getenv("ENROLLMENT_TOKEN"))
-    parser.add_argument("--video-device", default=os.getenv("VIDEO_DEVICE", "auto"))
-    parser.add_argument("--audio-device", default=os.getenv("AUDIO_DEVICE", "default"))
-    parser.add_argument("--width", type=int, default=int(os.getenv("VIDEO_WIDTH", DEFAULT_VIDEO_WIDTH)))
-    parser.add_argument("--height", type=int, default=int(os.getenv("VIDEO_HEIGHT", DEFAULT_VIDEO_HEIGHT)))
-    parser.add_argument("--fps", type=int, default=int(os.getenv("VIDEO_FPS", DEFAULT_FPS)))
-    parser.add_argument("--poll-interval", type=float, default=float(os.getenv("POLL_INTERVAL", DEFAULT_POLL_INTERVAL)))
-    parser.add_argument("--heartbeat-interval", type=float, default=float(os.getenv("HEARTBEAT_INTERVAL", DEFAULT_HEARTBEAT_INTERVAL)))
-    parser.add_argument("--vision-webhook-port", type=int, default=int(os.getenv("VISION_WEBHOOK_PORT", DEFAULT_VISION_WEBHOOK_PORT)), help="local port for RoboVisionAI_PI's motion webhook (0 disables)")
-    parser.add_argument("--vision-trigger-cooldown", type=float, default=float(os.getenv("VISION_TRIGGER_COOLDOWN", DEFAULT_VISION_TRIGGER_COOLDOWN)))
-    parser.add_argument("--vision-session-seconds", type=float, default=float(os.getenv("VISION_SESSION_SECONDS", DEFAULT_VISION_SESSION_SECONDS)))
-    parser.add_argument("--save-config", action="store_true", help="write CLI args to ~/.robopark/preview_agent.json")
-    parser.add_argument("-v", "--verbose", action="store_true")
-    args = parser.parse_args()
-
-    logging.basicConfig(
-        level=logging.DEBUG if args.verbose else logging.INFO,
-        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
-    )
-
-    cfg = _load_config()
-    cfg.update({
-        "scheduler_url": args.scheduler_url,
-        "robot_id": args.robot_id,
-        "video_device": args.video_device,
-        "audio_device": args.audio_device,
-        "video_width": args.width,
-        "video_height": args.height,
-        "video_fps": args.fps,
-        "poll_interval": args.poll_interval,
-        "heartbeat_interval": args.heartbeat_interval,
-        "vision_webhook_port": args.vision_webhook_port,
-        "vision_trigger_cooldown": args.vision_trigger_cooldown,
-        "vision_session_seconds": args.vision_session_seconds,
-    })
-    if args.device_token:
-        cfg["device_token"] = args.device_token
-        _save_token(args.device_token)
-    if args.enrollment_token:
-        cfg["enrollment_token"] = args.enrollment_token
-
-    if args.save_config:
-        _save_config(cfg)
-        logger.info(f"saved config to {CONFIG_FILE}")
-
-    agent = PreviewAgent(cfg)
-
-    loop = asyncio.new_event_loop()
-    asyncio.set_event_loop(loop)
-    for sig in (signal.SIGINT, signal.SIGTERM):
-        try:
-            loop.add_signal_handler(sig, agent.shutdown)
-        except NotImplementedError:
-            # add_signal_handler is POSIX-only (raises on Windows) — fall back to
-            # signal.signal, dispatched back onto the loop thread-safely.
-            signal.signal(sig, lambda *_: loop.call_soon_threadsafe(agent.shutdown))
-
-    try:
-        loop.run_until_complete(agent.run())
-    finally:
-        loop.close()
-
-
-if __name__ == "__main__":
-    main()
+#!/usr/bin/env python3
+"""
+RoboPark Preview Agent — runs on each robot/satellite Pi.
+
+Polls the scheduler for an active operator preview request. When active,
+opens the selected camera + microphone and publishes them to the returned
+LiveKit room. When the preview expires or is stopped, the agent leaves the
+room and releases the hardware.
+
+Also runs a small local HTTP listener for RoboVisionAI_PI's motion webhook
+(POST /api/motion/webhook target — see RoboVisionAI_PI's app_pi_clean.py).
+On a motion event it calls the scheduler's presence-triggered
+POST /api/devices/{id}/request-session and publishes into the returned room
+using the same LiveKitPublisher as the operator preview — this is the
+"scene detection" trigger point the scheduler's request-session docstring
+describes; RoboVisionAI_PI supplies the detection, this agent supplies the
+bridge to an actual session.
+
+Configuration (env / ~/.robopark/preview_agent.json):
+  SCHEDULER_URL          base URL of the RoboPark scheduler
+  ROBOT_ID               robot identity in the scheduler (defaults to hostname)
+  DEVICE_TOKEN           long-lived device token (after enrollment)
+  ENROLLMENT_TOKEN       one-time enrollment token (device token will be saved)
+  VIDEO_DEVICE           camera path/index/name (e.g. /dev/video0, 0, "PiCamera")
+  AUDIO_DEVICE           microphone name/index or "default"
+  VIDEO_WIDTH / HEIGHT   capture resolution (default 640x480)
+  VIDEO_FPS              capture fps (default 15)
+  POLL_INTERVAL          seconds between scheduler polls (default 3)
+  HEARTBEAT_INTERVAL     seconds between device heartbeats (default 30)
+  VISION_WEBHOOK_PORT    local port for the RoboVision motion webhook (default 5057, 0 disables)
+  VISION_TRIGGER_COOLDOWN  min seconds between motion-triggered sessions (default 20)
+  VISION_SESSION_SECONDS   HARD ceiling on how long a motion-triggered session can
+                            hold the publisher, regardless of activity (default 90)
+  VISION_SILENCE_TIMEOUT   how long a motion-triggered session may go without an
+                            activity signal before it's ended early (default 15).
+                            Activity is reported via POST /api/sessions/{id}/keepalive,
+                            which this agent polls for via GET /api/sessions/{id}/status
+                            on every poll tick. The actual caller of keepalive (the
+                            voice agent, VAD-driven) lives in a different repo — see
+                            main.py's keepalive endpoint docstring for the integration
+                            contract. Without any caller ever hitting keepalive, a
+                            vision session simply ends after VISION_SILENCE_TIMEOUT.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import signal
+import sys
+import threading
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger("robopark.preview_agent")
+
+CONFIG_DIR = Path.home() / ".robopark"
+CONFIG_FILE = CONFIG_DIR / "preview_agent.json"
+TOKEN_FILE = CONFIG_DIR / "device_token"
+
+DEFAULT_VIDEO_WIDTH = 640
+DEFAULT_VIDEO_HEIGHT = 480
+DEFAULT_FPS = 15
+DEFAULT_POLL_INTERVAL = 3.0
+DEFAULT_HEARTBEAT_INTERVAL = 30.0
+DEFAULT_VISION_WEBHOOK_PORT = 5057
+DEFAULT_VISION_TRIGGER_COOLDOWN = 20.0
+DEFAULT_VISION_SESSION_SECONDS = 90.0
+# How long a motion-triggered session may go without an activity signal
+# (POST /api/sessions/{id}/keepalive, called by the voice agent — a
+# different repo, not this one) before preview_agent tears it down.
+# vision_session_seconds remains a hard ceiling regardless of activity.
+DEFAULT_VISION_SILENCE_TIMEOUT = 15.0
+
+
+def _load_config() -> dict:
+    cfg: dict = {}
+    if CONFIG_FILE.exists():
+        try:
+            cfg = json.loads(CONFIG_FILE.read_text(encoding="utf8"))
+        except Exception as e:
+            logger.warning(f"failed to read {CONFIG_FILE}: {e}")
+    return cfg
+
+
+def _save_config(cfg: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(cfg, indent=2), encoding="utf8")
+
+
+def _load_token() -> Optional[str]:
+    if TOKEN_FILE.exists():
+        return TOKEN_FILE.read_text(encoding="utf8").strip() or None
+    return None
+
+
+def _save_token(token: str) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    TOKEN_FILE.write_text(token, encoding="utf8")
+    os.chmod(TOKEN_FILE, 0o600)
+
+
+async def _enroll(scheduler_url: str, enrollment_token: str, robot_id: str) -> str:
+    """Enroll this Pi with the scheduler and return the device token."""
+    import socket
+    payload = {
+        "enrollment_token": enrollment_token,
+        "name": robot_id,
+        "lan_ip": _get_lan_ip(),
+    }
+    async with httpx.AsyncClient() as client:
+        r = await client.post(
+            f"{scheduler_url.rstrip('/')}/api/devices/enroll",
+            json=payload,
+            timeout=30.0,
+        )
+        r.raise_for_status()
+        data = r.json()
+    device_token = data.get("device_token")
+    if not device_token:
+        raise RuntimeError("enrollment did not return a device_token")
+    _save_token(device_token)
+    cfg = _load_config()
+    cfg["device_id"] = data.get("device_id")
+    cfg["scheduler_url"] = data.get("scheduler_url", scheduler_url)
+    _save_config(cfg)
+    logger.info(f"enrolled as device {data.get('device_id')}")
+    return device_token
+
+
+def _get_lan_ip() -> Optional[str]:
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.settimeout(0.5)
+        s.connect(("10.255.255.255", 1))
+        ip = s.getsockname()[0]
+        s.close()
+        return ip
+    except Exception:
+        return None
+
+
+async def _send_heartbeat(scheduler_url: str, device_id: str, token: str) -> None:
+    try:
+        async with httpx.AsyncClient() as client:
+            await client.post(
+                f"{scheduler_url.rstrip('/')}/api/devices/{device_id}/heartbeat",
+                json={"status": "online", "ip": _get_lan_ip()},
+                headers={"Authorization": f"Bearer {token}"},
+                timeout=10.0,
+            )
+    except Exception as e:
+        logger.debug(f"heartbeat failed: {e}")
+
+
+@dataclass
+class PreviewState:
+    active: bool = False
+    url: Optional[str] = None
+    token: Optional[str] = None
+    room: Optional[str] = None
+
+
+class PreviewAgent:
+    def __init__(self, cfg: dict):
+        self.scheduler_url = cfg.get("scheduler_url", os.getenv("SCHEDULER_URL", "http://localhost:8080"))
+        self.robot_id = cfg.get("robot_id", os.getenv("ROBOT_ID", _hostname()))
+        self.device_token: Optional[str] = cfg.get("device_token") or os.getenv("DEVICE_TOKEN") or _load_token()
+        self.device_id: Optional[str] = cfg.get("device_id")
+        self.enrollment_token: Optional[str] = cfg.get("enrollment_token")
+        self.video_device = cfg.get("video_device", os.getenv("VIDEO_DEVICE", "auto"))
+        self.audio_device = cfg.get("audio_device", os.getenv("AUDIO_DEVICE", "default"))
+        self.width = int(cfg.get("video_width", os.getenv("VIDEO_WIDTH", DEFAULT_VIDEO_WIDTH)))
+        self.height = int(cfg.get("video_height", os.getenv("VIDEO_HEIGHT", DEFAULT_VIDEO_HEIGHT)))
+        self.fps = int(cfg.get("video_fps", os.getenv("VIDEO_FPS", DEFAULT_FPS)))
+        self.poll_interval = float(cfg.get("poll_interval", os.getenv("POLL_INTERVAL", DEFAULT_POLL_INTERVAL)))
+        self.heartbeat_interval = float(cfg.get("heartbeat_interval", os.getenv("HEARTBEAT_INTERVAL", DEFAULT_HEARTBEAT_INTERVAL)))
+        self.vision_webhook_port = int(cfg.get("vision_webhook_port", os.getenv("VISION_WEBHOOK_PORT", DEFAULT_VISION_WEBHOOK_PORT)))
+        self.vision_trigger_cooldown = float(cfg.get("vision_trigger_cooldown", os.getenv("VISION_TRIGGER_COOLDOWN", DEFAULT_VISION_TRIGGER_COOLDOWN)))
+        self.vision_session_seconds = float(cfg.get("vision_session_seconds", os.getenv("VISION_SESSION_SECONDS", DEFAULT_VISION_SESSION_SECONDS)))
+        self.vision_silence_timeout = float(cfg.get("vision_silence_timeout", os.getenv("VISION_SILENCE_TIMEOUT", DEFAULT_VISION_SILENCE_TIMEOUT)))
+
+        self._shutdown = asyncio.Event()
+        self._task: Optional[asyncio.Task] = None
+        self._session: Optional[httpx.AsyncClient] = None
+        self._current_state: PreviewState = PreviewState()
+        self._publisher: Optional["LiveKitPublisher"] = None
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._vision_server: Optional[ThreadingHTTPServer] = None
+        self._last_vision_trigger: float = 0.0
+        # Motion-triggered ("vision") session bookkeeping. Silence-timeout
+        # with a hard ceiling — see DEFAULT_VISION_SILENCE_TIMEOUT above and
+        # _check_vision_session() below for the full design.
+        self._vision_session_id: Optional[str] = None
+        self._vision_hard_deadline: float = 0.0
+        self._vision_last_activity: float = 0.0
+
+    async def run(self) -> None:
+        enrollment_token = os.getenv("ENROLLMENT_TOKEN") or self.enrollment_token
+        if not self.device_token and enrollment_token:
+            self.device_token = await _enroll(self.scheduler_url, enrollment_token, self.robot_id)
+
+        if not self.device_token:
+            logger.error("no DEVICE_TOKEN and no ENROLLMENT_TOKEN; cannot poll scheduler")
+            sys.exit(1)
+
+        self._session = httpx.AsyncClient()
+
+        # Must come after self._session exists — _resolve_device_id() guards
+        # on it and silently no-ops otherwise. On a fresh enroll (no cached
+        # device_id in ~/.robopark/preview_agent.json) that made this ALWAYS
+        # no-op, so device_id never resolved and preview/agent polling fell
+        # back to robot_id (the display name) instead of the real device_id
+        # for the entire session — the same id-mismatch bug fixed elsewhere,
+        # recurring here only on a first-ever enroll.
+        if not self.device_id:
+            await self._resolve_device_id()
+
+        self._loop = asyncio.get_running_loop()
+        self._start_vision_webhook_server()
+
+        tasks = [
+            asyncio.create_task(self._poll_loop()),
+            asyncio.create_task(self._heartbeat_loop()),
+        ]
+        await self._shutdown.wait()
+        for t in tasks:
+            t.cancel()
+            try:
+                await t
+            except asyncio.CancelledError:
+                pass
+        if self._vision_server:
+            self._vision_server.shutdown()
+        await self._stop_publisher()
+        await self._session.aclose()
+
+    async def _resolve_device_id(self) -> None:
+        """Look up our device_id from the scheduler using the token."""
+        if not self._session or not self.device_token:
+            return
+        try:
+            r = await self._session.get(
+                f"{self.scheduler_url.rstrip('/')}/api/devices",
+                headers={"Authorization": f"Bearer {self.device_token}"},
+                timeout=10.0,
+            )
+            r.raise_for_status()
+            for d in r.json():
+                if d.get("name") == self.robot_id:
+                    self.device_id = d.get("id")
+                    cfg = _load_config()
+                    cfg["device_id"] = self.device_id
+                    _save_config(cfg)
+                    return
+        except Exception as e:
+            logger.warning(f"could not resolve device_id: {e}")
+
+    async def _poll_loop(self) -> None:
+        while not self._shutdown.is_set():
+            try:
+                if self._vision_session_id:
+                    # A vision-triggered session currently owns the publisher.
+                    # Decide whether it's still "active" (silence timeout vs.
+                    # hard ceiling) instead of letting the unrelated
+                    # operator-preview state tear it down.
+                    await self._check_vision_session()
+                if not self._vision_session_id:
+                    state = await self._fetch_preview_state()
+                    await self._apply_state(state)
+            except Exception as e:
+                logger.warning(f"poll error: {e}")
+            try:
+                await asyncio.wait_for(self._shutdown.wait(), timeout=self.poll_interval)
+            except asyncio.TimeoutError:
+                pass
+
+    async def _check_vision_session(self) -> None:
+        """Decide whether the active motion-triggered session should keep
+        holding the publisher.
+
+        Two limits apply, whichever comes first:
+          1. HARD ceiling — vision_session_seconds after the session started.
+             Enforced locally, no scheduler round-trip needed. Guarantees a
+             stuck/misbehaving caller can never hold the publisher forever.
+          2. SILENCE timeout — vision_silence_timeout since last_activity_at
+             last moved. last_activity_at lives on the scheduler and is only
+             ever bumped by POST /api/sessions/{id}/keepalive — a call this
+             agent does NOT make itself. In production that call is made by
+             the VOICE AGENT (a separate process/repo, VAD-driven), which is
+             the only thing that actually knows whether the user/agent are
+             still talking. We poll GET /api/sessions/{id}/status here every
+             poll_interval to pull the latest value.
+
+        If nothing ever calls keepalive, last_activity_at never advances past
+        started_at and the session ends after vision_silence_timeout — a safe
+        default, not a malfunction. Wiring the voice agent to call keepalive
+        is required to make this genuinely silence-aware; that integration is
+        out of scope for this repo.
+        """
+        now = time.time()
+        if now >= self._vision_hard_deadline:
+            logger.info("vision session hit its hard ceiling (vision_session_seconds) — ending")
+            await self._end_vision_session()
+            return
+
+        try:
+            last_activity = await self._fetch_session_last_activity(self._vision_session_id)
+            if last_activity is not None and last_activity > self._vision_last_activity:
+                self._vision_last_activity = last_activity
+        except Exception as e:
+            logger.debug(f"could not refresh session activity: {e}")
+
+        if now - self._vision_last_activity >= self.vision_silence_timeout:
+            logger.info(
+                f"vision session silent for {now - self._vision_last_activity:.0f}s "
+                f"(>= {self.vision_silence_timeout}s timeout) — ending"
+            )
+            await self._end_vision_session()
+
+    async def _fetch_session_last_activity(self, session_id: str) -> Optional[float]:
+        """GET /api/sessions/{id}/status and return last_activity_at as a Unix
+        timestamp, or None if unavailable. Naive UTC ISO strings (as written
+        by main.py's datetime.utcnow().isoformat()) are interpreted as UTC
+        explicitly — treating them as local time would silently skew the
+        silence calculation on any host not running in UTC."""
+        if not self._session or not self.device_token:
+            return None
+        r = await self._session.get(
+            f"{self.scheduler_url.rstrip('/')}/api/sessions/{session_id}/status",
+            headers={"Authorization": f"Bearer {self.device_token}"},
+            timeout=10.0,
+        )
+        r.raise_for_status()
+        data = r.json()
+        ts = data.get("last_activity_at") or data.get("started_at")
+        if not ts:
+            return None
+        dt = datetime.fromisoformat(ts)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt.timestamp()
+
+    async def _end_vision_session(self) -> None:
+        self._vision_session_id = None
+        self._vision_hard_deadline = 0.0
+        self._vision_last_activity = 0.0
+        await self._stop_publisher()
+        self._current_state = PreviewState()
+
+    async def _heartbeat_loop(self) -> None:
+        while not self._shutdown.is_set():
+            if self.device_id and self.device_token:
+                await _send_heartbeat(self.scheduler_url, self.device_id, self.device_token)
+            try:
+                await asyncio.wait_for(self._shutdown.wait(), timeout=self.heartbeat_interval)
+            except asyncio.TimeoutError:
+                pass
+
+    async def _fetch_preview_state(self) -> PreviewState:
+        if not self._session or not self.device_token:
+            return PreviewState()
+        r = await self._session.get(
+            f"{self.scheduler_url.rstrip('/')}/api/robots/{self.device_id or self.robot_id}/preview/agent",
+            headers={"Authorization": f"Bearer {self.device_token}"},
+            timeout=10.0,
+        )
+        r.raise_for_status()
+        data = r.json()
+        if not data.get("active"):
+            return PreviewState()
+        return PreviewState(
+            active=True,
+            url=data.get("url"),
+            token=data.get("token"),
+            room=data.get("room"),
+        )
+
+    async def _apply_state(self, state: PreviewState) -> None:
+        same = (
+            state.active == self._current_state.active
+            and state.room == self._current_state.room
+            and state.token == self._current_state.token
+            and state.url == self._current_state.url
+        )
+        if same:
+            return
+        self._current_state = state
+        if not state.active:
+            await self._stop_publisher()
+            return
+        await self._start_publisher(state)
+
+    async def _start_publisher(self, state: PreviewState) -> None:
+        await self._stop_publisher()
+        if not state.url or not state.token or not state.room:
+            return
+        try:
+            pub = LiveKitPublisher(state.url, state.token, state.room, self)
+            await pub.start()
+            self._publisher = pub
+            logger.info(f"joined preview room {state.room}")
+        except Exception as e:
+            logger.error(f"failed to start publisher: {e}")
+
+    async def _stop_publisher(self) -> None:
+        if self._publisher:
+            try:
+                await self._publisher.stop()
+            except Exception as e:
+                logger.warning(f"publisher stop error: {e}")
+            self._publisher = None
+
+    # ---- vision (RoboVisionAI_PI motion webhook) -> presence-triggered session ----
+
+    def _start_vision_webhook_server(self) -> None:
+        if not self.vision_webhook_port:
+            return
+        agent = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, fmt, *a):  # noqa: A002 — quiet by default
+                logger.debug("vision webhook: " + fmt, *a)
+
+            def do_POST(self):  # noqa: N802 — http.server's required method name
+                try:
+                    length = int(self.headers.get("Content-Length", 0))
+                    body = self.rfile.read(length) if length else b"{}"
+                    payload = json.loads(body or b"{}")
+                except Exception as e:
+                    self.send_response(400)
+                    self.end_headers()
+                    self.wfile.write(str(e).encode())
+                    return
+                self.send_response(200)
+                self.end_headers()
+                self.wfile.write(b'{"ok":true}')
+                if agent._loop:
+                    asyncio.run_coroutine_threadsafe(agent._on_vision_motion(payload), agent._loop)
+
+            def do_GET(self):  # noqa: N802
+                self.send_response(200)
+                self.end_headers()
+                self.wfile.write(b'{"status":"ok","listening_for":"robovision motion webhook"}')
+
+        try:
+            self._vision_server = ThreadingHTTPServer(("0.0.0.0", self.vision_webhook_port), Handler)
+            thread = threading.Thread(target=self._vision_server.serve_forever, daemon=True)
+            thread.start()
+            logger.info(
+                f"vision webhook listening on :{self.vision_webhook_port} — "
+                f"point RoboVisionAI_PI's POST /api/motion/webhook at "
+                f"http://<this-host>:{self.vision_webhook_port}/"
+            )
+        except Exception as e:
+            logger.error(f"could not start vision webhook server: {e}")
+            self._vision_server = None
+
+    async def _on_vision_motion(self, payload: dict) -> None:
+        now = time.time()
+        if now - self._last_vision_trigger < self.vision_trigger_cooldown:
+            logger.debug("vision trigger suppressed (cooldown)")
+            return
+        self._last_vision_trigger = now
+        if not self.device_id or not self.device_token or not self._session:
+            logger.warning("vision motion event received but not enrolled yet — ignoring")
+            return
+        logger.info("motion detected by RoboVisionAI_PI — requesting a session")
+        try:
+            r = await self._session.post(
+                f"{self.scheduler_url.rstrip('/')}/api/devices/{self.device_id}/request-session",
+                headers={"Authorization": f"Bearer {self.device_token}"},
+                timeout=10.0,
+            )
+            r.raise_for_status()
+            data = r.json()
+        except Exception as e:
+            logger.error(f"request-session failed: {e}")
+            return
+        state = PreviewState(
+            active=True,
+            url=data.get("server_url"),
+            token=data.get("token"),
+            room=data.get("room_name"),
+        )
+        session_id = data.get("session_id")
+        now = time.time()
+        self._vision_session_id = session_id
+        self._vision_hard_deadline = now + self.vision_session_seconds
+        self._vision_last_activity = now
+        self._current_state = state
+        await self._start_publisher(state)
+        if session_id and self._session:
+            try:
+                await self._session.post(
+                    f"{self.scheduler_url.rstrip('/')}/api/sessions/{session_id}/joined",
+                    headers={"Authorization": f"Bearer {self.device_token}"},
+                    timeout=10.0,
+                )
+            except Exception as e:
+                logger.debug(f"could not mark session joined: {e}")
+
+    def shutdown(self) -> None:
+        self._shutdown.set()
+
+
+class LiveKitPublisher:
+    """Encapsulates LiveKit room connection, camera capture and mic capture."""
+
+    def __init__(self, url: str, token: str, room_name: str, agent: PreviewAgent):
+        from livekit import rtc
+        self.url = url
+        self.token = token
+        self.room_name = room_name
+        self.agent = agent
+        self.rtc = rtc
+        self.room: Optional[rtc.Room] = None
+        self.video_source: Optional[rtc.VideoSource] = None
+        self.video_track: Optional[rtc.LocalVideoTrack] = None
+        self.audio_source: Optional[rtc.AudioSource] = None
+        self.audio_track: Optional[rtc.LocalAudioTrack] = None
+        self._stop_event = asyncio.Event()
+        self._tasks: list[asyncio.Task] = []
+        self._capture: Optional["VideoCapture"] = None
+
+    async def start(self) -> None:
+        self.room = self.rtc.Room()
+        await self.room.connect(self.url, self.token)
+
+        # Video
+        self.video_source = self.rtc.VideoSource(self.agent.width, self.agent.height)
+        self.video_track = self.rtc.LocalVideoTrack.create_video_track("camera", self.video_source)
+        vopts = self.rtc.TrackPublishOptions()
+        vopts.source = self.rtc.TrackSource.SOURCE_CAMERA
+        await self.room.local_participant.publish_track(self.video_track, vopts)
+
+        # Audio
+        self.audio_source = self.rtc.AudioSource(48000, 1)
+        self.audio_track = self.rtc.LocalAudioTrack.create_audio_track("microphone", self.audio_source)
+        aopts = self.rtc.TrackPublishOptions()
+        aopts.source = self.rtc.TrackSource.SOURCE_MICROPHONE
+        await self.room.local_participant.publish_track(self.audio_track, aopts)
+
+        # Register speaker playback (subscribe to the voice agent's TTS audio
+        # track) BEFORE opening the camera. Camera open is a slow/occasionally
+        # hanging blocking call (see create_video_capture below), and since
+        # asyncio is single-threaded, running it inline here would stall the
+        # entire event loop — including receiving the agent's greeting audio
+        # — until it finished, so a short "Hello friend!" greeting could be
+        # over and gone before we ever got a chance to subscribe to it.
+        self._playback_streams: dict = {}
+
+        def _on_track_subscribed(track, publication, participant):
+            logger.info(f"track_subscribed: kind={track.kind} from={participant.identity} sid={publication.sid}")
+            if track.kind != self.rtc.TrackKind.KIND_AUDIO:
+                return
+            if participant.identity == self.room.local_participant.identity:
+                return  # don't play our own mic back
+            self._tasks.append(asyncio.create_task(self._play_remote_audio(track, publication.sid)))
+
+        self.room.on("track_subscribed", _on_track_subscribed)
+        logger.info("audio out: track_subscribed listener registered")
+
+        if has_audio():
+            self._tasks.append(asyncio.create_task(self._audio_loop()))
+
+        # Camera open can block for a long time (flaky USB/driver reopen) —
+        # run it in a thread so it can't stall the event loop (and therefore
+        # incoming agent audio / heartbeats / the playback subscribed above).
+        self._capture = await asyncio.to_thread(
+            create_video_capture, self.agent.video_device, self.agent.width, self.agent.height, self.agent.fps
+        )
+        if self._capture:
+            self._tasks.append(asyncio.create_task(self._video_loop()))
+
+    async def _play_remote_audio(self, track, sid: str) -> None:
+        try:
+            import pyaudio
+        except Exception as e:
+            logger.warning(f"pyaudio unavailable for playback: {e}")
+            return
+        OUT_RATE = 48000
+        pa = pyaudio.PyAudio()
+        out = pa.open(format=pyaudio.paInt16, channels=1, rate=OUT_RATE, output=True)
+        logger.info(f"audio out: opened playback stream for {sid}")
+        frame_count = 0
+        try:
+            stream = self.rtc.AudioStream(track=track)
+            async for frame in stream:
+                af = frame.frame if hasattr(frame, "frame") else frame
+                data = bytes(af.data)
+                frame_count += 1
+                if frame_count == 1:
+                    logger.info(f"audio out: first frame received for {sid} (rate={af.sample_rate})")
+                if af.sample_rate != OUT_RATE:
+                    # Frames from Kokoro/TTS are already 48kHz in this stack;
+                    # a mismatch here would need resampling like the Pi
+                    # client does, but isn't expected on the local test loop.
+                    logger.debug(
+                        f"audio out: unexpected sample rate {af.sample_rate}, expected {OUT_RATE}"
+                    )
+                out.write(data)
+        except Exception as e:
+            logger.warning(f"audio out stream error: {e}")
+        finally:
+            out.stop_stream()
+            out.close()
+            pa.terminate()
+
+    async def stop(self) -> None:
+        self._stop_event.set()
+        for t in self._tasks:
+            t.cancel()
+            try:
+                await t
+            except asyncio.CancelledError:
+                pass
+        self._tasks.clear()
+        if self._capture:
+            self._capture.stop()
+            self._capture = None
+        if self.room:
+            await self.room.disconnect()
+            self.room = None
+
+    async def _video_loop(self) -> None:
+        assert self._capture is not None and self.video_source is not None
+        frame_interval = 1.0 / self.agent.fps
+        while not self._stop_event.is_set():
+            start = time.monotonic()
+            # self._capture.read() is a synchronous, occasionally slow cv2
+            # call (same USB/driver flakiness as the initial camera open).
+            # Calling it inline here blocks the whole single-threaded event
+            # loop every ~66ms, starving the mic audio loop running on the
+            # same loop — audio throughput was observed collapsing from
+            # ~25 frames/sec to ~1 frame/sec whenever this stalled.
+            frame = await asyncio.to_thread(self._capture.read)
+            if frame is not None:
+                self.video_source.capture_frame(frame)
+            elapsed = time.monotonic() - start
+            sleep_for = frame_interval - elapsed
+            if sleep_for > 0:
+                try:
+                    await asyncio.wait_for(self._stop_event.wait(), timeout=sleep_for)
+                except asyncio.TimeoutError:
+                    pass
+
+    async def _audio_loop(self) -> None:
+        assert self.audio_source is not None
+        mic = create_audio_capture(self.agent.audio_device)
+        if mic is None:
+            logger.warning("audio_loop: create_audio_capture returned None, mic will not publish")
+            return
+        logger.info(f"audio_loop: mic capture started ({type(mic).__name__})")
+        # Read in bigger batches (100ms) instead of one 20ms frame per
+        # asyncio.to_thread() dispatch. Each dispatch/poll cycle has a fixed
+        # overhead (~30ms observed on this machine) that dominates when the
+        # payload itself is only 20ms — real capture fell to ~11 real
+        # frames/sec against a 50/sec target, and the resulting audio was so
+        # gappy (mostly *missing* frames, not silence) that the agent's VAD
+        # never saw enough continuous signal to trigger, even with loud,
+        # close-mic speech landing clean peaks in the frames that did arrive.
+        # Batching amortizes that overhead over 5 frames per dispatch.
+        BATCH_MS = 100
+        frame_ms = 20
+        samples_per_frame = int(48000 * frame_ms / 1000)
+        samples_per_batch = int(48000 * BATCH_MS / 1000)
+        bytes_per_frame = samples_per_frame * 2  # int16 mono
+        import audioop
+        _diag_peak = 0
+        _diag_count = 0
+        _diag_last_log = time.monotonic()
+        _diag_read_ms = 0.0
+        _diag_publish_ms = 0.0
+        batch_interval = BATCH_MS / 1000
+        while not self._stop_event.is_set():
+            _iter_start = time.monotonic()
+            _t0 = time.monotonic()
+            batch = await asyncio.to_thread(mic.read, samples_per_batch)
+            _t1 = time.monotonic()
+            if batch is not None:
+                data = bytes(batch.data)
+                _pub_start = time.monotonic()
+                for off in range(0, len(data) - bytes_per_frame + 1, bytes_per_frame):
+                    chunk = data[off:off + bytes_per_frame]
+                    frame = self.rtc.AudioFrame(
+                        data=chunk, sample_rate=48000, num_channels=1, samples_per_channel=samples_per_frame,
+                    )
+                    await self.audio_source.capture_frame(frame)
+                    p = audioop.max(chunk, 2)
+                    _diag_peak = max(_diag_peak, p)
+                    _diag_count += 1
+                _diag_read_ms += (_t1 - _t0) * 1000
+                _diag_publish_ms += (time.monotonic() - _pub_start) * 1000
+                if time.monotonic() - _diag_last_log > 1.0:
+                    logger.info(f"audio_loop: {_diag_count} frames sent in last 1s, peak={_diag_peak}/32767, read={_diag_read_ms:.0f}ms, publish={_diag_publish_ms:.0f}ms")
+                    _diag_peak = 0
+                    _diag_count = 0
+                    _diag_read_ms = 0.0
+                    _diag_publish_ms = 0.0
+                    _diag_last_log = time.monotonic()
+            # Pace to real wall-clock time per batch. mic.read()'s own
+            # buffer-polling wait is not a reliable substitute — a driver
+            # that briefly double-buffers can let it return a full batch
+            # almost instantly, and capture_frame() (which expects real-time
+            # delivery, blocking internally if fed faster) then accumulates
+            # backpressure that snowballs into multi-second stalls per call.
+            elapsed = time.monotonic() - _iter_start
+            sleep_for = batch_interval - elapsed
+            if sleep_for > 0:
+                try:
+                    await asyncio.wait_for(self._stop_event.wait(), timeout=sleep_for)
+                except asyncio.TimeoutError:
+                    pass
+
+
+# -----------------------------------------------------------------------------
+# Video capture abstraction: V4L2/USB via OpenCV, or picamera2 on Pi.
+# -----------------------------------------------------------------------------
+
+class VideoCapture:
+    def read(self) -> Optional["rtc.VideoFrame"]:
+        raise NotImplementedError
+
+    def stop(self) -> None:
+        raise NotImplementedError
+
+
+class OpencvVideoCapture(VideoCapture):
+    def __init__(self, device: int | str, width: int, height: int, fps: int):
+        import cv2
+        self.cv2 = cv2
+        if isinstance(device, str) and device.startswith("/dev/video"):
+            device = int(device.replace("/dev/video", ""))
+        self.cap = cv2.VideoCapture(device)
+        self.cap.set(cv2.CAP_PROP_FRAME_WIDTH, width)
+        self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, height)
+        self.cap.set(cv2.CAP_PROP_FPS, fps)
+        self._ensure_frame()
+
+    def _ensure_frame(self):
+        ok, _ = self.cap.read()
+        if not ok:
+            raise RuntimeError("cannot read from camera")
+
+    def read(self):
+        from livekit import rtc
+        ok, bgr = self.cap.read()
+        if not ok or bgr is None:
+            return None
+        return rtc.VideoFrame(
+            width=bgr.shape[1],
+            height=bgr.shape[0],
+            type=rtc.VideoBufferType.BGR,
+            data=bgr.tobytes(),
+        )
+
+    def stop(self):
+        self.cap.release()
+
+
+class Picamera2Capture(VideoCapture):
+    def __init__(self, width: int, height: int, fps: int):
+        from picamera2 import Picamera2
+        self.picam = Picamera2()
+        config = self.picam.create_video_configuration(
+            main={"format": "RGB888", "size": (width, height)},
+            controls={"FrameRate": fps},
+        )
+        self.picam.configure(config)
+        self.picam.start()
+        self.width = width
+        self.height = height
+
+    def read(self):
+        from livekit import rtc
+        arr = self.picam.capture_array()
+        if arr is None:
+            return None
+        return rtc.VideoFrame(
+            width=self.width,
+            height=self.height,
+            type=rtc.VideoBufferType.RGB,
+            data=arr.tobytes(),
+        )
+
+    def stop(self):
+        try:
+            self.picam.stop()
+        except Exception:
+            pass
+
+
+def create_video_capture(device: str, width: int, height: int, fps: int) -> Optional[VideoCapture]:
+    if device.lower() in ("none", "", "false", "null"):
+        return None
+    try:
+        from livekit import rtc
+        _ = rtc.VideoSource
+    except Exception as e:
+        logger.error(f"livekit python sdk not installed: {e}")
+        return None
+
+    # Auto-detect: prefer first V4L2 device, fall back to picamera2 if available.
+    if device.lower() in ("auto", "default", "first"):
+        for i in range(4):
+            try:
+                cap = OpencvVideoCapture(i, width, height, fps)
+                logger.info(f"auto-selected USB camera /dev/video{i}")
+                return cap
+            except Exception:
+                continue
+        try:
+            cap = Picamera2Capture(width, height, fps)
+            logger.info("auto-selected Pi Camera")
+            return cap
+        except Exception:
+            pass
+        logger.error("no camera found (tried V4L2 and picamera2)")
+        return None
+
+    if device.lower() in ("picamera", "picamera2", "pi", "rpi"):
+        return Picamera2Capture(width, height, fps)
+
+    # Treat as V4L2 index or path
+    return OpencvVideoCapture(device, width, height, fps)
+
+
+# -----------------------------------------------------------------------------
+# Audio capture abstraction: PyAudio or sounddevice -> LiveKit AudioFrame.
+# -----------------------------------------------------------------------------
+
+class AudioCapture:
+    def read(self, samples_per_frame: int) -> Optional["rtc.AudioFrame"]:
+        raise NotImplementedError
+
+    def stop(self) -> None:
+        raise NotImplementedError
+
+
+class PyAudioCapture(AudioCapture):
+    def __init__(self, device: str | int | None):
+        import pyaudio
+        self.pa = pyaudio.PyAudio()
+        self.device_index = self._resolve_device(device)
+        self.buffer = bytearray()
+        self.stream = self.pa.open(
+            format=pyaudio.paInt16,
+            channels=1,
+            rate=48000,
+            input=True,
+            input_device_index=self.device_index,
+            frames_per_buffer=960,
+            stream_callback=self._callback,
+        )
+        self.stream.start_stream()
+
+    def _resolve_device(self, device: str | int | None) -> Optional[int]:
+        if isinstance(device, int):
+            return device
+        if device is None or device == "default":
+            # PyAudio's global default resolves through the MME host API,
+            # which on Windows can silently capture pure silence (no error,
+            # no exception — the stream just never has any real signal in
+            # it) even though the same physical mic works fine everywhere
+            # else, including Windows' own input meter. WASAPI is the API
+            # actually backing that meter, so prefer its default input.
+            import pyaudio
+            try:
+                wasapi = self.pa.get_host_api_info_by_type(pyaudio.paWASAPI)
+                idx = wasapi.get("defaultInputDevice")
+                if idx is not None and idx >= 0:
+                    return idx
+            except Exception:
+                pass
+            return None
+        # Try exact name match
+        for i in range(self.pa.get_device_count()):
+            info = self.pa.get_device_info_by_index(i)
+            if info.get("maxInputChannels", 0) > 0 and device.lower() in str(info.get("name", "")).lower():
+                return i
+        return None
+
+    def _callback(self, in_data, frame_count, time_info, status):
+        import pyaudio
+        self.buffer.extend(in_data)
+        return (None, pyaudio.paContinue)
+
+    def read(self, samples_per_frame: int):
+        from livekit import rtc
+        bytes_needed = samples_per_frame * 2  # int16 mono
+        while len(self.buffer) < bytes_needed:
+            time.sleep(0.005)
+        chunk = bytes(self.buffer[:bytes_needed])
+        self.buffer = self.buffer[bytes_needed:]
+        return rtc.AudioFrame(
+            data=chunk,
+            sample_rate=48000,
+            num_channels=1,
+            samples_per_channel=samples_per_frame,
+        )
+
+    def stop(self):
+        if self.stream:
+            self.stream.stop_stream()
+            self.stream.close()
+        self.pa.terminate()
+
+
+def has_audio() -> bool:
+    try:
+        import pyaudio  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def create_audio_capture(device: str) -> Optional[AudioCapture]:
+    if device.lower() in ("none", "", "false", "null"):
+        return None
+    try:
+        import pyaudio  # noqa: F401
+        return PyAudioCapture(device if device != "default" else None)
+    except Exception as e:
+        logger.warning(f"pyaudio not available: {e}")
+        return None
+
+
+def _hostname() -> str:
+    import socket
+    return socket.gethostname().split(".")[0]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="RoboPark preview agent")
+    parser.add_argument("--scheduler-url", default=os.getenv("SCHEDULER_URL", "http://localhost:8080"))
+    parser.add_argument("--robot-id", default=os.getenv("ROBOT_ID", _hostname()))
+    parser.add_argument("--device-token", default=os.getenv("DEVICE_TOKEN"))
+    parser.add_argument("--enrollment-token", default=os.getenv("ENROLLMENT_TOKEN"))
+    parser.add_argument("--video-device", default=os.getenv("VIDEO_DEVICE", "auto"))
+    parser.add_argument("--audio-device", default=os.getenv("AUDIO_DEVICE", "default"))
+    parser.add_argument("--width", type=int, default=int(os.getenv("VIDEO_WIDTH", DEFAULT_VIDEO_WIDTH)))
+    parser.add_argument("--height", type=int, default=int(os.getenv("VIDEO_HEIGHT", DEFAULT_VIDEO_HEIGHT)))
+    parser.add_argument("--fps", type=int, default=int(os.getenv("VIDEO_FPS", DEFAULT_FPS)))
+    parser.add_argument("--poll-interval", type=float, default=float(os.getenv("POLL_INTERVAL", DEFAULT_POLL_INTERVAL)))
+    parser.add_argument("--heartbeat-interval", type=float, default=float(os.getenv("HEARTBEAT_INTERVAL", DEFAULT_HEARTBEAT_INTERVAL)))
+    parser.add_argument("--vision-webhook-port", type=int, default=int(os.getenv("VISION_WEBHOOK_PORT", DEFAULT_VISION_WEBHOOK_PORT)), help="local port for RoboVisionAI_PI's motion webhook (0 disables)")
+    parser.add_argument("--vision-trigger-cooldown", type=float, default=float(os.getenv("VISION_TRIGGER_COOLDOWN", DEFAULT_VISION_TRIGGER_COOLDOWN)))
+    parser.add_argument("--vision-session-seconds", type=float, default=float(os.getenv("VISION_SESSION_SECONDS", DEFAULT_VISION_SESSION_SECONDS)))
+    parser.add_argument("--save-config", action="store_true", help="write CLI args to ~/.robopark/preview_agent.json")
+    parser.add_argument("-v", "--verbose", action="store_true")
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+    cfg = _load_config()
+    cfg.update({
+        "scheduler_url": args.scheduler_url,
+        "robot_id": args.robot_id,
+        "video_device": args.video_device,
+        "audio_device": args.audio_device,
+        "video_width": args.width,
+        "video_height": args.height,
+        "video_fps": args.fps,
+        "poll_interval": args.poll_interval,
+        "heartbeat_interval": args.heartbeat_interval,
+        "vision_webhook_port": args.vision_webhook_port,
+        "vision_trigger_cooldown": args.vision_trigger_cooldown,
+        "vision_session_seconds": args.vision_session_seconds,
+    })
+    if args.device_token:
+        cfg["device_token"] = args.device_token
+        _save_token(args.device_token)
+    if args.enrollment_token:
+        cfg["enrollment_token"] = args.enrollment_token
+
+    if args.save_config:
+        _save_config(cfg)
+        logger.info(f"saved config to {CONFIG_FILE}")
+
+    agent = PreviewAgent(cfg)
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, agent.shutdown)
+        except NotImplementedError:
+            # add_signal_handler is POSIX-only (raises on Windows) — fall back to
+            # signal.signal, dispatched back onto the loop thread-safely.
+            signal.signal(sig, lambda *_: loop.call_soon_threadsafe(agent.shutdown))
+
+    try:
+        loop.run_until_complete(agent.run())
+    finally:
+        loop.close()
+
+
+if __name__ == "__main__":
+    main()