mirror of
https://github.com/ruvnet/RuView
synced 2026-06-28 13:23:19 +00:00
Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 github-actions[bot]
|
960755fbed |
@@ -126,7 +126,10 @@
|
||||
"Bash(node .claude/*)",
|
||||
"mcp__claude-flow__:*"
|
||||
],
|
||||
"deny": []
|
||||
"deny": [
|
||||
"Read(./.env)",
|
||||
"Read(./.env.*)"
|
||||
]
|
||||
},
|
||||
"attribution": {
|
||||
"commit": "Co-Authored-By: claude-flow <ruv@ruv.net>",
|
||||
|
||||
@@ -26,8 +26,6 @@ on:
|
||||
- 'v2/crates/wifi-densepose-signal/**'
|
||||
- 'v2/crates/wifi-densepose-vitals/**'
|
||||
- 'v2/crates/wifi-densepose-wifiscan/**'
|
||||
- 'v2/crates/wifi-densepose-bfld/**'
|
||||
- 'v2/crates/cog-ha-matter/**'
|
||||
- 'v2/Cargo.toml'
|
||||
- 'v2/Cargo.lock'
|
||||
- 'ui/**'
|
||||
@@ -61,16 +59,11 @@ jobs:
|
||||
- uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Log in to Docker Hub
|
||||
# Bypassing docker/login-action@v3: the action kept emitting
|
||||
# "malformed HTTP Authorization header" against a known-good
|
||||
# dckr_pat_* token (verified by direct curl against the Hub API).
|
||||
# `docker login --password-stdin` is the documented credential
|
||||
# path and avoids whatever encoding step the action injects.
|
||||
env:
|
||||
DH_USER: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
DH_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
run: |
|
||||
printf '%s' "$DH_TOKEN" | docker login docker.io -u "$DH_USER" --password-stdin
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
registry: docker.io
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
|
||||
- name: Log in to ghcr.io
|
||||
uses: docker/login-action@v3
|
||||
|
||||
@@ -63,7 +63,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
### Added
|
||||
- **BFLD — Beamforming Feedback Layer for Detection (ADR-118 umbrella + ADR-119 frame format + ADR-120 privacy class + ADR-121 identity risk scoring + ADR-122 RuView HA/Matter exposure + ADR-123 capture path, [#787](https://github.com/ruvnet/RuView/issues/787)).** New crate `wifi-densepose-bfld` (`v2/crates/wifi-densepose-bfld/`) — the privacy-gated WiFi sensing layer that detects when RF data crosses from "ambient sensing" into "identity record" and **structurally prevents** identity-correlated data from leaving the node. Three invariants enforced by the type system (not policy): **I1** raw BFI never exits the node (`Sink` marker-trait hierarchy + `PrivacyClass::Raw.allows_network() == false`), **I2** identity embedding is in-RAM-only (`IdentityEmbedding` has no `Serialize`/`Clone`/`Copy` + `Drop` zeroizes), **I3** cross-site identity correlation is cryptographically impossible (per-site BLAKE3-keyed `SignatureHasher` with daily epoch rotation; mean cross-site Hamming distance ≥120 bits across 100 trials). Ships the complete operator surface: `BfldPipeline` + `BfldPipelineHandle` (worker-thread variant + `spawn_with_oracle` for Soul Signature deployments), `BfldEvent` with JSON publishing (`"blake3:<hex>"` `rf_signature_hash` format per spec), 4 `privacy_class` levels (Raw/Derived/Anonymous/Restricted) with `PrivacyGate::demote` monotonic transformer + irreversible `apply_privacy_gating`, `CoherenceGate` with ±0.05 hysteresis + 5-second debounce + clock-skew resilience (saturating_sub), `SoulMatchOracle` Recalibrate-exemption trait for enrolled-person deployments. **MQTT/HA surface**: `mqtt_topics::render_events` + `publish_event` (class-gated topic routing — Raw/Derived publish 0 topics, Anonymous publishes 6, Restricted publishes 5 with `identity_risk` stripped), `ha_discovery::render_discovery_payloads` + `publish_discovery` (HA-DISCO config payloads with `availability_topic` integration), `availability` module (`online`/`offline` + LWT-aware `with_lwt` helper for `rumqttc::MqttOptions`), `RumqttPublisher` behind a `mqtt` feature gate with `connect_with_lwt` for broker-side auto-offline. **3 operator HA Blueprints** under `v2/crates/cog-ha-matter/blueprints/bfld/` (presence-driven-lighting, motion-aware-HVAC, identity-risk-anomaly-notification with rolling 7-day z-score). **Two runnable examples** (`bfld_minimal` for in-process consumers, `bfld_handle` for the production worker-thread + bootstrap-then-spawn pattern). **GitHub Actions CI workflow** (`.github/workflows/bfld-mqtt-integration.yml`) spins up `eclipse-mosquitto:2` as a service container so the env-gated `mosquitto_integration` and `rumqttc_lwt` tests run end-to-end in CI. **Performance**: `BfldFrame::to_bytes()` measured at **320,255 frames/sec** debug (6.4× ADR-119 AC7 release target of 50k), header-only at 1,654,517 frames/sec, presence-detection latency p95 = **0.9µs** (~1,000,000× under ADR-119 AC2's 1s target), 9.96 Hz motion-publish rate through `BfldPipelineHandle` (10× ADR-122 AC3 floor). **Coverage**: 327 tests at default features, 101 no_std-compatible, 220+ with `--features mqtt`. CRC-32/ISO-HDLC polynomial pinned against `"123456789" → 0xCBF43926`, public-API surface snapshot pinned across all `pub use` re-exports, `BfldError` Display contract pinned for log-grep monitoring rules, reserved-flag-bits forward-compat round-trip property, `apply_privacy_gating` irreversibility (5-cycle round-trip stress proves stripped fields never resurrect). Companion research dossier in `docs/research/BFLD/` (11 files, 13,544 words). 49-iter implementation chain from scaffold (`feat/adr-118/p1`, `c965e3e6c`) through current head with per-iter progress comments on issue [#787](https://github.com/ruvnet/RuView/issues/787). Try it: `cargo run -p wifi-densepose-bfld --example bfld_handle`.
|
||||
- **SENSE-BRIDGE — rvagent MCP server + ruvector npm + ruflo integration (ADR-124, [#787](https://github.com/ruvnet/RuView/issues/787)).** New npm package `@ruvnet/rvagent` (`tools/ruview-mcp/`) — a dual-transport [Model Context Protocol](https://modelcontextprotocol.io/) server that bridges the RuView WiFi-DensePose sensing stack to AI agents (Claude Code, Cursor, ruflo swarms). **6 of 20 ADR-124 §4.1 tools wired** in this initial release: `ruview.presence.now` (occupancy), `ruview.vitals.get_breathing` / `get_heart_rate` / `get_all` (biometric vitals via `EdgeVitalsMessage` surface, ADR-124 §6 Python ws.py:74-88 parity), `ruview.bfld.last_scan` (latest BFLD event — `identity_risk_score`, `privacy_class`, `n_frames`, `timestamp_ms`), `ruview.bfld.subscribe` (MQTT wildcard subscription with synthetic UUID envelope fallback). **Dual-transport architecture (ADR-124 §3)**: stdio (`npx @ruvnet/rvagent stdio` — recommended for Claude Code / Cursor local flow) + Streamable HTTP (`POST /mcp` bound to `127.0.0.1:3001` by default — for remote ruflo swarms across the Tailscale fleet). **Security model (ADR-124 §6)**: Origin header validation (cross-origin POST → 403), bearer-token auth slot (`RVAGENT_HTTP_TOKEN` → 401), bind default `127.0.0.1` per MCP spec requirement. **Uniform schema validation gate (ADR-124 §3)**: every `CallTool` request runs `zod.safeParse` via `TOOL_INPUT_SCHEMAS` before dispatch; failures throw `McpError(InvalidParams)`. **Full Zod schema barrel (ADR-124 §4.1 + §4.1a)**: `src/schemas/tools.ts` defines all 20 tool input schemas including the 5 RUVIEW-POLICY governance tools (can_access_vitals, can_query_presence, can_subscribe, redact_identity_fields, audit_log). **Python surface parity**: `EdgeVitalsMessage` TypeScript interface mirrors Python ws.py:74-88; ADR-124 §6 parity table drives the field names. **93 tests across 7 suites** (manifest, schemas, validate, tools, http-transport, bfld-tools, vitals-tools) — all green. Try it: `npx @ruvnet/rvagent stdio` (with `RUVIEW_SENSING_SERVER_URL=http://localhost:3000`).
|
||||
- **Home Assistant + Matter integration (ADR-115).** New `--mqtt` and `--matter` flags on `wifi-densepose-sensing-server` expose the full sensing capability set to any Home Assistant install via MQTT auto-discovery (HA-DISCO) and to any Matter controller (Apple Home / Google Home / Alexa / SmartThings) via a built-in Matter Bridge scaffolding (HA-FABRIC, SDK wiring v0.7.1). Includes 21 entity kinds per node — 11 raw signals + 10 inferred semantic primitives (HA-MIND: someone-sleeping, possible-distress, room-active, elderly-inactivity-anomaly, meeting, bathroom, fall-risk, bed-exit, no-movement, multi-room-transition). The semantic primitives run server-side so `--privacy-mode` strips HR/BR/pose values from the wire while still publishing the inferred *states* — the architectural win for healthcare and AAL deployments. Ships **8 starter HA Blueprints** under `examples/ha-blueprints/`, **3 drop-in Lovelace dashboards** under `examples/lovelace/` (including a privacy-mode-compatible healthcare care view), mTLS support, 32 KB payload-size cap, MQTT-wildcard topic-injection rejection, `RUVIEW_MQTT_STRICT_TLS=1` v0.8.0 upgrade path. **420 lib tests** cover the implementation including **~2,560 fuzzed assertions per CI run** (10 proptest cases across wire-boundary security + semantic-bus invariants). Plus mosquitto-backed integration tests in `.github/workflows/mqtt-integration.yml`, criterion benchmarks beating every ADR target by 1.6×–208×, and an ESP32-S3 hardware validation harness (`scripts/validate-esp32-mqtt.sh`) that asserts the full pipeline end-to-end with a witness bundle generator (`scripts/witness-adr-115.sh`) that self-verifies. See [`docs/releases/v0.7.0-mqtt-matter.md`](docs/releases/v0.7.0-mqtt-matter.md), [`docs/integrations/home-assistant.md`](docs/integrations/home-assistant.md), [`docs/integrations/semantic-primitives-metrics.md`](docs/integrations/semantic-primitives-metrics.md), [`docs/integrations/benchmarks.md`](docs/integrations/benchmarks.md), [`docs/adr/ADR-115-home-assistant-integration.md`](docs/adr/ADR-115-home-assistant-integration.md), tracking issue [#776](https://github.com/ruvnet/RuView/issues/776), PR [#778](https://github.com/ruvnet/RuView/pull/778). Matter SDK wiring (P8b) and CSA-certification path (P10) deferred to v0.7.1+ per ADR §9.10. Try it: `cargo run -p wifi-densepose-sensing-server --features mqtt --example mqtt_publisher -- --mqtt --mqtt-host 127.0.0.1`.
|
||||
- **ESP32-C6 firmware target with Wi-Fi 6 / 802.15.4 / TWT / LP-core support ([ADR-110](docs/adr/ADR-110-esp32-c6-firmware-extension.md), #762).** `firmware/esp32-csi-node` now builds for **both** `esp32s3` (existing production node) and `esp32c6` (new research/seed-node target) from the same source tree — pick via `idf.py set-target esp32c6` and ESP-IDF auto-applies the new `sdkconfig.defaults.esp32c6` overlay. Every C6 module is `#ifdef CONFIG_IDF_TARGET_ESP32C6` gated, so the S3 build is byte-identical to today (no regression).
|
||||
- **Wi-Fi 6 HE-LTF subcarrier tagging** — `csi_collector.c` now reads `rx_ctrl.cur_bb_format` and writes the PPDU type (0=HT/legacy, 1=HE-SU, 2=HE-MU, 3=HE-TB) into ADR-018 frame byte 18, plus bandwidth flags (20/40 MHz, STBC, 802.15.4-sync-valid) into byte 19. Bytes 18-19 were previously reserved-zero, so old aggregators read them as before — fully backwards compatible. Magic stays `0xC5110001`. Default on via `CONFIG_CSI_FRAME_HE_TAGGING`. First firmware in the open ESP32 ecosystem to tag CSI frames with 11ax PPDU metadata.
|
||||
|
||||
@@ -595,7 +595,6 @@ Verify the plugin structure: `bash plugins/ruview/scripts/smoke.sh`. Full detail
|
||||
| [Build Guide](docs/build-guide.md) | Building from source (Rust and Python) |
|
||||
| [**Home Assistant + Matter Integration**](docs/integrations/home-assistant.md) | **Works with Home Assistant** via MQTT auto-discovery + **Works with Matter** (Apple Home / Google Home / Alexa / SmartThings) — full entity catalog, 3 starter blueprints, Lovelace dashboards, privacy mode, threshold tuning ([ADR-115](docs/adr/ADR-115-home-assistant-integration.md)). |
|
||||
| [**BFLD — Beamforming Feedback Layer for Detection**](v2/crates/wifi-densepose-bfld/README.md) | New privacy-gated WiFi sensing layer that measures + structurally prevents identity leakage from 802.11ac/ax Beamforming Feedback Information. Three type-enforced invariants (raw BFI never exits node, identity embedding is in-RAM-only, cross-site correlation cryptographically impossible via per-site BLAKE3 keyed hash + daily rotation). Ships full operator surface (`BfldPipeline`, `BfldPipelineHandle`, Soul Signature `SoulMatchOracle` integration), MQTT topic router + HA-DISCO + availability + LWT, 3 operator HA blueprints, two runnable examples, eclipse-mosquitto:2 CI service container. 327+ tests. [ADR-118](docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md) umbrella + sub-ADRs [119](docs/adr/ADR-119-bfld-frame-format-and-wire-protocol.md)/[120](docs/adr/ADR-120-bfld-privacy-class-and-hash-rotation.md)/[121](docs/adr/ADR-121-bfld-identity-risk-scoring.md)/[122](docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md)/[123](docs/adr/ADR-123-bfld-capture-path-nexmon-and-esp32.md). Research dossier: [`docs/research/BFLD/`](docs/research/BFLD/) (11 files, 13,544 words). |
|
||||
| [**SENSE-BRIDGE — rvagent MCP server**](tools/ruview-mcp/README.md) | Dual-transport MCP server (`@ruvnet/rvagent`) bridging the RuView sensing stack to AI agents (Claude Code, Cursor, ruflo swarms). 6 tools wired: `ruview.presence.now`, `ruview.vitals.get_{breathing,heart_rate,all}`, `ruview.bfld.last_scan`, `ruview.bfld.subscribe`. stdio + Streamable HTTP (`POST /mcp`, Origin-validated, bearer-token auth, `127.0.0.1` bind). Full 20-tool Zod schema barrel + 5 RUVIEW-POLICY governance tools. 93 tests. [ADR-124](docs/adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md). Try: `npx @ruvnet/rvagent stdio`. |
|
||||
| [Semantic Primitives — Precision/Recall](docs/integrations/semantic-primitives-metrics.md) | Per-primitive F1 on the held-out paired-capture set: someone-sleeping, possible-distress, room-active, elderly-inactivity-anomaly, meeting, bathroom, fall-risk, bed-exit, no-movement, multi-room. |
|
||||
| [Claude Code / Codex Plugin](plugins/ruview/README.md) | The `ruview` plugin + marketplace — skills, `/ruview-*` commands, agents, and the Codex prompt mirror |
|
||||
| [Architecture Decisions](docs/adr/README.md) | 96 ADRs — why each technical choice was made, organized by domain (hardware, signal processing, ML, platform, infrastructure) |
|
||||
|
||||
+5
-14
@@ -3,7 +3,7 @@
|
||||
# Multi-stage build for minimal final image
|
||||
|
||||
# Stage 1: Build
|
||||
FROM rust:1.89-bookworm AS builder
|
||||
FROM rust:1.85-bookworm AS builder
|
||||
|
||||
WORKDIR /build
|
||||
|
||||
@@ -14,14 +14,9 @@ COPY v2/crates/ ./crates/
|
||||
# Copy vendored RuVector crates
|
||||
COPY vendor/ruvector/ /build/vendor/ruvector/
|
||||
|
||||
# Build release binaries:
|
||||
# - sensing-server with `mqtt` feature so the HA-DISCO MQTT publisher
|
||||
# (ADR-115) is wired in (auto-discovery topics flow to Home Assistant)
|
||||
# - cog-ha-matter, the ADR-116 Cognitum cog that wraps HA-DISCO +
|
||||
# HA-MIND + mDNS + embedded broker for Home Assistant / Matter
|
||||
RUN cargo build --release -p wifi-densepose-sensing-server --features mqtt 2>&1 \
|
||||
&& cargo build --release -p cog-ha-matter 2>&1 \
|
||||
&& strip target/release/sensing-server target/release/cog-ha-matter
|
||||
# Build release binary
|
||||
RUN cargo build --release -p wifi-densepose-sensing-server 2>&1 \
|
||||
&& strip target/release/sensing-server
|
||||
|
||||
# Stage 2: Runtime
|
||||
FROM debian:bookworm-slim
|
||||
@@ -32,9 +27,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Copy binaries
|
||||
# Copy binary
|
||||
COPY --from=builder /build/target/release/sensing-server /app/sensing-server
|
||||
COPY --from=builder /build/target/release/cog-ha-matter /app/cog-ha-matter
|
||||
|
||||
# Copy UI assets
|
||||
COPY ui/ /app/ui/
|
||||
@@ -51,7 +45,6 @@ RUN set -e; \
|
||||
test -d "$d" || { echo "FATAL: missing UI directory $d"; exit 1; }; \
|
||||
done; \
|
||||
test -x /app/sensing-server || { echo "FATAL: /app/sensing-server is not executable"; exit 1; }; \
|
||||
test -x /app/cog-ha-matter || { echo "FATAL: /app/cog-ha-matter is not executable"; exit 1; }; \
|
||||
echo "image assets OK"
|
||||
|
||||
# Optional bearer-token auth on /api/v1/*: leave unset for LAN-mode (default),
|
||||
@@ -65,8 +58,6 @@ EXPOSE 3000
|
||||
EXPOSE 3001
|
||||
# ESP32 UDP
|
||||
EXPOSE 5005/udp
|
||||
# MQTT broker (cog-ha-matter embedded broker — Home Assistant + Matter)
|
||||
EXPOSE 1883
|
||||
|
||||
ENV RUST_LOG=info
|
||||
|
||||
|
||||
@@ -15,21 +15,6 @@
|
||||
# MODELS_DIR — directory to scan for .rvf model files (default: data/models)
|
||||
set -e
|
||||
|
||||
# Route to cog-ha-matter (ADR-116) when invoked as:
|
||||
# docker run <image> cog-ha-matter [--flags]
|
||||
# or via the short alias `ha-matter`. Strips the keyword and execs the
|
||||
# Home Assistant + Matter cog binary, defaulting --sensing-url to the
|
||||
# co-located sensing-server endpoint so docker-compose deployments work
|
||||
# out of the box.
|
||||
case "${1:-}" in
|
||||
cog-ha-matter|ha-matter)
|
||||
shift
|
||||
exec /app/cog-ha-matter \
|
||||
--sensing-url "${SENSING_URL:-http://127.0.0.1:3000}" \
|
||||
"$@"
|
||||
;;
|
||||
esac
|
||||
|
||||
# If the first argument looks like a flag (starts with -), prepend the
|
||||
# server binary so users can just pass flags:
|
||||
# docker run <image> --source esp32 --tick-ms 500
|
||||
|
||||
@@ -1,285 +0,0 @@
|
||||
# ADR-125: RuView ↔ Apple Home native HAP bridge — direct HomeKit accessory advertisement from the Seed
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-25 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **APPLE-FABRIC** — RuView speaks HomeKit directly so Apple HomePod / Apple TV act as the discovery + automation surface with zero Home-Assistant middle layer |
|
||||
| **Relates to** | [ADR-115](ADR-115-home-assistant-integration.md) (HA-DISCO MQTT publisher), [ADR-116](ADR-116-cog-ha-matter-seed.md) (cog-ha-matter §P7 left HAP/Matter as a feature-flag stub), [ADR-118](ADR-118-bfld-beamforming-feedback-layer-for-detection.md) (BFLD presence + identity-risk events), [ADR-122](ADR-122-bfld-ruview-ha-matter-exposure.md) (BFLD HA/Matter exposure) |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
### 1.1 The misunderstanding worth correcting once
|
||||
|
||||
A naive integration tries to **push** data to a HomePod — open a socket, send a JSON-RPC, call an MQTT topic on `homepod.local`. Apple intentionally does not expose that surface. The HomePod is not an endpoint; it is the **Home Hub + Matter Controller + HomeKit Controller + Siri endpoint** for the Apple Home ecosystem on the LAN. It **discovers** accessories that advertise themselves on the local network via Bonjour/mDNS using the HomeKit Accessory Protocol (HAP) or Matter.
|
||||
|
||||
The correct direction of flow is therefore:
|
||||
|
||||
```text
|
||||
RuView / Seed
|
||||
↓ (advertise HAP / Matter accessory on LAN)
|
||||
HomeKit / Matter accessory
|
||||
↓ (mDNS discovery)
|
||||
HomePod
|
||||
↓ (forwards to Apple Home automation graph)
|
||||
Apple Home ecosystem (iPhone, Watch, Mac, Siri, automations)
|
||||
```
|
||||
|
||||
### 1.2 What we ship today and where it stops
|
||||
|
||||
ADR-115 ships an **MQTT auto-discovery publisher** that talks to Home Assistant. ADR-116's `cog-ha-matter` Cognitum cog wraps that publisher into a Seed-installable artifact with mDNS, an embedded rumqttd broker, RuVector-backed thresholds, and an Ed25519 witness chain. ADR-122 explicitly extends the same publisher with the BFLD presence / identity-risk / Soul-Match topics so a Home Assistant install sees them as auto-discovered entities. The current path to HomePod therefore runs:
|
||||
|
||||
```text
|
||||
RuView sensing-server ──► cog-ha-matter (MQTT HA-DISCO + HA-MIND)
|
||||
↓
|
||||
Home Assistant broker
|
||||
↓
|
||||
Home Assistant HomeKit Bridge add-on
|
||||
↓
|
||||
HomePod
|
||||
```
|
||||
|
||||
This works and the auto-discovery is real, but it introduces a hard dependency: an operator must run Home Assistant, install its HomeKit Bridge integration, and pair the bridge in the Apple Home app. The Seed alone does not appear in Apple Home.
|
||||
|
||||
ADR-116 §P7 anticipated this — the `cog-ha-matter` `Cargo.toml` already carries a `matter = []` feature stub with the comment "matter-rs is added in P7; intentionally absent in P1 to keep the dep surface small until the SDK choice is validated." This ADR closes that box.
|
||||
|
||||
### 1.3 Why now
|
||||
|
||||
Three forces line up in 2026-05:
|
||||
|
||||
1. **The BFLD privacy gate (ADR-118 / 120 / 121) is shipped.** Class-2 and class-3 frames are the only ones eligible to cross the Matter boundary (ADR-122 §2.4). Without that gate we could not safely expose RuView signals to a consumer ecosystem. With it, every Anonymous / Restricted event is safe to advertise as a HomeKit sensor.
|
||||
2. **`@ruvnet/rvagent` (ADR-124) is on npm.** The MCP surface that lets agents query RuView is live. A first-class Apple-Home presence widens RuView's reach from "agents that speak MCP" to "anyone with an iPhone and a HomePod" — the consumer wedge.
|
||||
3. **The Cognitum Seed Docker image now bundles `cog-ha-matter`** (this branch's `Dockerfile.rust` change, see #794) — the runtime where a HAP advertiser would live is finally a single-image deployment.
|
||||
|
||||
### 1.4 Strategic framing
|
||||
|
||||
The combination is asymmetric:
|
||||
|
||||
| Layer | RuView contributes | Apple Home contributes |
|
||||
|-------|---------------------|------------------------|
|
||||
| Sensing | Passive RF presence, breathing, heart rate, fall risk, BFLD identity-risk, through-wall occupancy, longitudinal wellness | (none — Apple has no native RF sensing surface) |
|
||||
| Adoption | (limited — researcher-grade hardware today) | iPhone, Watch, Mac, HomePod, Apple TV installed base; consumer trust; voice; on-device intelligence |
|
||||
| UX | (utility CLI + a Web UI) | Home app, Siri, automation engine, notifications, accessibility |
|
||||
| Trust | Ed25519 witness chain, privacy class gate, local-first | Apple HomeKit local pairing, end-to-end encrypted, no cloud requirement |
|
||||
|
||||
RuView supplies the **invisible cognition layer** Apple cannot provide on its own; Apple supplies the **distribution and UX** that an open sensing stack cannot bootstrap. Direct HAP integration removes the only structural barrier between those two layers — Home Assistant as a mandatory intermediary.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Ship a **native HomeKit / Matter accessory** in the Seed runtime so a freshly-imaged Cognitum Seed appears in the Apple Home app under `Add Accessory → More Options` with **zero Home-Assistant dependency**.
|
||||
|
||||
Concretely:
|
||||
|
||||
1. Add a `hap-accessory` workspace component that advertises a set of HomeKit characteristics over mDNS using HAP-1.1 (HomeKit Accessory Protocol).
|
||||
2. The component subscribes to `wifi-densepose-sensing-server`'s WebSocket / BFLD `MqttEvent` stream and maps each privacy-class-2/3 event onto a HomeKit characteristic update.
|
||||
3. The same Docker image that ships `sensing-server` and `cog-ha-matter` ships the new advertiser as a third entrypoint:
|
||||
|
||||
```bash
|
||||
docker run --network host ruvnet/wifi-densepose:latest hap-accessory --privacy-mode
|
||||
```
|
||||
|
||||
`--network host` (or a macvlan bridge) is required because HAP pairing depends on the accessory and the controller seeing each other's mDNS broadcasts on the same L2 segment — same constraint Home Assistant's HomeKit Bridge has.
|
||||
|
||||
### 2.1 Two implementation tracks (decided here together; ship 2.1.a first)
|
||||
|
||||
#### 2.1.a — **HAP-python sidecar** (fastest to ship, lands first)
|
||||
|
||||
Add a tiny Python entrypoint `bridges/hap-python/ruview_hap.py` using the well-maintained [`HAP-python`](https://github.com/ikalchev/HAP-python) library. The Dockerfile gets a thin Python runtime stage; the entrypoint script polls `sensing-server` over HTTP and pushes characteristic updates into the HAP loop.
|
||||
|
||||
```python
|
||||
# bridges/hap-python/ruview_hap.py (≈80 LOC)
|
||||
from pyhap.accessory import Accessory
|
||||
from pyhap.accessory_driver import AccessoryDriver
|
||||
from pyhap.const import CATEGORY_SENSOR
|
||||
import urllib.request, json, threading, time
|
||||
|
||||
SENSING_URL = "http://127.0.0.1:3000/api/v1"
|
||||
|
||||
class RuViewSensor(Accessory):
|
||||
category = CATEGORY_SENSOR
|
||||
|
||||
def __init__(self, *args, **kwargs):
|
||||
super().__init__(*args, **kwargs)
|
||||
s_motion = self.add_preload_service('MotionSensor')
|
||||
self.c_motion = s_motion.configure_char('MotionDetected')
|
||||
s_occ = self.add_preload_service('OccupancySensor')
|
||||
self.c_occ = s_occ.configure_char('OccupancyDetected')
|
||||
s_temp = self.add_preload_service('TemperatureSensor')
|
||||
self.c_temp = s_temp.configure_char('CurrentTemperature')
|
||||
threading.Thread(target=self._poll, daemon=True).start()
|
||||
|
||||
def _poll(self):
|
||||
while True:
|
||||
try:
|
||||
v = json.loads(urllib.request.urlopen(f"{SENSING_URL}/vitals").read())
|
||||
self.c_motion.set_value(bool(v.get("motion_present")))
|
||||
self.c_occ.set_value(int(bool(v.get("occupancy"))))
|
||||
if "ambient_temp_c" in v:
|
||||
self.c_temp.set_value(v["ambient_temp_c"])
|
||||
except Exception:
|
||||
pass
|
||||
time.sleep(1.0)
|
||||
|
||||
driver = AccessoryDriver(port=51826)
|
||||
driver.add_accessory(accessory=RuViewSensor(driver, 'RuView Sense'))
|
||||
driver.start()
|
||||
```
|
||||
|
||||
Pairing flow on the operator's iPhone:
|
||||
|
||||
1. Open Apple Home → `Add Accessory` → `More Options`
|
||||
2. Tap `RuView Sense` (appears via mDNS automatically)
|
||||
3. Enter the setup code shown in `docker logs` (or pinned in env)
|
||||
4. Done — Siri can say "Hey Siri, is anyone in the living room?"
|
||||
|
||||
Replace the `motion_present` / `occupancy` mappings progressively as RuView capabilities mature: BFLD class-2 `presence` event → `OccupancyDetected`; BFLD class-3 `identity_risk_score > threshold` → `SecuritySystemCurrentState`; `breathing_present` → `OccupancyDetected` (sleep room); `fall_risk` → a programmable switch that fires an Apple Home automation.
|
||||
|
||||
Acceptance criteria for 2.1.a:
|
||||
|
||||
- A1: `docker run ... hap-accessory --privacy-mode` advertises an `_hap._tcp` service that the HomePod sees within 30s (`dns-sd -B _hap._tcp local.` on a peer Mac shows `RuView Sense`).
|
||||
- A2: Pairing from Apple Home succeeds and the entity appears in the Home app under the configured room.
|
||||
- A3: `MotionDetected` flips within 2 s of an actual RF presence detection from a calibrated ESP32 source (`CSI_SOURCE=esp32`).
|
||||
- A4: Restarting the container preserves the pairing (HAP state persisted under `/var/lib/ruview-hap/`).
|
||||
- A5: Privacy: the entrypoint refuses to launch without `--privacy-mode` when `RUVIEW_BFLD_PRIVACY_CLASS` is unset, matching the structural invariant I1 (Raw BFI never exits the node — ADR-118 §2.2).
|
||||
|
||||
#### 2.1.b — **Rust-native HAP** (single binary, closes ADR-116 P7)
|
||||
|
||||
Wire one of the maintained Rust HAP crates into `cog-ha-matter` so the Python sidecar can be removed. Candidate crates:
|
||||
|
||||
- [`hap`](https://crates.io/crates/hap) (Sebastian Schmidt) — last published 0.1.0-pre.16, MIT, active in 2024, supports HAP-1.1, has examples for `MotionSensor`, `LightBulb`, `OccupancySensor`. **First choice.**
|
||||
- [`accessory-server`](https://crates.io/crates/accessory-server) — narrower scope, fewer services
|
||||
- A future `matter-rs` crate from project-chip — once stable (CHIP SDK Rust bindings are still emerging in 2026-05)
|
||||
|
||||
The `matter = []` feature stub in `cog-ha-matter/Cargo.toml` (added in ADR-116 P1) becomes:
|
||||
|
||||
```toml
|
||||
[features]
|
||||
default = []
|
||||
mqtt = ["dep:rumqttc"]
|
||||
matter = ["dep:hap"] # ADR-125 §2.1.b
|
||||
```
|
||||
|
||||
with a runtime subcommand `cog-ha-matter --mode hap` that mirrors the Python advertiser's accessory set. Single binary, no Python interpreter in the image, matches the all-Rust ethos of the Cognitum Seed (ADR-116 §1.4).
|
||||
|
||||
### 2.1.c — **Topology: one HAP bridge, N child accessories** (decided)
|
||||
|
||||
The advertiser publishes a **single HAP bridge** (`RuView Sense`) that owns N child accessories — one per logical sensor surface (presence-bedroom, presence-office, vitals-bedroom, semantic-events, …). Operators pair the bridge once; child accessories appear automatically and can be re-assigned to rooms in the Apple Home app.
|
||||
|
||||
The alternative — N independent accessories each advertised separately — was rejected. It forces operators to pair RuView once per room (`RuView Bedroom`, `RuView Office`, `RuView Wellness`, `RuView Presence`, …), which becomes messy after the second or third room, and diverges from how every reference HomeKit accessory in the Home app behaves (a Hue bridge with bulbs, an Eve Energy bridge, etc.). Single pairing also makes container restart / re-image trivial — one persisted pairing key, not N.
|
||||
|
||||
### 2.1.d — **Identity-risk mapping: semantic events, not probabilistic surveillance** (decided)
|
||||
|
||||
`identity_risk_score` is a continuous 0..1 confidence from the BFLD identity-features pipeline (ADR-121 §2.6). It must NOT cross the HomeKit boundary as a raw value, and must NOT be wired to `SecuritySystemCurrentState`. Apple-Home users read security-system state as **"intruder detected"** — exposing a probability there turns RuView into surveillance UX with all the false-positive blame that entails.
|
||||
|
||||
Instead, the bridge exposes **thresholded semantic events** that read like ambient awareness, not threat detection:
|
||||
|
||||
| Semantic event | HomeKit primitive | Trigger (illustrative) |
|
||||
|----------------|--------------------|-------------------------|
|
||||
| `Unknown Presence` | `MotionSensor` (programmable; stateful) | BFLD class-2 presence + no matching SoulMatch oracle hit (ADR-121 §2.6) for > 30 s |
|
||||
| `Unexpected Occupancy` | `OccupancySensor` (programmable) | Occupancy in a room outside its operator-defined "expected schedule" window |
|
||||
| `Unrecognized Activity Pattern` | Programmable `Switch` (stateful, momentary) | BFLD longitudinal drift gate (ADR-118 §2.3 / ADR-122 §2.7) fires Reject or Recalibrate |
|
||||
|
||||
What stays internal:
|
||||
|
||||
- Raw `identity_risk_score` (numeric 0..1) — never published
|
||||
- Soul-Signature match probability — never published
|
||||
- `rf_signature_hash` — never published (already enforced by ADR-118 §2.5 / ADR-122 §2.4 — this is the structural invariant restated at the HAP boundary)
|
||||
|
||||
The naming is the contract. "Unknown Presence" is *who's-here-and-it's-fine-but-worth-noting*; an end user will write an automation ("turn on the porch light when Unknown Presence is detected after 9pm") without ever thinking it accuses anyone of being an intruder. That semantic framing is the difference between RuView becoming the calm-tech ambient substrate Apple Home needs vs. another paranoid surveillance widget.
|
||||
|
||||
This is the part of the ADR that determines whether RuView's HomeKit story ages well or generates the wrong kind of headlines.
|
||||
|
||||
### 2.2 What we DO NOT do in 2.1.a or 2.1.b
|
||||
|
||||
- **No Matter (CHIP) controller code.** Matter is the long-term play but its SDK in Rust is not yet stable and the certificate provisioning is heavy. HAP-1.1 over Bonjour gives 95% of the UX for 10% of the complexity, today.
|
||||
- **No direct connection to the HomePod.** As the framing in §1.1 makes explicit, RuView never opens a socket to the HomePod. It advertises; the HomePod discovers.
|
||||
- **No iCloud account binding.** HAP pairing is local-network-only by design — RuView gets adoption without ever touching Apple ID, which is a privacy story we keep cleanly.
|
||||
- **No Class-0 (`Raw`) BFI exposure.** Structural invariant I1 (ADR-118 §2.2) holds. Only privacy-class-2 (Anonymous) and class-3 (Restricted) frames may be mapped onto HomeKit characteristics. The advertiser refuses to start in any other mode.
|
||||
|
||||
### 2.3 Sequencing
|
||||
|
||||
1. **P1** (this ADR-125 + 1 PR) — HAP-python sidecar (§2.1.a) lands as a separate entrypoint in the same Docker image. AC A1–A5 are gates.
|
||||
2. **P2** (follow-up PR after operator feedback from 5+ Apple Home pairings) — Rust-native HAP (§2.1.b). Replaces P1; P1's `bridges/hap-python/` becomes an archived reference implementation.
|
||||
3. **P3** (when matter-rs stabilizes) — Matter Controller path (still RuView-as-accessory, but using the Matter clusters rather than HAP-1.1 services). The Cognitum Cog gains a Matter QR code; pairing flow widens to "any Matter-capable controller, not just Apple."
|
||||
|
||||
---
|
||||
|
||||
## 3. Consequences
|
||||
|
||||
### 3.1 Wins
|
||||
|
||||
- **Direct discoverability on Apple Home.** A Seed in the kitchen appears as `RuView Sense` in the Home app within seconds of `docker run`. No HA, no MQTT broker, no Home-Assistant HomeKit Bridge add-on.
|
||||
- **Siri natively answers RuView questions.** "Hey Siri, is anyone in the kitchen?" — the question reaches the HomeKit characteristic without any custom skill or HA template sensor.
|
||||
- **Apple-Home automations gain ambient triggers** RuView already produces (presence, breathing, fall, identity-risk) for free — they become first-class automation triggers in the Home app's UI.
|
||||
- **Strategically corrects RuView's distribution problem.** The Apple Home installed base is the largest consumer surface for HomeKit-grade accessories. RuView's sensing IP becomes addressable to that base without an SDK port.
|
||||
- **Closes ADR-116 §P7** — the long-flagged matter / HAP gap is now scheduled, not deferred indefinitely.
|
||||
|
||||
### 3.2 Costs
|
||||
|
||||
- **Python runtime in the Docker image (only for 2.1.a, until 2.1.b lands).** Adds ~30 MB to the runtime layer. Mitigation: P2 removes it; P1 isolates the Python dep in a side-stage so the sensing-server / cog-ha-matter layers stay clean.
|
||||
- **Network-mode constraint.** HAP pairing needs the controller and accessory on the same L2 segment (mDNS broadcasts). Operators who run RuView in a container behind a NAT/bridge need `--network host` or a macvlan — same constraint HA's HomeKit Bridge has, but worth documenting.
|
||||
- **Pairing state persistence.** HAP-python stores pairing data in a local file; that state must survive container restarts. Volume-mount `/var/lib/ruview-hap/` to a persistent location.
|
||||
|
||||
### 3.3 Risks
|
||||
|
||||
- **HAP-python maintenance.** The library is community-maintained; if it goes stale, P2 (Rust-native) absorbs the risk. 2.1.a is explicitly a stepping stone, not a long-term commitment.
|
||||
- **Apple's evolving requirements.** HomeKit Accessory Certification is required to put a HAP logo on hardware, not to ship a software accessory that pairs locally. RuView's container deployment is squarely in the "uncertified developer accessory" lane, which Apple explicitly permits for local pairing. Worth restating in the operator README.
|
||||
- **Privacy-class enforcement at the bridge boundary.** A bug that lets a class-0 BFI frame's data influence a HAP characteristic update would violate I1. Mitigation: the bridge consumes only the BFLD `MqttEvent` stream (which is already gated by `PrivacyGate` per ADR-120), never raw BFI; tests assert this in the same style as ADR-122 §4.3.
|
||||
|
||||
### 3.4 Reversibility
|
||||
|
||||
The advertiser is a separate entrypoint — pulling it out is `docker run` without the `hap-accessory` first-arg, identical to today's behavior. Zero impact on `sensing-server` and `cog-ha-matter` operations.
|
||||
|
||||
---
|
||||
|
||||
## 4. Acceptance test (P1 / §2.1.a)
|
||||
|
||||
```bash
|
||||
# 1. Start a sensing server (simulated source so the test runs anywhere)
|
||||
docker run -d --name rs -p 3000:3000 -e CSI_SOURCE=simulated \
|
||||
ruvnet/wifi-densepose:latest
|
||||
|
||||
# 2. Launch the HAP advertiser sidecar in privacy mode
|
||||
docker run -d --name hap --network host \
|
||||
-v /var/lib/ruview-hap:/var/lib/ruview-hap \
|
||||
-e RUVIEW_BFLD_PRIVACY_CLASS=2 \
|
||||
ruvnet/wifi-densepose:latest hap-accessory --privacy-mode
|
||||
|
||||
# 3. From a Mac on the same LAN: should see RuView Sense as HAP
|
||||
dns-sd -B _hap._tcp local. # expect: "RuView Sense" within 30 s
|
||||
|
||||
# 4. From iPhone Home app: Add Accessory → More Options → RuView Sense
|
||||
# Enter setup code from `docker logs hap`
|
||||
# Expect: pairing completes, entity appears in selected Room
|
||||
|
||||
# 5. Cycle the container; re-open Home app: entity is still paired
|
||||
docker restart hap
|
||||
# Expect: no re-pairing prompt; characteristic updates resume
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Open questions
|
||||
|
||||
Two questions from the original draft were resolved during review (§2.1.c and §2.1.d). Genuinely-open questions that follow-up PRs will close:
|
||||
|
||||
- **Setup-code derivation.** Derived deterministically from the Seed's Ed25519 witness key (so reinstalls re-use the same code, operator never re-enters), or random per launch (slightly better security, worse UX on container restarts)? Leaning deterministic + witness-key-derived; verify against Apple's HomeKit Accessory Protocol §5.6.5 (setup-code uniqueness) before committing.
|
||||
- **ESP32 / Cognitum-Seed-class hardware as a direct HAP advertiser** (not via the host appliance). The current decision parks the bridge on the host runtime; a future ADR can evaluate whether an ESP32-S3 with 8MB flash has enough headroom to run HAP-1.1 directly, which would remove the host appliance from the path entirely for single-room deployments.
|
||||
|
||||
---
|
||||
|
||||
## 6. References
|
||||
|
||||
- ADR-115 — Home-Assistant integration (HA-DISCO MQTT publisher)
|
||||
- ADR-116 — `cog-ha-matter` Seed cog (this is where the `matter` feature stub lives)
|
||||
- ADR-118 — BFLD beamforming-feedback layer (privacy gate + class invariants)
|
||||
- ADR-122 — BFLD RuView HA/Matter exposure (current MQTT-based bridge that this ADR's HAP-native path complements)
|
||||
- HomeKit Accessory Protocol Specification (Non-Commercial Version), Apple — https://developer.apple.com/apple-home/
|
||||
- HAP-python — https://github.com/ikalchev/HAP-python
|
||||
- `hap` (Rust) — https://crates.io/crates/hap
|
||||
@@ -845,39 +845,6 @@ The `rumqttc 0.24` (`use-rustls`) backend ships behind the `mqtt` feature; `Rumq
|
||||
|
||||
Detailed surface: [`v2/crates/wifi-densepose-bfld/README.md`](../v2/crates/wifi-densepose-bfld/README.md), [`docs/research/BFLD/`](research/BFLD/) (11 files, 13,544 words), [ADR-118 through ADR-123](adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md).
|
||||
|
||||
### SENSE-BRIDGE — rvagent MCP server for AI agents (ADR-124)
|
||||
|
||||
`@ruvnet/rvagent` is a dual-transport MCP server that makes RuView sensing primitives callable by Claude Code, Cursor, and ruflo swarms without bespoke HTTP client code.
|
||||
|
||||
**Install (Claude Code)**:
|
||||
|
||||
```bash
|
||||
claude mcp add rvagent -- npx @ruvnet/rvagent stdio
|
||||
# With a remote sensing-server:
|
||||
RUVIEW_SENSING_SERVER_URL=http://cognitum-v0:3000 claude mcp add rvagent -- npx @ruvnet/rvagent stdio
|
||||
```
|
||||
|
||||
**Available tools (6 of 20 in v0.1.0)**:
|
||||
|
||||
| Tool | Returns |
|
||||
|------|---------|
|
||||
| `ruview.presence.now` | `present`, `n_persons`, `confidence`, `timestamp_ms` |
|
||||
| `ruview.vitals.get_breathing` | `breathing_rate_bpm` (null if unavailable), `confidence` |
|
||||
| `ruview.vitals.get_heart_rate` | `heartrate_bpm` (null if unavailable), `confidence` |
|
||||
| `ruview.vitals.get_all` | Full `EdgeVitalsMessage` (all vitals in one call) |
|
||||
| `ruview.bfld.last_scan` | `identity_risk_score`, `privacy_class`, `n_frames`, `timestamp_ms` |
|
||||
| `ruview.bfld.subscribe` | `subscription_id`, `expires_at`, `topic` (MQTT wildcard) |
|
||||
|
||||
**Streamable HTTP** (for remote ruflo swarms):
|
||||
|
||||
```bash
|
||||
RVAGENT_HTTP_TOKEN=secret npx @ruvnet/rvagent http --port 3001
|
||||
# POST JSON-RPC to http://127.0.0.1:3001/mcp
|
||||
# Cross-origin requests are rejected with 403; missing/wrong token → 401.
|
||||
```
|
||||
|
||||
Source: [`tools/ruview-mcp/`](../tools/ruview-mcp/README.md). Tracking issue: [#787](https://github.com/ruvnet/RuView/issues/787). Full ADR: [ADR-124](adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md).
|
||||
|
||||
---
|
||||
|
||||
## Web UI
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "ruview",
|
||||
"description": "End-to-end RuView (WiFi-DensePose) toolkit for Claude Code: onboarding, ESP32 hardware setup, configuration, sensing applications, model training, advanced multistatic sensing, witness verification, BFLD privacy layer, and rvAgent + RVF agentic flows — from practical to advanced.",
|
||||
"version": "0.3.0",
|
||||
"version": "0.2.0",
|
||||
"author": {
|
||||
"name": "ruvnet",
|
||||
"url": "https://github.com/ruvnet/RuView"
|
||||
@@ -19,14 +19,5 @@
|
||||
"edge-ai",
|
||||
"model-training",
|
||||
"onboarding"
|
||||
],
|
||||
"mcpServers": {
|
||||
"rvagent": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@ruvnet/rvagent"],
|
||||
"env": {
|
||||
"RVAGENT_SENSING_URL": "http://localhost:3000"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -2,24 +2,6 @@
|
||||
|
||||
You are helping the operator explore or prototype the integration of `vendor/ruvector/crates/rvAgent/` (a production Rust AI-agent framework) with RuView's existing sensing pipeline (`v2/crates/wifi-densepose-*`) and the RVF cognitive container format (`v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs`).
|
||||
|
||||
## Live MCP server: `@ruvnet/rvagent` v0.1.0
|
||||
|
||||
The TypeScript MCP server (`tools/ruview-mcp/`, published as `@ruvnet/rvagent`) is live on npm and exposes `bfld_last_scan`, `bfld_subscribe`, `presence_now`, `vitals_get_breathing`, `vitals_get_heart_rate`, `vitals_get_all`, `vitals_fetch`. Add to a Codex MCP config:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"rvagent": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@ruvnet/rvagent"],
|
||||
"env": { "RVAGENT_SENSING_URL": "http://localhost:3000" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This is the operator-facing tool surface; the Rust crate below remains the substrate for deeper RVF-aware agentic flows.
|
||||
|
||||
## Trigger phrasing
|
||||
|
||||
- "wire rvAgent into RuView"
|
||||
|
||||
@@ -7,24 +7,6 @@ description: Explore and prototype rvAgent + RVF integration for RuView agentic
|
||||
|
||||
Surface area for wiring `vendor/ruvector/crates/rvAgent/` into RuView so the existing sensing pipeline becomes the substrate an agentic flow can read, reason about, and respond to.
|
||||
|
||||
## Quickstart — published MCP server (`@ruvnet/rvagent` v0.1.0)
|
||||
|
||||
Installing this plugin registers `@ruvnet/rvagent` as an MCP server. On activation, Claude Code spawns `npx -y @ruvnet/rvagent` and exposes its tools directly:
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `bfld_last_scan` | Most recent BFLD event from the sensing server |
|
||||
| `bfld_subscribe` | Stream BFLD events for a window |
|
||||
| `presence_now` | Current room-level presence state |
|
||||
| `vitals_get_breathing` | Latest breathing-rate sample |
|
||||
| `vitals_get_heart_rate` | Latest heart-rate sample |
|
||||
| `vitals_get_all` | Composite vitals snapshot |
|
||||
| `vitals_fetch` | Historical vitals window |
|
||||
|
||||
Override the sensing-server URL via the `RVAGENT_SENSING_URL` env var (default `http://localhost:3000`). Source lives at `tools/ruview-mcp/`; ADR-124 captures the design.
|
||||
|
||||
Smoke-check the wiring: `npm view @ruvnet/rvagent version` should return `0.1.0` (or newer).
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- "I want an agent that reacts to BFLD presence in the kitchen and pages the carer."
|
||||
|
||||
@@ -128,39 +128,6 @@ for crate_dir in "$REPO_ROOT/v2/crates/"*/; do
|
||||
done
|
||||
cat "$BUNDLE_DIR/crate-manifest/versions.txt"
|
||||
|
||||
# ---------------------------------------------------------------
|
||||
# 6b. npm manifest — @ruvnet/rvagent tarball sha256 (ADR-124)
|
||||
# ---------------------------------------------------------------
|
||||
echo "[6b] Building @ruvnet/rvagent npm tarball and hashing..."
|
||||
mkdir -p "$BUNDLE_DIR/npm-manifest"
|
||||
NPM_PKG_DIR="$REPO_ROOT/tools/ruview-mcp"
|
||||
if [ -d "$NPM_PKG_DIR" ]; then
|
||||
(
|
||||
cd "$NPM_PKG_DIR"
|
||||
# Ensure latest build before packing
|
||||
npm run build --silent 2>/dev/null || true
|
||||
npm pack --quiet 2>/dev/null || true
|
||||
TARBALL=$(ls ruvnet-rvagent-*.tgz 2>/dev/null | head -1)
|
||||
if [ -n "$TARBALL" ]; then
|
||||
SHA=$(sha256sum "$TARBALL" 2>/dev/null | cut -d' ' -f1 \
|
||||
|| powershell -Command "(Get-FileHash '$TARBALL' -Algorithm SHA256).Hash.ToLower()" 2>/dev/null \
|
||||
|| echo "sha256-unavailable")
|
||||
echo "${SHA} ${TARBALL}" > "$BUNDLE_DIR/npm-manifest/${TARBALL}.sha256"
|
||||
# Keep the version string for VERIFY.sh
|
||||
echo "$TARBALL" > "$BUNDLE_DIR/npm-manifest/tarball-name.txt"
|
||||
echo "$SHA" > "$BUNDLE_DIR/npm-manifest/tarball-sha256.txt"
|
||||
# Remove local tarball — it's recorded in the bundle, not shipped in it
|
||||
rm -f "$TARBALL"
|
||||
echo " @ruvnet/rvagent tarball sha256: ${SHA}"
|
||||
else
|
||||
echo " WARNING: npm pack produced no tarball — skipping npm manifest"
|
||||
echo "npm-pack-failed" > "$BUNDLE_DIR/npm-manifest/tarball-name.txt"
|
||||
fi
|
||||
)
|
||||
else
|
||||
echo " WARNING: tools/ruview-mcp not found — skipping npm manifest"
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------
|
||||
# 7. Generate VERIFY.sh for recipients
|
||||
# ---------------------------------------------------------------
|
||||
@@ -229,21 +196,7 @@ else
|
||||
check "Crate manifest present" "FAIL"
|
||||
fi
|
||||
|
||||
# Check 6: npm tarball sha256 (ADR-124 SENSE-BRIDGE)
|
||||
if [ -f "npm-manifest/tarball-sha256.txt" ] && [ -f "npm-manifest/tarball-name.txt" ]; then
|
||||
EXPECTED_SHA=$(cat npm-manifest/tarball-sha256.txt)
|
||||
TARBALL_NAME=$(cat npm-manifest/tarball-name.txt)
|
||||
if [ "$EXPECTED_SHA" = "npm-pack-failed" ] || [ "$TARBALL_NAME" = "npm-pack-failed" ]; then
|
||||
check "npm tarball sha256 (@ruvnet/rvagent)" "FAIL"
|
||||
else
|
||||
check "npm manifest present (@ruvnet/rvagent ${TARBALL_NAME})" "PASS"
|
||||
echo " Recorded sha256: ${EXPECTED_SHA}"
|
||||
fi
|
||||
else
|
||||
check "npm manifest present (@ruvnet/rvagent)" "FAIL"
|
||||
fi
|
||||
|
||||
# Check 8: Proof verification log
|
||||
# Check 6: Proof verification log
|
||||
if [ -f "proof/verification-output.log" ]; then
|
||||
if grep -q "VERDICT: PASS" proof/verification-output.log; then
|
||||
check "Python proof verification PASS" "PASS"
|
||||
|
||||
@@ -1,75 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# rotate-npm-token.sh — push NPM_TOKEN from .env into GCP Secret Manager
|
||||
# and (optionally) publish @ruvnet/rvagent.
|
||||
#
|
||||
# Usage:
|
||||
# bash scripts/rotate-npm-token.sh # rotate only
|
||||
# bash scripts/rotate-npm-token.sh --publish # rotate + npm publish
|
||||
#
|
||||
# Env overrides:
|
||||
# GCP_PROJECT (default: cognitum-20260110)
|
||||
# NPM_TOKEN_SECRET (default: NPM_TOKEN)
|
||||
# ENV_FILE (default: <repo-root>/.env)
|
||||
# PUBLISH_PACKAGE_DIR (default: <repo-root>/tools/ruview-mcp)
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
ENV_FILE="${ENV_FILE:-$REPO_ROOT/.env}"
|
||||
PROJECT="${GCP_PROJECT:-cognitum-20260110}"
|
||||
SECRET="${NPM_TOKEN_SECRET:-NPM_TOKEN}"
|
||||
PKG_DIR="${PUBLISH_PACKAGE_DIR:-$REPO_ROOT/tools/ruview-mcp}"
|
||||
|
||||
[ -f "$ENV_FILE" ] || { echo "ERROR: .env not found at $ENV_FILE" >&2; exit 1; }
|
||||
|
||||
TOKEN="$(awk -F= '
|
||||
/^[[:space:]]*NPM_TOKEN[[:space:]]*=/ {
|
||||
sub(/^[^=]*=[[:space:]]*/, "", $0)
|
||||
sub(/^["'\'']/, "", $0)
|
||||
sub(/["'\''][[:space:]]*$/, "", $0)
|
||||
sub(/[[:space:]]+$/, "", $0)
|
||||
print
|
||||
exit
|
||||
}
|
||||
' "$ENV_FILE")"
|
||||
|
||||
if [ -z "${TOKEN:-}" ]; then
|
||||
echo "ERROR: NPM_TOKEN not found in $ENV_FILE" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
LEN=${#TOKEN}
|
||||
echo "Found NPM_TOKEN in .env (length=$LEN)"
|
||||
|
||||
echo "Pushing new version to gcloud secret '$SECRET' in project '$PROJECT'..."
|
||||
if ! gcloud secrets describe "$SECRET" --project="$PROJECT" >/dev/null 2>&1; then
|
||||
echo "Secret '$SECRET' not found; creating..."
|
||||
printf '%s' "$TOKEN" | gcloud secrets create "$SECRET" \
|
||||
--project="$PROJECT" --replication-policy=automatic --data-file=-
|
||||
else
|
||||
printf '%s' "$TOKEN" | gcloud secrets versions add "$SECRET" \
|
||||
--project="$PROJECT" --data-file=-
|
||||
fi
|
||||
|
||||
echo "Verifying secret round-trips..."
|
||||
RETRIEVED="$(gcloud secrets versions access latest --secret="$SECRET" --project="$PROJECT")"
|
||||
if [ "$RETRIEVED" != "$TOKEN" ]; then
|
||||
echo "ERROR: retrieved token does not match the value written to .env" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "OK — secret '$SECRET' updated and verified (length=${#RETRIEVED})."
|
||||
|
||||
if [ "${1:-}" = "--publish" ]; then
|
||||
[ -d "$PKG_DIR" ] || { echo "ERROR: package dir not found at $PKG_DIR" >&2; exit 1; }
|
||||
echo "Publishing @ruvnet/rvagent from $PKG_DIR..."
|
||||
(
|
||||
cd "$PKG_DIR"
|
||||
if [ -f package.json ] && grep -q '"build"' package.json; then
|
||||
npm run build
|
||||
fi
|
||||
NODE_AUTH_TOKEN="$RETRIEVED" npm publish --access public
|
||||
)
|
||||
fi
|
||||
|
||||
echo "Done."
|
||||
@@ -1,65 +0,0 @@
|
||||
# @ruvnet/rvagent — SENSE-BRIDGE MCP Server
|
||||
|
||||
**SENSE-BRIDGE** is a dual-transport [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that bridges the RuView WiFi-DensePose sensing stack to AI agents (Claude Code, Cursor, ruflo swarms, and any MCP-compatible client).
|
||||
|
||||
Install once; AI agents can then call `ruview.presence.now`, `ruview.vitals.get_heart_rate`, `ruview.bfld.last_scan`, and more — without writing HTTP or WebSocket client code.
|
||||
|
||||
## Quickstart
|
||||
|
||||
```bash
|
||||
# 1. Add to Claude Code
|
||||
claude mcp add rvagent -- npx @ruvnet/rvagent stdio
|
||||
|
||||
# 2. Or run directly
|
||||
RUVIEW_SENSING_SERVER_URL=http://cognitum-v0:3000 npx @ruvnet/rvagent stdio
|
||||
|
||||
# 3. Streamable HTTP (remote agents, ruflo swarms)
|
||||
RUVIEW_SENSING_SERVER_URL=http://cognitum-v0:3000 \
|
||||
RVAGENT_HTTP_TOKEN=your-secret \
|
||||
npx @ruvnet/rvagent http --port 3001
|
||||
# POST JSON-RPC to http://127.0.0.1:3001/mcp
|
||||
```
|
||||
|
||||
Requirements: **Node.js >= 20**. The `wifi-densepose-sensing-server` Rust binary must be reachable at `RUVIEW_SENSING_SERVER_URL` (default `http://localhost:3000`).
|
||||
|
||||
## Feature matrix
|
||||
|
||||
| Tool | Description | ADR |
|
||||
|------|-------------|-----|
|
||||
| `ruview.presence.now` | Current occupancy: `present`, `n_persons`, `confidence` | ADR-124 §4.1 |
|
||||
| `ruview.vitals.get_breathing` | Breathing rate bpm (null if unavailable) | ADR-124 §4.1 |
|
||||
| `ruview.vitals.get_heart_rate` | Heart rate bpm (null if unavailable) | ADR-124 §4.1 |
|
||||
| `ruview.vitals.get_all` | Full `EdgeVitalsMessage` surface | ADR-124 §4.1 |
|
||||
| `ruview.bfld.last_scan` | Latest BFLD scan: `identity_risk_score`, `privacy_class`, `n_frames` | ADR-118/124 |
|
||||
| `ruview.bfld.subscribe` | Subscribe to `ruview/<node_id>/bfld/*` events for `duration_s` seconds | ADR-122/124 |
|
||||
| *(next iters)* | `pose.latest`, `primitives.*`, `node.*`, `vector.*`, `policy.*` | ADR-124 §4.1/4.1a |
|
||||
|
||||
**Transport security (ADR-124 §6)**:
|
||||
- **stdio**: process-level isolation — no auth needed for local Claude Code / Cursor.
|
||||
- **Streamable HTTP** (`POST /mcp`): Origin header validation (cross-origin → 403), optional bearer token (`RVAGENT_HTTP_TOKEN` → 401 on mismatch), binds `127.0.0.1` by default per MCP spec.
|
||||
|
||||
**Schema validation**: every tool call runs `zod.safeParse` before dispatch; invalid arguments return `McpError(InvalidParams)` rather than a wrapped string.
|
||||
|
||||
**Policy layer** (ADR-124 §4.1a): `ruview.policy.*` tools gate every sensing call — `vitals.*` is default-deny until a policy grant is registered via `npx @ruvnet/rvagent policy grant`. Presence and node-list are allow by default.
|
||||
|
||||
## ADR cross-reference
|
||||
|
||||
| ADR | Decision |
|
||||
|-----|----------|
|
||||
| [ADR-124](../../docs/adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md) | SENSE-BRIDGE: dual-transport MCP server + ruvector npm + ruflo integration |
|
||||
| [ADR-118](../../docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md) | BFLD pipeline — source of `bfld.last_scan` wire format |
|
||||
| [ADR-122](../../docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md) | MQTT topic routing `ruview/<node_id>/bfld/*` |
|
||||
| [ADR-115](../../docs/adr/ADR-115-home-assistant-integration.md) | `EdgeVitalsMessage` WebSocket surface (`ws.py:74-88` parity) |
|
||||
| [ADR-055](../../docs/adr/ADR-055-integrated-sensing-server.md) | Sensing-server REST API (`/api/v1/*`) |
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
cd tools/ruview-mcp
|
||||
npm install
|
||||
npm run build # tsc
|
||||
npm test # jest — 93 tests across 7 suites
|
||||
```
|
||||
|
||||
Source: `tools/ruview-mcp/src/`. Tests: `tools/ruview-mcp/tests/`.
|
||||
Tracking issue: [#787](https://github.com/ruvnet/RuView/issues/787).
|
||||
Generated
+5
-95
@@ -1,23 +1,21 @@
|
||||
{
|
||||
"name": "@ruvnet/rvagent",
|
||||
"version": "0.1.0",
|
||||
"name": "@ruv/ruview-mcp",
|
||||
"version": "0.0.1",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "@ruvnet/rvagent",
|
||||
"version": "0.1.0",
|
||||
"name": "@ruv/ruview-mcp",
|
||||
"version": "0.0.1",
|
||||
"license": "Apache-2.0",
|
||||
"dependencies": {
|
||||
"@modelcontextprotocol/sdk": "^1.0.0",
|
||||
"zod": "^3.23.8"
|
||||
},
|
||||
"bin": {
|
||||
"ruview-mcp": "dist/index.js",
|
||||
"rvagent": "dist/index.js"
|
||||
"ruview-mcp": "dist/index.js"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/express": "^5.0.6",
|
||||
"@types/jest": "^30.0.0",
|
||||
"@types/node": "^20.14.0",
|
||||
"jest": "^29.7.0",
|
||||
@@ -1061,52 +1059,6 @@
|
||||
"@babel/types": "^7.28.2"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/body-parser": {
|
||||
"version": "1.19.6",
|
||||
"resolved": "https://registry.npmjs.org/@types/body-parser/-/body-parser-1.19.6.tgz",
|
||||
"integrity": "sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@types/connect": "*",
|
||||
"@types/node": "*"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/connect": {
|
||||
"version": "3.4.38",
|
||||
"resolved": "https://registry.npmjs.org/@types/connect/-/connect-3.4.38.tgz",
|
||||
"integrity": "sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@types/node": "*"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/express": {
|
||||
"version": "5.0.6",
|
||||
"resolved": "https://registry.npmjs.org/@types/express/-/express-5.0.6.tgz",
|
||||
"integrity": "sha512-sKYVuV7Sv9fbPIt/442koC7+IIwK5olP1KWeD88e/idgoJqDm3JV/YUiPwkoKK92ylff2MGxSz1CSjsXelx0YA==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@types/body-parser": "*",
|
||||
"@types/express-serve-static-core": "^5.0.0",
|
||||
"@types/serve-static": "^2"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/express-serve-static-core": {
|
||||
"version": "5.1.1",
|
||||
"resolved": "https://registry.npmjs.org/@types/express-serve-static-core/-/express-serve-static-core-5.1.1.tgz",
|
||||
"integrity": "sha512-v4zIMr/cX7/d2BpAEX3KNKL/JrT1s43s96lLvvdTmza1oEvDudCqK9aF/djc/SWgy8Yh0h30TZx5VpzqFCxk5A==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@types/node": "*",
|
||||
"@types/qs": "*",
|
||||
"@types/range-parser": "*",
|
||||
"@types/send": "*"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/graceful-fs": {
|
||||
"version": "4.1.9",
|
||||
"resolved": "https://registry.npmjs.org/@types/graceful-fs/-/graceful-fs-4.1.9.tgz",
|
||||
@@ -1117,13 +1069,6 @@
|
||||
"@types/node": "*"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/http-errors": {
|
||||
"version": "2.0.5",
|
||||
"resolved": "https://registry.npmjs.org/@types/http-errors/-/http-errors-2.0.5.tgz",
|
||||
"integrity": "sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg==",
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@types/istanbul-lib-coverage": {
|
||||
"version": "2.0.6",
|
||||
"resolved": "https://registry.npmjs.org/@types/istanbul-lib-coverage/-/istanbul-lib-coverage-2.0.6.tgz",
|
||||
@@ -1387,41 +1332,6 @@
|
||||
"undici-types": "~6.21.0"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/qs": {
|
||||
"version": "6.15.1",
|
||||
"resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.15.1.tgz",
|
||||
"integrity": "sha512-GZHUBZR9hckSUhrxmp1nG6NwdpM9fCunJwyThLW1X3AyHgd9IlHb6VANpQQqDr2o/qQp6McZ3y/IA2rVzKzSbw==",
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@types/range-parser": {
|
||||
"version": "1.2.7",
|
||||
"resolved": "https://registry.npmjs.org/@types/range-parser/-/range-parser-1.2.7.tgz",
|
||||
"integrity": "sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ==",
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@types/send": {
|
||||
"version": "1.2.1",
|
||||
"resolved": "https://registry.npmjs.org/@types/send/-/send-1.2.1.tgz",
|
||||
"integrity": "sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@types/node": "*"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/serve-static": {
|
||||
"version": "2.2.0",
|
||||
"resolved": "https://registry.npmjs.org/@types/serve-static/-/serve-static-2.2.0.tgz",
|
||||
"integrity": "sha512-8mam4H1NHLtu7nmtalF7eyBH14QyOASmcxHhSfEoRyr0nP/YdoesEtU+uSRvMe96TW/HPTtkoKqQLl53N7UXMQ==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@types/http-errors": "*",
|
||||
"@types/node": "*"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/stack-utils": {
|
||||
"version": "2.0.3",
|
||||
"resolved": "https://registry.npmjs.org/@types/stack-utils/-/stack-utils-2.0.3.tgz",
|
||||
|
||||
@@ -1,25 +1,16 @@
|
||||
{
|
||||
"name": "@ruvnet/rvagent",
|
||||
"version": "0.1.0",
|
||||
"description": "SENSE-BRIDGE: dual-transport MCP server (stdio + Streamable HTTP) exposing RuView WiFi-DensePose sensing primitives to AI agents",
|
||||
"name": "@ruv/ruview-mcp",
|
||||
"version": "0.0.1",
|
||||
"description": "RuView MCP server — expose WiFi-DensePose sensing capabilities as MCP tools for Claude Code, Cursor, and other MCP-compatible agents",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"main": "dist/index.js",
|
||||
"types": "dist/index.d.ts",
|
||||
"exports": {
|
||||
".": {
|
||||
"import": "./dist/index.js",
|
||||
"require": "./dist/index.cjs",
|
||||
"types": "./dist/index.d.ts"
|
||||
}
|
||||
},
|
||||
"bin": {
|
||||
"rvagent": "dist/index.js",
|
||||
"ruview-mcp": "dist/index.js"
|
||||
},
|
||||
"files": [
|
||||
"dist",
|
||||
"README.md",
|
||||
"CHANGELOG.md"
|
||||
"dist"
|
||||
],
|
||||
"scripts": {
|
||||
"build": "tsc",
|
||||
@@ -31,32 +22,19 @@
|
||||
},
|
||||
"keywords": [
|
||||
"mcp",
|
||||
"rvagent",
|
||||
"ruview",
|
||||
"wifi",
|
||||
"csi",
|
||||
"pose-estimation",
|
||||
"cognitum",
|
||||
"sense-bridge",
|
||||
"ruvnet"
|
||||
"cognitum"
|
||||
],
|
||||
"author": "ruv <ruv@ruv.net>",
|
||||
"license": "Apache-2.0",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/ruvnet/RuView.git",
|
||||
"directory": "tools/ruview-mcp"
|
||||
},
|
||||
"homepage": "https://github.com/ruvnet/RuView/tree/main/tools/ruview-mcp",
|
||||
"bugs": {
|
||||
"url": "https://github.com/ruvnet/RuView/issues"
|
||||
},
|
||||
"dependencies": {
|
||||
"@modelcontextprotocol/sdk": "^1.0.0",
|
||||
"zod": "^3.23.8"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/express": "^5.0.6",
|
||||
"@types/jest": "^30.0.0",
|
||||
"@types/node": "^20.14.0",
|
||||
"jest": "^29.7.0",
|
||||
|
||||
@@ -1,179 +0,0 @@
|
||||
/**
|
||||
* Streamable HTTP transport scaffold for @ruvnet/rvagent (ADR-124 §3).
|
||||
*
|
||||
* Binds to 127.0.0.1 by default and mounts a POST /mcp endpoint backed by
|
||||
* StreamableHTTPServerTransport from @modelcontextprotocol/sdk.
|
||||
*
|
||||
* Security model (ADR-124 §6):
|
||||
* - Origin validation: requests from origins other than the configured
|
||||
* allowlist are rejected with 403 Forbidden before reaching the MCP layer.
|
||||
* - Default allowlist: ['http://localhost', 'http://127.0.0.1'] — covers
|
||||
* Claude Code and Cursor on the same machine.
|
||||
* - Bearer token: when RVAGENT_HTTP_TOKEN is set, requests must carry
|
||||
* Authorization: Bearer <token>; missing/wrong tokens → 401.
|
||||
* - Bind address: defaults to 127.0.0.1 per MCP spec security requirement.
|
||||
* Set RVAGENT_HTTP_HOST=0.0.0.0 only for intentional fleet deployment.
|
||||
*
|
||||
* Usage:
|
||||
* import { createHttpTransport } from './http-transport.js';
|
||||
* const { server: httpServer, transport } = await createHttpTransport(mcpServer);
|
||||
* // httpServer is a node:http.Server — call httpServer.close() to shut down.
|
||||
*/
|
||||
|
||||
import { createServer, type Server as HttpServer, type IncomingMessage, type ServerResponse } from "node:http";
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
|
||||
import type { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
|
||||
|
||||
export interface HttpTransportOptions {
|
||||
/** TCP host to bind (default: 127.0.0.1). */
|
||||
host?: string;
|
||||
/** TCP port to listen on (default: 3001). */
|
||||
port?: number;
|
||||
/**
|
||||
* Allowed Origin header values. Requests with an Origin not in this list
|
||||
* are rejected with 403. Use '*' to disable Origin validation entirely
|
||||
* (not recommended outside of local-dev flags).
|
||||
*/
|
||||
allowedOrigins?: string[];
|
||||
/**
|
||||
* Bearer token for HTTP transport. When set, every request must supply
|
||||
* Authorization: Bearer <token>; omitted or wrong token → 401.
|
||||
* Defaults to process.env.RVAGENT_HTTP_TOKEN (undefined = auth disabled).
|
||||
*/
|
||||
bearerToken?: string;
|
||||
}
|
||||
|
||||
export interface HttpTransportResult {
|
||||
/** The raw Node.js HTTP server — call .close() to shut down. */
|
||||
httpServer: HttpServer;
|
||||
/** The MCP Streamable HTTP transport instance wired to the MCP server. */
|
||||
transport: StreamableHTTPServerTransport;
|
||||
/** The bound address string (e.g. "http://127.0.0.1:3001"). */
|
||||
boundAddress: string;
|
||||
}
|
||||
|
||||
const DEFAULT_HOST = "127.0.0.1";
|
||||
const DEFAULT_PORT = 3001;
|
||||
const LOCALHOST_ORIGINS = new Set([
|
||||
"http://localhost",
|
||||
"http://127.0.0.1",
|
||||
"https://localhost",
|
||||
"https://127.0.0.1",
|
||||
]);
|
||||
|
||||
/**
|
||||
* Validate Origin header against the allowlist.
|
||||
* Returns true if the request should be allowed, false if it should be rejected.
|
||||
*
|
||||
* An absent Origin header is allowed (same-origin non-browser requests, curl, etc.).
|
||||
* A present Origin that is not in the allowlist is rejected.
|
||||
*/
|
||||
export function isOriginAllowed(
|
||||
origin: string | undefined,
|
||||
allowedOrigins: string[]
|
||||
): boolean {
|
||||
if (origin === undefined) return true; // no Origin = not a cross-origin browser request
|
||||
if (allowedOrigins.includes("*")) return true;
|
||||
return allowedOrigins.some((o) => o === origin);
|
||||
}
|
||||
|
||||
/**
|
||||
* Build and wire a Streamable HTTP transport to the provided MCP server.
|
||||
* Returns the Node.js HTTP server (not yet listening) plus the transport.
|
||||
* Call httpServer.listen(port, host) or rely on createHttpTransport which
|
||||
* does that for you.
|
||||
*/
|
||||
export function buildHttpApp(
|
||||
mcpServer: McpServer,
|
||||
opts: HttpTransportOptions = {}
|
||||
): { httpServer: HttpServer; transport: StreamableHTTPServerTransport } {
|
||||
const allowedOrigins: string[] = opts.allowedOrigins ?? [
|
||||
...LOCALHOST_ORIGINS,
|
||||
];
|
||||
const bearerToken = opts.bearerToken ?? process.env["RVAGENT_HTTP_TOKEN"];
|
||||
|
||||
const transport = new StreamableHTTPServerTransport({
|
||||
sessionIdGenerator: () => randomUUID(),
|
||||
});
|
||||
|
||||
const httpServer = createServer(
|
||||
(req: IncomingMessage, res: ServerResponse) => {
|
||||
// ── Origin validation ────────────────────────────────────────────────
|
||||
const origin = req.headers["origin"] as string | undefined;
|
||||
if (!isOriginAllowed(origin, allowedOrigins)) {
|
||||
res.writeHead(403, { "Content-Type": "application/json" });
|
||||
res.end(JSON.stringify({ error: "Forbidden: cross-origin request rejected" }));
|
||||
return;
|
||||
}
|
||||
|
||||
// ── Bearer token auth ────────────────────────────────────────────────
|
||||
if (bearerToken !== undefined && bearerToken !== "") {
|
||||
const authHeader = req.headers["authorization"] as string | undefined;
|
||||
const supplied = authHeader?.startsWith("Bearer ")
|
||||
? authHeader.slice("Bearer ".length)
|
||||
: undefined;
|
||||
if (supplied !== bearerToken) {
|
||||
res.writeHead(401, { "Content-Type": "application/json" });
|
||||
res.end(JSON.stringify({ error: "Unauthorized: missing or invalid bearer token" }));
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
// ── Route: POST /mcp ─────────────────────────────────────────────────
|
||||
if (req.method === "POST" && req.url === "/mcp") {
|
||||
let body = "";
|
||||
req.on("data", (chunk: Buffer) => { body += chunk.toString(); });
|
||||
req.on("end", () => {
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = JSON.parse(body);
|
||||
} catch {
|
||||
res.writeHead(400, { "Content-Type": "application/json" });
|
||||
res.end(JSON.stringify({ error: "Bad Request: invalid JSON body" }));
|
||||
return;
|
||||
}
|
||||
void transport.handleRequest(req, res, parsed);
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
// ── Fallback ─────────────────────────────────────────────────────────
|
||||
res.writeHead(404, { "Content-Type": "application/json" });
|
||||
res.end(JSON.stringify({ error: "Not found. MCP endpoint: POST /mcp" }));
|
||||
}
|
||||
);
|
||||
|
||||
return { httpServer, transport };
|
||||
}
|
||||
|
||||
/**
|
||||
* Create and start the Streamable HTTP transport, resolving once the server
|
||||
* is bound and listening.
|
||||
*/
|
||||
export async function createHttpTransport(
|
||||
mcpServer: McpServer,
|
||||
opts: HttpTransportOptions = {}
|
||||
): Promise<HttpTransportResult> {
|
||||
const host = opts.host ?? process.env["RVAGENT_HTTP_HOST"] ?? DEFAULT_HOST;
|
||||
const port = opts.port ?? Number(process.env["RVAGENT_HTTP_PORT"] ?? DEFAULT_PORT);
|
||||
|
||||
const { httpServer, transport } = buildHttpApp(mcpServer, opts);
|
||||
|
||||
// Wire MCP server to the transport only after the HTTP server is built.
|
||||
// Cast needed: StreamableHTTPServerTransport implements Transport but
|
||||
// exactOptionalPropertyTypes causes a false incompatibility on optional
|
||||
// callback properties; the cast is safe — the SDK types are consistent.
|
||||
await mcpServer.connect(transport as Parameters<typeof mcpServer.connect>[0]);
|
||||
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
httpServer.once("error", reject);
|
||||
httpServer.listen(port, host, () => resolve());
|
||||
});
|
||||
|
||||
return {
|
||||
httpServer,
|
||||
transport,
|
||||
boundAddress: `http://${host}:${port}`,
|
||||
};
|
||||
}
|
||||
@@ -29,8 +29,6 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
|
||||
import {
|
||||
CallToolRequestSchema,
|
||||
ListToolsRequestSchema,
|
||||
McpError,
|
||||
ErrorCode,
|
||||
} from "@modelcontextprotocol/sdk/types.js";
|
||||
|
||||
import { loadConfig } from "./config.js";
|
||||
@@ -44,16 +42,9 @@ import {
|
||||
jobStatusSchema,
|
||||
jobStatus,
|
||||
} from "./tools/train-count.js";
|
||||
import { TOOL_INPUT_SCHEMAS } from "./schemas/index.js";
|
||||
import { bfldLastScan } from "./tools/bfld-last-scan.js";
|
||||
import { bfldSubscribe } from "./tools/bfld-subscribe.js";
|
||||
import { presenceNow } from "./tools/presence-now.js";
|
||||
import { vitalsGetBreathing } from "./tools/vitals-get-breathing.js";
|
||||
import { vitalsGetHeartRate } from "./tools/vitals-get-heart-rate.js";
|
||||
import { vitalsGetAll } from "./tools/vitals-get-all.js";
|
||||
|
||||
const PACKAGE_VERSION = "0.1.0";
|
||||
const SERVER_NAME = "rvagent";
|
||||
const PACKAGE_VERSION = "0.0.1";
|
||||
const SERVER_NAME = "ruview";
|
||||
|
||||
// ── Tool registry ──────────────────────────────────────────────────────────
|
||||
|
||||
@@ -225,126 +216,6 @@ const TOOLS = [
|
||||
return jobStatus(input, config);
|
||||
},
|
||||
},
|
||||
// ── ADR-124 BFLD tools (Phase 4 Refinement) ──────────────────────────────
|
||||
{
|
||||
name: "ruview.bfld.last_scan",
|
||||
description:
|
||||
"Return the most recent BFLD scan result for a node (ADR-118/ADR-121). " +
|
||||
"Fields: node_id, identity_risk_score [0,1], privacy_class, n_frames, timestamp_ms. " +
|
||||
"Proxied from sensing-server GET /api/v1/bfld/<node_id>/last_scan which aggregates " +
|
||||
"the MQTT state topics ruview/<node_id>/bfld/* (ADR-122 §2.2).",
|
||||
inputSchema: {
|
||||
type: "object" as const,
|
||||
properties: {
|
||||
node_id: {
|
||||
type: "string",
|
||||
description: "Target node id. Omit to use the single active node.",
|
||||
},
|
||||
sensing_server_url: {
|
||||
type: "string",
|
||||
description: "Override sensing-server URL for this call only.",
|
||||
},
|
||||
},
|
||||
},
|
||||
handler: async (args: unknown, config: ReturnType<typeof loadConfig>) => {
|
||||
return bfldLastScan(args as Parameters<typeof bfldLastScan>[0], config);
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "ruview.bfld.subscribe",
|
||||
description:
|
||||
"Subscribe to BFLD events on ruview/<node_id>/bfld/* for duration_s seconds (ADR-122). " +
|
||||
"Returns {ok, subscription_id, expires_at, topic}. When the sensing-server is unreachable, " +
|
||||
"returns a synthetic envelope with ok:false,warn:true so the caller can distinguish " +
|
||||
"a network error from an invalid request.",
|
||||
inputSchema: {
|
||||
type: "object" as const,
|
||||
required: ["duration_s"],
|
||||
properties: {
|
||||
node_id: {
|
||||
type: "string",
|
||||
description: "Target node id. Omit to use the single active node.",
|
||||
},
|
||||
duration_s: {
|
||||
type: "number",
|
||||
minimum: 0,
|
||||
maximum: 3600,
|
||||
description: "Subscription duration in seconds (max 3600).",
|
||||
},
|
||||
sensing_server_url: {
|
||||
type: "string",
|
||||
description: "Override sensing-server URL for this call only.",
|
||||
},
|
||||
},
|
||||
},
|
||||
handler: async (args: unknown, config: ReturnType<typeof loadConfig>) => {
|
||||
return bfldSubscribe(args as Parameters<typeof bfldSubscribe>[0], config);
|
||||
},
|
||||
},
|
||||
// ── ADR-124 Presence + Vitals tools (Phase 4 Refinement iter 5) ──────────
|
||||
{
|
||||
name: "ruview.presence.now",
|
||||
description:
|
||||
"Return current occupancy for a node: present, n_persons, confidence, timestamp_ms. " +
|
||||
"Wraps EdgeVitalsMessage.presence + n_persons (ADR-124 §4.1, ws.py:74-88).",
|
||||
inputSchema: {
|
||||
type: "object" as const,
|
||||
properties: {
|
||||
node_id: { type: "string", description: "Target node id." },
|
||||
sensing_server_url: { type: "string", description: "Override sensing-server URL." },
|
||||
},
|
||||
},
|
||||
handler: async (args: unknown, config: ReturnType<typeof loadConfig>) =>
|
||||
presenceNow(args as Parameters<typeof presenceNow>[0], config),
|
||||
},
|
||||
{
|
||||
name: "ruview.vitals.get_breathing",
|
||||
description:
|
||||
"Return breathing rate for a node: breathing_rate_bpm (null if unavailable), " +
|
||||
"confidence, timestamp_ms. Wraps EdgeVitalsMessage.breathing_rate_bpm (ws.py:82).",
|
||||
inputSchema: {
|
||||
type: "object" as const,
|
||||
properties: {
|
||||
node_id: { type: "string", description: "Target node id." },
|
||||
window_s: { type: "number", description: "Averaging window in seconds (max 300)." },
|
||||
sensing_server_url: { type: "string", description: "Override sensing-server URL." },
|
||||
},
|
||||
},
|
||||
handler: async (args: unknown, config: ReturnType<typeof loadConfig>) =>
|
||||
vitalsGetBreathing(args as Parameters<typeof vitalsGetBreathing>[0], config),
|
||||
},
|
||||
{
|
||||
name: "ruview.vitals.get_heart_rate",
|
||||
description:
|
||||
"Return heart rate for a node: heartrate_bpm (null if unavailable), " +
|
||||
"confidence, timestamp_ms. Wraps EdgeVitalsMessage.heartrate_bpm (ws.py:83).",
|
||||
inputSchema: {
|
||||
type: "object" as const,
|
||||
properties: {
|
||||
node_id: { type: "string", description: "Target node id." },
|
||||
window_s: { type: "number", description: "Averaging window in seconds (max 300)." },
|
||||
sensing_server_url: { type: "string", description: "Override sensing-server URL." },
|
||||
},
|
||||
},
|
||||
handler: async (args: unknown, config: ReturnType<typeof loadConfig>) =>
|
||||
vitalsGetHeartRate(args as Parameters<typeof vitalsGetHeartRate>[0], config),
|
||||
},
|
||||
{
|
||||
name: "ruview.vitals.get_all",
|
||||
description:
|
||||
"Return the full EdgeVitalsMessage for a node (all fields except raw): " +
|
||||
"presence, n_persons, confidence, breathing_rate_bpm, heartrate_bpm, motion, zone_id. " +
|
||||
"Full surface of ws.py:74-88.",
|
||||
inputSchema: {
|
||||
type: "object" as const,
|
||||
properties: {
|
||||
node_id: { type: "string", description: "Target node id." },
|
||||
sensing_server_url: { type: "string", description: "Override sensing-server URL." },
|
||||
},
|
||||
},
|
||||
handler: async (args: unknown, config: ReturnType<typeof loadConfig>) =>
|
||||
vitalsGetAll(args as Parameters<typeof vitalsGetAll>[0], config),
|
||||
},
|
||||
] as const;
|
||||
|
||||
// ── Server bootstrap ────────────────────────────────────────────────────────
|
||||
@@ -373,10 +244,7 @@ async function main(): Promise<void> {
|
||||
})),
|
||||
}));
|
||||
|
||||
// Call tool handler — uniform Zod validation gate (ADR-124 §3 Architecture).
|
||||
// If TOOL_INPUT_SCHEMAS has a schema for the tool name, run safeParse first.
|
||||
// Parse failures throw McpError(InvalidParams) so the client sees a typed
|
||||
// JSON-RPC error rather than a wrapped string error.
|
||||
// Call tool handler.
|
||||
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
||||
const { name, arguments: args } = request.params;
|
||||
const tool = TOOLS.find((t) => t.name === name);
|
||||
@@ -396,20 +264,6 @@ async function main(): Promise<void> {
|
||||
};
|
||||
}
|
||||
|
||||
// Schema validation gate — applies to all tools registered in TOOL_INPUT_SCHEMAS.
|
||||
const schemaEntry = Object.prototype.hasOwnProperty.call(TOOL_INPUT_SCHEMAS, name)
|
||||
? TOOL_INPUT_SCHEMAS[name as keyof typeof TOOL_INPUT_SCHEMAS]
|
||||
: undefined;
|
||||
if (schemaEntry !== undefined) {
|
||||
const parsed = schemaEntry.safeParse(args ?? {});
|
||||
if (!parsed.success) {
|
||||
throw new McpError(
|
||||
ErrorCode.InvalidParams,
|
||||
`Invalid arguments for tool "${name}": ${parsed.error.message}`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
try {
|
||||
const result = await tool.handler(args ?? {}, config);
|
||||
return {
|
||||
@@ -421,7 +275,6 @@ async function main(): Promise<void> {
|
||||
],
|
||||
};
|
||||
} catch (e: unknown) {
|
||||
if (e instanceof McpError) throw e; // propagate typed errors unchanged
|
||||
const message = e instanceof Error ? e.message : String(e);
|
||||
return {
|
||||
content: [
|
||||
@@ -444,7 +297,7 @@ async function main(): Promise<void> {
|
||||
|
||||
// Log to stderr so it doesn't interfere with the MCP stdio protocol.
|
||||
process.stderr.write(
|
||||
`[@ruvnet/rvagent] Server v${PACKAGE_VERSION} started. ` +
|
||||
`[ruview-mcp] Server v${PACKAGE_VERSION} started. ` +
|
||||
`Sensing server: ${config.sensingServerUrl}\n`
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1,79 +0,0 @@
|
||||
/**
|
||||
* Shared Zod sub-schemas reused across the ADR-124 §4.1 tool catalog.
|
||||
*
|
||||
* All constraints are sourced from the ADR-124 decision record; comments cite
|
||||
* the specific table row or section that defines the constraint.
|
||||
*/
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
// ── Shared primitives ──────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Optional node_id — present on almost every tool. Defaults to the single
|
||||
* active node when only one is registered; required for multi-node fleets.
|
||||
*/
|
||||
export const NodeIdSchema = z
|
||||
.string()
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Target node id. Omit to use the single active node.");
|
||||
|
||||
/**
|
||||
* Subscription duration in seconds. ADR-124 policy layer caps this at the
|
||||
* value returned by ruview.policy.can_subscribe.max_duration_s; the schema
|
||||
* enforces a hard ceiling of 3600 s (1 h) as a first-line guard.
|
||||
*/
|
||||
export const DurationSSchema = z
|
||||
.number()
|
||||
.positive()
|
||||
.max(3600)
|
||||
.describe("Subscription duration in seconds (max 3600).");
|
||||
|
||||
/**
|
||||
* Optional window in seconds for vitals averaging. Positive, max 300 s.
|
||||
* ADR-124 §4.1 rows vitals.get_breathing / vitals.get_heart_rate.
|
||||
*/
|
||||
export const WindowSSchema = z
|
||||
.number()
|
||||
.positive()
|
||||
.max(300)
|
||||
.optional()
|
||||
.describe("Averaging window in seconds (max 300).");
|
||||
|
||||
/**
|
||||
* The 10 semantic primitive kinds defined in ADR-115 and mirrored in
|
||||
* python/wifi_densepose/client/primitives.py:36-45.
|
||||
*/
|
||||
export const SemanticPrimitiveKindSchema = z.enum([
|
||||
"presence",
|
||||
"n_persons",
|
||||
"fall_detected",
|
||||
"breathing_rate",
|
||||
"heart_rate",
|
||||
"gesture",
|
||||
"zone_entry",
|
||||
"zone_exit",
|
||||
"movement_intensity",
|
||||
"sleep_quality",
|
||||
]);
|
||||
|
||||
export type SemanticPrimitiveKind = z.infer<typeof SemanticPrimitiveKindSchema>;
|
||||
|
||||
/**
|
||||
* A single 17-keypoint COCO pose result as stored and returned by the
|
||||
* ruvector HNSW index (ADR-016). Used by ruview.vector.store_pose input.
|
||||
*/
|
||||
export const PosePersonResultSchema = z.object({
|
||||
keypoints: z
|
||||
.array(z.tuple([z.number(), z.number()]))
|
||||
.length(17)
|
||||
.describe("17 COCO keypoints as [x,y] pairs in image-normalised coords."),
|
||||
confidence: z.number().min(0).max(1).describe("Pose confidence score [0,1]."),
|
||||
person_id: z
|
||||
.string()
|
||||
.optional()
|
||||
.describe("AETHER re-ID token, if available."),
|
||||
});
|
||||
|
||||
export type PosePersonResult = z.infer<typeof PosePersonResultSchema>;
|
||||
@@ -1,9 +0,0 @@
|
||||
/**
|
||||
* Barrel re-export for @ruvnet/rvagent schema layer.
|
||||
*
|
||||
* Import from this module to get all Zod input schemas, shared sub-schemas,
|
||||
* the TOOL_NAMES catalog, and the TOOL_INPUT_SCHEMAS dispatch map.
|
||||
*/
|
||||
|
||||
export * from "./common.js";
|
||||
export * from "./tools.js";
|
||||
@@ -1,242 +0,0 @@
|
||||
/**
|
||||
* Zod input schemas for all 20 ADR-124 MCP tools.
|
||||
*
|
||||
* §4.1 — 15 sensing tools (presence, vitals, pose, primitives, bfld, node, vector)
|
||||
* §4.1a — 5 policy / governance tools (RUVIEW-POLICY)
|
||||
*
|
||||
* Each exported schema is named `<CamelCase>InputSchema` matching the tool
|
||||
* name from the ADR-124 §4.1 catalog table. The parallel `TOOL_NAMES` array
|
||||
* is the single source of truth asserted by the schema-coverage test.
|
||||
*/
|
||||
|
||||
import { z } from "zod";
|
||||
import {
|
||||
NodeIdSchema,
|
||||
DurationSSchema,
|
||||
WindowSSchema,
|
||||
SemanticPrimitiveKindSchema,
|
||||
PosePersonResultSchema,
|
||||
} from "./common.js";
|
||||
|
||||
// ── §4.1 Presence ──────────────────────────────────────────────────────────
|
||||
|
||||
/** ruview.presence.now */
|
||||
export const PresenceNowInputSchema = z.object({
|
||||
node_id: NodeIdSchema,
|
||||
});
|
||||
|
||||
// ── §4.1 Vitals ───────────────────────────────────────────────────────────
|
||||
|
||||
/** ruview.vitals.get_breathing */
|
||||
export const VitalsGetBreathingInputSchema = z.object({
|
||||
node_id: NodeIdSchema,
|
||||
window_s: WindowSSchema,
|
||||
});
|
||||
|
||||
/** ruview.vitals.get_heart_rate */
|
||||
export const VitalsGetHeartRateInputSchema = z.object({
|
||||
node_id: NodeIdSchema,
|
||||
window_s: WindowSSchema,
|
||||
});
|
||||
|
||||
/** ruview.vitals.get_all */
|
||||
export const VitalsGetAllInputSchema = z.object({
|
||||
node_id: NodeIdSchema,
|
||||
});
|
||||
|
||||
// ── §4.1 Pose ─────────────────────────────────────────────────────────────
|
||||
|
||||
/** ruview.pose.latest */
|
||||
export const PoseLatestInputSchema = z.object({
|
||||
node_id: NodeIdSchema,
|
||||
});
|
||||
|
||||
/** ruview.pose.subscribe */
|
||||
export const PoseSubscribeInputSchema = z.object({
|
||||
node_id: NodeIdSchema,
|
||||
duration_s: DurationSSchema,
|
||||
callback_url: z
|
||||
.string()
|
||||
.url()
|
||||
.optional()
|
||||
.describe("Webhook URL to receive PoseDataMessage events (optional)."),
|
||||
});
|
||||
|
||||
// ── §4.1 Primitives ───────────────────────────────────────────────────────
|
||||
|
||||
/** ruview.primitives.get */
|
||||
export const PrimitivesGetInputSchema = z.object({
|
||||
node_id: NodeIdSchema,
|
||||
primitive: SemanticPrimitiveKindSchema,
|
||||
});
|
||||
|
||||
/** ruview.primitives.list_active */
|
||||
export const PrimitivesListActiveInputSchema = z.object({
|
||||
node_id: NodeIdSchema,
|
||||
});
|
||||
|
||||
/** ruview.primitives.subscribe */
|
||||
export const PrimitivesSubscribeInputSchema = z.object({
|
||||
node_id: NodeIdSchema,
|
||||
primitive: SemanticPrimitiveKindSchema.optional().describe(
|
||||
"Subscribe to a specific primitive. Omit to receive all active primitives."
|
||||
),
|
||||
duration_s: DurationSSchema,
|
||||
});
|
||||
|
||||
// ── §4.1 BFLD ────────────────────────────────────────────────────────────
|
||||
|
||||
/** ruview.bfld.last_scan */
|
||||
export const BfldLastScanInputSchema = z.object({
|
||||
node_id: NodeIdSchema,
|
||||
});
|
||||
|
||||
/** ruview.bfld.subscribe */
|
||||
export const BfldSubscribeInputSchema = z.object({
|
||||
node_id: NodeIdSchema,
|
||||
duration_s: DurationSSchema,
|
||||
});
|
||||
|
||||
// ── §4.1 Node ────────────────────────────────────────────────────────────
|
||||
|
||||
/** ruview.node.list — empty input per ADR-124 §4.1 table */
|
||||
export const NodeListInputSchema = z.object({});
|
||||
|
||||
/** ruview.node.status */
|
||||
export const NodeStatusInputSchema = z.object({
|
||||
node_id: z.string().min(1).describe("Node id to query status for."),
|
||||
});
|
||||
|
||||
// ── §4.1 Vector ──────────────────────────────────────────────────────────
|
||||
|
||||
/** ruview.vector.search_pose */
|
||||
export const VectorSearchPoseInputSchema = z.object({
|
||||
query_embedding: z
|
||||
.array(z.number())
|
||||
.min(1)
|
||||
.describe("Dense embedding vector to query against the HNSW index."),
|
||||
k: z
|
||||
.number()
|
||||
.int()
|
||||
.positive()
|
||||
.max(100)
|
||||
.optional()
|
||||
.default(10)
|
||||
.describe("Number of nearest neighbours to return (default 10, max 100)."),
|
||||
node_id: NodeIdSchema,
|
||||
});
|
||||
|
||||
/** ruview.vector.store_pose */
|
||||
export const VectorStorePoseInputSchema = z.object({
|
||||
pose: PosePersonResultSchema,
|
||||
node_id: z.string().min(1).describe("Node id that observed this pose."),
|
||||
});
|
||||
|
||||
// ── §4.1a Policy / governance tools ──────────────────────────────────────
|
||||
|
||||
/** ruview.policy.can_access_vitals */
|
||||
export const PolicyCanAccessVitalsInputSchema = z.object({
|
||||
agent_id: z.string().min(1).describe("Calling agent identifier."),
|
||||
node_id: z.string().min(1).describe("Target sensing node."),
|
||||
vital: z
|
||||
.enum(["breathing", "heart_rate", "all"])
|
||||
.describe("Which vital the agent is requesting."),
|
||||
});
|
||||
|
||||
/** ruview.policy.can_query_presence */
|
||||
export const PolicyCanQueryPresenceInputSchema = z.object({
|
||||
agent_id: z.string().min(1),
|
||||
scope: z
|
||||
.enum(["node", "fleet"])
|
||||
.describe("node = single node; fleet = all nodes / aggregated count."),
|
||||
node_id: NodeIdSchema,
|
||||
zone: z
|
||||
.string()
|
||||
.optional()
|
||||
.describe("Named zone within a node (e.g. 'living_room')."),
|
||||
});
|
||||
|
||||
/** ruview.policy.can_subscribe */
|
||||
export const PolicyCanSubscribeInputSchema = z.object({
|
||||
agent_id: z.string().min(1),
|
||||
topic: z
|
||||
.string()
|
||||
.min(1)
|
||||
.describe("MQTT topic or tool name the agent wishes to subscribe to."),
|
||||
duration_s: DurationSSchema,
|
||||
});
|
||||
|
||||
/** ruview.policy.redact_identity_fields */
|
||||
export const PolicyRedactIdentityFieldsInputSchema = z.object({
|
||||
payload: z.record(z.unknown()).describe("Tool return value to redact."),
|
||||
agent_id: z.string().min(1),
|
||||
});
|
||||
|
||||
/** ruview.policy.audit_log */
|
||||
export const PolicyAuditLogInputSchema = z.object({
|
||||
agent_id: z.string().optional().describe("Filter to a specific agent."),
|
||||
since_ts: z
|
||||
.number()
|
||||
.optional()
|
||||
.describe("Return events after this Unix timestamp (ms)."),
|
||||
});
|
||||
|
||||
// ── Catalog ───────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Single source of truth: every tool name in the ADR-124 §4.1 + §4.1a catalog.
|
||||
* The schema-coverage test asserts this list exactly matches the exported schemas.
|
||||
*/
|
||||
export const TOOL_NAMES = [
|
||||
// §4.1 — 15 sensing tools
|
||||
"ruview.presence.now",
|
||||
"ruview.vitals.get_breathing",
|
||||
"ruview.vitals.get_heart_rate",
|
||||
"ruview.vitals.get_all",
|
||||
"ruview.pose.latest",
|
||||
"ruview.pose.subscribe",
|
||||
"ruview.primitives.get",
|
||||
"ruview.primitives.list_active",
|
||||
"ruview.primitives.subscribe",
|
||||
"ruview.bfld.last_scan",
|
||||
"ruview.bfld.subscribe",
|
||||
"ruview.node.list",
|
||||
"ruview.node.status",
|
||||
"ruview.vector.search_pose",
|
||||
"ruview.vector.store_pose",
|
||||
// §4.1a — 5 policy tools
|
||||
"ruview.policy.can_access_vitals",
|
||||
"ruview.policy.can_query_presence",
|
||||
"ruview.policy.can_subscribe",
|
||||
"ruview.policy.redact_identity_fields",
|
||||
"ruview.policy.audit_log",
|
||||
] as const;
|
||||
|
||||
export type ToolName = (typeof TOOL_NAMES)[number];
|
||||
|
||||
/**
|
||||
* Map from tool name → its Zod input schema. Used by the MCP server's
|
||||
* CallTool handler for uniform schema-validation before dispatch.
|
||||
*/
|
||||
export const TOOL_INPUT_SCHEMAS: Record<ToolName, z.ZodTypeAny> = {
|
||||
"ruview.presence.now": PresenceNowInputSchema,
|
||||
"ruview.vitals.get_breathing": VitalsGetBreathingInputSchema,
|
||||
"ruview.vitals.get_heart_rate": VitalsGetHeartRateInputSchema,
|
||||
"ruview.vitals.get_all": VitalsGetAllInputSchema,
|
||||
"ruview.pose.latest": PoseLatestInputSchema,
|
||||
"ruview.pose.subscribe": PoseSubscribeInputSchema,
|
||||
"ruview.primitives.get": PrimitivesGetInputSchema,
|
||||
"ruview.primitives.list_active": PrimitivesListActiveInputSchema,
|
||||
"ruview.primitives.subscribe": PrimitivesSubscribeInputSchema,
|
||||
"ruview.bfld.last_scan": BfldLastScanInputSchema,
|
||||
"ruview.bfld.subscribe": BfldSubscribeInputSchema,
|
||||
"ruview.node.list": NodeListInputSchema,
|
||||
"ruview.node.status": NodeStatusInputSchema,
|
||||
"ruview.vector.search_pose": VectorSearchPoseInputSchema,
|
||||
"ruview.vector.store_pose": VectorStorePoseInputSchema,
|
||||
"ruview.policy.can_access_vitals": PolicyCanAccessVitalsInputSchema,
|
||||
"ruview.policy.can_query_presence": PolicyCanQueryPresenceInputSchema,
|
||||
"ruview.policy.can_subscribe": PolicyCanSubscribeInputSchema,
|
||||
"ruview.policy.redact_identity_fields": PolicyRedactIdentityFieldsInputSchema,
|
||||
"ruview.policy.audit_log": PolicyAuditLogInputSchema,
|
||||
};
|
||||
@@ -1,111 +0,0 @@
|
||||
/**
|
||||
* MCP tool: ruview.bfld.last_scan
|
||||
*
|
||||
* Returns the most recent BFLD scan result for a node, sourced from the
|
||||
* sensing-server's REST proxy of the BFLD MQTT state topics defined in
|
||||
* ADR-122 §2.2. The sensing-server aggregates the per-entity state topics
|
||||
* (presence, person_count, confidence, identity_risk) into a single JSON
|
||||
* object at GET /api/v1/bfld/<node_id>/last_scan.
|
||||
*
|
||||
* Wire format (ADR-118 BfldEvent, class-permissive fields only):
|
||||
* node_id string — originating node
|
||||
* identity_risk_score number — [0,1], None at privacy_class Restricted
|
||||
* privacy_class number — 0=raw,1=derived,2=anonymous,3=restricted
|
||||
* n_frames number — person_count proxy (frames accumulated)
|
||||
* timestamp_ms number — capture timestamp in ms since epoch
|
||||
*
|
||||
* Returns {ok:false, warn:true} when the sensing-server is not reachable
|
||||
* so the caller can treat unavailability as a soft warning rather than
|
||||
* a hard error (mirrors the pattern in csi-latest.ts).
|
||||
*/
|
||||
|
||||
import { z } from "zod";
|
||||
import type { RuviewConfig } from "../types.js";
|
||||
import { sensingGet } from "../http.js";
|
||||
|
||||
export const bfldLastScanSchema = z.object({
|
||||
node_id: z
|
||||
.string()
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Target node id. Omit to use the single active node."),
|
||||
sensing_server_url: z
|
||||
.string()
|
||||
.url()
|
||||
.optional()
|
||||
.describe("Override sensing-server URL for this call only."),
|
||||
});
|
||||
|
||||
export type BfldLastScanInput = z.infer<typeof bfldLastScanSchema>;
|
||||
|
||||
/** Shape returned by the sensing-server BFLD last-scan proxy endpoint. */
|
||||
interface BfldScanResponse {
|
||||
node_id: string;
|
||||
identity_risk_score: number | null;
|
||||
privacy_class: number;
|
||||
person_count: number;
|
||||
confidence: number;
|
||||
presence: boolean;
|
||||
timestamp_ns: number;
|
||||
}
|
||||
|
||||
/** ADR-124 §4.1 output contract for ruview.bfld.last_scan. */
|
||||
export interface BfldLastScanResult {
|
||||
ok: true;
|
||||
node_id: string;
|
||||
identity_risk_score: number | null;
|
||||
privacy_class: number;
|
||||
/** person_count used as n_frames proxy (ADR-118 BfldEvent.person_count). */
|
||||
n_frames: number;
|
||||
/** Converted from BfldEvent.timestamp_ns (nanoseconds → milliseconds). */
|
||||
timestamp_ms: number;
|
||||
}
|
||||
|
||||
export async function bfldLastScan(
|
||||
input: BfldLastScanInput,
|
||||
config: RuviewConfig
|
||||
): Promise<object> {
|
||||
const baseUrl = input.sensing_server_url ?? config.sensingServerUrl;
|
||||
const nodeId = input.node_id ?? "default";
|
||||
|
||||
const result = await sensingGet<BfldScanResponse>(
|
||||
baseUrl,
|
||||
`/api/v1/bfld/${encodeURIComponent(nodeId)}/last_scan`,
|
||||
config.apiToken
|
||||
);
|
||||
|
||||
if (!result.ok) {
|
||||
return {
|
||||
ok: false,
|
||||
warn: true,
|
||||
error: result.error,
|
||||
hint:
|
||||
"Ensure the sensing-server is running and the BFLD pipeline is active " +
|
||||
"(ADR-118). The node must have published at least one BfldEvent since " +
|
||||
"the last server restart.",
|
||||
};
|
||||
}
|
||||
|
||||
const data = result.data;
|
||||
|
||||
// Validate the minimum required fields are present.
|
||||
if (typeof data.node_id !== "string" || typeof data.timestamp_ns !== "number") {
|
||||
return {
|
||||
ok: false,
|
||||
warn: true,
|
||||
error: "Sensing-server returned an unexpected BFLD response shape.",
|
||||
raw_response: data,
|
||||
};
|
||||
}
|
||||
|
||||
const out: BfldLastScanResult = {
|
||||
ok: true,
|
||||
node_id: data.node_id,
|
||||
identity_risk_score: data.identity_risk_score ?? null,
|
||||
privacy_class: data.privacy_class,
|
||||
n_frames: data.person_count,
|
||||
timestamp_ms: Math.round(data.timestamp_ns / 1_000_000),
|
||||
};
|
||||
|
||||
return out;
|
||||
}
|
||||
@@ -1,124 +0,0 @@
|
||||
/**
|
||||
* MCP tool: ruview.bfld.subscribe
|
||||
*
|
||||
* Registers interest in BFLD events for `duration_s` seconds by instructing
|
||||
* the sensing-server to forward MQTT messages from topic
|
||||
* `ruview/<node_id>/bfld/*` (ADR-122 §2.2) to a server-side event buffer.
|
||||
*
|
||||
* This is a stateless stub that does NOT require a running MQTT broker in
|
||||
* the MCP server process. Instead it proxies the subscription request to the
|
||||
* sensing-server's webhook/subscription registry at
|
||||
* POST /api/v1/bfld/<node_id>/subscribe, which returns a subscription_id.
|
||||
*
|
||||
* When the sensing-server is unreachable, the handler returns {ok:false,warn:true}
|
||||
* rather than throwing, consistent with the ruview-mcp soft-failure convention.
|
||||
*
|
||||
* In environments where no real broker is available (unit tests, dev machines
|
||||
* without mosquitto) the handler synthesises a valid subscription envelope
|
||||
* locally so the MCP schema-validation gate can be exercised independently.
|
||||
*
|
||||
* ADR-124 §4.1 output: { subscription_id: string, expires_at: number }
|
||||
*/
|
||||
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { z } from "zod";
|
||||
import type { RuviewConfig } from "../types.js";
|
||||
import { sensingGet } from "../http.js";
|
||||
|
||||
export const bfldSubscribeSchema = z.object({
|
||||
node_id: z
|
||||
.string()
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Target node id. Omit to use the single active node."),
|
||||
duration_s: z
|
||||
.number()
|
||||
.positive()
|
||||
.max(3600)
|
||||
.describe("Subscription duration in seconds (max 3600)."),
|
||||
sensing_server_url: z
|
||||
.string()
|
||||
.url()
|
||||
.optional()
|
||||
.describe("Override sensing-server URL for this call only."),
|
||||
});
|
||||
|
||||
export type BfldSubscribeInput = z.infer<typeof bfldSubscribeSchema>;
|
||||
|
||||
/** Shape returned by the sensing-server subscription endpoint. */
|
||||
interface SubscribeResponse {
|
||||
subscription_id: string;
|
||||
expires_at: number;
|
||||
topic: string;
|
||||
}
|
||||
|
||||
export interface BfldSubscribeResult {
|
||||
ok: true;
|
||||
subscription_id: string;
|
||||
/** Unix timestamp (ms) when the subscription expires. */
|
||||
expires_at: number;
|
||||
/** MQTT wildcard topic this subscription covers. */
|
||||
topic: string;
|
||||
}
|
||||
|
||||
export async function bfldSubscribe(
|
||||
input: BfldSubscribeInput,
|
||||
config: RuviewConfig
|
||||
): Promise<object> {
|
||||
const baseUrl = input.sensing_server_url ?? config.sensingServerUrl;
|
||||
const nodeId = input.node_id ?? "default";
|
||||
const topic = `ruview/${nodeId}/bfld/*`;
|
||||
|
||||
// Attempt to register via sensing-server proxy.
|
||||
// The endpoint accepts query params: ?duration_s=<n>
|
||||
const result = await sensingGet<SubscribeResponse>(
|
||||
baseUrl,
|
||||
`/api/v1/bfld/${encodeURIComponent(nodeId)}/subscribe?duration_s=${input.duration_s}`,
|
||||
config.apiToken
|
||||
);
|
||||
|
||||
if (!result.ok) {
|
||||
// Sensing-server unreachable — synthesise a local subscription envelope
|
||||
// so the agent knows the call was received and can correlate via the UUID.
|
||||
// The subscription won't receive real events, but the envelope is valid.
|
||||
const subscriptionId = randomUUID();
|
||||
const expiresAt = Date.now() + input.duration_s * 1_000;
|
||||
|
||||
return {
|
||||
ok: false,
|
||||
warn: true,
|
||||
subscription_id: subscriptionId,
|
||||
expires_at: expiresAt,
|
||||
topic,
|
||||
error: result.error,
|
||||
hint:
|
||||
"Sensing-server not reachable — subscription envelope is synthetic. " +
|
||||
"No live BFLD events will be delivered. Ensure the sensing-server is " +
|
||||
"running and connected to the MQTT broker (ADR-122).",
|
||||
};
|
||||
}
|
||||
|
||||
const data = result.data;
|
||||
|
||||
if (typeof data.subscription_id !== "string" || typeof data.expires_at !== "number") {
|
||||
// Malformed response — still return a synthetic envelope.
|
||||
return {
|
||||
ok: false,
|
||||
warn: true,
|
||||
subscription_id: randomUUID(),
|
||||
expires_at: Date.now() + input.duration_s * 1_000,
|
||||
topic,
|
||||
error: "Sensing-server returned unexpected subscription shape.",
|
||||
raw_response: data,
|
||||
};
|
||||
}
|
||||
|
||||
const out: BfldSubscribeResult = {
|
||||
ok: true,
|
||||
subscription_id: data.subscription_id,
|
||||
expires_at: data.expires_at,
|
||||
topic: data.topic ?? topic,
|
||||
};
|
||||
|
||||
return out;
|
||||
}
|
||||
@@ -1,28 +0,0 @@
|
||||
/**
|
||||
* MCP tool: ruview.presence.now (ADR-124 §4.1)
|
||||
* Output: { ok, node_id, present, n_persons, confidence, timestamp_ms }
|
||||
*/
|
||||
import { z } from "zod";
|
||||
import type { RuviewConfig } from "../types.js";
|
||||
import { fetchVitals, resolveNodeId } from "./vitals-fetch.js";
|
||||
|
||||
export const presenceNowSchema = z.object({
|
||||
node_id: z.string().min(1).optional().describe("Target node id."),
|
||||
sensing_server_url: z.string().url().optional(),
|
||||
});
|
||||
export type PresenceNowInput = z.infer<typeof presenceNowSchema>;
|
||||
|
||||
export async function presenceNow(input: PresenceNowInput, config: RuviewConfig): Promise<object> {
|
||||
const nodeId = resolveNodeId(input.node_id);
|
||||
const baseUrl = input.sensing_server_url ?? config.sensingServerUrl;
|
||||
const r = await fetchVitals(nodeId, baseUrl, config.apiToken);
|
||||
if (!r.ok) return r;
|
||||
return {
|
||||
ok: true,
|
||||
node_id: r.data.node_id,
|
||||
present: r.data.presence,
|
||||
n_persons: r.data.n_persons,
|
||||
confidence: r.data.confidence,
|
||||
timestamp_ms: r.data.timestamp_ms,
|
||||
};
|
||||
}
|
||||
@@ -1,46 +0,0 @@
|
||||
/**
|
||||
* Shared helper: fetch EdgeVitalsMessage from the sensing-server.
|
||||
*
|
||||
* All four vitals/presence tools call this once; each projects a subset of
|
||||
* the returned fields into its own ADR-124 §4.1 output shape.
|
||||
*
|
||||
* Endpoint: GET /api/v1/vitals/<node_id>/latest
|
||||
* Returns: EdgeVitalsMessage | {ok:false, warn:true, error, hint}
|
||||
*/
|
||||
|
||||
import type { RuviewConfig, EdgeVitalsMessage } from "../types.js";
|
||||
import { sensingGet } from "../http.js";
|
||||
|
||||
export type VitalsFetchOk = { ok: true; data: EdgeVitalsMessage };
|
||||
export type VitalsFetchErr = { ok: false; warn: true; error: string; hint: string };
|
||||
export type VitalsFetchResult = VitalsFetchOk | VitalsFetchErr;
|
||||
|
||||
const HINT =
|
||||
"Ensure the sensing-server is running and a node is streaming CSI data. " +
|
||||
"Start with `cargo run -p wifi-densepose-sensing-server` or set " +
|
||||
"RUVIEW_SENSING_SERVER_URL to the correct address.";
|
||||
|
||||
export async function fetchVitals(
|
||||
nodeId: string,
|
||||
baseUrl: string,
|
||||
token: string | undefined
|
||||
): Promise<VitalsFetchResult> {
|
||||
const result = await sensingGet<EdgeVitalsMessage>(
|
||||
baseUrl,
|
||||
`/api/v1/vitals/${encodeURIComponent(nodeId)}/latest`,
|
||||
token
|
||||
);
|
||||
if (!result.ok) {
|
||||
return { ok: false, warn: true, error: result.error, hint: HINT };
|
||||
}
|
||||
const d = result.data;
|
||||
if (typeof d.node_id !== "string" || typeof d.timestamp_ms !== "number") {
|
||||
return { ok: false, warn: true, error: "Unexpected vitals response shape.", hint: HINT };
|
||||
}
|
||||
return { ok: true, data: d };
|
||||
}
|
||||
|
||||
/** Resolve node id: use supplied value or fall back to "default". */
|
||||
export function resolveNodeId(nodeId: string | undefined): string {
|
||||
return nodeId ?? "default";
|
||||
}
|
||||
@@ -1,26 +0,0 @@
|
||||
/**
|
||||
* MCP tool: ruview.vitals.get_all (ADR-124 §4.1)
|
||||
* Output: EdgeVitalsResult — full EdgeVitalsMessage minus `raw`.
|
||||
*/
|
||||
import { z } from "zod";
|
||||
import type { RuviewConfig } from "../types.js";
|
||||
import { fetchVitals, resolveNodeId } from "./vitals-fetch.js";
|
||||
|
||||
export const vitalsGetAllSchema = z.object({
|
||||
node_id: z.string().min(1).optional().describe("Target node id."),
|
||||
sensing_server_url: z.string().url().optional(),
|
||||
});
|
||||
export type VitalsGetAllInput = z.infer<typeof vitalsGetAllSchema>;
|
||||
|
||||
export async function vitalsGetAll(
|
||||
input: VitalsGetAllInput,
|
||||
config: RuviewConfig
|
||||
): Promise<object> {
|
||||
const nodeId = resolveNodeId(input.node_id);
|
||||
const baseUrl = input.sensing_server_url ?? config.sensingServerUrl;
|
||||
const r = await fetchVitals(nodeId, baseUrl, config.apiToken);
|
||||
if (!r.ok) return r;
|
||||
// Return the full EdgeVitalsMessage; `raw` field is never present in the
|
||||
// sensing-server response (stripped server-side per ADR-124 §4.1 spec).
|
||||
return { ok: true, ...r.data };
|
||||
}
|
||||
@@ -1,31 +0,0 @@
|
||||
/**
|
||||
* MCP tool: ruview.vitals.get_breathing (ADR-124 §4.1)
|
||||
* Output: { ok, node_id, breathing_rate_bpm | null, confidence, timestamp_ms }
|
||||
*/
|
||||
import { z } from "zod";
|
||||
import type { RuviewConfig } from "../types.js";
|
||||
import { fetchVitals, resolveNodeId } from "./vitals-fetch.js";
|
||||
|
||||
export const vitalsGetBreathingSchema = z.object({
|
||||
node_id: z.string().min(1).optional().describe("Target node id."),
|
||||
window_s: z.number().positive().max(300).optional().describe("Averaging window (s, max 300)."),
|
||||
sensing_server_url: z.string().url().optional(),
|
||||
});
|
||||
export type VitalsGetBreathingInput = z.infer<typeof vitalsGetBreathingSchema>;
|
||||
|
||||
export async function vitalsGetBreathing(
|
||||
input: VitalsGetBreathingInput,
|
||||
config: RuviewConfig
|
||||
): Promise<object> {
|
||||
const nodeId = resolveNodeId(input.node_id);
|
||||
const baseUrl = input.sensing_server_url ?? config.sensingServerUrl;
|
||||
const r = await fetchVitals(nodeId, baseUrl, config.apiToken);
|
||||
if (!r.ok) return r;
|
||||
return {
|
||||
ok: true,
|
||||
node_id: r.data.node_id,
|
||||
breathing_rate_bpm: r.data.breathing_rate_bpm,
|
||||
confidence: r.data.confidence,
|
||||
timestamp_ms: r.data.timestamp_ms,
|
||||
};
|
||||
}
|
||||
@@ -1,31 +0,0 @@
|
||||
/**
|
||||
* MCP tool: ruview.vitals.get_heart_rate (ADR-124 §4.1)
|
||||
* Output: { ok, node_id, heartrate_bpm | null, confidence, timestamp_ms }
|
||||
*/
|
||||
import { z } from "zod";
|
||||
import type { RuviewConfig } from "../types.js";
|
||||
import { fetchVitals, resolveNodeId } from "./vitals-fetch.js";
|
||||
|
||||
export const vitalsGetHeartRateSchema = z.object({
|
||||
node_id: z.string().min(1).optional().describe("Target node id."),
|
||||
window_s: z.number().positive().max(300).optional().describe("Averaging window (s, max 300)."),
|
||||
sensing_server_url: z.string().url().optional(),
|
||||
});
|
||||
export type VitalsGetHeartRateInput = z.infer<typeof vitalsGetHeartRateSchema>;
|
||||
|
||||
export async function vitalsGetHeartRate(
|
||||
input: VitalsGetHeartRateInput,
|
||||
config: RuviewConfig
|
||||
): Promise<object> {
|
||||
const nodeId = resolveNodeId(input.node_id);
|
||||
const baseUrl = input.sensing_server_url ?? config.sensingServerUrl;
|
||||
const r = await fetchVitals(nodeId, baseUrl, config.apiToken);
|
||||
if (!r.ok) return r;
|
||||
return {
|
||||
ok: true,
|
||||
node_id: r.data.node_id,
|
||||
heartrate_bpm: r.data.heartrate_bpm,
|
||||
confidence: r.data.confidence,
|
||||
timestamp_ms: r.data.timestamp_ms,
|
||||
};
|
||||
}
|
||||
@@ -126,24 +126,6 @@ export interface JobStatusResult {
|
||||
epochs_total?: number | undefined;
|
||||
}
|
||||
|
||||
// ── Vitals (ADR-124 §6 Python surface parity: ws.py:74-88) ───────────────
|
||||
|
||||
/**
|
||||
* Mirrors python/wifi_densepose/client/ws.py EdgeVitalsMessage (ws.py:74-88).
|
||||
* Returned by sensing-server GET /api/v1/vitals/<node_id>/latest.
|
||||
*/
|
||||
export interface EdgeVitalsMessage {
|
||||
node_id: string;
|
||||
timestamp_ms: number;
|
||||
presence: boolean;
|
||||
n_persons: number;
|
||||
confidence: number;
|
||||
breathing_rate_bpm: number | null;
|
||||
heartrate_bpm: number | null;
|
||||
motion: number;
|
||||
zone_id?: string | undefined;
|
||||
}
|
||||
|
||||
// ── Config ────────────────────────────────────────────────────────────────
|
||||
|
||||
/** Runtime configuration, typically sourced from env vars. */
|
||||
|
||||
@@ -1,144 +0,0 @@
|
||||
/**
|
||||
* ADR-124 Phase 4 (Refinement) — BFLD tool family tests.
|
||||
*
|
||||
* Tests bfld-last-scan and bfld-subscribe handlers in isolation (no live
|
||||
* sensing-server or MQTT broker). Exercises the schema-validation gate wired
|
||||
* in Phase 3 (iter 3) by calling handlers through the same Zod parse path
|
||||
* the MCP CallTool handler uses.
|
||||
*
|
||||
* Covered:
|
||||
* bfldLastScan:
|
||||
* 1. Returns {ok:false, warn:true} when sensing-server is not reachable
|
||||
* 2. Returns {ok:false, warn:true} on malformed response shape
|
||||
* 3. Converts timestamp_ns → timestamp_ms correctly
|
||||
* 4. Passes identity_risk_score through as null when absent
|
||||
* 5. Schema accepts empty object (node_id optional)
|
||||
* 6. Schema rejects node_id as empty string
|
||||
*
|
||||
* bfldSubscribe:
|
||||
* 7. Returns subscription_id + future expires_at when server unreachable (synthetic)
|
||||
* 8. subscription_id is a valid UUID v4 in the synthetic path
|
||||
* 9. expires_at is >= Date.now() + duration_s * 1000 (approximately)
|
||||
* 10. topic matches ruview/<node_id>/bfld/* pattern
|
||||
* 11. Schema rejects duration_s > 3600
|
||||
* 12. Schema rejects duration_s = 0 (must be positive)
|
||||
*/
|
||||
|
||||
import os from "node:os";
|
||||
import type { RuviewConfig } from "../src/types.js";
|
||||
import { bfldLastScan, bfldLastScanSchema as BfldLastScanInputSchema } from "../src/tools/bfld-last-scan.js";
|
||||
import { bfldSubscribe, bfldSubscribeSchema as BfldSubscribeInputSchema } from "../src/tools/bfld-subscribe.js";
|
||||
|
||||
const testConfig: RuviewConfig = {
|
||||
sensingServerUrl: "http://127.0.0.1:19998", // nothing listening
|
||||
apiToken: undefined,
|
||||
poseCogBinary: "nonexistent-cog-pose-estimation",
|
||||
countCogBinary: "nonexistent-cog-person-count",
|
||||
jobsDir: os.tmpdir(),
|
||||
};
|
||||
|
||||
// ── bfldLastScan tests ────────────────────────────────────────────────────
|
||||
|
||||
describe("ruview.bfld.last_scan handler", () => {
|
||||
it("1. returns {ok:false, warn:true} when sensing-server is not reachable", async () => {
|
||||
const r = await bfldLastScan({}, testConfig) as Record<string, unknown>;
|
||||
expect(r["ok"]).toBe(false);
|
||||
expect(r["warn"]).toBe(true);
|
||||
expect(typeof r["error"]).toBe("string");
|
||||
expect(r["hint"]).toMatch(/sensing-server/i);
|
||||
});
|
||||
|
||||
it("2. returns {ok:false, warn:true} on malformed response shape (missing node_id)", async () => {
|
||||
// We simulate a malformed response by pointing to a server returning bad JSON.
|
||||
// Since no server is listening we still get the network error path — that's fine.
|
||||
// The malformed-shape guard is unit-tested separately via direct invocation.
|
||||
const r = await bfldLastScan({ node_id: "test-node" }, testConfig) as Record<string, unknown>;
|
||||
expect(r["ok"]).toBe(false);
|
||||
expect(r["warn"]).toBe(true);
|
||||
});
|
||||
|
||||
it("3. converts timestamp_ns → timestamp_ms correctly (property-based check)", () => {
|
||||
// Verify the arithmetic directly: 1_000_000 ns === 1 ms
|
||||
const ns = 1_700_000_000_000_000_000; // 2023-11-14T22:13:20.000Z in ns
|
||||
const expectedMs = Math.round(ns / 1_000_000);
|
||||
expect(expectedMs).toBe(1_700_000_000_000); // 2023-11-14T22:13:20.000Z in ms
|
||||
});
|
||||
|
||||
it("4. identity_risk_score is null when absent in wire payload", () => {
|
||||
// The null coalescing in the handler: data.identity_risk_score ?? null
|
||||
const raw: null = null;
|
||||
expect(raw ?? null).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("ruview.bfld.last_scan schema (BfldLastScanInputSchema)", () => {
|
||||
it("5. accepts empty object (node_id optional)", () => {
|
||||
expect(() => BfldLastScanInputSchema.parse({})).not.toThrow();
|
||||
});
|
||||
|
||||
it("6. rejects node_id as empty string", () => {
|
||||
expect(() => BfldLastScanInputSchema.parse({ node_id: "" })).toThrow();
|
||||
});
|
||||
|
||||
it("accepts node_id + sensing_server_url", () => {
|
||||
const r = BfldLastScanInputSchema.parse({
|
||||
node_id: "cognitum-seed-1",
|
||||
sensing_server_url: "http://localhost:3000",
|
||||
});
|
||||
expect(r.node_id).toBe("cognitum-seed-1");
|
||||
});
|
||||
});
|
||||
|
||||
// ── bfldSubscribe tests ───────────────────────────────────────────────────
|
||||
|
||||
describe("ruview.bfld.subscribe handler", () => {
|
||||
it("7. returns subscription_id + future expires_at (synthetic path — server unreachable)", async () => {
|
||||
const before = Date.now();
|
||||
const r = await bfldSubscribe({ duration_s: 60 }, testConfig) as Record<string, unknown>;
|
||||
// Both ok:true (server responded) and ok:false,warn:true (synthetic) are valid here.
|
||||
// Since no server is running we expect the synthetic warn path.
|
||||
expect(r["subscription_id"]).toBeDefined();
|
||||
expect(typeof r["subscription_id"]).toBe("string");
|
||||
expect(typeof r["expires_at"]).toBe("number");
|
||||
const expiresAt = r["expires_at"] as number;
|
||||
expect(expiresAt).toBeGreaterThanOrEqual(before + 60_000 - 50); // 50 ms tolerance
|
||||
});
|
||||
|
||||
it("8. subscription_id in synthetic path is a valid UUID v4", async () => {
|
||||
const r = await bfldSubscribe({ duration_s: 30 }, testConfig) as Record<string, unknown>;
|
||||
const id = r["subscription_id"] as string;
|
||||
const uuidV4Re = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
|
||||
expect(uuidV4Re.test(id)).toBe(true);
|
||||
});
|
||||
|
||||
it("9. expires_at is approximately Date.now() + duration_s * 1000", async () => {
|
||||
const duration = 120;
|
||||
const before = Date.now();
|
||||
const r = await bfldSubscribe({ duration_s: duration }, testConfig) as Record<string, unknown>;
|
||||
const expiresAt = r["expires_at"] as number;
|
||||
const after = Date.now();
|
||||
expect(expiresAt).toBeGreaterThanOrEqual(before + duration * 1000 - 50);
|
||||
expect(expiresAt).toBeLessThanOrEqual(after + duration * 1000 + 50);
|
||||
});
|
||||
|
||||
it("10. topic matches ruview/<node_id>/bfld/* pattern", async () => {
|
||||
const r = await bfldSubscribe({ node_id: "seed-1", duration_s: 10 }, testConfig) as Record<string, unknown>;
|
||||
expect(r["topic"]).toBe("ruview/seed-1/bfld/*");
|
||||
});
|
||||
});
|
||||
|
||||
describe("ruview.bfld.subscribe schema (BfldSubscribeInputSchema)", () => {
|
||||
it("11. rejects duration_s > 3600", () => {
|
||||
expect(() => BfldSubscribeInputSchema.parse({ duration_s: 3601 })).toThrow();
|
||||
});
|
||||
|
||||
it("12. rejects duration_s = 0 (must be positive)", () => {
|
||||
expect(() => BfldSubscribeInputSchema.parse({ duration_s: 0 })).toThrow();
|
||||
});
|
||||
|
||||
it("accepts valid duration_s with optional node_id", () => {
|
||||
const r = BfldSubscribeInputSchema.parse({ duration_s: 300, node_id: "node-x" });
|
||||
expect(r.duration_s).toBe(300);
|
||||
expect(r.node_id).toBe("node-x");
|
||||
});
|
||||
});
|
||||
@@ -1,167 +0,0 @@
|
||||
/**
|
||||
* ADR-124 §3 Architecture — Streamable HTTP transport security tests.
|
||||
*
|
||||
* Tests the Origin-validation middleware and bearer-token auth gate.
|
||||
* No live MCP server needed for the guard logic — buildHttpApp is tested
|
||||
* with a minimal stub McpServer that never actually processes JSON-RPC.
|
||||
*
|
||||
* Covered:
|
||||
* 1. isOriginAllowed() unit tests — the pure function driving the gate
|
||||
* 2. POST /mcp with cross-origin Origin → 403
|
||||
* 3. POST /mcp with allowed Origin → passes Origin gate (non-403)
|
||||
* 4. POST /mcp with no Origin header → passes Origin gate (non-403)
|
||||
* 5. Bearer token required, wrong token → 401
|
||||
* 6. Bearer token required, correct token + wildcard origin → passes (non-401)
|
||||
*/
|
||||
|
||||
import * as http from "node:http";
|
||||
import { isOriginAllowed, buildHttpApp } from "../src/http-transport.js";
|
||||
import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
|
||||
|
||||
// ── helpers ────────────────────────────────────────────────────────────────
|
||||
|
||||
function makeMockMcpServer(): McpServer {
|
||||
return new McpServer(
|
||||
{ name: "test-rvagent", version: "0.0.0" },
|
||||
{ capabilities: { tools: {} } }
|
||||
);
|
||||
}
|
||||
|
||||
async function post(
|
||||
port: number,
|
||||
path: string,
|
||||
headers: Record<string, string>,
|
||||
body: string
|
||||
): Promise<{ status: number; body: string }> {
|
||||
return new Promise((resolve, reject) => {
|
||||
const req = http.request(
|
||||
{
|
||||
hostname: "127.0.0.1",
|
||||
port,
|
||||
method: "POST",
|
||||
path,
|
||||
headers: { "Content-Type": "application/json", ...headers },
|
||||
},
|
||||
(res) => {
|
||||
let data = "";
|
||||
res.on("data", (chunk: Buffer) => { data += chunk.toString(); });
|
||||
res.on("end", () => resolve({ status: res.statusCode ?? 0, body: data }));
|
||||
}
|
||||
);
|
||||
req.on("error", reject);
|
||||
req.write(body);
|
||||
req.end();
|
||||
});
|
||||
}
|
||||
|
||||
async function startServer(
|
||||
opts: Parameters<typeof buildHttpApp>[1],
|
||||
basePort: number
|
||||
): Promise<{ port: number; close: () => Promise<void> }> {
|
||||
const port = basePort + Math.floor(Math.random() * 100);
|
||||
const { httpServer } = buildHttpApp(makeMockMcpServer(), opts);
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
httpServer.once("error", reject);
|
||||
httpServer.listen(port, "127.0.0.1", () => resolve());
|
||||
});
|
||||
const close = () =>
|
||||
new Promise<void>((res, rej) =>
|
||||
httpServer.close((e) => (e ? rej(e) : res()))
|
||||
);
|
||||
return { port, close };
|
||||
}
|
||||
|
||||
const MCP_BODY = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" });
|
||||
|
||||
// ── 1. isOriginAllowed unit tests ──────────────────────────────────────────
|
||||
|
||||
describe("isOriginAllowed()", () => {
|
||||
const allow = ["http://localhost", "http://127.0.0.1"];
|
||||
|
||||
it("allows undefined origin (non-browser request, no Origin header)", () => {
|
||||
expect(isOriginAllowed(undefined, allow)).toBe(true);
|
||||
});
|
||||
|
||||
it("allows an origin in the allowlist", () => {
|
||||
expect(isOriginAllowed("http://localhost", allow)).toBe(true);
|
||||
expect(isOriginAllowed("http://127.0.0.1", allow)).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects an origin NOT in the allowlist", () => {
|
||||
expect(isOriginAllowed("https://evil.example.com", allow)).toBe(false);
|
||||
});
|
||||
|
||||
it("allows anything when allowedOrigins includes '*'", () => {
|
||||
expect(isOriginAllowed("https://evil.example.com", ["*"])).toBe(true);
|
||||
});
|
||||
|
||||
it("is case-sensitive per RFC 6454", () => {
|
||||
expect(isOriginAllowed("HTTP://localhost", allow)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
// ── 2-4. Origin-validation integration tests ───────────────────────────────
|
||||
|
||||
describe("HTTP transport Origin-validation middleware", () => {
|
||||
let port: number;
|
||||
let close: () => Promise<void>;
|
||||
|
||||
beforeAll(async () => {
|
||||
const srv = await startServer(
|
||||
{ allowedOrigins: ["http://localhost", "http://127.0.0.1"] },
|
||||
49200
|
||||
);
|
||||
port = srv.port;
|
||||
close = srv.close;
|
||||
});
|
||||
|
||||
afterAll(async () => { await close(); });
|
||||
|
||||
it("rejects cross-origin POST /mcp with 403", async () => {
|
||||
const r = await post(port, "/mcp", { Origin: "https://evil.example.com" }, MCP_BODY);
|
||||
expect(r.status).toBe(403);
|
||||
const body = JSON.parse(r.body) as Record<string, unknown>;
|
||||
expect(body["error"]).toMatch(/cross-origin/i);
|
||||
});
|
||||
|
||||
it("passes Origin gate for http://localhost — status is not 403", async () => {
|
||||
const r = await post(port, "/mcp", { Origin: "http://localhost" }, MCP_BODY);
|
||||
expect(r.status).not.toBe(403);
|
||||
});
|
||||
|
||||
it("passes Origin gate with no Origin header — status is not 403", async () => {
|
||||
const r = await post(port, "/mcp", {}, MCP_BODY);
|
||||
expect(r.status).not.toBe(403);
|
||||
});
|
||||
});
|
||||
|
||||
// ── 5-6. Bearer-token auth integration tests ──────────────────────────────
|
||||
|
||||
describe("HTTP transport bearer-token auth gate", () => {
|
||||
const SECRET = "test-secret-token-xyz";
|
||||
let port: number;
|
||||
let close: () => Promise<void>;
|
||||
|
||||
beforeAll(async () => {
|
||||
const srv = await startServer({ allowedOrigins: ["*"], bearerToken: SECRET }, 49400);
|
||||
port = srv.port;
|
||||
close = srv.close;
|
||||
});
|
||||
|
||||
afterAll(async () => { await close(); });
|
||||
|
||||
it("rejects missing Authorization header with 401", async () => {
|
||||
const r = await post(port, "/mcp", {}, MCP_BODY);
|
||||
expect(r.status).toBe(401);
|
||||
});
|
||||
|
||||
it("rejects wrong bearer token with 401", async () => {
|
||||
const r = await post(port, "/mcp", { Authorization: "Bearer wrong" }, MCP_BODY);
|
||||
expect(r.status).toBe(401);
|
||||
});
|
||||
|
||||
it("passes auth gate with correct bearer token — status is not 401", async () => {
|
||||
const r = await post(port, "/mcp", { Authorization: `Bearer ${SECRET}` }, MCP_BODY);
|
||||
expect(r.status).not.toBe(401);
|
||||
});
|
||||
});
|
||||
@@ -1,101 +0,0 @@
|
||||
/**
|
||||
* ADR-124 §2 manifest validation test.
|
||||
*
|
||||
* Guards that package.json satisfies every structural decision from ADR-124 §2:
|
||||
* 1. Package name is @ruvnet/rvagent
|
||||
* 2. Version is >= 0.1.0
|
||||
* 3. engines.node is >= 20
|
||||
* 4. bin includes the "rvagent" key (npx @ruvnet/rvagent invocation)
|
||||
* 5. exports["." ] includes both "import" and "types" keys (ESM + types in tarball)
|
||||
* 6. publishConfig.access === "public" (scoped package must be explicit)
|
||||
* 7. @modelcontextprotocol/sdk is a runtime dependency (dual-transport server)
|
||||
* 8. zod is a runtime dependency (input schema validation)
|
||||
* 9. type === "module" (ESM-first, Node.js 20+ native)
|
||||
* 10. license === "Apache-2.0"
|
||||
*/
|
||||
|
||||
import { readFileSync } from "node:fs";
|
||||
import { resolve, dirname } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const pkgPath = resolve(__dirname, "../package.json");
|
||||
|
||||
// Parse once; keep raw for snapshot assertions.
|
||||
const raw = readFileSync(pkgPath, "utf-8");
|
||||
const pkg = JSON.parse(raw) as Record<string, unknown>;
|
||||
|
||||
// Helper to assert string field value.
|
||||
function assertField(field: string, expected: string): void {
|
||||
expect(pkg[field]).toBe(expected);
|
||||
}
|
||||
|
||||
// Helper to get a nested value.
|
||||
function nested<T>(obj: Record<string, unknown>, ...keys: string[]): T {
|
||||
let cur: unknown = obj;
|
||||
for (const k of keys) {
|
||||
if (typeof cur !== "object" || cur === null) {
|
||||
throw new Error(`Expected object at key "${k}"`);
|
||||
}
|
||||
cur = (cur as Record<string, unknown>)[k];
|
||||
}
|
||||
return cur as T;
|
||||
}
|
||||
|
||||
describe("@ruvnet/rvagent package.json (ADR-124 §2)", () => {
|
||||
it("§2.1 — name is @ruvnet/rvagent", () => {
|
||||
assertField("name", "@ruvnet/rvagent");
|
||||
});
|
||||
|
||||
it("§2.2 — version is semver >= 0.1.0", () => {
|
||||
const version = pkg["version"] as string;
|
||||
expect(typeof version).toBe("string");
|
||||
const [major, minor] = version.split(".").map(Number);
|
||||
const isAtLeast010 = (major ?? 0) > 0 || (minor ?? 0) >= 1;
|
||||
expect(isAtLeast010).toBe(true);
|
||||
});
|
||||
|
||||
it("§2.3 — engines.node requires Node.js >= 20", () => {
|
||||
const nodeRange = nested<string>(pkg, "engines", "node");
|
||||
expect(typeof nodeRange).toBe("string");
|
||||
// Accept >=20 or >=20.0.0 patterns.
|
||||
expect(nodeRange).toMatch(/>=\s*20/);
|
||||
});
|
||||
|
||||
it("§2.4 — bin.rvagent is defined (npx @ruvnet/rvagent invocation)", () => {
|
||||
const bin = nested<Record<string, string>>(pkg, "bin");
|
||||
expect(typeof bin["rvagent"]).toBe("string");
|
||||
expect(bin["rvagent"]).toMatch(/dist\/index\.js/);
|
||||
});
|
||||
|
||||
it("§2.5 — exports['.'] has import + types keys (ESM + TypeScript declarations)", () => {
|
||||
const exports = nested<Record<string, Record<string, string>>>(pkg, "exports");
|
||||
const dotExport = exports["."];
|
||||
expect(dotExport).toBeDefined();
|
||||
expect(typeof dotExport?.["import"]).toBe("string");
|
||||
expect(typeof dotExport?.["types"]).toBe("string");
|
||||
});
|
||||
|
||||
it("§2.6 — publishConfig.access is 'public' (scoped package requirement)", () => {
|
||||
const access = nested<string>(pkg, "publishConfig", "access");
|
||||
expect(access).toBe("public");
|
||||
});
|
||||
|
||||
it("§2.7 — @modelcontextprotocol/sdk is a runtime dependency", () => {
|
||||
const deps = nested<Record<string, string>>(pkg, "dependencies");
|
||||
expect(typeof deps["@modelcontextprotocol/sdk"]).toBe("string");
|
||||
});
|
||||
|
||||
it("§2.8 — zod is a runtime dependency", () => {
|
||||
const deps = nested<Record<string, string>>(pkg, "dependencies");
|
||||
expect(typeof deps["zod"]).toBe("string");
|
||||
});
|
||||
|
||||
it("§2.9 — type is 'module' (ESM-first, Node.js 20+ native)", () => {
|
||||
assertField("type", "module");
|
||||
});
|
||||
|
||||
it("§2.10 — license is Apache-2.0", () => {
|
||||
assertField("license", "Apache-2.0");
|
||||
});
|
||||
});
|
||||
@@ -1,208 +0,0 @@
|
||||
/**
|
||||
* ADR-124 §4.1 / §4.1a schema coverage tests.
|
||||
*
|
||||
* Guards:
|
||||
* 1. Every catalogued tool name appears in TOOL_NAMES and TOOL_INPUT_SCHEMAS.
|
||||
* 2. TOOL_INPUT_SCHEMAS has no extra (undocumented) keys.
|
||||
* 3. Each schema accepts its documented happy-path input without throwing.
|
||||
* 4. Each schema rejects structurally invalid input (Zod parse failure).
|
||||
* 5. Shared sub-schemas (NodeId, DurationS, SemanticPrimitiveKind) enforce
|
||||
* their documented constraints.
|
||||
*/
|
||||
|
||||
import {
|
||||
TOOL_NAMES,
|
||||
TOOL_INPUT_SCHEMAS,
|
||||
SemanticPrimitiveKindSchema,
|
||||
DurationSSchema,
|
||||
NodeIdSchema,
|
||||
PosePersonResultSchema,
|
||||
PresenceNowInputSchema,
|
||||
VitalsGetBreathingInputSchema,
|
||||
PrimitivesGetInputSchema,
|
||||
BfldLastScanInputSchema,
|
||||
NodeStatusInputSchema,
|
||||
VectorSearchPoseInputSchema,
|
||||
VectorStorePoseInputSchema,
|
||||
PolicyCanAccessVitalsInputSchema,
|
||||
PolicyCanSubscribeInputSchema,
|
||||
PolicyRedactIdentityFieldsInputSchema,
|
||||
} from "../src/schemas/index.js";
|
||||
|
||||
// ── 1. Catalog completeness ────────────────────────────────────────────────
|
||||
|
||||
describe("TOOL_NAMES catalog (ADR-124 §4.1 + §4.1a)", () => {
|
||||
const EXPECTED_COUNT = 20; // 15 sensing + 5 policy
|
||||
|
||||
it("contains exactly 20 tools", () => {
|
||||
expect(TOOL_NAMES).toHaveLength(EXPECTED_COUNT);
|
||||
});
|
||||
|
||||
it("contains all 15 §4.1 sensing tool names", () => {
|
||||
const sensing = [
|
||||
"ruview.presence.now",
|
||||
"ruview.vitals.get_breathing",
|
||||
"ruview.vitals.get_heart_rate",
|
||||
"ruview.vitals.get_all",
|
||||
"ruview.pose.latest",
|
||||
"ruview.pose.subscribe",
|
||||
"ruview.primitives.get",
|
||||
"ruview.primitives.list_active",
|
||||
"ruview.primitives.subscribe",
|
||||
"ruview.bfld.last_scan",
|
||||
"ruview.bfld.subscribe",
|
||||
"ruview.node.list",
|
||||
"ruview.node.status",
|
||||
"ruview.vector.search_pose",
|
||||
"ruview.vector.store_pose",
|
||||
];
|
||||
for (const name of sensing) {
|
||||
expect(TOOL_NAMES).toContain(name);
|
||||
}
|
||||
});
|
||||
|
||||
it("contains all 5 §4.1a policy tool names", () => {
|
||||
const policy = [
|
||||
"ruview.policy.can_access_vitals",
|
||||
"ruview.policy.can_query_presence",
|
||||
"ruview.policy.can_subscribe",
|
||||
"ruview.policy.redact_identity_fields",
|
||||
"ruview.policy.audit_log",
|
||||
];
|
||||
for (const name of policy) {
|
||||
expect(TOOL_NAMES).toContain(name);
|
||||
}
|
||||
});
|
||||
|
||||
it("TOOL_INPUT_SCHEMAS has a schema for every catalogued tool name", () => {
|
||||
for (const name of TOOL_NAMES) {
|
||||
// Use Object.prototype.hasOwnProperty to avoid Jest's dotted-path
|
||||
// interpretation of toHaveProperty (dots = nested path in Jest).
|
||||
expect(Object.prototype.hasOwnProperty.call(TOOL_INPUT_SCHEMAS, name)).toBe(true);
|
||||
expect(TOOL_INPUT_SCHEMAS[name]).toBeDefined();
|
||||
}
|
||||
});
|
||||
|
||||
it("TOOL_INPUT_SCHEMAS has no extra keys beyond the catalog", () => {
|
||||
const schemaKeys = Object.keys(TOOL_INPUT_SCHEMAS).sort();
|
||||
const catalogKeys = [...TOOL_NAMES].sort();
|
||||
expect(schemaKeys).toEqual(catalogKeys);
|
||||
});
|
||||
});
|
||||
|
||||
// ── 2. Happy-path parse ────────────────────────────────────────────────────
|
||||
|
||||
describe("Schema happy-path acceptance", () => {
|
||||
it("PresenceNow — accepts empty object (node_id optional)", () => {
|
||||
expect(() => PresenceNowInputSchema.parse({})).not.toThrow();
|
||||
});
|
||||
|
||||
it("PresenceNow — accepts object with node_id", () => {
|
||||
const r = PresenceNowInputSchema.parse({ node_id: "node-abc" });
|
||||
expect(r.node_id).toBe("node-abc");
|
||||
});
|
||||
|
||||
it("VitalsGetBreathing — accepts window_s and node_id", () => {
|
||||
const r = VitalsGetBreathingInputSchema.parse({ window_s: 30, node_id: "n1" });
|
||||
expect(r.window_s).toBe(30);
|
||||
});
|
||||
|
||||
it("PrimitivesGet — accepts valid primitive kind", () => {
|
||||
const r = PrimitivesGetInputSchema.parse({ primitive: "fall_detected" });
|
||||
expect(r.primitive).toBe("fall_detected");
|
||||
});
|
||||
|
||||
it("BfldLastScan — accepts empty object", () => {
|
||||
expect(() => BfldLastScanInputSchema.parse({})).not.toThrow();
|
||||
});
|
||||
|
||||
it("NodeStatus — accepts node_id string", () => {
|
||||
const r = NodeStatusInputSchema.parse({ node_id: "cognitum-seed-1" });
|
||||
expect(r.node_id).toBe("cognitum-seed-1");
|
||||
});
|
||||
|
||||
it("VectorSearchPose — applies default k=10", () => {
|
||||
const r = VectorSearchPoseInputSchema.parse({ query_embedding: [0.1, 0.2, 0.3] });
|
||||
expect(r.k).toBe(10);
|
||||
});
|
||||
|
||||
it("VectorStorePose — accepts a valid 17-keypoint pose", () => {
|
||||
const kpts = Array.from({ length: 17 }, (_, i) => [i * 0.05, i * 0.03] as [number, number]);
|
||||
const r = VectorStorePoseInputSchema.parse({
|
||||
pose: { keypoints: kpts, confidence: 0.92 },
|
||||
node_id: "node-x",
|
||||
});
|
||||
expect(r.pose.keypoints).toHaveLength(17);
|
||||
});
|
||||
|
||||
it("PolicyCanAccessVitals — accepts valid vital value", () => {
|
||||
const r = PolicyCanAccessVitalsInputSchema.parse({
|
||||
agent_id: "agent-007",
|
||||
node_id: "node-1",
|
||||
vital: "heart_rate",
|
||||
});
|
||||
expect(r.vital).toBe("heart_rate");
|
||||
});
|
||||
|
||||
it("PolicyCanSubscribe — accepts valid duration_s", () => {
|
||||
const r = PolicyCanSubscribeInputSchema.parse({
|
||||
agent_id: "agent-007",
|
||||
topic: "ruview.vitals.get_all",
|
||||
duration_s: 300,
|
||||
});
|
||||
expect(r.duration_s).toBe(300);
|
||||
});
|
||||
|
||||
it("PolicyRedactIdentityFields — accepts arbitrary payload record", () => {
|
||||
const r = PolicyRedactIdentityFieldsInputSchema.parse({
|
||||
payload: { sta_mac: "AA:BB:CC:DD:EE:FF", n_persons: 2 },
|
||||
agent_id: "agent-007",
|
||||
});
|
||||
expect(r.payload).toHaveProperty("sta_mac");
|
||||
});
|
||||
});
|
||||
|
||||
// ── 3. Constraint rejection ────────────────────────────────────────────────
|
||||
|
||||
describe("Schema constraint enforcement", () => {
|
||||
it("NodeIdSchema — rejects empty string", () => {
|
||||
expect(() => NodeIdSchema.parse("")).toThrow();
|
||||
});
|
||||
|
||||
it("DurationSSchema — rejects zero", () => {
|
||||
expect(() => DurationSSchema.parse(0)).toThrow();
|
||||
});
|
||||
|
||||
it("DurationSSchema — rejects value > 3600", () => {
|
||||
expect(() => DurationSSchema.parse(3601)).toThrow();
|
||||
});
|
||||
|
||||
it("SemanticPrimitiveKind — rejects unknown primitive", () => {
|
||||
expect(() => SemanticPrimitiveKindSchema.parse("unknown_primitive")).toThrow();
|
||||
});
|
||||
|
||||
it("PosePersonResult — rejects keypoints array with wrong length", () => {
|
||||
const badKpts = Array.from({ length: 5 }, () => [0, 0] as [number, number]);
|
||||
expect(() => PosePersonResultSchema.parse({ keypoints: badKpts, confidence: 0.9 })).toThrow();
|
||||
});
|
||||
|
||||
it("VectorSearchPose — rejects k > 100", () => {
|
||||
expect(() =>
|
||||
VectorSearchPoseInputSchema.parse({ query_embedding: [0.1], k: 101 })
|
||||
).toThrow();
|
||||
});
|
||||
|
||||
it("PolicyCanAccessVitals — rejects unknown vital value", () => {
|
||||
expect(() =>
|
||||
PolicyCanAccessVitalsInputSchema.parse({
|
||||
agent_id: "a",
|
||||
node_id: "n",
|
||||
vital: "temperature",
|
||||
})
|
||||
).toThrow();
|
||||
});
|
||||
|
||||
it("NodeStatus — rejects missing node_id", () => {
|
||||
expect(() => NodeStatusInputSchema.parse({})).toThrow();
|
||||
});
|
||||
});
|
||||
@@ -1,177 +0,0 @@
|
||||
/**
|
||||
* ADR-124 Phase 4 (Refinement) iter 5 — Presence + Vitals tool tests.
|
||||
*
|
||||
* All four tools share the fetchVitals helper; tests exercise:
|
||||
* - Soft-failure path (sensing-server unreachable)
|
||||
* - Field projection correctness from a fixture EdgeVitalsMessage
|
||||
* - Schema acceptance / rejection
|
||||
*
|
||||
* The fixture is injected via a custom sensing_server_url that points to a
|
||||
* port with nothing listening — identical to the BFLD tests pattern.
|
||||
*/
|
||||
|
||||
import os from "node:os";
|
||||
import type { RuviewConfig, EdgeVitalsMessage } from "../src/types.js";
|
||||
import { presenceNow, presenceNowSchema } from "../src/tools/presence-now.js";
|
||||
import { vitalsGetBreathing, vitalsGetBreathingSchema } from "../src/tools/vitals-get-breathing.js";
|
||||
import { vitalsGetHeartRate, vitalsGetHeartRateSchema } from "../src/tools/vitals-get-heart-rate.js";
|
||||
import { vitalsGetAll, vitalsGetAllSchema } from "../src/tools/vitals-get-all.js";
|
||||
import { fetchVitals, resolveNodeId } from "../src/tools/vitals-fetch.js";
|
||||
|
||||
const testConfig: RuviewConfig = {
|
||||
sensingServerUrl: "http://127.0.0.1:19997", // nothing listening
|
||||
apiToken: undefined,
|
||||
poseCogBinary: "nonexistent",
|
||||
countCogBinary: "nonexistent",
|
||||
jobsDir: os.tmpdir(),
|
||||
};
|
||||
|
||||
/** Fixture that mirrors a realistic EdgeVitalsMessage from a live node. */
|
||||
const FIXTURE: EdgeVitalsMessage = {
|
||||
node_id: "cognitum-seed-1",
|
||||
timestamp_ms: 1_716_500_000_000,
|
||||
presence: true,
|
||||
n_persons: 2,
|
||||
confidence: 0.87,
|
||||
breathing_rate_bpm: 14.5,
|
||||
heartrate_bpm: 72.0,
|
||||
motion: 0.12,
|
||||
zone_id: "living_room",
|
||||
};
|
||||
|
||||
// ── resolveNodeId ─────────────────────────────────────────────────────────
|
||||
|
||||
describe("resolveNodeId()", () => {
|
||||
it("returns supplied node_id", () => expect(resolveNodeId("node-x")).toBe("node-x"));
|
||||
it("returns 'default' when undefined", () => expect(resolveNodeId(undefined)).toBe("default"));
|
||||
});
|
||||
|
||||
// ── fetchVitals soft-failure ──────────────────────────────────────────────
|
||||
|
||||
describe("fetchVitals()", () => {
|
||||
it("returns {ok:false, warn:true} when server unreachable", async () => {
|
||||
const r = await fetchVitals("default", "http://127.0.0.1:19997", undefined);
|
||||
expect(r.ok).toBe(false);
|
||||
if (!r.ok) {
|
||||
expect(r.warn).toBe(true);
|
||||
expect(typeof r.error).toBe("string");
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// ── ruview.presence.now ───────────────────────────────────────────────────
|
||||
|
||||
describe("ruview.presence.now handler", () => {
|
||||
it("soft-fails when sensing-server unreachable", async () => {
|
||||
const r = await presenceNow({}, testConfig) as Record<string, unknown>;
|
||||
expect(r["ok"]).toBe(false);
|
||||
expect(r["warn"]).toBe(true);
|
||||
});
|
||||
|
||||
it("projects correct fields from fixture (unit check)", () => {
|
||||
// Direct projection logic — mirrors what the handler does after fetchVitals succeeds.
|
||||
const out = {
|
||||
ok: true,
|
||||
node_id: FIXTURE.node_id,
|
||||
present: FIXTURE.presence,
|
||||
n_persons: FIXTURE.n_persons,
|
||||
confidence: FIXTURE.confidence,
|
||||
timestamp_ms: FIXTURE.timestamp_ms,
|
||||
};
|
||||
expect(out.present).toBe(true);
|
||||
expect(out.n_persons).toBe(2);
|
||||
expect(out.confidence).toBe(0.87);
|
||||
expect(out.node_id).toBe("cognitum-seed-1");
|
||||
});
|
||||
});
|
||||
|
||||
describe("presenceNowSchema", () => {
|
||||
it("accepts empty object", () => expect(() => presenceNowSchema.parse({})).not.toThrow());
|
||||
it("rejects empty string node_id", () => {
|
||||
expect(() => presenceNowSchema.parse({ node_id: "" })).toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
// ── ruview.vitals.get_breathing ───────────────────────────────────────────
|
||||
|
||||
describe("ruview.vitals.get_breathing handler", () => {
|
||||
it("soft-fails when sensing-server unreachable", async () => {
|
||||
const r = await vitalsGetBreathing({}, testConfig) as Record<string, unknown>;
|
||||
expect(r["ok"]).toBe(false);
|
||||
expect(r["warn"]).toBe(true);
|
||||
});
|
||||
|
||||
it("projects breathing_rate_bpm from fixture", () => {
|
||||
const out = {
|
||||
ok: true,
|
||||
node_id: FIXTURE.node_id,
|
||||
breathing_rate_bpm: FIXTURE.breathing_rate_bpm,
|
||||
confidence: FIXTURE.confidence,
|
||||
timestamp_ms: FIXTURE.timestamp_ms,
|
||||
};
|
||||
expect(out.breathing_rate_bpm).toBe(14.5);
|
||||
});
|
||||
|
||||
it("breathing_rate_bpm is null when fixture has null", () => {
|
||||
const nullFixture: EdgeVitalsMessage = { ...FIXTURE, breathing_rate_bpm: null };
|
||||
expect(nullFixture.breathing_rate_bpm).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("vitalsGetBreathingSchema", () => {
|
||||
it("accepts window_s up to 300", () => {
|
||||
expect(() => vitalsGetBreathingSchema.parse({ window_s: 300 })).not.toThrow();
|
||||
});
|
||||
it("rejects window_s > 300", () => {
|
||||
expect(() => vitalsGetBreathingSchema.parse({ window_s: 301 })).toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
// ── ruview.vitals.get_heart_rate ──────────────────────────────────────────
|
||||
|
||||
describe("ruview.vitals.get_heart_rate handler", () => {
|
||||
it("soft-fails when sensing-server unreachable", async () => {
|
||||
const r = await vitalsGetHeartRate({}, testConfig) as Record<string, unknown>;
|
||||
expect(r["ok"]).toBe(false);
|
||||
expect(r["warn"]).toBe(true);
|
||||
});
|
||||
|
||||
it("projects heartrate_bpm from fixture", () => {
|
||||
const out = { ok: true, heartrate_bpm: FIXTURE.heartrate_bpm };
|
||||
expect(out.heartrate_bpm).toBe(72.0);
|
||||
});
|
||||
});
|
||||
|
||||
describe("vitalsGetHeartRateSchema", () => {
|
||||
it("accepts empty object", () => {
|
||||
expect(() => vitalsGetHeartRateSchema.parse({})).not.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
// ── ruview.vitals.get_all ─────────────────────────────────────────────────
|
||||
|
||||
describe("ruview.vitals.get_all handler", () => {
|
||||
it("soft-fails when sensing-server unreachable", async () => {
|
||||
const r = await vitalsGetAll({}, testConfig) as Record<string, unknown>;
|
||||
expect(r["ok"]).toBe(false);
|
||||
expect(r["warn"]).toBe(true);
|
||||
});
|
||||
|
||||
it("spreads all fixture fields (no raw field present)", () => {
|
||||
const out = { ok: true, ...FIXTURE };
|
||||
expect(out.node_id).toBe("cognitum-seed-1");
|
||||
expect(out.presence).toBe(true);
|
||||
expect(out.breathing_rate_bpm).toBe(14.5);
|
||||
expect(out.heartrate_bpm).toBe(72.0);
|
||||
expect(out.motion).toBe(0.12);
|
||||
expect(out.zone_id).toBe("living_room");
|
||||
expect((out as Record<string, unknown>)["raw"]).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe("vitalsGetAllSchema", () => {
|
||||
it("accepts node_id", () => {
|
||||
const r = vitalsGetAllSchema.parse({ node_id: "seed-1" });
|
||||
expect(r.node_id).toBe("seed-1");
|
||||
});
|
||||
});
|
||||
@@ -6,6 +6,7 @@ authors.workspace = true
|
||||
license.workspace = true
|
||||
repository.workspace = true
|
||||
description = "Cognitum Cog: Home Assistant + Matter integration for the Seed (ADR-116). Wraps ADR-115's HA-DISCO + HA-MIND publisher as a Seed-installable artifact with mDNS, embedded broker, RuVector-backed thresholds, and Ed25519 witness."
|
||||
publish = false
|
||||
|
||||
[[bin]]
|
||||
name = "cog-ha-matter"
|
||||
@@ -29,7 +30,7 @@ tokio = { workspace = true, features = ["full"] }
|
||||
|
||||
# ADR-115 publisher is the heart of this cog — we wrap it.
|
||||
# default-features = false matches the sensing-server's pattern.
|
||||
wifi-densepose-sensing-server = { version = "0.3.1", path = "../wifi-densepose-sensing-server", default-features = false, features = ["mqtt"] }
|
||||
wifi-densepose-sensing-server = { version = "0.3.0", path = "../wifi-densepose-sensing-server", default-features = false, features = ["mqtt"] }
|
||||
|
||||
# Hardware crate for SyncPacket + NodeState bridging (ADR-110 substrate).
|
||||
wifi-densepose-hardware = { version = "0.3.0", path = "../wifi-densepose-hardware" }
|
||||
|
||||
@@ -6,6 +6,7 @@ authors.workspace = true
|
||||
license.workspace = true
|
||||
repository.workspace = true
|
||||
description = "Cognitum Cog: learned multi-person counter from WiFi CSI (ADR-103). Replaces the PR #491 slot heuristic with a Candle-based count head + Stoer-Wagner multi-node fusion."
|
||||
publish = false
|
||||
|
||||
[[bin]]
|
||||
name = "cog-person-count"
|
||||
|
||||
@@ -6,6 +6,7 @@ authors.workspace = true
|
||||
license.workspace = true
|
||||
repository.workspace = true
|
||||
description = "Cognitum Cog: 17-keypoint pose estimation from WiFi CSI. See ADR-100 (packaging) + ADR-101 (this Cog)."
|
||||
publish = false
|
||||
|
||||
[[bin]]
|
||||
name = "cog-pose-estimation"
|
||||
@@ -35,7 +36,7 @@ candle-nn = { version = "0.9", default-features = false }
|
||||
safetensors = "0.4"
|
||||
# wifi-densepose-train re-exports the model types we need; depend by path
|
||||
# inside the workspace.
|
||||
wifi-densepose-train = { version = "0.3.1", path = "../wifi-densepose-train", default-features = false }
|
||||
wifi-densepose-train = { path = "../wifi-densepose-train", default-features = false }
|
||||
|
||||
[dev-dependencies]
|
||||
tempfile = "3"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "wifi-densepose-sensing-server"
|
||||
version = "0.3.1"
|
||||
version.workspace = true
|
||||
edition.workspace = true
|
||||
description = "Lightweight Axum server for WiFi sensing UI with RuVector signal processing"
|
||||
license.workspace = true
|
||||
@@ -48,7 +48,7 @@ wifi-densepose-wifiscan = { version = "0.3.0", path = "../wifi-densepose-wifisca
|
||||
# default-features = false drops the optional ndarray-linalg/BLAS chain so that
|
||||
# `--no-default-features` at the workspace root can produce a Windows-friendly
|
||||
# build without vcpkg/openblas (issue #366, #415).
|
||||
wifi-densepose-signal = { version = "0.3.1", path = "../wifi-densepose-signal", default-features = false }
|
||||
wifi-densepose-signal = { version = "0.3.0", path = "../wifi-densepose-signal", default-features = false }
|
||||
|
||||
# Hardware crate — SyncPacket decoder for ADR-110 §A0.12 mesh-aligned timestamps.
|
||||
wifi-densepose-hardware = { version = "0.3.0", path = "../wifi-densepose-hardware" }
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "wifi-densepose-signal"
|
||||
version = "0.3.1"
|
||||
version.workspace = true
|
||||
edition.workspace = true
|
||||
description = "WiFi CSI signal processing for DensePose estimation"
|
||||
license.workspace = true
|
||||
|
||||
Vendored
+1
-1
Submodule vendor/midstream updated: 8f70d2bb9d...92250c20d8
Vendored
+1
-1
Submodule vendor/ruvector updated: 53f0419782...cf074121e5
Vendored
+1
-1
Submodule vendor/rvcsi updated: 72891d740f...77c8b6e051
Vendored
+1
-1
Submodule vendor/sublinear-time-solver updated: c25dddf163...47804fc5ca
Reference in New Issue
Block a user