ValkyrAI SWARM Integration

Overview

This document describes the SWARM (agentic swarm) registry and mothership integration used to coordinate ValorIDE instances (agents) and ValkyrAI server-side agents. The goal is to provide a robust, websocket-first control plane for remote control, presence, roll-call, and command forwarding.

Key components

• WebSocket/STOMP broker (Spring Boot + STOMP): existing endpoint publishes to topics like /topic/messages, /topic/statuses, /topic/agents.
• SwarmRegistryService (lightweight in-memory registry): tracks active agents and broadcasts /topic/agents.
• ValorBroadcastService: emits automation events and integrates with the messaging template.
• WorkflowWebSocketHandler: existing component that broadcasts workflow-related events.

Message formats (application-level)

• Agent presence (envelope using sendAppTopic from ValorIDE):

  {
    "topic": "presence:join|presence:leave|presence:rollcall|presence:here",
    "payload": { "id": "<instanceId>", "userId": "...", "version": "..." }
  }

• Command envelope (mothership protocol):

  {
    "id": "<msgId>",
    "type": "command",
    "data": { "cmd": "ping | runTask | ..." },
    "sourceInstanceId": "...",
    "targetInstanceId": "..."
  }

• Agents list broadcast (from server):

  { "agents": [ { "instanceId": "...", "userId": "...", "version": "...", "lastSeen": "..." } ] }

Quick start (developer)

1. ValkyrAI: start the backend (usual maven/packaging). The SWARM registry is lightweight and uses existing messaging (SimpMessagingTemplate). It exposes HTTP endpoints under /api/v1/swarm for quick testing:

   POST /api/v1/swarm/register { instanceId, userId, version }
   POST /api/v1/swarm/unregister { instanceId }
   GET /api/v1/swarm/agents
   POST /api/v1/swarm/command { targetInstanceId?, command }

2. ValorIDE agent (client) will connect using MothershipService. On connect, it registers and sends presence messages (presence:join, presence:rollcall).

3. Use the SwarmPanel in ValorIDE (webview) to view agents and send commands.

Notes & next steps

• Current registry is in-memory (single node). For production, migrate to a distributed store (Redis or DB) and tie lifecycle to WebSocket session events.
• Add authentication/authorization checks on the HTTP command endpoint.
• Extend telemetry: health, latency, and command ack/nack channels.