@trillboards/edge-sdk 0.2.74 → 0.2.76

package/deploy/macos/scripts/setup-detector.sh

@@ -0,0 +1,185 @@
+#!/bin/bash
+#
+# setup-detector.sh — provision the on-device OBJECT DETECTOR service
+# (RF-DETR Medium, fp32 ONNX, 127.0.0.1:9380). Runs AS THE USER (home-domain,
+# no sudo). Idempotent and safe to re-run.
+#
+# WHAT IT DOES, AND WHAT IT DELIBERATELY DOES NOT.
+#   1. Ensure `uv` — same discovery, same enterprise-TLS and proxy handling as
+#      setup-litertlm.sh, because the failure it prevents is identical: behind a
+#      TLS-inspecting proxy, `uv tool install` dies on the private root and the
+#      installer blames the wrong component.
+#   2. `uv tool install` the staged `trillboards-detector` package. ITS OWN TOOL
+#      NAME, so uv gives it its own venv — never a package added into litert-lm's,
+#      which `uv tool install --force` rebuilds from scratch on any drift.
+#   3. Render + bootstrap the LaunchAgent. Port 9380; 9379 is not touched.
+#   4. Verify the SERVICE ANSWERS. Not that it is ready — see below.
+#
+#   It does NOT fetch the model. 124 MB of ONNX does not fit under the macOS
+#   slim build's MAX_SLIM_PKG_BYTES = 250 MiB cap with a ~207 MB code slice, so
+#   the artifact is OTA'd by edge-core's ModelManager exactly as Gemma's is.
+#
+# WHY THIS IS BEST-EFFORT AND setup-litertlm.sh IS FATAL.
+# That script may abort the install because without Gemma the connector cannot
+# sense at all. The detector is a CASCADE GATE: with it, ~84.7% of VLM calls are
+# removed for ~2.1% of events; without it every frame simply goes to the VLM, as
+# it does today. A cost optimisation must never be able to block a customer's
+# camera pairing.
+#
+# WHY "ANSWERS" AND NOT "READY" IS THE INSTALL-TIME BAR.
+# At install time the model has not been downloaded yet, so /health is 503 by
+# design. Demanding 200 here would fail every fresh install. What IS checkable —
+# and what actually distinguishes a working install from a broken one — is that
+# the service is listening and speaking JSON at all. The distinction is recorded
+# in the log so an operator reading it can tell "waiting for the model" from
+# "did not start", which is the exact pair litert-lm's `/v1/models` check could
+# not tell apart.
+
+set -u
+USER_HOME="${HOME:-$(eval echo "~$(id -un)")}"
+LOG_DIR="$USER_HOME/Library/Logs/Trillboards"
+SHARE_DIR="$USER_HOME/Library/Trillboards/edge/share"
+LA_DIR="$USER_HOME/Library/LaunchAgents"
+LOCAL_BIN="$USER_HOME/.local/bin"
+SERVE_LABEL="com.trillboards.detector"
+SERVE_PORT="${TRILLBOARDS_DETECTOR_PORT:-9380}"
+DETECTOR_PYTHON="${TRILLBOARDS_DETECTOR_PYTHON:-3.12}"
+# The staged package source. `uv tool install <dir>` builds and installs it into
+# its own venv; the directory is a few tens of KB (no model, no weights).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd || echo .)"
+mkdir -p "$LOG_DIR" "$LA_DIR" 2>/dev/null || true
+LOG="$LOG_DIR/detector-setup.log"
+log() { printf '[trillboards setup-detector] %s %s\n' "$(date '+%H:%M:%S')" "$*" >>"$LOG" 2>&1; printf '[trillboards setup-detector] %s\n' "$*"; }
+
+find_detector_source() {
+  for _c in "$SCRIPT_DIR/detector" \
+            "$SCRIPT_DIR/../detector" \
+            "$SCRIPT_DIR/../../detector"; do
+    [ -f "$_c/pyproject.toml" ] && { (cd "$_c" && pwd); return 0; }
+  done
+  return 1
+}
+
+# One provisioning process per user, and its OWN lock — never litert-lm's.
+# Sharing a lock would make a detector repair block a Gemma repair, which is the
+# component that can actually stop a customer sensing.
+LOCK_DIR="$LOG_DIR/detector-setup.lock"
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+  LOCK_PID="$(cat "$LOCK_DIR/pid" 2>/dev/null || echo '')"
+  if [ -n "$LOCK_PID" ] &&
+     kill -0 "$LOCK_PID" 2>/dev/null &&
+     ps -p "$LOCK_PID" -o command= 2>/dev/null | grep -q '[s]etup-detector.sh'; then
+    log "detector provisioning is already running (pid $LOCK_PID)"
+    exit 0
+  fi
+  rm -rf "$LOCK_DIR" 2>/dev/null || true
+  mkdir "$LOCK_DIR" 2>/dev/null || { log "detector provisioning is already starting in another process"; exit 0; }
+fi
+printf '%s\n' "$$" > "$LOCK_DIR/pid" 2>/dev/null || true
+trap 'rm -rf "$LOCK_DIR" 2>/dev/null || true' EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+log "starting detector provisioning"
+
+# 0b. Enterprise TLS + proxy for uv — identical to setup-litertlm.sh, and for
+# the identical reason. uv ships bundled Mozilla roots and does NOT consult the
+# macOS keychain, nor does it read the system proxy. Both names are exported
+# because an unknown env var is ignored while a CLI flag would fail outright.
+export UV_SYSTEM_CERTS=1
+export UV_NATIVE_TLS=1
+if [ -z "${HTTPS_PROXY:-}" ] && [ -z "${https_proxy:-}" ] && [ -z "${ALL_PROXY:-}" ]; then
+  _proxy_conf="$(/usr/sbin/scutil --proxy 2>/dev/null || true)"
+  if [ "$(printf '%s\n' "$_proxy_conf" | awk '/HTTPSEnable/ {print $3}')" = "1" ]; then
+    _proxy_host="$(printf '%s\n' "$_proxy_conf" | awk '/HTTPSProxy/ {print $3}')"
+    _proxy_port="$(printf '%s\n' "$_proxy_conf" | awk '/HTTPSPort/ {print $3}')"
+    if [ -n "$_proxy_host" ]; then
+      HTTPS_PROXY="http://$_proxy_host${_proxy_port:+:$_proxy_port}"
+      export HTTPS_PROXY
+      export HTTP_PROXY="$HTTPS_PROXY"
+      log "using this machine's configured proxy for detector downloads: $HTTPS_PROXY"
+    fi
+  fi
+fi
+
+# 1. uv.
+export PATH="$LOCAL_BIN:$USER_HOME/.cargo/bin:$PATH"
+if ! command -v uv >/dev/null 2>&1; then
+  log "uv not found — installing via astral.sh standalone installer (no sudo)"
+  curl -LsSf https://astral.sh/uv/install.sh | sh >>"$LOG" 2>&1 || log "WARN: uv install failed"
+  export PATH="$LOCAL_BIN:$USER_HOME/.local/share/uv/bin:$PATH"
+fi
+UV="$(command -v uv || echo "$LOCAL_BIN/uv")"
+if ! command -v "$UV" >/dev/null 2>&1 && [ ! -x "$UV" ]; then
+  log "ERROR: uv unavailable; the detector cascade stays off and every frame goes to the VLM"
+  exit 0
+fi
+
+# 2. The tool. Reinstalled unconditionally: the source is a few tens of KB, the
+# dependency versions are PINNED in pyproject.toml, and uv skips work it has
+# already done — so `--force` costs nothing on a healthy machine and repairs a
+# drifted one. Gating it behind a health check is how a repaired-and-healthy box
+# keeps a broken venv while reporting fine (setup-litertlm.sh's shim carries the
+# same note, from the same mistake).
+SOURCE="$(find_detector_source)" || { log "ERROR: detector package source not found next to this script"; exit 0; }
+log "installing/repairing trillboards-detector from $SOURCE with uv-managed Python $DETECTOR_PYTHON"
+if ! "$UV" tool install --python "$DETECTOR_PYTHON" --managed-python --force "$SOURCE" >>"$LOG" 2>&1; then
+  log "ERROR: trillboards-detector install failed; the cascade stays off (the VLM still runs every frame)"
+  exit 0
+fi
+DETECTOR="$LOCAL_BIN/trillboards-detector"
+[ -x "$DETECTOR" ] || DETECTOR="$(command -v trillboards-detector || echo "$DETECTOR")"
+if [ ! -x "$DETECTOR" ]; then
+  log "ERROR: trillboards-detector binary missing after install"
+  exit 0
+fi
+log "trillboards-detector installed at $DETECTOR"
+
+# 3. Render + bootstrap the LaunchAgent.
+TEMPLATE="$SHARE_DIR/$SERVE_LABEL.plist"
+TARGET="$LA_DIR/$SERVE_LABEL.plist"
+[ -f "$TEMPLATE" ] || TEMPLATE="$SCRIPT_DIR/../$SERVE_LABEL.plist"
+if [ ! -f "$TEMPLATE" ]; then
+  log "ERROR: detector LaunchAgent template missing"
+  exit 0
+fi
+sed -e "s#__DETECTOR__#$DETECTOR#g" \
+    -e "s#__PORT__#$SERVE_PORT#g" \
+    -e "s#__LOG_DIR__#$LOG_DIR#g" \
+    "$TEMPLATE" > "$TARGET" 2>/dev/null || { log "WARN: could not render the detector plist"; exit 0; }
+
+SERVICE_DOMAIN="gui/$(id -u)"
+SERVICE_TARGET="$SERVICE_DOMAIN/$SERVE_LABEL"
+if launchctl print "$SERVICE_TARGET" >/dev/null 2>&1; then
+  log "stopping the existing detector LaunchAgent"
+  launchctl bootout "$SERVICE_TARGET" >>"$LOG" 2>&1 || true
+  for _i in $(seq 1 40); do launchctl print "$SERVICE_TARGET" >/dev/null 2>&1 || break; sleep 0.25; done
+fi
+_bootstrapped=0
+for _attempt in $(seq 1 10); do
+  if launchctl bootstrap "$SERVICE_DOMAIN" "$TARGET" >>"$LOG" 2>&1; then _bootstrapped=1; break; fi
+  launchctl print "$SERVICE_TARGET" >/dev/null 2>&1 && { _bootstrapped=1; break; }
+  sleep 1
+done
+[ "$_bootstrapped" -eq 1 ] || { log "WARN: launchctl bootstrap failed for the detector agent"; exit 0; }
+log "detector LaunchAgent bootstrapped on :$SERVE_PORT"
+
+# 4. Does it ANSWER? Not "is it ready" — the model is OTA'd and is legitimately
+# absent right now. `curl --fail` would treat the designed 503 as a failure, so
+# read the status code instead and say which of the two states we are in.
+HEALTH_CODE=""
+for _attempt in $(seq 1 30); do
+  HEALTH_CODE="$(curl -s -o "$LOG_DIR/.detector-health.json" -w '%{http_code}' --max-time 3 \
+    "http://127.0.0.1:$SERVE_PORT/health" 2>/dev/null)"
+  [ -n "$HEALTH_CODE" ] && [ "$HEALTH_CODE" != "000" ] && break
+  sleep 1
+done
+case "$HEALTH_CODE" in
+  200) log "detector is READY (model already present)" ;;
+  503) log "detector is running and AWAITING ITS MODEL — the OTA will land it and the service picks it up without a restart" ;;
+  *)   log "WARN: the detector service did not answer /health (code '${HEALTH_CODE:-none}'); every frame keeps going to the VLM" ;;
+esac
+rm -f "$LOG_DIR/.detector-health.json" 2>/dev/null || true
+
+log "done"
+exit 0

package/deploy/systemd/install.sh

@@ -53,6 +53,36 @@ sudo -u trillboards HOME=/opt/trillboards bash \
   *** itself as 'waiting for the on-device model' until it does — it will NOT
   *** fall back to paid cloud inference. Re-run install.sh to retry."
 
+# The on-device OBJECT DETECTOR cascade gate (RF-DETR, 127.0.0.1:9380). Its own
+# uv tool, its own venv, its own unit — never a package added into litert-lm's,
+# which `uv tool install --force` rebuilds from scratch on any drift.
+#
+# BEST EFFORT, unlike the block above. Gemma is required because without it the
+# connector cannot sense at all; the detector removes ~84.7% of VLM calls for
+# ~2.1% of events, and without it every frame simply goes to the VLM as it does
+# today. The 124 MB ONNX is NOT fetched here — it arrives over the air on the
+# same channel as Gemma's weights, and the service starts, reports itself
+# unhealthy, and picks the artifact up when it lands without a restart.
+echo "Provisioning the on-device object detector (cascade gate; optional)..."
+sudo cp node_modules/@trillboards/edge-sdk/deploy/systemd/trillboards-detector.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo -u trillboards HOME=/opt/trillboards bash \
+  node_modules/@trillboards/edge-sdk/deploy/systemd/setup-detector.sh \
+  || echo "  *** Detector provisioning did not finish. Sensing is unaffected — every
+  *** frame goes to the on-device VLM exactly as it does without the detector.
+  *** Re-run install.sh to retry."
+# `enable --now`, AFTER the provisioner, and this ORDER is the fix.
+#
+# `systemctl enable` only enables — it does NOT start — and the provisioner above
+# runs as the unprivileged `trillboards` service user (nologin, no sudoers
+# entry), so it cannot start the unit either. Enabling before it and never
+# starting left a fresh Linux box with no detector until its next reboot, with
+# the installer reporting success. `--now` starts it here, where we have root,
+# and after the provisioner so the binary the unit points at already exists.
+sudo systemctl enable --now trillboards-detector \
+  || echo "  *** The detector unit did not start. Sensing is unaffected. Check:
+  *** sudo systemctl status trillboards-detector"
+
 # Pair with a claim code from the portal (Add a camera -> Install). Pairing writes
 # /etc/trillboards/config.json (device token + feeds) — the token is delivered at
 # pair, NEVER baked. Accept the code as $1 for headless installs, else prompt.
@@ -89,5 +119,10 @@ echo "  3. Logs:  sudo journalctl -u trillboards-edge -f"
 echo "  4. Local AI: sudo systemctl status trillboards-litertlm"
 echo "     (the connector runs ON-DEVICE only; if the serve is down it waits and"
 echo "      reports 'waiting' in the portal rather than billing cloud inference)"
+echo "  5. Detector: sudo systemctl status trillboards-detector"
+echo "     (a cascade gate in front of the VLM. Its model arrives over the air,"
+echo "      so 'awaiting its model' on a fresh install is expected, not a fault:"
+echo "      curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:9380/health"
+echo "      answers 503 until the artifact lands and 200 after)"
 echo "  4. Status: sudo systemctl status trillboards-edge"
 echo ""

package/deploy/systemd/setup-detector.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+#
+# setup-detector.sh (Linux) — provision the on-device OBJECT DETECTOR service
+# (RF-DETR Medium, fp32 ONNX, 127.0.0.1:9380).
+#
+# Idempotent and safe to re-run. Run as the `trillboards` service user:
+#   sudo -u trillboards HOME=/opt/trillboards bash setup-detector.sh
+#
+# It installs the tool and starts the unit. It does NOT fetch the model — the
+# 124 MB ONNX is OTA'd by edge-core's ModelManager, the same channel Gemma's
+# weights use — and it does NOT install the unit file (install.sh has the sudo).
+#
+# BEST EFFORT THROUGHOUT. Every failure path exits 0 with a logged reason,
+# because a missing detector means every frame goes to the VLM exactly as it
+# does today. Only the litert-lm provisioner may be fatal, and only because
+# without Gemma the connector cannot sense at all.
+
+set -u
+
+USER_HOME="${HOME:-/opt/trillboards}"
+LOG_DIR="${TRILLBOARDS_LOG_DIR:-/var/log/trillboards}"
+LOCAL_BIN="$USER_HOME/.local/bin"
+SERVE_PORT="${TRILLBOARDS_DETECTOR_PORT:-9380}"
+SERVE_UNIT="trillboards-detector"
+DETECTOR_PYTHON="${TRILLBOARDS_DETECTOR_PYTHON:-3.12}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd || echo .)"
+
+mkdir -p "$LOG_DIR" 2>/dev/null || LOG_DIR="$USER_HOME/.trillboards-logs"
+mkdir -p "$LOG_DIR" 2>/dev/null || true
+LOG="$LOG_DIR/detector-setup.log"
+log() { printf '[trillboards setup-detector] %s %s\n' "$(date '+%H:%M:%S')" "$*" >>"$LOG" 2>&1; printf '[trillboards setup-detector] %s\n' "$*"; }
+
+find_detector_source() {
+  for _c in "$SCRIPT_DIR/detector" \
+            "$SCRIPT_DIR/../detector" \
+            "$SCRIPT_DIR/../../detector"; do
+    [ -f "$_c/pyproject.toml" ] && { (cd "$_c" && pwd); return 0; }
+  done
+  return 1
+}
+
+log "starting detector provisioning"
+
+# Enterprise TLS + proxy for uv. Same two names as the litert-lm provisioner,
+# for the same reason: uv ships bundled Mozilla roots and reads proxy settings
+# only from the environment, so behind a TLS-inspecting proxy this is the step
+# that fails and it fails naming the wrong component.
+export UV_SYSTEM_CERTS=1
+export UV_NATIVE_TLS=1
+
+export PATH="$LOCAL_BIN:$USER_HOME/.cargo/bin:$PATH"
+if ! command -v uv >/dev/null 2>&1; then
+  log "uv not found - installing via astral.sh standalone installer (no sudo)"
+  curl -LsSf https://astral.sh/uv/install.sh | sh >>"$LOG" 2>&1 || log "WARN: uv install failed"
+  export PATH="$LOCAL_BIN:$USER_HOME/.local/share/uv/bin:$PATH"
+fi
+UV="$(command -v uv || echo "$LOCAL_BIN/uv")"
+if ! command -v "$UV" >/dev/null 2>&1 && [ ! -x "$UV" ]; then
+  log "ERROR: uv unavailable; the detector cascade stays off and every frame goes to the VLM"
+  exit 0
+fi
+
+SOURCE="$(find_detector_source)" || { log "ERROR: detector package source not found near $SCRIPT_DIR"; exit 0; }
+
+# ITS OWN TOOL NAME, so uv gives it its own venv. Never a package added into
+# litert-lm's: `uv tool install --force` rebuilds that venv from scratch on any
+# version drift or health failure and would take the addition with it.
+log "installing/repairing trillboards-detector from $SOURCE with uv-managed Python $DETECTOR_PYTHON"
+if ! "$UV" tool install --python "$DETECTOR_PYTHON" --managed-python --force "$SOURCE" >>"$LOG" 2>&1; then
+  log "ERROR: trillboards-detector install failed; the cascade stays off"
+  exit 0
+fi
+DETECTOR="$LOCAL_BIN/trillboards-detector"
+[ -x "$DETECTOR" ] || DETECTOR="$(command -v trillboards-detector || echo "$DETECTOR")"
+[ -x "$DETECTOR" ] || { log "ERROR: trillboards-detector binary missing after install"; exit 0; }
+log "trillboards-detector installed at $DETECTOR"
+
+# The unit is installed AND STARTED by install.sh, which has root. This script
+# runs as the unprivileged `trillboards` service user (nologin, no sudoers
+# entry), so on a fresh install BOTH attempts below fail by design.
+#
+# It still tries, because a re-run by an operator who DOES have privileges is a
+# real recovery path. What it must not do is pretend: it returns non-zero when
+# it could not act, and the caller then skips the health probe entirely rather
+# than waiting 30 s to report a service nobody started as "not answering".
+# `systemctl enable` only enables — it does not start — so before this, a fresh
+# Linux box had no detector until its next reboot and the installer said
+# nothing. Caught by codex on this PR.
+restart_detector_service() {
+  command -v systemctl >/dev/null 2>&1 || return 1
+  if ! systemctl list-unit-files "$SERVE_UNIT.service" >/dev/null 2>&1; then
+    log "WARN: $SERVE_UNIT.service is not installed yet (install.sh installs it)"
+    return 1
+  fi
+  systemctl restart "$SERVE_UNIT" >>"$LOG" 2>&1 && return 0
+  sudo -n systemctl restart "$SERVE_UNIT" >>"$LOG" 2>&1 && return 0
+  return 1
+}
+
+# Does it ANSWER? Not "is it ready" - the model is OTA'd and is legitimately
+# absent right now, so /health is 503 by design and `curl --fail` would call a
+# correct install broken. Read the code and name which state we are in, so an
+# operator can tell "waiting for the model" from "did not start" - the exact
+# pair litert-lm's /v1/models check cannot distinguish.
+#
+# ONLY WHEN WE COULD ACTUALLY START IT. Probing a service this account has no
+# permission to start would spend 30 s to report "did not answer" about a
+# service nobody has started yet, which reads as a broken install and is not
+# one. install.sh owns the start, with root, right after this script returns.
+if ! restart_detector_service; then
+  log "tool installed; this account cannot start $SERVE_UNIT - the installer starts it with root"
+  log "done"
+  exit 0
+fi
+
+HEALTH_CODE=""
+for _attempt in $(seq 1 30); do
+  HEALTH_CODE="$(curl -s -o /dev/null -w '%{http_code}' --max-time 3 \
+    "http://127.0.0.1:$SERVE_PORT/health" 2>/dev/null)"
+  [ -n "$HEALTH_CODE" ] && [ "$HEALTH_CODE" != "000" ] && break
+  sleep 1
+done
+case "$HEALTH_CODE" in
+  200) log "detector is READY (model already present)" ;;
+  503) log "detector is running and AWAITING ITS MODEL - the OTA will land it and the service picks it up without a restart" ;;
+  *)   log "WARN: the detector service did not answer /health (code '${HEALTH_CODE:-none}'); every frame keeps going to the VLM" ;;
+esac
+
+log "done"
+exit 0

package/deploy/systemd/trillboards-detector.service

@@ -0,0 +1,54 @@
+[Unit]
+Description=Trillboards on-device object detector (RF-DETR cascade gate for the BYO-CCTV connector)
+Documentation=https://github.com/trillboards/packages
+After=network-online.target
+Wants=network-online.target
+# NOT Before=trillboards-edge.service, and not Requires= either.
+#
+# The litert-lm unit orders itself before the connector because without Gemma
+# the connector cannot sense at all. This one gates a COST: with it, ~84.7% of
+# VLM calls are removed for ~2.1% of events; without it every frame goes to the
+# VLM exactly as it does today. Ordering the connector behind a pure
+# optimisation would let a slow detector start delay sensing, which is a strictly
+# worse trade than the one it exists to make.
+
+[Service]
+Type=simple
+User=trillboards
+Group=trillboards
+WorkingDirectory=/opt/trillboards
+# Path is written by setup-detector.sh; the tool lands in the trillboards user's
+# home-domain uv bin, never system-wide (no sudo pip, no root-owned venv).
+ExecStart=/opt/trillboards/.local/bin/trillboards-detector serve --host 127.0.0.1 --port 9380
+Restart=always
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=trillboards-detector
+
+# Security hardening. TIGHTER than the litert-lm unit: this process needs no GPU
+# render nodes (`docs/runbooks/cctv-detector-tier.md` §6 — the DirectML/ROCm path
+# was never exercised and the decision is CPU-only), and it needs no model store
+# of its own beyond the connector's data dir.
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=false
+ReadWritePaths=/opt/trillboards
+PrivateTmp=true
+PrivateDevices=true
+
+# Bind ONLY to loopback (see ExecStart --host). `LocalDetectorClient` talks to
+# 127.0.0.1:9380; nothing off-box has any business reaching this.
+IPAddressAllow=localhost
+IPAddressDeny=any
+
+# HOME decides where the model artifact is read from: setup-detector.sh and
+# `modelpath.py` both resolve ${TRILLBOARDS_DATA_DIR:-$HOME/.trillboards}/models,
+# matching config.ts's `DEFAULTS.dataDir`. If this and the connector's HOME ever
+# disagree, the detector is permanently unhealthy on a box whose artifact is
+# sitting right there.
+Environment=HOME=/opt/trillboards
+EnvironmentFile=-/etc/trillboards/env
+
+[Install]
+WantedBy=multi-user.target

package/deploy/windows/build-windows.ps1

@@ -227,6 +227,44 @@ Copy-Item -Force "$Here\setup-litertlm.ps1"         "$Payload\bin\setup-litertlm
 # provisioning time; nothing else reads it, and no upstream file is modified.
 Copy-Item -Force "$Here\..\litertlm\trillboards_litertlm_shim.py" "$Payload\bin\trillboards_litertlm_shim.py"
 Copy-Item -Force "$Here\register-litertlm-task.ps1" "$Payload\bin\register-litertlm-task.ps1"
+
+# On-device OBJECT DETECTOR (RF-DETR cascade gate, :9380). Its own uv tool, its
+# own venv, its own Scheduled Task -- never a package added into litert-lm's,
+# which `uv tool install --force` rebuilds from scratch on any drift.
+#
+# THE EXACT STAGING SHAPE BELOW IS LOAD-BEARING, character for character.
+# ci\list-shipped-scripts.ps1 REGEX-SCRAPES this file to derive the Authenticode
+# signing set: a literal Copy-Item -Force, a "$Here\..." source with no inner
+# backslash, and a "$Payload\bin\..." destination. A Join-Path, a loop, or a
+# `..\` in the source is invisible to it and the script ships UNSIGNED -- which
+# then fails apply-update.ps1's Assert-PayloadSignatures in the FIELD, not just
+# at install. (And do not write that pattern out in a comment: the scrape is a
+# regex over the whole file, so a comment naming it enrols a file that does not
+# exist. This paragraph is deliberately phrased so it cannot match.)
+Copy-Item -Force "$Here\setup-detector.ps1"          "$Payload\bin\setup-detector.ps1"
+Copy-Item -Force "$Here\register-detector-task.ps1"  "$Payload\bin\register-detector-task.ps1"
+# The Python package SOURCE that `uv tool install` builds into its own venv.
+# Tens of KB; the 124 MB fp32 ONNX it runs is OTA'd, never bundled. Not matched
+# by the signing derivation above (the `..\` forbids it, and .py is not a
+# signable kind) -- the same treatment trillboards_litertlm_shim.py gets.
+New-Item -ItemType Directory -Force -Path "$Payload\bin\detector" | Out-Null
+# `build`/`dist`/`*.egg-info` are excluded for a REASON: setuptools copies from
+# `build\lib\` on a later build, so a stale one staged here would install the
+# PREVIOUS revision of the service behind a green installer. The package uses
+# hatchling so it never creates one; this covers a leftover from an older
+# backend or a hand-run build.
+#
+# ALL FOUR ARE DIRECTORIES, SO ALL FOUR GO IN /XD. `*.egg-info` sat in /XF for
+# one commit, where it matched nothing at all -- /XF excludes FILES -- so the
+# comment above described an exclusion that was not happening. An exclude that
+# silently matches nothing is worse than no exclude, because the comment stops
+# anyone checking.
+robocopy "$Here\..\detector" "$Payload\bin\detector" /E /NFL /NDL /NJH /NJS /NP `
+  /XD "__pycache__" "bench" "build" "dist" "*.egg-info" /XF "*.pyc" | Out-Null
+if ($LASTEXITCODE -ge 8) { Die "failed to stage the detector package source (robocopy $LASTEXITCODE)" }
+$global:LASTEXITCODE = 0
+if (-not (Test-Path "$Payload\bin\detector\pyproject.toml")) { Die "detector package source did not stage" }
+
 Copy-Item -Force "$Here\check-feeds.js"       "$Payload\bin\check-feeds.js"
 
 # ─── 7. Smoke-test the staged bundle BEFORE packaging ──────────────────────────

package/deploy/windows/installer.nsi

@@ -27,6 +27,7 @@
 !define APP_NAME "Sense Anything Connector"
 !define TASK_NAME "TrillboardsEdge"
 !define LITERT_TASK_NAME "TrillboardsLiteRtLm"
+!define DETECTOR_TASK_NAME "TrillboardsDetector"
 !define MUI_ICON "${APP_ICON}"
 !define MUI_UNICON "${APP_ICON}"
 
@@ -203,6 +204,26 @@ Section "Install"
   ${EndIf}
   DetailPrint "Private local AI is installed and healthy."
 
+  ; -- On-device object detector (cascade gate, :9380) -----------------------
+  ; BEST EFFORT, and deliberately NOT an Abort like the block above.
+  ;
+  ; Gemma is required: without it the connector cannot sense at all. The
+  ; detector is a gate in FRONT of it -- it removes ~84.7% of VLM calls for
+  ; ~2.1% of events -- so a machine without one senses exactly as it does today,
+  ; only more expensively. A cost optimisation must never block camera pairing.
+  ;
+  ; It also cannot be verified here the way Gemma is: its 124 MB ONNX is OTA'd
+  ; (bundling it would break the code-only size budget), so right now the
+  ; artifact is legitimately absent and the service correctly reports itself
+  ; unhealthy. setup-detector.ps1 checks that it ANSWERS and logs which of the
+  ; two states it is in.
+  DetailPrint "Installing the on-device object detector..."
+  nsExec::ExecToLog '"$WINDIR\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -ExecutionPolicy Bypass -File "$INSTDIR\bin\setup-detector.ps1"'
+  Pop $0
+  ${If} $0 != 0
+    DetailPrint "The object detector could not be installed; sensing is unaffected (every frame goes to the on-device VLM)."
+  ${EndIf}
+
   ; -- Unattended provisioning ----------------------------------------------
   ; With /ENROLLMENT_TOKEN=, the machine provisions ITSELF here - no code typed
   ; at the machine, no browser, no human. enroll-connector.ps1 writes the
@@ -252,12 +273,14 @@ Section "Install"
 SectionEnd
 
 Section "Uninstall"
-  ; Stop + remove the background tasks (connector + litert-lm serve).
+  ; Stop + remove the background tasks (connector + litert-lm serve + detector).
   nsExec::ExecToLog 'powershell -NoProfile -ExecutionPolicy Bypass -File "$INSTDIR\bin\stop-existing.ps1" -InstallDir "$INSTDIR"'
   nsExec::ExecToLog 'schtasks /End /TN "${TASK_NAME}"'
   nsExec::ExecToLog 'schtasks /Delete /F /TN "${TASK_NAME}"'
   nsExec::ExecToLog 'schtasks /End /TN "${LITERT_TASK_NAME}"'
   nsExec::ExecToLog 'schtasks /Delete /F /TN "${LITERT_TASK_NAME}"'
+  nsExec::ExecToLog 'schtasks /End /TN "${DETECTOR_TASK_NAME}"'
+  nsExec::ExecToLog 'schtasks /Delete /F /TN "${DETECTOR_TASK_NAME}"'
   ; Explicit, ahead of RMDir /r: a fleet enrollment credential must never
   ; survive an uninstall, and relying on the recursive delete makes that a
   ; property of statement ORDER rather than of intent.