infinicode 2.8.35 → 2.8.37

package/packages/robopark/scheduler/robot_supervisor.py

@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+"""
+RoboPark Robot Supervisor — runs on each robot/satellite Pi (or a Windows
+test rig), keeping every robot-side service alive without a human watching
+a terminal.
+
+Problem this solves: a real robot needs several independent processes —
+preview_agent.py (LiveKit publish + heartbeat + motion webhook), optionally
+a vision/motion-detection app (RoboVisionAI_PI's app_pi_clean.py or
+equivalent), optionally a motor server — and today each one has to be
+started by hand in its own terminal, with nothing bringing a crashed one
+back. This supervisor is a single process management layer, not a merge of
+those services into one program: each keeps its own hardware access,
+failure mode, and restart behavior isolated from the others, while still
+being "one thing to run" operationally.
+
+Configuration: ~/.robopark/supervisor.json (see supervisor.example.json in
+this directory for the schema). Services are opt-in — only preview_agent is
+enabled by default, since vision_app/motor_server commands are specific to
+each robot's actual hardware/codebase and have no safe generic default.
+
+Usage:
+    python robot_supervisor.py [--config PATH]
+
+Auto-start on boot:
+    Windows: scripts/install-robot-supervisor-windows.ps1 (Task Scheduler,
+             runs at user logon — required for mic/camera access, which
+             Windows restricts to an interactive session).
+    Linux:   scripts/robopark-supervisor.service (systemd unit template).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import signal
+import subprocess
+import sys
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger("robopark.supervisor")
+
+CONFIG_DIR = Path.home() / ".robopark"
+DEFAULT_CONFIG_FILE = CONFIG_DIR / "supervisor.json"
+LOG_DIR = CONFIG_DIR / "logs"
+
+# A service that has run this long without exiting is considered stable —
+# its failure/backoff count resets so a single crash after weeks of uptime
+# doesn't get treated like a crash loop.
+STABLE_UPTIME_SECONDS = 60.0
+BACKOFF_BASE_SECONDS = 2.0
+BACKOFF_MAX_SECONDS = 60.0
+LOG_ROTATE_BYTES = 5 * 1024 * 1024  # rotate a service's log past 5MB
+POLL_INTERVAL_SECONDS = 2.0
+STATUS_REPORT_INTERVAL_SECONDS = 10.0
+
+
+def _load_robopark_identity() -> Optional[tuple[str, str, str]]:
+    """Reuse preview_agent.py's own enrollment files (same ~/.robopark/ dir)
+    so the supervisor can report status to the scheduler without needing
+    separate credentials. Returns (device_id, scheduler_url, token) or None
+    if this robot hasn't been enrolled yet."""
+    cfg_file = CONFIG_DIR / "preview_agent.json"
+    token_file = CONFIG_DIR / "device_token"
+    if not cfg_file.exists() or not token_file.exists():
+        return None
+    try:
+        cfg = json.loads(cfg_file.read_text(encoding="utf8"))
+        device_id = cfg.get("device_id")
+        scheduler_url = cfg.get("scheduler_url", "http://localhost:8080")
+        token = token_file.read_text(encoding="utf8").strip()
+        if not device_id or not token:
+            return None
+        return device_id, scheduler_url, token
+    except Exception:
+        return None
+
+
+def _report_status(states: "list[ServiceState]", identity: tuple[str, str, str]) -> list[dict]:
+    """POST current service status; returns any pending remote-control
+    commands the scheduler had queued for this device (e.g. an operator
+    clicking "restart" in the dashboard) -- delivered on this same
+    request/response cycle rather than a separate poll."""
+    device_id, scheduler_url, token = identity
+    try:
+        import httpx
+    except ImportError:
+        logger.debug("httpx not installed -- skipping status report (see requirements-robot.txt)")
+        return []
+    payload = {"services": [s.status_dict() for s in states]}
+    url = f"{scheduler_url.rstrip('/')}/api/devices/{device_id}/supervisor-status"
+    try:
+        resp = httpx.post(url, json=payload, headers={"Authorization": f"Bearer {token}"}, timeout=5.0)
+        resp.raise_for_status()
+        return resp.json().get("commands", [])
+    except Exception as e:
+        logger.debug(f"status report failed (scheduler unreachable?): {e}")
+        return []
+
+
+@dataclass
+class ServiceSpec:
+    name: str
+    enabled: bool
+    command: list[str]
+    cwd: Optional[str] = None
+    env: Optional[dict] = None
+
+
+@dataclass
+class ServiceState:
+    spec: ServiceSpec
+    proc: Optional[subprocess.Popen] = None
+    log_file: Optional[object] = None
+    started_at: float = 0.0
+    failure_count: int = 0
+    next_restart_at: float = 0.0
+    last_exit_code: Optional[int] = None
+    stopped: bool = False  # true once the supervisor is shutting down
+
+    def status_dict(self) -> dict:
+        running = self.proc is not None
+        return {
+            "name": self.spec.name,
+            "enabled": self.spec.enabled,
+            "running": running,
+            "pid": self.proc.pid if running else None,
+            "uptime_seconds": (time.monotonic() - self.started_at) if running else None,
+            "failure_count": self.failure_count,
+            "last_exit_code": self.last_exit_code,
+        }
+
+
+def _load_config(path: Path) -> tuple[list[ServiceSpec], Path]:
+    if not path.exists():
+        raise SystemExit(
+            f"No config at {path}. Copy supervisor.example.json there and "
+            f"edit it, or pass --config PATH."
+        )
+    data = json.loads(path.read_text(encoding="utf8"))
+    services = [
+        ServiceSpec(
+            name=s["name"],
+            enabled=bool(s.get("enabled", False)),
+            command=list(s["command"]),
+            cwd=s.get("cwd"),
+            env=s.get("env"),
+        )
+        for s in data.get("services", [])
+    ]
+    log_dir = Path(data.get("log_dir", str(LOG_DIR))).expanduser()
+    return services, log_dir
+
+
+def _open_log(log_dir: Path, name: str):
+    log_dir.mkdir(parents=True, exist_ok=True)
+    path = log_dir / f"{name}.log"
+    if path.exists() and path.stat().st_size > LOG_ROTATE_BYTES:
+        rotated = log_dir / f"{name}.log.1"
+        try:
+            rotated.unlink(missing_ok=True)
+            path.rename(rotated)
+        except OSError as e:
+            logger.warning(f"log rotate failed for {name}: {e}")
+    return open(path, "a", encoding="utf8", buffering=1)
+
+
+def _spawn(state: ServiceState, log_dir: Path) -> None:
+    spec = state.spec
+    state.log_file = _open_log(log_dir, spec.name)
+    env = os.environ.copy()
+    if spec.env:
+        env.update(spec.env)
+    banner = f"\n=== supervisor: starting {spec.name} at {time.strftime('%Y-%m-%d %H:%M:%S')} ===\n"
+    state.log_file.write(banner)
+    try:
+        state.proc = subprocess.Popen(
+            spec.command,
+            cwd=spec.cwd,
+            env=env,
+            stdout=state.log_file,
+            stderr=subprocess.STDOUT,
+            stdin=subprocess.DEVNULL,
+        )
+        state.started_at = time.monotonic()
+        logger.info(f"started {spec.name} (pid={state.proc.pid}): {' '.join(spec.command)}")
+    except Exception as e:
+        logger.error(f"failed to start {spec.name}: {e}")
+        state.proc = None
+        state.failure_count += 1
+
+
+def _schedule_restart(state: ServiceState) -> None:
+    backoff = min(BACKOFF_BASE_SECONDS * (2 ** state.failure_count), BACKOFF_MAX_SECONDS)
+    state.next_restart_at = time.monotonic() + backoff
+    logger.warning(f"{state.spec.name} exited — restarting in {backoff:.0f}s (failure #{state.failure_count})")
+
+
+def _terminate(state: ServiceState) -> None:
+    if not state.proc:
+        return
+    try:
+        state.proc.terminate()
+        try:
+            state.proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            logger.warning(f"{state.spec.name} did not exit in time, killing")
+            state.proc.kill()
+            state.proc.wait(timeout=5)
+    except Exception as e:
+        logger.error(f"error stopping {state.spec.name}: {e}")
+    finally:
+        if state.log_file:
+            state.log_file.close()
+            state.log_file = None
+
+
+def _execute_command(state: ServiceState, action: str) -> None:
+    """Operator-initiated action from the dashboard. Currently only
+    "restart" -- terminate if running (the main loop's own restart logic
+    then respawns it), and clear any crash backoff since this isn't a
+    crash, it's a deliberate request that should take effect right away."""
+    if action != "restart":
+        logger.warning(f"ignoring unknown remote command {action!r} for {state.spec.name}")
+        return
+    logger.info(f"remote restart requested for {state.spec.name}")
+    if state.proc is not None:
+        _terminate(state)
+        state.proc = None
+    state.failure_count = 0
+    state.next_restart_at = 0.0  # due immediately -- the main loop respawns it next tick
+
+
+def run(config_path: Path) -> None:
+    services, log_dir = _load_config(config_path)
+    enabled = [s for s in services if s.enabled]
+    if not enabled:
+        raise SystemExit(f"No enabled services in {config_path} — nothing to supervise.")
+
+    states = [ServiceState(spec=s) for s in enabled]
+    for state in states:
+        _spawn(state, log_dir)
+
+    shutdown = {"flag": False}
+
+    def _on_signal(signum, frame):
+        logger.info(f"received signal {signum}, shutting down all services…")
+        shutdown["flag"] = True
+
+    signal.signal(signal.SIGINT, _on_signal)
+    signal.signal(signal.SIGTERM, _on_signal)
+
+    logger.info(f"supervising {len(states)} service(s): {', '.join(s.spec.name for s in states)}")
+
+    last_status_report_at = 0.0
+    try:
+        while not shutdown["flag"]:
+            now = time.monotonic()
+            for state in states:
+                if state.proc is None:
+                    if now >= state.next_restart_at:
+                        _spawn(state, log_dir)
+                    continue
+                ret = state.proc.poll()
+                if ret is None:
+                    continue  # still running
+                # Exited. A long uptime before exit resets the backoff —
+                # otherwise a service that's crash-looping keeps backing off.
+                uptime = now - state.started_at
+                state.last_exit_code = ret
+                if uptime >= STABLE_UPTIME_SECONDS:
+                    state.failure_count = 0
+                else:
+                    state.failure_count += 1
+                if state.log_file:
+                    state.log_file.write(f"=== supervisor: {state.spec.name} exited with code {ret} (uptime {uptime:.0f}s) ===\n")
+                    state.log_file.close()
+                    state.log_file = None
+                state.proc = None
+                _schedule_restart(state)
+            if now - last_status_report_at >= STATUS_REPORT_INTERVAL_SECONDS:
+                last_status_report_at = now
+                identity = _load_robopark_identity()
+                if identity:
+                    commands = _report_status(states, identity)
+                    by_name = {s.spec.name: s for s in states}
+                    for cmd in commands:
+                        target = by_name.get(cmd.get("service_name"))
+                        if target:
+                            _execute_command(target, cmd.get("action", "restart"))
+                        else:
+                            logger.warning(f"remote command for unknown service {cmd.get('service_name')!r} ignored")
+                else:
+                    logger.debug("not enrolled yet (no ~/.robopark/preview_agent.json + device_token) -- skipping status report")
+            time.sleep(POLL_INTERVAL_SECONDS)
+    finally:
+        for state in states:
+            _terminate(state)
+        logger.info("all services stopped, exiting")
+
+
+def main() -> None:
+    # stdout/stderr are fully buffered (not line-buffered) once redirected to
+    # a file or pipe -- which is exactly how Task Scheduler/systemd run this.
+    # Without this, restart/crash log lines can sit unflushed for minutes.
+    sys.stdout.reconfigure(line_buffering=True)
+    sys.stderr.reconfigure(line_buffering=True)
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG_FILE, help="path to supervisor.json")
+    args = parser.parse_args()
+    run(args.config)
+
+
+if __name__ == "__main__":
+    main()

package/packages/robopark/scheduler/scripts/install-robot-supervisor-linux.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# Installs the RoboPark robot supervisor as a systemd service on a real
+# robot (Raspberry Pi or similar). Auto-starts on boot, restarts on crash.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SUPERVISOR_DIR="$(dirname "$SCRIPT_DIR")"
+UNIT_SRC="$SCRIPT_DIR/robopark-supervisor.service"
+UNIT_DST="/etc/systemd/system/robopark-supervisor.service"
+
+if [ ! -f "$SUPERVISOR_DIR/robot_supervisor.py" ]; then
+    echo "robot_supervisor.py not found in $SUPERVISOR_DIR" >&2
+    exit 1
+fi
+
+if [ ! -f "$HOME/.robopark/supervisor.json" ]; then
+    echo "No ~/.robopark/supervisor.json yet — copy supervisor.example.json there and edit it first:" >&2
+    echo "  cp $SUPERVISOR_DIR/supervisor.example.json ~/.robopark/supervisor.json" >&2
+    exit 1
+fi
+
+echo "Installing systemd unit -> $UNIT_DST (requires sudo)"
+sudo sed \
+    -e "s#WorkingDirectory=.*#WorkingDirectory=$SUPERVISOR_DIR#" \
+    -e "s#User=.*#User=$(whoami)#" \
+    "$UNIT_SRC" | sudo tee "$UNIT_DST" > /dev/null
+
+sudo systemctl daemon-reload
+sudo systemctl enable robopark-supervisor.service
+sudo systemctl restart robopark-supervisor.service
+
+echo "Installed and started. Check status: sudo systemctl status robopark-supervisor.service"
+echo "Logs: journalctl -u robopark-supervisor.service -f  (or ~/.robopark/logs/*.log per-service)"

package/packages/robopark/scheduler/scripts/install-robot-supervisor-windows.ps1

@@ -0,0 +1,49 @@
+<#
+.SYNOPSIS
+  Registers the RoboPark robot supervisor to auto-start at Windows logon.
+
+.DESCRIPTION
+  Creates a Scheduled Task that runs robot_supervisor.py whenever this user
+  logs in, restarting it automatically if it ever exits unexpectedly. Runs
+  in the interactive session (not "run whether logged on or not") because
+  Windows restricts microphone/camera access to interactive sessions —
+  preview_agent.py needs both.
+
+  The supervisor itself (robot_supervisor.py) is what keeps the individual
+  robot services (preview_agent, vision app, motor server) alive; this task
+  is the one layer above that keeps the supervisor itself running.
+
+.PARAMETER PythonExe
+  Path to python.exe. Defaults to whatever `python` resolves to on PATH.
+
+.EXAMPLE
+  .\install-robot-supervisor-windows.ps1
+  .\install-robot-supervisor-windows.ps1 -PythonExe "C:\Python312\python.exe"
+#>
+param(
+    [string]$PythonExe = (Get-Command python -ErrorAction Stop).Source
+)
+
+$ErrorActionPreference = 'Stop'
+$scriptDir = Split-Path -Parent $PSScriptRoot
+$supervisorScript = Join-Path $scriptDir 'robot_supervisor.py'
+if (-not (Test-Path $supervisorScript)) {
+    throw "robot_supervisor.py not found at $supervisorScript"
+}
+
+$taskName = 'RoboParkSupervisor'
+$action = New-ScheduledTaskAction -Execute $PythonExe -Argument "`"$supervisorScript`"" -WorkingDirectory $scriptDir
+$trigger = New-ScheduledTaskTrigger -AtLogOn
+$settings = New-ScheduledTaskSettingsSet `
+    -RestartCount 999 `
+    -RestartInterval (New-TimeSpan -Minutes 1) `
+    -ExecutionTimeLimit (New-TimeSpan -Days 0) `
+    -AllowStartIfOnBatteries `
+    -DontStopIfGoingOnBatteries
+
+Register-ScheduledTask -TaskName $taskName -Action $action -Trigger $trigger -Settings $settings -Force | Out-Null
+
+Write-Output "Registered scheduled task '$taskName' — starts at logon, restarts on crash."
+Write-Output "Config: copy supervisor.example.json to `$HOME\.robopark\supervisor.json and edit it first if you haven't."
+Write-Output "Start it now without logging out: Start-ScheduledTask -TaskName '$taskName'"
+Write-Output "Remove it later: Unregister-ScheduledTask -TaskName '$taskName' -Confirm:`$false"

package/packages/robopark/scheduler/scripts/robopark-supervisor.service

@@ -0,0 +1,20 @@
+[Unit]
+Description=RoboPark robot supervisor (preview_agent + vision + motors)
+After=network-online.target sound.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+# Edit these two for your setup:
+User=pi
+WorkingDirectory=/home/pi/infinicode-main/packages/robopark/scheduler
+ExecStart=/usr/bin/python3 robot_supervisor.py
+Restart=always
+RestartSec=5
+# Camera/audio devices, GPIO — adjust group membership instead of running as
+# root: `sudo usermod -aG video,audio,gpio pi`
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target

package/packages/robopark/scheduler/scripts/start-scheduler-local.ps1

@@ -0,0 +1,50 @@
+<#
+.SYNOPSIS
+  Starts the RoboPark scheduler locally with every env var it needs.
+
+.DESCRIPTION
+  main.py's own auth for the voice agent's session-keepalive calls
+  (ROBOPARK_AGENT_TOKEN, checked in POST /api/sessions/{id}/keepalive)
+  silently degrades to "every keepalive gets 401'd" if the scheduler is
+  ever started without it set -- no startup error, no crash, just every
+  motion-triggered session getting cut off by its own silence-timeout
+  within ~15s because last_activity_at never updates. This bit twice in
+  one session from ad-hoc restarts that forgot the env var. Use this
+  script (or set the same vars) for every local restart instead of a bare
+  `python main.py`.
+
+  ROBOPARK_AGENT_TOKEN here MUST match ROBOPARK_AGENT_TOKEN in the voice
+  agent's own .env -- it's the shared secret the agent container presents
+  via the X-RoboPark-Agent-Token header. Never hardcode the actual value
+  in this script (it's committed to git) -- pass it explicitly, set it in
+  your shell first, or point -AgentEnvFile at the agent's .env to read it
+  from there at run time.
+
+.EXAMPLE
+  .\start-scheduler-local.ps1 -AgentToken "the-real-token"
+  .\start-scheduler-local.ps1 -AgentEnvFile "C:\path\to\ROBOVOICE-main\.env"
+  $env:ROBOPARK_AGENT_TOKEN = "the-real-token"; .\start-scheduler-local.ps1
+#>
+param(
+    [string]$DataDir = "C:\Users\yunge\OneDrive\Desktop\data",
+    [string]$AgentToken = $env:ROBOPARK_AGENT_TOKEN,
+    [string]$AgentEnvFile,
+    [string]$PythonExe = (Get-Command python -ErrorAction Stop).Source
+)
+
+$ErrorActionPreference = 'Stop'
+$schedulerDir = Split-Path -Parent $PSScriptRoot
+
+if (-not $AgentToken -and $AgentEnvFile -and (Test-Path $AgentEnvFile)) {
+    $line = Get-Content $AgentEnvFile | Where-Object { $_ -match '^ROBOPARK_AGENT_TOKEN=' } | Select-Object -First 1
+    if ($line) { $AgentToken = ($line -split '=', 2)[1].Trim() }
+}
+if (-not $AgentToken) {
+    throw "ROBOPARK_AGENT_TOKEN not provided. Pass -AgentToken, set `$env:ROBOPARK_AGENT_TOKEN first, or pass -AgentEnvFile pointing at the voice agent's .env."
+}
+
+$env:SCHEDULER_DATA_DIR = $DataDir
+$env:ROBOPARK_AGENT_TOKEN = $AgentToken
+
+Write-Output "Starting scheduler: SCHEDULER_DATA_DIR=$DataDir, ROBOPARK_AGENT_TOKEN set (len=$($AgentToken.Length))"
+& $PythonExe (Join-Path $schedulerDir 'main.py')

package/packages/robopark/scheduler/supervisor.example.json

@@ -0,0 +1,26 @@
+{
+  "log_dir": "~/.robopark/logs",
+  "services": [
+    {
+      "name": "preview_agent",
+      "enabled": true,
+      "comment": "Core service — heartbeat, LiveKit publish, motion webhook listener. Reads its own settings from ~/.robopark/preview_agent.json (device_id, scheduler_url, etc), enrolled once via `robopark add-robot`.",
+      "command": ["python", "preview_agent.py"],
+      "cwd": "/absolute/path/to/infinicode-main/packages/robopark/scheduler"
+    },
+    {
+      "name": "vision_app",
+      "enabled": false,
+      "comment": "Real motion/object detection (e.g. RoboVisionAI_PI's app_pi_clean.py). Must POST to preview_agent's motion webhook (http://localhost:<vision-webhook-port>/, default 5057) on detection. Disabled by default — no safe generic command, fill in your robot's actual vision app path.",
+      "command": ["python", "app_pi_clean.py"],
+      "cwd": "/absolute/path/to/RoboVisionAI_PI"
+    },
+    {
+      "name": "motor_server",
+      "enabled": false,
+      "comment": "Only needed if your robot's motors are NOT wired to preview_agent's LiveKit data-channel path — i.e. voice_agent.py falls back to motor_server_url (set on the character preset / device) instead of the data-channel. Disabled by default.",
+      "command": ["python", "-m", "uvicorn", "motors:app", "--host", "0.0.0.0", "--port", "8001"],
+      "cwd": "/absolute/path/to/motor-server-project"
+    }
+  ]
+}

package/packages/robopark/scheduler/vision_motion_trigger.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+Minimal cross-platform motion detector -> preview_agent.py's motion webhook.
+
+RoboVisionAI_PI's real app_pi_clean.py does full object detection + motion
++ MJPEG streaming in one Flask app, but its motion loop only actually runs
+while something is actively pulling /video_feed, and it wants Pi-specific
+caffemodel files for the object-detection half. For a plain "does motion
+actually reach the conversation pipeline" test (or a lightweight always-on
+trigger on a robot that doesn't need the vision overlay), this is a much
+smaller piece: open whatever camera OpenCV can see, do frame-differencing
+motion detection, POST to the webhook on motion, done. No Flask, no model
+files, works the same on Windows/Linux/Pi wherever cv2 can open a camera.
+
+preview_agent.py's webhook handler accepts any POST body (even {}) as a
+trigger signal -- it does not require the RoboVisionAI_PI payload shape --
+so this only needs to hit the URL, not match any particular JSON schema.
+
+Usage:
+    python vision_motion_trigger.py --webhook-url http://localhost:5058/
+    python vision_motion_trigger.py --camera 0 --min-area 800 --cooldown 15
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import time
+
+logger = logging.getLogger("robopark.vision_motion_trigger")
+
+
+def run(camera_index: int, webhook_url: str, min_area: float, cooldown: float, fps_limit: float) -> None:
+    import cv2
+    import httpx
+
+    cap = cv2.VideoCapture(camera_index)
+    if not cap.isOpened():
+        raise SystemExit(f"could not open camera index {camera_index}")
+    logger.info(f"camera {camera_index} opened, watching for motion (min_area={min_area}px, cooldown={cooldown}s)")
+
+    prev_gray = None
+    last_trigger = 0.0
+    frame_interval = 1.0 / fps_limit if fps_limit > 0 else 0.0
+    client = httpx.Client(timeout=5.0)
+
+    try:
+        while True:
+            loop_start = time.monotonic()
+            ok, frame = cap.read()
+            if not ok:
+                logger.warning("camera read failed, retrying")
+                time.sleep(1.0)
+                continue
+
+            gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+            gray = cv2.GaussianBlur(gray, (21, 21), 0)
+
+            if prev_gray is not None:
+                delta = cv2.absdiff(prev_gray, gray)
+                thresh = cv2.threshold(delta, 25, 255, cv2.THRESH_BINARY)[1]
+                thresh = cv2.dilate(thresh, None, iterations=2)
+                contours, _ = cv2.findContours(thresh, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+                motion = any(cv2.contourArea(c) >= min_area for c in contours)
+
+                if motion:
+                    now = time.time()
+                    if now - last_trigger >= cooldown:
+                        last_trigger = now
+                        logger.info("motion detected, posting to webhook")
+                        try:
+                            client.post(webhook_url, json={"source": "vision_motion_trigger"})
+                        except Exception as e:
+                            logger.warning(f"webhook POST failed: {e}")
+                    else:
+                        logger.debug("motion detected, still in cooldown")
+
+            prev_gray = gray
+
+            if frame_interval:
+                elapsed = time.monotonic() - loop_start
+                if elapsed < frame_interval:
+                    time.sleep(frame_interval - elapsed)
+    finally:
+        cap.release()
+        client.close()
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--camera", type=int, default=0, help="OpenCV camera index (default 0)")
+    parser.add_argument("--webhook-url", default="http://localhost:5058/", help="preview_agent.py's motion webhook")
+    parser.add_argument("--min-area", type=float, default=500.0, help="minimum changed-pixel contour area to count as motion")
+    parser.add_argument("--cooldown", type=float, default=20.0, help="minimum seconds between triggers")
+    parser.add_argument("--fps-limit", type=float, default=5.0, help="cap capture rate to reduce CPU (0 = uncapped)")
+    args = parser.parse_args()
+    run(args.camera, args.webhook_url, args.min_area, args.cooldown, args.fps_limit)
+
+
+if __name__ == "__main__":
+    main()