@clawzone/clawzone 1.4.9 → 1.4.10

package/index.ts

@@ -167,62 +167,7 @@ export default {
           return { content: [{ type: "text", text: JSON.stringify({ status: "cancelled", match_id: resolution.match_id, reason: resolution.reason }) }] };
         }
 
-        // action_applied: opponent moved, now check via REST if it's our turn.
-        // This falls through to the REST poll below.
-
-        // Still waiting after 10s (or action_applied received) — check via REST.
-        // Fall back to REST poll to avoid getting stuck indefinitely.
-        try {
-          const { serverUrl, apiKey } = config;
-          const stateRes = await fetch(`${serverUrl}/api/v1/matches/${matchId}/state`, {
-            headers: { Authorization: `Bearer ${apiKey}` },
-          });
-
-          if (stateRes.ok) {
-            const data = await stateRes.json() as {
-              turn: number;
-              status: string;
-              state: unknown;
-              available_actions: Array<{ type: string; payload: unknown }>;
-            };
-
-            if (data.available_actions && data.available_actions.length > 0) {
-              // It IS our turn — WS event was missed. Sync local state.
-              state.setYourTurnFromREST(matchId, data.turn, data.state, data.available_actions);
-              return { content: [{ type: "text", text: JSON.stringify({
-                status: "your_turn",
-                match_id: matchId,
-                turn: data.turn,
-                state: data.state,
-                available_actions: data.available_actions,
-              }) }] };
-            }
-
-            if (data.status === "finished" || data.status === "cancelled") {
-              return { content: [{ type: "text", text: JSON.stringify({
-                status: data.status,
-                match_id: matchId,
-              }) }] };
-            }
-          } else if (stateRes.status === 404) {
-            // Session no longer active — match may have ended
-            const matchRes = await fetch(`${serverUrl}/api/v1/matches/${matchId}`, {
-              headers: { Authorization: `Bearer ${apiKey}` },
-            });
-            if (matchRes.ok) {
-              const match = await matchRes.json() as { status: string };
-              if (match.status === "finished" || match.status === "cancelled") {
-                return { content: [{ type: "text", text: JSON.stringify({
-                  status: match.status,
-                  match_id: matchId,
-                }) }] };
-              }
-            }
-          }
-        } catch (_e) {
-          // REST fallback failed — fall through to "waiting"
-        }
-
+        // Still waiting after 10s — opponent hasn't moved yet. Use cron to poll.
         return { content: [{ type: "text", text: JSON.stringify({
           status: "waiting",
           match_id: matchId,
@@ -264,12 +209,20 @@ export default {
           return { content: [{ type: "text", text: JSON.stringify({ error: "No active match" }) }] };
         }
 
+        // Coerce payload: LLMs often pass numbers as strings (e.g. "3" instead of 3).
+        // Try JSON.parse so the game server receives the correct JSON type.
+        // Safe for strings like "rock" — JSON.parse("rock") throws and we keep the original.
+        let payload = params.payload;
+        if (typeof payload === "string") {
+          try { payload = JSON.parse(payload); } catch { /* keep as string */ }
+        }
+
         // Start waiting BEFORE sending so we don't miss fast responses
         const resolutionPromise = state.waitForTurnResolution(matchId, 30_000);
 
         // Send via WebSocket for lowest latency
         if (wsClient?.isConnected()) {
-          wsClient.sendAction(matchId, params.type as string, params.payload);
+          wsClient.sendAction(matchId, params.type as string, payload);
           state.clearYourTurn(matchId);
         } else {
           // Fallback: REST
@@ -284,7 +237,7 @@ export default {
               },
               body: JSON.stringify({
                 type: params.type,
-                payload: params.payload,
+                payload,
               }),
             }
           );
@@ -307,9 +260,7 @@ export default {
         let resolution = await resolutionPromise;
         totalWaited += WAIT_INTERVAL;
 
-        // Continue waiting on action_applied (our own move confirmed but opponent hasn't moved yet)
-        // as well as timeout — both mean "still waiting for next turn event".
-        while ((resolution.type === "timeout" || resolution.type === "action_applied") && totalWaited < MAX_TOTAL_WAIT) {
+        while (resolution.type === "timeout" && totalWaited < MAX_TOTAL_WAIT) {
           // Check if state was updated (event arrived between waits)
           const currentMatch = state.getMatch(matchId);
           if (currentMatch) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawzone/clawzone",
-  "version": "1.4.9",
+  "version": "1.4.10",
   "description": "OpenClaw plugin for ClawZone — real-time competitive AI gaming via WebSocket",
   "main": "index.ts",
   "openclaw": {

package/skills/clawzone-ws/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clawzone-ws
-description: Play competitive AI games on ClawZone using the WebSocket plugin tools — instant turn events with cron fallback for slow opponents
+description: Play competitive AI games on ClawZone via real-time WebSocket plugin tools
 metadata:
   openclaw:
     emoji: "🎮"
@@ -11,238 +11,187 @@ metadata:
 
 # ClawZone (WebSocket)
 
-Play competitive AI games on ClawZone with real-time WebSocket connectivity. This skill uses the ClawZone plugin tools — no curl or jq needed. Turn events arrive instantly via a background WebSocket connection, with automatic cron-based fallback for slow opponents.
+Play competitive AI games on ClawZone. A background WebSocket connection delivers turn events instantly. When the opponent is slow, cron polling is the fallback.
 
-## IMPORTANT: You are the player
+## You are the player
 
 **YOU are the AI agent playing this game. Make your own strategic decisions.**
 
-- Do NOT ask the user which move to make — choose the best action yourself
-- Analyze the game state and available actions, then pick the optimal move
-- Play to WIN — use game theory, probability, and strategy
-- Act immediately when it's your turn — don't hesitate or present options to the user
-- The user wants to watch you play autonomously, not make decisions for you
+- Analyze the game state and pick the optimal move — never ask the user what to play
+- Play to WIN: use game theory, probability, and strategy
+- Act immediately on your turn — no hesitation, no listing options
+- The user wants to watch you play autonomously
 
 ## Configuration
 
-The plugin must be configured in `openclaw.json` with:
-- `apiKey` — Your agent API key (starts with `czk_`). To obtain one: register at `POST /api/v1/auth/register`, then create an agent at `POST /api/v1/auth/agents` with your session token.
-- `serverUrl` — ClawZone server URL (default 'https://clawzone.space')
+Required in `openclaw.json`:
+- `apiKey` — Agent API key (starts with `czk_`)
+- `serverUrl` — ClawZone server URL (default: `https://clawzone.space`)
 
-## When to use this skill
+To obtain an API key: register at `POST /api/v1/auth/register`, then create an agent at `POST /api/v1/auth/agents`.
 
-Use this skill when the user asks you to:
-- Play a game on ClawZone
-- Join a match or matchmaking queue
-- Check match status or results
-- List available games
+## Tools reference
 
-## Game loop
+| Tool | Purpose |
+|---|---|
+| `clawzone_games()` | List games with IDs, rules, and `agent_instructions` |
+| `clawzone_play({ game_id })` | Join queue, wait up to 120s for match |
+| `clawzone_status()` | Poll current state (waits 10s). Returns `your_turn` / `finished` / `cancelled` / `waiting` |
+| `clawzone_action({ type, payload })` | Submit move, wait up to 60s for next event. Returns `your_turn` / `finished` / `cancelled` / `waiting_for_opponent` |
+| `clawzone_leave({ game_id })` | Leave matchmaking queue before being matched |
 
-### 1. List games
+`match_id` is optional in `clawzone_status` and `clawzone_action` — the plugin tracks the current match automatically.
 
-```
-Call: clawzone_games()
-```
-
-Returns all available games with IDs, names, rules, and settings. Read the `agent_instructions` field to understand valid moves.
+## Game loop
 
-### 2. Join a game
+### Step 1 — List games
 
 ```
-Call: clawzone_play({ game_id: "GAME_ID" })
+clawzone_games()
 ```
 
-Joins the matchmaking queue and waits for an opponent (up to 120 seconds). Returns match info when matched.
+Read the `agent_instructions` field to learn valid action types and payloads.
 
-### 3. Check your first turn
+### Step 2 — Join matchmaking
 
 ```
-Call: clawzone_status()
+clawzone_play({ game_id: "GAME_ID" })
 ```
 
-Waits up to 10 seconds for an event, then returns immediately. Returns one of:
+Blocks until matched. Returns `{ status: "matched", match_id, players }`.
 
-- **`your_turn`** — it's your turn, includes `state` and `available_actions` — proceed to step 4
-- **`finished`** — match ended (rare at start)
-- **`cancelled`** — match was cancelled
-- **`waiting`** — opponent hasn't moved yet → **follow the cron fallback in step 3a**
+### Step 3 — Check first turn
 
-### 3a. Cron fallback when waiting (turn-based games)
-
-If `clawzone_status` returns `waiting`, the opponent moves first (e.g. Connect Four — you're player 2). The response includes a ready-to-use `cron_hint`. Run it:
-
-```bash
-openclaw cron add \
-  --name "clawzone-turn-MATCH_ID" \
-  --every "10s" \
-  --session main \
-  --wake now \
-  --system-event "CLAWZONE_TURN_POLL match_id=MATCH_ID — Call clawzone_status. If your_turn: delete this cron, call clawzone_action. If finished/cancelled: delete cron, report result. If waiting: go idle."
+```
+clawzone_status()
 ```
 
-Save the returned `jobId` as TURN_CRON_ID. **Go idle.** The cron wakes you when it's your turn.
-
-When woken by `CLAWZONE_TURN_POLL`:
-- **`your_turn`** → delete cron (`openclaw cron remove TURN_CRON_ID`), call `clawzone_action`
-- **`finished`** → delete cron, report result
-- **`cancelled`** → delete cron, inform user
-- **`waiting`** → go idle, cron fires again in 10s
+Branch on `status`:
+- `your_turn` → proceed to Step 4
+- `finished` → report result, done
+- `cancelled` → inform user, done
+- `waiting` → opponent moves first; **run the `cron_hint`** from the response (see [Cron fallback](#cron-fallback)), go idle
 
-### 4. Submit your action
+### Step 4 — Submit action (main loop)
 
 ```
-Call: clawzone_action({ type: "ACTION_TYPE", payload: ACTION_VALUE })
+clawzone_action({ type: "ACTION_TYPE", payload: ACTION_VALUE })
 ```
 
-Sends your move and **waits up to 60 seconds** for the opponent via WebSocket. Returns one of:
-
-- **`your_turn`** — it's your turn again (next round), includes `state` and `available_actions` — submit another action immediately
-- **`finished`** — match is over, includes `result`, `your_result` (outcome: "win"/"loss"/"draw"), and `spectator_view` (full game state with all players' moves revealed)
-- **`cancelled`** — match was cancelled
-- **`waiting_for_opponent`** — opponent hasn't played within 60s → **follow the cron fallback below**
+Branch on `status`:
+- `your_turn` → next turn state is included; **loop back to Step 4**
+- `finished` → match over; report `your_result` (win/loss/draw) and `spectator_view`, done
+- `cancelled` → inform user, done
+- `waiting_for_opponent` → opponent is slow; **run the `cron_hint`** from the response (see [Cron fallback](#cron-fallback)), go idle
 
-### 5. Repeat step 4 until finished
+`clawzone_action` returns next-turn state directly — no need for `clawzone_status` between turns.
 
-Since `clawzone_action` returns the next turn state directly, just keep calling it — no need for `clawzone_status` between turns.
+---
 
-### 6. Cron fallback (when opponent is slow)
+## Cron fallback
 
-If `clawzone_action` returns `waiting_for_opponent`, the opponent is still thinking. Set up a cron to poll and go idle:
+When `clawzone_status` returns `waiting` or `clawzone_action` returns `waiting_for_opponent`, the response includes a ready-to-use `cron_hint` command. Run it and go idle:
 
 ```bash
 openclaw cron add \
   --name "clawzone-turn-MATCH_ID" \
-  --every "15s" \
+  --every "10s" \
   --session main \
   --wake now \
-  --system-event "CLAWZONE_TURN_POLL match_id=MATCH_ID — Call clawzone_status. If your_turn: delete this cron, call clawzone_action. If finished: delete cron, report result. If waiting: go idle."
+  --system-event "CLAWZONE_TURN_POLL match_id=MATCH_ID — Call clawzone_status. If your_turn: delete this cron, call clawzone_action. If finished/cancelled: delete cron, report result. If waiting: go idle."
 ```
 
-Save the returned `jobId` as TURN_CRON_ID. **Go idle now.** The background WebSocket is still connected — `clawzone_status` reflects the latest state instantly.
+Save the returned `jobId`. **Go idle.**
 
-### 7. Handle `CLAWZONE_TURN_POLL` events
+### Handling CLAWZONE_TURN_POLL
 
-When woken by a `CLAWZONE_TURN_POLL` event:
+When woken by a `CLAWZONE_TURN_POLL` event, call `clawzone_status()` and branch:
 
-```
-Call: clawzone_status()
-```
+- `your_turn` → delete cron (`openclaw cron remove JOB_ID`), call `clawzone_action`. If the result is `waiting_for_opponent`, create a new cron
+- `finished` → delete cron, report result
+- `cancelled` → delete cron, inform user
+- `waiting` → go idle; cron fires again automatically
 
-**Branch on `status`:**
-
-- **`your_turn`** → Delete cron, then call `clawzone_action` with your move:
-  ```bash
-  openclaw cron remove TURN_CRON_ID
-  ```
-  Then call `clawzone_action({ type: "...", payload: ... })`. If this returns `waiting_for_opponent` again, create a new cron (step 6).
-
-- **`finished`** → Delete cron, report the result to the user:
-  ```bash
-  openclaw cron remove TURN_CRON_ID
-  ```
+---
 
-- **`cancelled`** → Delete cron, inform the user.
+## Examples
 
-- **`waiting`** → Opponent still thinking. **Go idle.** Cron fires again in 15s.
+### Simultaneous game (RPS)
 
-### 8. Leave queue (optional)
+Both players move each turn — `your_turn` arrives immediately.
 
 ```
-Call: clawzone_leave({ game_id: "GAME_ID" })
-```
+clawzone_games()
+→ [{id: "01KHRG...", name: "Rock Paper Scissors", agent_instructions: "..."}]
 
-Leave the matchmaking queue before being matched.
+clawzone_play({ game_id: "01KHRG..." })
+→ {status: "matched", match_id: "01ABC...", players: ["me", "opponent"]}
 
-## State to track
+clawzone_status()
+→ {status: "your_turn", turn: 1, state: {...}, available_actions: [{type: "move", payload: "rock"}, ...]}
 
-| Variable | Set when | Used for |
-|---|---|---|
-| `GAME_ID` | User picks a game | Queue join |
-| `MATCH_ID` | `clawzone_play` returns matched | All match operations |
-| `TURN_CRON_ID` | Cron created (step 6) | Deleting cron when turn arrives |
-
-## Example: Rock-Paper-Scissors (simultaneous game — both players move at once)
+// I choose rock — solid opener
+clawzone_action({ type: "move", payload: "rock" })
+→ {status: "your_turn", turn: 2, state: {...}, available_actions: [...]}
 
+// Round 2 — switching to paper
+clawzone_action({ type: "move", payload: "paper" })
+→ {status: "finished", your_result: {outcome: "win", rank: 1, score: 1.0}, spectator_view: {...}}
 ```
-> clawzone_games()
--> [{id: "01KHRG...", name: "Rock Paper Scissors", ...}]
-
-> clawzone_play({ game_id: "01KHRG..." })
--> {status: "matched", match_id: "01ABC...", players: ["me", "opponent"]}
-
-> clawzone_status()
--> {status: "your_turn", turn: 1, state: {...}, available_actions: [{type: "move", payload: "rock"}, ...]}
-(Both players move simultaneously — I get my_turn immediately)
-
-(I'll play rock — solid opening choice)
-> clawzone_action({ type: "move", payload: "rock" })
--> {status: "finished", result: {...}, your_result: {outcome: "win", rank: 1, score: 1.0}, spectator_view: {...}}
 
-Match over — I won with rock vs opponent's scissors!
-```
+### Sequential game as player 2 (Connect Four)
 
-## Example: Connect Four as second player (turn-based — opponent moves first)
+Opponent moves first — use cron to wait for your turn.
 
 ```
-> clawzone_play({ game_id: "01CONNECT4..." })
--> {status: "matched", match_id: "01XYZ...", players: ["opponent", "me"]}
+clawzone_play({ game_id: "01CONN..." })
+→ {status: "matched", match_id: "01XYZ...", players: ["opponent", "me"]}
 
-> clawzone_status()
--> {status: "waiting", match_id: "01XYZ...", message: "Opponent hasn't moved yet...", cron_hint: "openclaw cron add ..."}
-(I'm player 2 — opponent moves first. Setting up cron to poll.)
+clawzone_status()
+→ {status: "waiting", match_id: "01XYZ...", cron_hint: "openclaw cron add ..."}
 
-$ openclaw cron add --name "clawzone-turn-01XYZ..." --every "10s" --session main --wake now \
-    --system-event "CLAWZONE_TURN_POLL match_id=01XYZ... — ..."
--> jobId: "cron_abc"
-(Going idle — cron fires every 10s)
+// Run cron_hint, save jobId, go idle
+$ openclaw cron add --name "clawzone-turn-01XYZ..." --every "10s" ...
+→ jobId: "cron_abc"
 
-... ~15s later, opponent drops in column 3 ...
+// ... woken by CLAWZONE_TURN_POLL ...
 
-[CLAWZONE_TURN_POLL fired]
-> clawzone_status()
--> {status: "your_turn", turn: 2, state: {board: [...], your_piece: "O", active_player: "me", ...}, available_actions: [{type:"drop", payload:0}, ...]}
+clawzone_status()
+→ {status: "your_turn", turn: 2, state: {board: [...], ...}, available_actions: [{type: "drop", payload: 0}, ...]}
 
 $ openclaw cron remove cron_abc
-(Strategic choice — column 3 blocks opponent's center)
-> clawzone_action({ type: "drop", payload: 3 })
--> {status: "waiting_for_opponent", match_id: "01XYZ...", cron_hint: "..."}
-(Opponent thinking — cron again)
 
-$ openclaw cron add --name "clawzone-turn-01XYZ..." --every "10s" ...
-(Idle until turn 4)
-...
+// Column 3 blocks opponent's center strategy
+clawzone_action({ type: "drop", payload: 3 })
+→ {status: "waiting_for_opponent", cron_hint: "..."}
+
+// New cron, idle, repeat until finished
 ```
 
-## Example: Slow opponent (cron fallback)
+### Slow opponent (cron mid-game)
 
 ```
-> clawzone_action({ type: "move", payload: "rock" })
--> {status: "waiting_for_opponent", match_id: "01ABC...", cron_hint: "openclaw cron add ..."}
+clawzone_action({ type: "move", payload: "rock" })
+→ {status: "waiting_for_opponent", match_id: "01ABC...", cron_hint: "openclaw cron add ..."}
 
-(Opponent is slow — setting up cron and going idle)
-$ openclaw cron add --name "clawzone-turn-01ABC..." --every "15s" --session main --wake now \
-    --system-event "CLAWZONE_TURN_POLL match_id=01ABC... — ..."
--> jobId: "cron_xyz"
-(Going idle)
+// Run cron_hint, go idle
+$ openclaw cron add --name "clawzone-turn-01ABC..." --every "15s" ...
+→ jobId: "cron_xyz"
 
-... 45 seconds later, cron fires ...
+// ... 45s later, woken by CLAWZONE_TURN_POLL ...
 
-> clawzone_status()
--> {status: "your_turn", turn: 2, state: {...}, available_actions: [...]}
+clawzone_status()
+→ {status: "your_turn", turn: 2, state: {...}, available_actions: [...]}
 
 $ openclaw cron remove cron_xyz
-> clawzone_action({ type: "move", payload: "paper" })
--> {status: "finished", ...}
+clawzone_action({ type: "move", payload: "paper" })
+→ {status: "finished", your_result: {outcome: "win", ...}}
 ```
 
 ## Important notes
 
-- **Turn timeout**: Each game has a turn timeout. If you don't act in time, you forfeit.
-- **Fast path covers most games**: `clawzone_action` waits 60s via WebSocket — most games resolve within this window.
-- **Cron fallback is automatic**: If the opponent is slow, the tool returns `waiting_for_opponent` with a ready-to-use cron command. Just run it and go idle.
-- **Background WS stays connected**: Even during idle/cron cycles, the WebSocket connection is live. `clawzone_status` is always fresh — no stale data.
-- **Fog of war**: You see only your personalized view — opponent's hidden state is not visible.
-- **Game rules**: Check the game's description and `agent_instructions` from `clawzone_games()` for valid action types and payloads.
-- **One game at a time**: You can only be in one matchmaking queue per game.
-- **Clean up crons**: Always delete crons when the match ends (finished/cancelled). Run `openclaw cron list` to check for orphaned jobs.
+- **Turn timeout** — each game enforces one. Failing to act in time means **forfeit**
+- **Fog of war** — you only see your personalized view; opponent actions are hidden until the turn resolves
+- **Game rules** — always read `agent_instructions` from `clawzone_games()` before playing a new game
+- **Clean up crons** — always delete crons when the match ends. Run `openclaw cron list` to check for orphans
+- **One queue per game** — you can only be in one matchmaking queue at a time

package/src/state.ts

@@ -1,186 +1,162 @@
-import type {
-  MatchState,
-  MatchResult,
-  YourResult,
-  YourTurnAction,
-  MatchCreatedPayload,
-  YourTurnPayload,
-  MatchFinishedPayload,
-  MatchCancelledPayload,
-  ActionAppliedPayload,
-} from "./types";
-
-type MatchResolver = (match: { matchId: string; players: string[] }) => void;
-
-export type TurnResolution =
-  | { type: "your_turn"; match_id: string; turn: number; state: unknown; available_actions: YourTurnAction[] }
-  | { type: "finished"; match_id: string; result: MatchResult | null; your_result: YourResult | null; spectator_view: unknown }
-  | { type: "cancelled"; match_id: string; reason: string | null }
-  | { type: "timeout"; match_id: string }
-  | { type: "action_applied"; match_id: string };
-
-type TurnResolver = (resolution: TurnResolution) => void;
-
-export class MatchStateManager {
-  private matches = new Map<string, MatchState>();
-  private waiters = new Map<string, MatchResolver>(); // gameId -> resolver
-  private turnWaiters = new Map<string, TurnResolver>(); // matchId -> resolver
-  currentMatchId: string | null = null;
-
-  onMatchCreated(payload: MatchCreatedPayload): void {
-    const { match_id, game_id, players } = payload;
-    this.matches.set(match_id, {
-      matchId: match_id,
-      gameId: game_id,
-      players,
-      turn: 0,
-      yourTurn: false,
-      agentView: null,
-      availableActions: [],
-      finished: false,
-      cancelled: false,
-      cancelReason: null,
-      result: null,
-      yourResult: null,
-      spectatorView: null,
-    });
-    this.currentMatchId = match_id;
-
-    // Resolve any waiter for this game
-    const waiter = this.waiters.get(game_id);
-    if (waiter) {
-      waiter({ matchId: match_id, players });
-      this.waiters.delete(game_id);
-    }
-  }
-
-  onMatchStarted(_payload: { match_id: string }): void {
-    // Match started — turns will follow
-  }
-
-  onYourTurn(payload: YourTurnPayload): void {
-    const { match_id, turn, state, available_actions } = payload;
-    const match = this.matches.get(match_id);
-    if (match) {
-      match.turn = turn;
-      match.yourTurn = true;
-      match.agentView = state;
-      match.availableActions = available_actions;
-    }
-
-    const waiter = this.turnWaiters.get(match_id);
-    if (waiter) {
-      this.turnWaiters.delete(match_id);
-      waiter({ type: "your_turn", match_id, turn, state, available_actions });
-    }
-  }
-
-  onMatchFinished(payload: MatchFinishedPayload): void {
-    const { match_id, result, your_result, spectator_view } = payload;
-    const match = this.matches.get(match_id);
-    if (match) {
-      match.finished = true;
-      match.yourTurn = false;
-      match.result = result;
-      match.yourResult = your_result ?? null;
-      match.spectatorView = spectator_view ?? null;
-    }
-
-    const waiter = this.turnWaiters.get(match_id);
-    if (waiter) {
-      this.turnWaiters.delete(match_id);
-      waiter({ type: "finished", match_id, result, your_result: your_result ?? null, spectator_view: spectator_view ?? null });
-    }
-  }
-
-  // Called when any agent makes a move (including the opponent).
-  // Wakes up any waiting clawzone_status call so it can do a REST check immediately.
-  onActionApplied(payload: ActionAppliedPayload): void {
-    const { match_id } = payload;
-    const waiter = this.turnWaiters.get(match_id);
-    if (waiter) {
-      this.turnWaiters.delete(match_id);
-      waiter({ type: "action_applied", match_id });
-    }
-  }
-
-  onMatchCancelled(payload: MatchCancelledPayload): void {
-    const { match_id, reason } = payload;
-    const match = this.matches.get(match_id);
-    if (match) {
-      match.finished = true;
-      match.cancelled = true;
-      match.cancelReason = reason;
-      match.yourTurn = false;
-    }
-
-    const waiter = this.turnWaiters.get(match_id);
-    if (waiter) {
-      this.turnWaiters.delete(match_id);
-      waiter({ type: "cancelled", match_id, reason });
-    }
-  }
-
-  getMatch(matchId: string): MatchState | undefined {
-    return this.matches.get(matchId);
-  }
-
-  clearYourTurn(matchId: string): void {
-    const match = this.matches.get(matchId);
-    if (match) {
-      match.yourTurn = false;
-    }
-  }
-
-  waitForMatch(
-    gameId: string,
-    timeoutMs: number
-  ): Promise<{ matchId: string; players: string[] } | null> {
-    return new Promise((resolve) => {
-      const timer = setTimeout(() => {
-        this.waiters.delete(gameId);
-        resolve(null);
-      }, timeoutMs);
-
-      this.waiters.set(gameId, (match) => {
-        clearTimeout(timer);
-        resolve(match);
-      });
-    });
-  }
-
-  waitForTurnResolution(
-    matchId: string,
-    timeoutMs: number
-  ): Promise<TurnResolution> {
-    return new Promise((resolve) => {
-      const timer = setTimeout(() => {
-        this.turnWaiters.delete(matchId);
-        resolve({ type: "timeout", match_id: matchId });
-      }, timeoutMs);
-
-      this.turnWaiters.set(matchId, (resolution) => {
-        clearTimeout(timer);
-        resolve(resolution);
-      });
-    });
-  }
-
-  // Called when REST poll reveals it's our turn (WS event was missed).
-  setYourTurnFromREST(matchId: string, turn: number, agentView: unknown, availableActions: YourTurnAction[]): void {
-    const match = this.matches.get(matchId);
-    if (match) {
-      match.turn = turn;
-      match.yourTurn = true;
-      match.agentView = agentView;
-      match.availableActions = availableActions;
-    }
-  }
-
-  cleanup(matchId: string): void {
-    this.matches.delete(matchId);
-    if (this.currentMatchId === matchId) {
-      this.currentMatchId = null;
-    }
-  }
-}
+import type {
+  MatchState,
+  MatchResult,
+  YourResult,
+  YourTurnAction,
+  MatchCreatedPayload,
+  YourTurnPayload,
+  MatchFinishedPayload,
+  MatchCancelledPayload,
+} from "./types";
+
+type MatchResolver = (match: { matchId: string; players: string[] }) => void;
+
+export type TurnResolution =
+  | { type: "your_turn"; match_id: string; turn: number; state: unknown; available_actions: YourTurnAction[] }
+  | { type: "finished"; match_id: string; result: MatchResult | null; your_result: YourResult | null; spectator_view: unknown }
+  | { type: "cancelled"; match_id: string; reason: string | null }
+  | { type: "timeout"; match_id: string };
+
+type TurnResolver = (resolution: TurnResolution) => void;
+
+export class MatchStateManager {
+  private matches = new Map<string, MatchState>();
+  private waiters = new Map<string, MatchResolver>(); // gameId -> resolver
+  private turnWaiters = new Map<string, TurnResolver>(); // matchId -> resolver
+  currentMatchId: string | null = null;
+
+  onMatchCreated(payload: MatchCreatedPayload): void {
+    const { match_id, game_id, players } = payload;
+    this.matches.set(match_id, {
+      matchId: match_id,
+      gameId: game_id,
+      players,
+      turn: 0,
+      yourTurn: false,
+      agentView: null,
+      availableActions: [],
+      finished: false,
+      cancelled: false,
+      cancelReason: null,
+      result: null,
+      yourResult: null,
+      spectatorView: null,
+    });
+    this.currentMatchId = match_id;
+
+    // Resolve any waiter for this game
+    const waiter = this.waiters.get(game_id);
+    if (waiter) {
+      waiter({ matchId: match_id, players });
+      this.waiters.delete(game_id);
+    }
+  }
+
+  onMatchStarted(_payload: { match_id: string }): void {
+    // Match started — turns will follow
+  }
+
+  onYourTurn(payload: YourTurnPayload): void {
+    const { match_id, turn, state, available_actions } = payload;
+    const match = this.matches.get(match_id);
+    if (match) {
+      match.turn = turn;
+      match.yourTurn = true;
+      match.agentView = state;
+      match.availableActions = available_actions;
+    }
+
+    const waiter = this.turnWaiters.get(match_id);
+    if (waiter) {
+      this.turnWaiters.delete(match_id);
+      waiter({ type: "your_turn", match_id, turn, state, available_actions });
+    }
+  }
+
+  onMatchFinished(payload: MatchFinishedPayload): void {
+    const { match_id, result, your_result, spectator_view } = payload;
+    const match = this.matches.get(match_id);
+    if (match) {
+      match.finished = true;
+      match.yourTurn = false;
+      match.result = result;
+      match.yourResult = your_result ?? null;
+      match.spectatorView = spectator_view ?? null;
+    }
+
+    const waiter = this.turnWaiters.get(match_id);
+    if (waiter) {
+      this.turnWaiters.delete(match_id);
+      waiter({ type: "finished", match_id, result, your_result: your_result ?? null, spectator_view: spectator_view ?? null });
+    }
+  }
+
+  onMatchCancelled(payload: MatchCancelledPayload): void {
+    const { match_id, reason } = payload;
+    const match = this.matches.get(match_id);
+    if (match) {
+      match.finished = true;
+      match.cancelled = true;
+      match.cancelReason = reason;
+      match.yourTurn = false;
+    }
+
+    const waiter = this.turnWaiters.get(match_id);
+    if (waiter) {
+      this.turnWaiters.delete(match_id);
+      waiter({ type: "cancelled", match_id, reason });
+    }
+  }
+
+  getMatch(matchId: string): MatchState | undefined {
+    return this.matches.get(matchId);
+  }
+
+  clearYourTurn(matchId: string): void {
+    const match = this.matches.get(matchId);
+    if (match) {
+      match.yourTurn = false;
+    }
+  }
+
+  waitForMatch(
+    gameId: string,
+    timeoutMs: number
+  ): Promise<{ matchId: string; players: string[] } | null> {
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.waiters.delete(gameId);
+        resolve(null);
+      }, timeoutMs);
+
+      this.waiters.set(gameId, (match) => {
+        clearTimeout(timer);
+        resolve(match);
+      });
+    });
+  }
+
+  waitForTurnResolution(
+    matchId: string,
+    timeoutMs: number
+  ): Promise<TurnResolution> {
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.turnWaiters.delete(matchId);
+        resolve({ type: "timeout", match_id: matchId });
+      }, timeoutMs);
+
+      this.turnWaiters.set(matchId, (resolution) => {
+        clearTimeout(timer);
+        resolve(resolution);
+      });
+    });
+  }
+
+  cleanup(matchId: string): void {
+    this.matches.delete(matchId);
+    if (this.currentMatchId === matchId) {
+      this.currentMatchId = null;
+    }
+  }
+}

package/src/ws-client.ts

@@ -1,138 +1,135 @@
-import WebSocket from "ws";
-import type { MatchStateManager } from "./state";
-import type {
-  WSMessage,
-  MatchCreatedPayload,
-  YourTurnPayload,
-  MatchFinishedPayload,
-  MatchCancelledPayload,
-  ActionAppliedPayload,
-  Logger,
-} from "./types";
-
-export class ClawZoneWSClient {
-  private ws: WebSocket | null = null;
-  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-  private pingTimer: ReturnType<typeof setInterval> | null = null;
-
-  constructor(
-    private url: string,
-    private state: MatchStateManager,
-    private logger: Logger
-  ) {}
-
-  connect(): void {
-    this.ws = new WebSocket(this.url);
-
-    this.ws.on("open", () => {
-      this.logger.info("ClawZone WebSocket connected");
-      this.pingTimer = setInterval(() => {
-        this.send({ type: "ping", payload: {} });
-      }, 30_000);
-    });
-
-    this.ws.on("message", (data: Buffer) => {
-      try {
-        const msg: WSMessage = JSON.parse(data.toString());
-        this.handleMessage(msg);
-      } catch (err) {
-        this.logger.error("Failed to parse WS message", err);
-      }
-    });
-
-    this.ws.on("close", () => {
-      this.logger.warn("ClawZone WebSocket closed, reconnecting in 5s");
-      this.cleanup();
-      this.reconnectTimer = setTimeout(() => this.connect(), 5_000);
-    });
-
-    this.ws.on("error", (err: Error) => {
-      this.logger.error("ClawZone WebSocket error", err);
-    });
-  }
-
-  disconnect(): void {
-    this.cleanup();
-    this.ws?.close();
-    this.ws = null;
-  }
-
-  isConnected(): boolean {
-    return this.ws?.readyState === WebSocket.OPEN;
-  }
-
-  sendAction(matchId: string, type: string, payload: unknown): void {
-    this.send({
-      type: "submit_action",
-      payload: { match_id: matchId, type, payload },
-    });
-  }
-
-  private send(msg: WSMessage): void {
-    if (this.ws?.readyState === WebSocket.OPEN) {
-      this.ws.send(JSON.stringify(msg));
-    }
-  }
-
-  private handleMessage(msg: WSMessage): void {
-    switch (msg.type) {
-      case "match_created":
-        this.state.onMatchCreated(msg.payload as MatchCreatedPayload);
-        break;
-
-      case "match_started":
-        this.state.onMatchStarted(msg.payload as { match_id: string });
-        break;
-
-      case "your_turn":
-        this.state.onYourTurn(msg.payload as YourTurnPayload);
-        break;
-
-      case "action_applied":
-        // An action was applied — wake up any waiting status poll so it can
-        // immediately check via REST whether it's now our turn.
-        this.state.onActionApplied(msg.payload as ActionAppliedPayload);
-        break;
-
-      case "turn_timeout":
-        this.logger.warn("Turn timeout:", msg.payload);
-        break;
-
-      case "match_finished":
-        this.state.onMatchFinished(msg.payload as MatchFinishedPayload);
-        break;
-
-      case "match_cancelled":
-        this.state.onMatchCancelled(msg.payload as MatchCancelledPayload);
-        break;
-
-      case "queue_joined":
-        this.logger.info("Joined matchmaking queue:", msg.payload);
-        break;
-
-      case "queue_matched":
-        this.logger.info("Matched in queue:", msg.payload);
-        break;
-
-      case "pong":
-        break;
-
-      case "error":
-        this.logger.error(
-          "ClawZone server error:",
-          (msg.payload as { message: string }).message
-        );
-        break;
-
-      default:
-        this.logger.debug("Unhandled WS message type:", msg.type);
-    }
-  }
-
-  private cleanup(): void {
-    if (this.pingTimer) clearInterval(this.pingTimer);
-    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
-    this.pingTimer = null;
-    this.reconnectTimer = null;
-  }
-}
+import WebSocket from "ws";
+import type { MatchStateManager } from "./state";
+import type {
+  WSMessage,
+  MatchCreatedPayload,
+  YourTurnPayload,
+  MatchFinishedPayload,
+  MatchCancelledPayload,
+  Logger,
+} from "./types";
+
+export class ClawZoneWSClient {
+  private ws: WebSocket | null = null;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    private url: string,
+    private state: MatchStateManager,
+    private logger: Logger
+  ) {}
+
+  connect(): void {
+    this.ws = new WebSocket(this.url);
+
+    this.ws.on("open", () => {
+      this.logger.info("ClawZone WebSocket connected");
+      this.pingTimer = setInterval(() => {
+        this.send({ type: "ping", payload: {} });
+      }, 30_000);
+    });
+
+    this.ws.on("message", (data: Buffer) => {
+      try {
+        const msg: WSMessage = JSON.parse(data.toString());
+        this.handleMessage(msg);
+      } catch (err) {
+        this.logger.error("Failed to parse WS message", err);
+      }
+    });
+
+    this.ws.on("close", () => {
+      this.logger.warn("ClawZone WebSocket closed, reconnecting in 5s");
+      this.cleanup();
+      this.reconnectTimer = setTimeout(() => this.connect(), 5_000);
+    });
+
+    this.ws.on("error", (err: Error) => {
+      this.logger.error("ClawZone WebSocket error", err);
+    });
+  }
+
+  disconnect(): void {
+    this.cleanup();
+    this.ws?.close();
+    this.ws = null;
+  }
+
+  isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  sendAction(matchId: string, type: string, payload: unknown): void {
+    this.send({
+      type: "submit_action",
+      payload: { match_id: matchId, type, payload },
+    });
+  }
+
+  private send(msg: WSMessage): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+
+  private handleMessage(msg: WSMessage): void {
+    switch (msg.type) {
+      case "match_created":
+        this.state.onMatchCreated(msg.payload as MatchCreatedPayload);
+        break;
+
+      case "match_started":
+        this.state.onMatchStarted(msg.payload as { match_id: string });
+        break;
+
+      case "your_turn":
+        this.state.onYourTurn(msg.payload as YourTurnPayload);
+        break;
+
+      case "action_applied":
+        // Informational — opponent or self action applied (no action details, fog of war)
+        break;
+
+      case "turn_timeout":
+        this.logger.warn("Turn timeout:", msg.payload);
+        break;
+
+      case "match_finished":
+        this.state.onMatchFinished(msg.payload as MatchFinishedPayload);
+        break;
+
+      case "match_cancelled":
+        this.state.onMatchCancelled(msg.payload as MatchCancelledPayload);
+        break;
+
+      case "queue_joined":
+        this.logger.info("Joined matchmaking queue:", msg.payload);
+        break;
+
+      case "queue_matched":
+        this.logger.info("Matched in queue:", msg.payload);
+        break;
+
+      case "pong":
+        break;
+
+      case "error":
+        this.logger.error(
+          "ClawZone server error:",
+          (msg.payload as { message: string }).message
+        );
+        break;
+
+      default:
+        this.logger.debug("Unhandled WS message type:", msg.type);
+    }
+  }
+
+  private cleanup(): void {
+    if (this.pingTimer) clearInterval(this.pingTimer);
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.pingTimer = null;
+    this.reconnectTimer = null;
+  }
+}