From 4557f6f614fe67b98d980dfb8c267c8b34f7f4de Mon Sep 17 00:00:00 2001 From: ruv Date: Sun, 24 May 2026 17:33:12 -0400 Subject: [PATCH] docs+plugins: rvAgent + RVF agentic-flow integration exploration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Land the rvAgent (vendor/ruvector/crates/rvAgent/) integration research dossier and update both the Claude Code and Codex plugins so future operators have a discoverable entry point for prototyping agentic flows on top of RuView's existing sensing pipeline + RVF cognitive containers. Added: - docs/research/rvagent-rvf-integration/README.md Full integration thesis: rvAgent's 8 crates + 14 middlewares share RVF as their state-persistence format with RuView's existing v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs. Three shippable touchpoints (each independent): 1. Two new RVF segment types (SEG_AGENT_STATE = 0x08, SEG_DECISION = 0x09) so rvAgent sessions and RuView sensing sessions interleave in one witness-bundle-attestable blob 2. BfldEvent → ToolOutput shim — agent reads BFLD events as tool context with no new IPC 3. cog-* subagent registration under a queen-agent router Open questions: workspace inclusion path, sync/async adapter placement, privacy-class composition with rvagent-middleware sanitizer, Soul Signature ↔ SoulMatchOracle bridge, MCP surface. Proposed next: ADR-124 before scaffolding wifi-densepose-agent. - plugins/ruview/skills/ruview-rvagent/SKILL.md New Claude Code skill exposing the integration surface, links to the research doc, and lists the three shippable touchpoints. Skill description tuned so Claude auto-discovers it for queries like "wire rvAgent into RuView" or "operator agent reacting to BFLD." - plugins/ruview/codex/prompts/ruview-rvagent.md Codex counterpart prompt with trigger phrasing, reading order, same three touchpoints + open questions, and the ADR-124 next step. Modified: - plugins/ruview/.claude-plugin/plugin.json Version 0.1.0 → 0.2.0; description extended to mention "BFLD privacy layer" and "rvAgent + RVF agentic flows". - plugins/ruview/codex/AGENTS.md Prompt table grows one row: `ruview-rvagent` for the new prompt. No code changes; no test impact. Co-Authored-By: claude-flow --- .../rvagent-rvf-integration/README.md | 113 ++++++++++++++++++ plugins/ruview/.claude-plugin/plugin.json | 4 +- plugins/ruview/codex/AGENTS.md | 1 + .../ruview/codex/prompts/ruview-rvagent.md | 36 ++++++ plugins/ruview/skills/ruview-rvagent/SKILL.md | 48 ++++++++ 5 files changed, 200 insertions(+), 2 deletions(-) create mode 100644 docs/research/rvagent-rvf-integration/README.md create mode 100644 plugins/ruview/codex/prompts/ruview-rvagent.md create mode 100644 plugins/ruview/skills/ruview-rvagent/SKILL.md diff --git a/docs/research/rvagent-rvf-integration/README.md b/docs/research/rvagent-rvf-integration/README.md new file mode 100644 index 00000000..008c6cf6 --- /dev/null +++ b/docs/research/rvagent-rvf-integration/README.md @@ -0,0 +1,113 @@ +# rvAgent + RVF integration for agentic flows in RuView + +**Status**: Research (Exploration) — Pre-Proposal +**Date**: 2026-05-24 +**Author**: ruv + +--- + +## TL;DR + +`vendor/ruvector/crates/rvAgent/` ships a production-grade Rust AI-agent framework with eight composable crates (`rvagent-core`, `-middleware`, `-tools`, `-subagents`, `-backends`, `-a2a`, `-acp`, `-mcp`, `-cli`). The framework already speaks **RVF cognitive containers** as its native state-persistence and inter-agent transport. RuView already uses RVF in `v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs`. + +**Integration thesis**: the two systems share a serialization substrate. Wiring `rvAgent` swarms into RuView turns the existing sensing pipeline into the substrate that an agentic flow can read from, reason about, and respond to — without writing a new agent runtime. + +Concrete value: + +1. **Operator-facing agents** that interpret BFLD / pose / vitals events live ("the kitchen has had no presence for 6 h but the kettle stayed on — page the carer"). +2. **In-process subagent coordination** for the multi-cog Cognitum Seed appliance — `cog-pose-estimation`, `cog-person-count`, `cog-ha-matter`, and the new BFLD pipeline can negotiate via rvAgent's CRDT state merging instead of ad-hoc IPC. +3. **Witness chains** (ADR-028 / ADR-110) get an upstream consumer — rvAgent's audit-trail middleware persists per-decision attestations into the same RVF container an operator already verifies. +4. **Local SONA learning** — rvAgent's 3-loop adaptive learning slots in alongside the per-home RuVector thresholds already proposed in ADR-116, with the same in-RAM-only privacy posture BFLD enforces (ADR-118 I2). + +--- + +## 1. What rvAgent ships + +| Crate | Role | Key types | +|-------|------|-----------| +| `rvagent-core` | State machine + COW state cloning + budget tracking | `AgentState`, `Message`, `AgiContainer`, `Arena`, `Budget`, `Graph` | +| `rvagent-middleware` | 14 built-in middlewares (security, witness, sanitizer, sona, hnsw) | `PipelineConfig`, `build_default_pipeline()` | +| `rvagent-tools` | Tool definitions + dispatch | `Tool`, `ToolInput`, `ToolOutput` | +| `rvagent-subagents` | Spawn isolated subagents with O(1) state clone | `Subagent`, CRDT merge | +| `rvagent-backends` | LLM provider abstraction (Anthropic, OpenAI, local) | `Backend` trait | +| `rvagent-mcp` | MCP server integration | MCP-style tool registry | +| `rvagent-a2a` / `-acp` | Agent-to-agent transport, agent communication protocol | wire format | +| `rvagent-cli` | Operator CLI | argv parsing | + +Selling points relevant to RuView: + +- **O(1) state cloning via `Arc`** → can spawn one subagent per sensing zone without copying gigabytes of context. +- **Parallel tool execution** → multiple sensor queries (BFLD presence, vitals BPM, pose) issued in parallel from one rvAgent decision step. +- **Path confinement + env-var sanitization** → operator-facing agents that touch the host filesystem (e.g., reading `data/recordings/`) stay sandboxed. +- **Witness chains** in `rvagent-middleware::witness` → already RVF-formatted; round-trips cleanly with ADR-028. + +## 2. What RVF already does in RuView + +`v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs` defines the on-disk container format used for: + +- ADR-110 witness attestations (`SEG_MANIFEST`, `SEG_META`). +- Soul Signature graphs (`docs/research/soul/specification.md` §3). +- BFLD class-1 (derived) frames once the operator opts into research mode (ADR-118 §1.4). + +Each RVF blob is content-addressed (BLAKE3 of the canonical byte representation) and carries a typed segment manifest. The format is intentionally extension-friendly — segment types are `u8` enums, new types can land without breaking older readers. + +## 3. The integration surface + +Three concrete touchpoints, each shippable independently. + +### 3.1 RVF as the rvAgent ↔ RuView wire + +rvAgent's `AgiContainer` (`rvagent-core/src/agi_container.rs`, 627 LOC) already produces RVF-compatible blobs as its persistent state format. RuView only needs to define **two segment types** in `rvf_container.rs`: + +- `SEG_AGENT_STATE = 0x08` — serialized `rvagent_core::AgentState` (the cloned-on-write tree from `cow_state.rs`). +- `SEG_DECISION = 0x09` — a single agent decision step: tool calls issued, outputs received, witness signature. + +With these two segments, an rvAgent session and a RuView sensing session can interleave entries in the same RVF blob. The witness-bundle script (ADR-028) iterates segments by type, so it would attest both halves with one signing pass. + +### 3.2 BFLD events as rvAgent tool inputs + +`wifi-densepose-bfld::BfldEvent` (iter 13) is already JSON-serializable via `to_json()`. Wrapping it as an `rvagent_tools::ToolOutput` is a 20-line shim: the agent issues a `read_bfld_state()` tool, the runtime returns the latest event JSON, the agent reasons over it. The full event surface (presence/motion/count/identity_risk/zone_id) becomes available as agent context without any new IPC. + +`BfldEvent → ToolOutput` mapping: +```rust +impl From for ToolOutput { + fn from(e: BfldEvent) -> Self { + ToolOutput::json(e.to_json().expect("BfldEvent JSON")) + } +} +``` + +### 3.3 cog-* as rvAgent subagents + +`cog-pose-estimation`, `cog-person-count`, `cog-ha-matter`, and (proposed) `cog-bfld` already share a packaging convention (ADR-100). Each cog can register as a subagent with rvAgent's hub: the cog implements the `Subagent` trait, exports its tool surface, and inherits the parent agent's CRDT state. The queen agent (`rvagent-queen.md` persona) routes operator queries across the cog mesh. + +Concrete example: +- Operator query: "is grandma awake yet?" +- Queen agent fans out to: `cog-bfld` (presence in bedroom), `cog-quantum-vitals` (HR baseline shift), `cog-pose-estimation` (sitting/standing transition). +- Each cog returns within budget; queen synthesizes the answer; witness chain logs the decision for compliance audit. + +## 4. Open questions + +1. **Workspace inclusion**: is `vendor/ruvector/crates/rvAgent/` already on the v2 workspace path, or does it need to be added as a path dep under `wifi-densepose-bfld` / a new `wifi-densepose-agent` crate? +2. **Async runtime**: rvAgent backends are tokio-based. The BFLD `Publish` trait is intentionally sync (iter 22). A small adapter (sync `Publish` ↔ async `Backend`) probably belongs in a `wifi-densepose-agent` crate, not in BFLD itself. +3. **Privacy class composition**: what's the rvAgent equivalent of BFLD's `PrivacyClass`? `rvagent-middleware::sanitizer` strips at the tool-output boundary; should it consume `PrivacyClass` from the originating BFLD event so the agent never even sees a class-3 identity field? +4. **Soul Signature interaction**: rvAgent's `SoulMatchOracle` integration (ADR-121 §2.6) could be the bridge from the Soul Signature graph (`docs/research/soul/`) to the agent decision layer. Worth a dedicated sub-section. +5. **MCP**: `rvagent-mcp` exposes tools to external MCP clients. Should the BFLD `BfldPipelineHandle::send` surface land as an MCP tool here, or stay private to in-process rvAgent flows? + +## 5. Proposed next steps (decision deferred) + +- **D1**: Open ADR-124 — "rvAgent + RVF integration for RuView agentic flows" — capturing the segment-type assignments, the cog-subagent contract, and the privacy-class composition rule. +- **D2**: Scaffold `v2/crates/wifi-densepose-agent` with the sync ↔ async adapter and one example tool (`read_bfld_state`). +- **D3**: Add `SEG_AGENT_STATE` and `SEG_DECISION` to `rvf_container.rs` as `#[cfg(feature = "agent")]` segments so the v0 ship doesn't pull rvAgent's transitive deps by default. +- **D4**: Land a one-page demo in `examples/agent-bedroom-check/` showing the queen-agent flow end-to-end against the `BfldPipelineHandle`. + +## 6. References + +- rvAgent: `vendor/ruvector/crates/rvAgent/README.md`, `rvagent-core/src/agi_container.rs`, `rvagent-middleware/docs/UNICODE_SECURITY.md` +- Agent personas: `vendor/ruvector/crates/rvAgent/.ruv/agents/{rvagent-coder,rvagent-queen,rvagent-tester,rvagent-security}.md` +- RVF container: `v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs` +- ADR-028 (witness): `docs/adr/ADR-028-esp32-capability-audit.md` +- ADR-100 (cog packaging), ADR-110 (witness chain), ADR-116 (cog-ha-matter) +- ADR-118 (BFLD): `docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md` +- Soul Signature: `docs/research/soul/specification.md` +- BFLD impl branch: `feat/adr-118-bfld-impl`, currently at iter 25 (`e8b4fdbc8`) diff --git a/plugins/ruview/.claude-plugin/plugin.json b/plugins/ruview/.claude-plugin/plugin.json index 2c081c8d..d46671c1 100644 --- a/plugins/ruview/.claude-plugin/plugin.json +++ b/plugins/ruview/.claude-plugin/plugin.json @@ -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, and witness verification — from practical to advanced.", - "version": "0.1.0", + "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.2.0", "author": { "name": "ruvnet", "url": "https://github.com/ruvnet/RuView" diff --git a/plugins/ruview/codex/AGENTS.md b/plugins/ruview/codex/AGENTS.md index 08207f22..00d79efb 100644 --- a/plugins/ruview/codex/AGENTS.md +++ b/plugins/ruview/codex/AGENTS.md @@ -47,6 +47,7 @@ After significant changes: run the Rust tests + Python proof, then `bash scripts | `ruview-app` | Run a sensing application (presence / vitals / pose / sleep / MAT / point cloud) | | `ruview-train` | Train / evaluate / publish a model (incl. GPU on GCloud) | | `ruview-verify` | Run the trust pipeline + pre-merge checklist | +| `ruview-rvagent` | Explore rvAgent + RVF agentic flows wiring into RuView | Install: copy `codex/prompts/*.md` into `~/.codex/prompts/`, or run Codex with this directory on its prompt path. diff --git a/plugins/ruview/codex/prompts/ruview-rvagent.md b/plugins/ruview/codex/prompts/ruview-rvagent.md new file mode 100644 index 00000000..553fe22d --- /dev/null +++ b/plugins/ruview/codex/prompts/ruview-rvagent.md @@ -0,0 +1,36 @@ +# ruview-rvagent — explore rvAgent + RVF agentic flows for RuView + +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`). + +## Trigger phrasing + +- "wire rvAgent into RuView" +- "I want a queen agent that fans out to cog-pose-estimation and cog-bfld" +- "persist agent decisions in the same witness bundle as sensing events" +- "how do I keep agent outputs class-3 compliant?" + +## What to read first + +1. `docs/research/rvagent-rvf-integration/README.md` — full integration thesis, open questions, next steps. +2. `vendor/ruvector/crates/rvAgent/README.md` — what rvAgent ships (8 crates, 14 middlewares). +3. `vendor/ruvector/crates/rvAgent/.ruv/agents/rvagent-queen.md` — queen-agent persona that coordinates cog subagents. +4. `v2/crates/wifi-densepose-bfld/src/{event.rs,pipeline_handle.rs}` — the BFLD event surface and the operator-facing handle that an agent would call. +5. `v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs` — segment types; `SEG_AGENT_STATE = 0x08` and `SEG_DECISION = 0x09` are the proposed additions. + +## Three shippable touchpoints (each independent) + +1. **RVF wire** — add `SEG_AGENT_STATE` + `SEG_DECISION` segments so rvAgent and RuView sessions can interleave in one blob (witness-bundle covers both halves). +2. **Tool shim** — `BfldEvent::to_json()` already exists; wrap as `rvagent_tools::ToolOutput`. +3. **Cog subagents** — register `cog-pose-estimation`, `cog-person-count`, `cog-ha-matter`, (proposed) `cog-bfld` under the queen via the `Subagent` trait. + +## Open questions to surface + +- Is `vendor/ruvector/crates/rvAgent/` on the v2 workspace path? +- Sync ↔ async adapter location (BFLD `Publish` is sync; rvAgent backends are tokio). +- Privacy-class composition — does `rvagent-middleware::sanitizer` consume `BfldEvent::privacy_class`? +- Soul Signature ↔ `SoulMatchOracle` bridge (ADR-121 §2.6). +- Should `BfldPipelineHandle::send` land as a public MCP tool via `rvagent-mcp`? + +## Suggested next action + +Draft ADR-124 — "rvAgent + RVF integration for RuView agentic flows" — capturing segment assignments, cog-subagent contract, and privacy-class composition. Land **before** scaffolding `v2/crates/wifi-densepose-agent`. diff --git a/plugins/ruview/skills/ruview-rvagent/SKILL.md b/plugins/ruview/skills/ruview-rvagent/SKILL.md new file mode 100644 index 00000000..63ba3e8a --- /dev/null +++ b/plugins/ruview/skills/ruview-rvagent/SKILL.md @@ -0,0 +1,48 @@ +--- +name: ruview-rvagent +description: Explore and prototype rvAgent + RVF integration for RuView agentic flows. Use when working on cross-cog coordination, operator-facing agents reading BFLD / pose / vitals events live, or persisting agent state alongside sensing data in the same RVF container. +--- + +# RuView rvAgent + RVF integration + +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. + +## When to use this skill + +- "I want an agent that reacts to BFLD presence in the kitchen and pages the carer." +- "I need cog-pose-estimation and cog-bfld to negotiate before publishing a synthesized event." +- "Can the witness chain attest both the sensing event AND the agent decision in one RVF blob?" +- "How do we keep rvAgent's tool outputs class-3 compliant when the source BFLD event is Restricted?" + +## Key surfaces + +| Surface | File | Notes | +|---------|------|-------| +| rvAgent core | `vendor/ruvector/crates/rvAgent/rvagent-core/src/agi_container.rs` (627 LOC) | RVF-compatible state container | +| rvAgent middleware | `vendor/ruvector/crates/rvAgent/rvagent-middleware/` | Witness, sanitizer, SONA, HNSW | +| Agent personas | `vendor/ruvector/crates/rvAgent/.ruv/agents/rvagent-{queen,coder,tester,security}.md` | Reference patterns | +| RVF container | `v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs` | Add `SEG_AGENT_STATE`, `SEG_DECISION` | +| BFLD event | `v2/crates/wifi-densepose-bfld/src/event.rs` | `BfldEvent::to_json()` → `ToolOutput` | +| BFLD pipeline handle | `v2/crates/wifi-densepose-bfld/src/pipeline_handle.rs` | `BfldPipelineHandle::send` | + +## Research dossier + +Full integration analysis lives at `docs/research/rvagent-rvf-integration/README.md`. + +Three shippable touchpoints, each independent: + +1. **RVF wire**: two new segment types (`SEG_AGENT_STATE = 0x08`, `SEG_DECISION = 0x09`) let rvAgent sessions interleave with RuView sensing sessions in the same blob. +2. **Tool surface**: `BfldEvent → ToolOutput` shim turns BFLD events into agent context with no new IPC. +3. **Cog subagents**: `cog-pose-estimation` / `cog-person-count` / `cog-ha-matter` / `cog-bfld` register as rvAgent subagents under a queen-agent router. + +## Open questions + +- Workspace inclusion of `vendor/ruvector/crates/rvAgent/` (path dep vs published crate) +- Sync ↔ async adapter (BFLD `Publish` is sync, rvAgent backends are tokio) +- Privacy-class composition (does rvAgent's sanitizer consume `PrivacyClass`?) +- Soul Signature ↔ `SoulMatchOracle` bridge +- Whether `BfldPipelineHandle::send` lands as a public MCP tool via `rvagent-mcp` + +## Next decision + +ADR-124 (proposed) — "rvAgent + RVF integration for RuView agentic flows" — would capture segment assignments, cog-subagent contract, and the privacy-class composition rule. Land before scaffolding `v2/crates/wifi-densepose-agent`.