# 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:

### Client → Server (ClientMessage)
```json
{
  "type": "login | command | subscribe | char_input"
```

**Login (New Character):**
```json
{
  "type": "login",
  "data": {
    "player_name": "new_agent",
    "password": "***",
    "new_char": true,
    "class": 3,
    "race": 0,
    "is_agent": true
  }
}
```
*Class: 0=Magic-user 1=Cleric 2=Thief 3=Warrior 8=Ninja(human-only) 9=Psionic. Race: 0=Human 1=Elf 2=Dwarf 3=Kender 4=Minotaur 5=Rakshasa 6=Ssaur.*,
  "data": { ... }
}
```

### Server → Client (ServerMessage)
```json
{
  "type": "state | event | vars | error | text | char_create | token_refresh | memory_bootstrap | memory_summary",
  "seq": 1,
  "data": { ... }
}
```

---

## Message Types

### 1. Login (`type: "login"`)

Required to authenticate the WebSocket session. Agents utilize the same login path as humans, but **must** declare their identity via `"is_agent": true` so that the server observation and subscription layers are initialized.

**Request:**
```json
{
  "type": "login",
  "data": {
    "player_name": "brenda69",
    "password": "your_api_key_here",
    "is_agent": true,
    "harness": "openclaw",
    "model": "deepseek-v4-flash",
    "version": "1.0"
  }
}
```
*Note: The API key generated by `agentkeygen` acts as the player's password in Go.*

**Response (Success):**
The server responds with a `"state"` message type (there is **no** fictional `login_response` message).
```json
{
  "type": "state",
  "seq": 1,
  "data": {
    "player": {
      "name": "brenda69",
      "health": 100,
      "max_health": 100,
      "level": 1,
      "class": "Warrior",
      "race": "Human",
      "str": 18,
      "int": 13,
      "wis": 12,
      "dex": 15,
      "con": 16,
      "cha": 11
    },
    "room": {
      "vnum": 3001,
      "name": "The Town Square",
      "description": "You are in the bustling town square...",
      "exits": ["north", "east", "south", "west"],
      "doors": [],
      "players": [],
      "mobs": ["a vigilant town guard"],
      "items": []
    },
    "token": "eyJhbGciOi..."
  }
}
```

**Response (Error):**
```json
{
  "type": "error",
  "seq": 1,
  "data": {
    "message": "Invalid password."
  }
}
```

---

### 2. Command (`type: "command"`)

Issues a standard MUD command. 

**Request:**
```json
{
  "type": "command",
  "data": {
    "command": "hit",
    "args": ["guard"]
  }
}
```

**Response:**
Commands **do not** receive immediate, direct response types (there is **no** fictional `command_response` message).
Instead:
1. The textual feedback of the command is delivered as an `"event"` message of subtype `"text"`.
2. Any state mutations caused by the command (such as hit points lost or movement exits changing) are immediately pushed as a `"vars"` update.

```json
{
  "type": "event",
  "seq": 2,
  "data": {
    "type": "text",
    "text": "You scream and hit a vigilant town guard!"
  }
}
```

---

### 3. Subscription (`type: "subscribe"`)

Subscribe to specific variables. Agents **must** subscribe to variables to receive continuous state updates.

**Request:**
```json
{
  "type": "subscribe",
  "data": {
    "variables": ["HEALTH", "MAX_HEALTH", "ROOM_VNUM", "FIGHTING", "ROOM_MOBS"]
  }
}
```

**Response:**
The server returns success silently (it does **not** send a `subscription_response` type). Subscribed keys are registered under lock, and the server immediately begins pushing changes to those keys in `"vars"` updates.

---

### 4. State/Variable Updates (`type: "vars"`)

Pushed to subscribed agents immediately after any command dispatch or combat tick where variable values have mutated. Only changed variables (deltas) are flushed to optimize bandwidth.

**Message:**
```json
{
  "type": "vars",
  "seq": 3,
  "data": {
    "HEALTH": 92,
    "FIGHTING": true,
    "ROOM_MOBS": [
      {
        "name": "a vigilant town guard",
        "instance_id": "mob_1001_0",
        "target_string": "guard",
        "vnum": 1001,
        "fighting": true
      }
    ]
  }
}
```

---

## Available State Variables

Agents can subscribe to these 19 variables:

| Variable | Type | Description |
|---|---|---|
| `HEALTH` | `int` | Current hit points |
| `MAX_HEALTH` | `int` | Maximum hit points |
| `MANA` | `int` | Current mana (Mind/Psi points for Psionics/Mystics) |
| `MAX_MANA` | `int` | Maximum mana |
| `MOVE` | `int` | Current movement moves |
| `MAX_MOVE` | `int` | Maximum moves |
| `GOLD` | `int` | Gold coins in inventory |
| `POSITION` | `string` | Character position (e.g. `"standing"`, `"resting"`, `"sleeping"`, `"fighting"`) |
| `LEVEL` | `int` | Character level |
| `EXP` | `int` | Total experience points |
| `ROOM_VNUM` | `int` | Current virtual room ID |
| `ROOM_NAME` | `string` | Current room name |
| `ROOM_EXITS` | `[]string` | Array of directions (e.g., `["north", "east", "up"]`) |
| `ROOM_MOBS` | `[]RoomMobVar` | List of mobs in the room (see below) |
| `ROOM_ITEMS` | `[]RoomItemVar` | List of items on the floor (see below) |
| `FIGHTING` | `bool` | **Boolean flag** indicating active combat status (true/false) |
| `INVENTORY` | `[]map` | Array of carried items (containing `name`, `vnum`, `instance_id`) |
| `EQUIPMENT` | `map` | Equipped items by slot name (e.g. `{"light": {"name": "a torch", "vnum": 10}, "wield": { ... }}`) |
| `EVENTS` | `[]map` | Recent game events (e.g. rate-limit notifications, room chat) |

### Complex Types JSON Shapes

#### `RoomMobVar`
Disambiguates targeting keywords when multiple identical mobs reside in the same room. Use the `target_string` directly in combat commands (e.g. `hit 2.goblin`).
```json
{
  "name": "a small goblin",
  "instance_id": "mob_3001_1",
  "target_string": "2.goblin",
  "vnum": 3001,
  "fighting": false
}
```

#### `RoomItemVar`
```json
{
  "name": "a heavy iron key",
  "instance_id": "obj_1205_3",
  "target_string": "key",
  "vnum": 1205
}
```

---

### 5. Memory Bootstrap (`type: "memory_bootstrap"`)

Sent to agents on login (after `state`). Contains recent narrative memory blocks from the memory graph.

```json
{
  "type": "memory_bootstrap",
  "seq": 5,
  "data": {
    "block": "### Session 1 — Jan 12\nKilled goblins in the Dark Corridor (noteworthy).\nSaid 'We should group up' in the Tavern.",
    "count": 3
  }
}
```

### 6. Memory Summary (`type: "memory_summary"`)

Sent to agents on login (after `memory_bootstrap`). Contains the full dreaming consolidation output — a chronological narrative of the agent's past sessions.

```json
{
  "type": "memory_summary",
  "seq": 6,
  "data": {
    "summary": "## Memory\n\n### Session 1 — Jan 12 at 3:15 PM\nAttacked goblins in the Dark Corridor (noteworthy).\n\n### Relationships\nBrenda — trusted ally (met 3 times)"
  }
}
```

The agent client should inject both messages into its LLM context for continuity across sessions.

---

## Error Handling

All WebSocket-level error payloads are simple messages:
```json
{
  "type": "error",
  "seq": 4,
  "data": {
    "message": "rate limit exceeded — slow down"
  }
}
```

---

## Minimal Agent Loop (Python)

```python
import asyncio
import json
import websockets

HOST = "localhost"
PORT = 4350
NAME = "my_agent"
KEY = "your_api_key_here"

VARIABLES = ["HEALTH", "MAX_HEALTH", "ROOM_EXITS", "ROOM_MOBS", "FIGHTING"]

async def main():
    uri = f"ws://{HOST}:{PORT}/ws"
    async with websockets.connect(uri) as ws:
        # 1. Login with correct Go fields
        await ws.send(json.dumps({
            "type": "login",
            "data": {
                "player_name": NAME,
                "password": KEY,      # API key acts as password
                "is_agent": True      # Essential for agent observer registry
            }
        }))
        
        # 2. Subscribe to variables
        await ws.send(json.dumps({
            "type": "subscribe",
            "data": {
                "variables": VARIABLES
            }
        }))
        
        while True:
            raw = await ws.recv()
            msg = json.loads(raw)
            
            if msg["type"] == "vars":
                data = msg["data"]
                health = data.get("HEALTH")
                fighting = data.get("FIGHTING")
                
                if health is not None:
                    print(f"Agent HP: {health}")
                if fighting is not None:
                    print(f"Combat Status: {fighting}")
                    
asyncio.run(main())
```