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-lib --bin horizon-ctl), 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

• 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. hello and status are described (the reference's "Replies" section; MCP outputSchema with structuredContent); the other groups follow one at a time.
• 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

• 0.1.0: the first numbered line. hello answers protocol, release (the game's version, which MCP serverInfo carries too) and features (the command groups the game serves). Before it the command table and the generated reference were the contract.
• horizon-ctl --api 0.1 (a tool change, the protocol stays 0.1.0): calls hello before the first command and refuses a game on another line or one without hello (exit status 5, kind: "api"). 0.1 takes 0.1.x; a full version must match exactly.