Enable rvAgent runtime and RVF app deployment on seed appliance

[ruvnet]

Problem

The seed appliance cannot run custom RVF applications or rvAgent sessions on-device. The agents feature flag (Phase 2A) is not enabled in the deployed v0.7.0 build, and there is no mechanism to install, manage, or sandbox third-party RVF apps on the appliance.

Users who want to run rvagent-core workflows on the seed must connect remotely via MCP from a laptop — there's no way to deploy persistent agent logic that runs directly on the device.

Current State

What exists (but is not compiled in)

• agent_runtime.rs — Session management, tool dispatch, state machine wrapping rvagent-core
• agents_api.rs — 9 endpoints: create/message/status/destroy sessions, brain share/search, neural routing, SONA learning
• mcp.rs — 114 MCP tools across 3 scopes (minimal/default/full), working MCP server on port 8443
• mcp_brain_bridge.rs — Knowledge sharing between agent sessions
• neural_router.rs — Tiny Dancer task routing
• sona_learning.rs — On-device SONA adaptation

Feature flags (Cargo.toml)

# Phase 2A: Agents — agent runtime, SONA, tiny-dancer, MCP brain
agents = [
    "foundation",
    "dep:rvagent-core",
    "dep:ruvector-sona",
    "dep:ruvector-tiny-dancer-core",
    "dep:mcp-brain",
]

What works today

• Remote MCP connection: https://169.254.42.1:8443/mcp — any MCP client can use seed tools
• RVF store: vectors, custody chains, witness proofs via REST API
• All 114 MCP tools available to remote agents

What's missing

1. agents feature not compiled — rvagent-core, SONA, Tiny Dancer, MCP Brain not in deployed binary
2. No app install endpoint — can't deploy RVF apps to the device
3. No app lifecycle management — no start/stop/update/remove for deployed apps
4. No sandboxing — no isolation between apps or resource limits per app
5. No app manifest format — no standard way to describe an RVF app's requirements

Proposed Fix

Phase 1: Enable agents feature in build

Files to change:

• Dockerfile.armhf — add --features agents to cargo build
• src/cognitum-agent/Cargo.toml — ensure path deps for rvagent-core, ruvector-sona, mcp-brain, ruvector-tiny-dancer-core resolve in Docker (git deps or vendored)

New endpoints activated (already coded in agents_api.rs):

Method	Endpoint	Description
POST	/api/v1/agents/create	Create agent session
POST	/api/v1/agents/{id}/message	Send message to agent
GET	/api/v1/agents/{id}/status	Session status
DELETE	/api/v1/agents/{id}	Destroy session
GET	/api/v1/agents/list	List active sessions
POST	/api/v1/brain/share	Share knowledge entry
POST	/api/v1/brain/search	Search brain entries
POST	/api/v1/routing/route	Neural route query (Tiny Dancer)
GET	/api/v1/learning/status	SONA learning stats

Resource constraints (Pi 5, 4GB RAM):

• Max concurrent agent sessions: 4 (configurable)
• Per-session memory budget: 256MB
• Tool execution timeout: 30s
• SONA adaptation: <0.05ms per step

Phase 2: RVF App deployment system

New endpoints:

Method	Endpoint	Description
POST	/api/v1/apps/install	Install RVF app from manifest
GET	/api/v1/apps/list	List installed apps
GET	/api/v1/apps/{id}/status	App status
POST	/api/v1/apps/{id}/start	Start app
POST	/api/v1/apps/{id}/stop	Stop app
DELETE	/api/v1/apps/{id}	Uninstall app
GET	/api/v1/apps/{id}/logs	App logs

App manifest format (rvf-app.json):

{
  "name": "my-rvf-agent",
  "version": "1.0.0",
  "description": "Custom vector processing agent",
  "entry": "agent.wasm",
  "runtime": "rvagent-core",
  "permissions": {
    "mcp_scopes": ["default"],
    "store_access": "read-write",
    "network": false,
    "max_memory_mb": 128,
    "max_sessions": 2
  },
  "tools": [
    {
      "name": "my-tool",
      "description": "Custom processing tool",
      "input_schema": { "type": "object" }
    }
  ]
}

App storage:

• Apps installed to /var/lib/cognitum/apps/{app-id}/
• App state persisted across reboots
• Apps survive OTA updates (data partition, not binary)

Sandboxing (leveraging existing systemd security):

• Each app runs in a dedicated cgroup with memory/CPU limits
• Apps get their own RVF namespace (isolated vector store)
• Network access denied by default (apps use seed's MCP tools)
• File access restricted to app's own directory

Phase 3: App distribution

• POST /api/v1/apps/install accepts URL to download app bundle
• App bundles are signed with the build key (same as firmware)
• Optional: app catalog at https://cognitum.one/apps
• Apps can register custom MCP tools that appear in the seed's tool list

Implementation Order

1. Enable agents feature — rebuild with rvagent-core compiled in, publish as v0.8.0
2. Add app manifest parsing — validate and store app definitions
3. Add app lifecycle endpoints — install/start/stop/remove
4. Add resource sandboxing — cgroup limits, namespace isolation
5. Add app distribution — signed bundles, optional catalog

Test Plan

Phase 1

• Build with --features agents succeeds for armhf target
• POST /api/v1/agents/create creates a session
• POST /api/v1/agents/{id}/message dispatches tool calls
• GET /api/v1/learning/status returns SONA stats
• Max session limit enforced (4 concurrent)
• Memory stays under 512MB with 4 active sessions

Phase 2

• POST /api/v1/apps/install with valid manifest succeeds
• App persists across agent restart
• App persists across OTA update
• DELETE /api/v1/apps/{id} cleanly removes all app data
• App memory limit enforced via cgroup
• App cannot access other apps' data

Phase 3

• Signed app bundle installs successfully
• Unsigned/tampered bundle rejected
• Custom MCP tools registered by app appear in tools/list
• Remote MCP client can call app-registered tools

Security Considerations

• Apps run with minimal privileges (no root, no network by default)
• App bundles must be signed with a trusted key
• Per-app resource quotas prevent DoS
• Apps cannot modify seed firmware or system config
• App data is isolated per-app (no cross-app reads)
• USB-only install by default (WiFi install requires pairing)

References

• ADR-069: v0 RuVector integration strategy (Phase 2A agents)
• ADR-057: USB implicit trust model
• ADR-071: SSH key provisioning & open WiFi (v0.7.0)
• src/cognitum-agent/src/agent_runtime.rs — existing rvAgent runtime
• src/cognitum-agent/src/agents_api.rs — existing 9 agent endpoints