Agent control API

Overview

The game listens on a local control socket (a Unix socket, or localhost TCP with a token on Windows), takes one command per text line and answers one JSON line. horizon-ctl wraps it: it starts the game, sends commands and serves the same commands as MCP tools. The launcher's MCP server offers them too, as game_<tool>.

Guide

1. Build horizon-ctl (cargo build --profile fast -p horizon-client), then horizon-ctl --socket $PWD/ctl.sock launch --world W --creative --wait --resources <prepared files>.
2. horizon-ctl --socket … state, keys, turn, command, screenshot, quit.
3. For an agent: horizon-ctl mcp, or the launcher's horizon-launcher mcp with agent-config to connect a client (launcher-commands.md).

Reference

horizon-ctl-commands.md, generated from the command table in crates/horizon-client/src/bin/horizon-ctl/commands.rs: every command, its MCP tool and its arguments.

Examples

• tools/agent_control_e2e.py: starts a game and drives it end to end through horizon-ctl and MCP.
• tools/lan_e2e.py: two games over LAN, both driven through their sockets.

Stability

Preview (stability.md). The commands in horizon-ctl's table and their MCP tool names are what the API offers; the other commands the game's socket answers are test hooks and experimental.

Not there yet

• A version. A hello command that answers the protocol version, the game's release and the features it has; MCP serverInfo carries the same version; horizon-ctl refuses a game whose major it doesn't speak.
• Reply schemas. Each command's reply described in the table (fields, types, units), so the reference documents replies as well as arguments and MCP tools declare an output schema.
• Events as a stream. events --since polls today; a subscription that pushes events as they happen.
• Test hooks apart. The hooks only harnesses use move under their own prefix, out of the agent's tool list.
• Compatibility tests. A transcript per protocol version: commands and the reply keys each must keep.

Changelog

• Unversioned so far: the command table and the generated reference are the contract.