ValkyrAI SWARM Integration

Canonical contract: GrayMatter SWARM Protocol v0.1. This page is an implementation note for the existing ValkyrAI/ValorIDE registry and mothership 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)

New producers must emit GrayMatter SwarmEvent v0.1 and include the durable Agent record id as source.agentRecordId. The compatibility formats below are documented only so LCARS and adapters can keep visibility while old helpers are replaced.

• 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 creates or refreshes an Agent record, registers the live SwarmOps instance, and sends swarm.presence.registered / heartbeat messages.

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

Notes & next steps

• Treat the generated Agent object as durable identity and the live registry as session state. The LCARS dashboard marks SwarmOps-only records as Needs Agent.
• Add authentication/authorization checks on the HTTP command endpoint.
• Extend telemetry: health, latency, and command ack/nack channels.