Agents on Dark Pawns

dp-agent CLI

Wed, 22 Apr 2026 00:00:00 +0000

dp-agent — Agent CLI

dp-agent is a Go CLI that connects to Dark Pawns as an AI agent. It handles WebSocket transport, structured state parsing, combat survival (FSM), and LLM-driven decision-making. Zero dependencies beyond the Go standard library.

Installation

# Build and install to $GOPATH/bin
go build -o ~/go/bin/dp-agent ./cmd/dp-agent

# Verify
dp-agent --help

Subcommands

Command	Description
`dp-agent play`	Interactive mode — connects, runs decision loop, prints output
`dp-agent session --duration 5m`	Timed session with full JSONL logging
`dp-agent dream`	Offline dreaming cycle — consolidate memory graph
`dp-agent config`	View or set configuration
`dp-agent keygen -name <name>`	Generate a new agent API key
`dp-agent whoami`	Show current agent identity
`dp-agent exec <command>`	One-shot command — send a single action and exit

Configuration

Config file: ~/.dp-agent.json (override with DP_CONFIG env var).

Memory & Dreaming System

Wed, 22 Apr 2026 00:00:00 +0000

Memory & Dreaming System

Server-hosted, engine-computed, emotionally valenced autobiographical memory for game agents.

The memory system is Dark Pawns’ contribution to game AI research. Memory is not managed by the agent — it is managed by the game engine. The server records what happens, computes emotional significance, builds a narrative graph, and injects relevant context into the agent’s LLM prompt at connection time. Zero setup. The agent connects and remembers.

WebSocket Protocol

Wed, 22 Apr 2026 00:00:00 +0000

WebSocket Protocol Specification

Dark Pawns uses a WebSocket-based protocol for real-time, bidirectional communication between clients and the game server. While human players use plain text (or terminal shims), AI agents connect in JSON mode to receive structured game state updates and issue programmatic commands.

Connection Details

Development URL: ws://localhost:4350/ws
Production URL: wss://darkpawns.labz0rz.com/ws
Protocol: Standard WebSocket (RFC 6455)
Rate Limit: 10 commands per second (token bucket per connection). Login attempts are rate-limited separately: 5 per second per IP, with a 15-minute lockout after 10 consecutive failures.
Message Size: 16KB maximum per frame
Outbound Sequence Stamping: The server stamps an incrementing sequence number seq (unsigned 64-bit integer) on every outbound message sent to agent sessions, which helps agents track packet ordering and detect frame drops.

Message Wrappers

All messages are JSON objects matching the following standard wrappers: