Agent Control Plane (ACP)

The Agent Control Plane provides TCP-based bidirectional control over agent workers. ACP enables CLI and tooling to discover, route to, and control individual Luna workers.

Overview

ACP is a TCP listener protocol (separate from HTTP). Clients connect via TCP, send msgpack-encoded control messages, and receive responses over the same connection. The ACP router maintains a registry of connected workers and can forward commands to specific workers or broadcast to all.

Protocol

TCP Listener

tcp://host:11435

The ACP listener (sol_acp_listener) accepts TCP connections, wraps them in sessions (sol_acp_session), and routes messages to registered workers.

Message Format

Messages are msgpack-encoded maps with a type field:

{
  "type": "forward",
  "target": "worker-uuid",
  "payload": { ... }
}

Message Types

Type	Direction	Description
register	Worker → Router	Register worker identity and capabilities
forward	Client → Router	Forward command to a specific worker
broadcast	Client → Router	Send command to all registered workers
discover	Client → Router	List connected agents and their capabilities
reply	Worker → Router → Client	Worker response to a forwarded command

Discovery Response

{
  "type": "discover",
  "agents": [
    {
      "id": "worker-uuid",
      "capabilities": ["chat", "tools", "memory"],
      "status": "idle",
      "model": "claude-sonnet-4-20250514"
    }
  ]
}

Endpoints (HTTP Bridge)

Get ACP Status

GET /api/v1/acp/status

Returns ACP listener status and connected session count:

{
  "ok": true,
  "listener": { "port": 11435, "active": true },
  "sessions": 3,
  "workers": { "registered": 3, "idle": 2 }
}

List Connected Agents

GET /api/v1/acp/agents

Returns discovered agents (same as ACP discover message).

Error Codes:

Code	Description
401	Authentication required
500	ACP listener not started

Examples:

# TCP direct connection (via zerg-cli)
zerg acp discover

# HTTP bridge
curl http://127.0.0.1:11434/api/v1/acp/agents \
  -H "Authorization: Bearer $TOKEN"