IoT Bridge

The IoT Bridge extension connects Mayros agents to aingle_minimal IoT nodes via REST. It provides fleet management, background health polling, DAG entry operations, and automatic context injection so agents are aware of connected edge devices.

Architecture

Each IoT node runs an aingle_minimal instance exposing a REST API. The bridge maintains a fleet registry of nodes, each backed by an IoTNodeClient with its own CircuitBreaker so a failing node does not affect others.

Mayros Agent
  └── IoT Bridge Plugin
        └── FleetManager
              ├── Node A → IoTNodeClient → http://192.168.1.10:19090
              ├── Node B → IoTNodeClient → http://192.168.1.11:19090
              └── Node C → IoTNodeClient → http://sensor-hub:8080

FleetManager

The FleetManager handles node lifecycle:

Operation	Description
`addNode(config)`	Register a node (id, host, port, label)
`removeNode(id)`	Remove a node from the fleet
`pollAll()`	Health-check all nodes in parallel
`pollNode(id)`	Health-check + fetch info/stats for one node
`startPolling(ms)`	Background polling at a fixed interval
`stopPolling()`	Stop background polling
`loadFleet()`	Load persisted fleet from disk
`saveFleet()`	Atomic write of fleet config to disk
`generateFleetSummary()`	XML context block for prompt injection

Node limit

The fleet enforces a configurable maxNodes cap (default: 50). Attempts to add beyond the limit throw an error.

IoTNodeClient

Each node client wraps the aingle_minimal REST API:

Endpoint	Method	Description
`/health`	GET	Health check (returns boolean)
`/api/v1/info`	GET	Node version, uptime, entries, peers, features
`/api/v1/stats`	GET	Storage, gossip rounds, sync success/failure
`/api/v1/peers`	GET	Connected peer list with quality metrics
`/api/v1/entries`	POST	Create a DAG entry
`/api/v1/entries/:hash`	GET	Retrieve a DAG entry by hash

All requests go through resilientFetch with per-node circuit breaker (3-state: closed/open/half-open).

Context injection

When injectContext is enabled (default: true), the before_prompt_build hook injects fleet status as XML into the prompt:

xml
<iot-fleet>
  <node id="sensor-hub" host="192.168.1.10:19090" online="true" version="0.0.101" entries="42" peers="3" gossip_rounds="128" storage_used="65536" />
  <node id="gateway" host="192.168.1.11:19090" online="false" />
</iot-fleet>

This gives the agent awareness of available nodes, their health, and current metrics without requiring a tool call.

HOPE observations

The iot_send_observation tool formats sensor data as HOPE (Hierarchical Observation Protocol for Edge) payloads:

typescript
{
  type: "observation",
  obs_type: "temperature",  // sensor type
  value: 23.5,
  timestamp: 1709913600000,
  confidence: 0.95,         // optional
  metadata: { unit: "C" }   // optional
}

Observations are published as DAG entries on the target node and propagate through the gossip network.

Agent tools

Tool	Description
`iot_node_info`	Get node version, uptime, entries, peers, features
`iot_node_stats`	Get storage, gossip, and sync statistics
`iot_list_fleet`	List all nodes with status (optionally online-only)
`iot_publish_entry`	Create a DAG entry on a node
`iot_get_entry`	Retrieve a DAG entry by hash
`iot_send_observation`	Forward a HOPE observation to a node

Hooks wiring

Hook	Action
`session_start`	Load persisted fleet, merge config nodes, initial poll, start background polling
`before_prompt_build`	Inject fleet summary XML into prompt context
`session_end`	Stop polling, persist fleet to disk

Configuration

typescript
{
  nodes: [                          // Static node definitions
    { id: "sensor-hub", host: "192.168.1.10", port: 19090, label: "Main sensor" }
  ],
  pollIntervalMs: 30000,            // Background poll interval (min: 1000)
  maxNodes: 50,                     // Fleet size limit
  injectContext: true,               // Inject fleet summary into prompts
  fleetPersistPath: "~/.mayros/iot-fleet.json",
  resilience: {
    timeoutMs: 5000,
    maxRetries: 2,
    retryDelayMs: 1000,
    circuitThreshold: 3,
    circuitResetMs: 30000
  }
}

CLI

bash
mayros iot fleet                   # List all nodes with status
mayros iot add <host> [--port 19090] [--id name] [--label "desc"]
mayros iot remove <id>             # Remove a node
mayros iot status <id>             # Detailed node info + stats + peers
mayros iot ping <id>               # Quick health check with latency

Cortex Resilience — circuit breaker and retry policies
Architecture — extension system overview
P2P Sync — native peer-to-peer synchronization