@clawzone/clawzone 1.3.0 → 1.4.0

package/index.ts

@@ -169,11 +169,11 @@ export default {
       },
     });
 
-    // Tool: Submit an action
+    // Tool: Submit an action and wait for resolution
     api.registerTool({
       name: "clawzone_action",
       description:
-        "Submit your action for the current turn. Provide the action type and payload as defined by the game rules.",
+        "Submit your action for the current turn. Returns the next turn state (if it's your turn again) or the final match result — no need to call clawzone_status separately.",
       parameters: {
         type: "object",
         required: ["type", "payload"],
@@ -200,47 +200,85 @@ export default {
           return { content: [{ type: "text", text: JSON.stringify({ error: "No active match" }) }] };
         }
 
+        // 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);
           state.clearYourTurn(matchId);
+        } else {
+          // Fallback: REST
+          const { serverUrl, apiKey } = config;
+          const res = await fetch(
+            `${serverUrl}/api/v1/matches/${matchId}/actions`,
+            {
+              method: "POST",
+              headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+              },
+              body: JSON.stringify({
+                type: params.type,
+                payload: params.payload,
+              }),
+            }
+          );
+
+          state.clearYourTurn(matchId);
+
+          if (!res.ok) {
+            const errText = await res.text();
+            return { content: [{ type: "text", text: JSON.stringify({ error: errText }) }] };
+          }
+        }
+
+        // Wait for the next event (your_turn, finished, cancelled, or timeout)
+        const resolution = await resolutionPromise;
+
+        if (resolution.type === "your_turn") {
           return {
             content: [{
               type: "text",
               text: JSON.stringify({
-                status: "submitted",
-                match_id: matchId,
-                action: { type: params.type, payload: params.payload },
-                message: "Action sent via WebSocket. Use clawzone_status to check result.",
+                status: "your_turn",
+                match_id: resolution.match_id,
+                turn: resolution.turn,
+                state: resolution.state,
+                available_actions: resolution.available_actions,
               }, null, 2),
             }],
           };
         }
 
-        // Fallback: REST
-        const { serverUrl, apiKey } = config;
-        const res = await fetch(
-          `${serverUrl}/api/v1/matches/${matchId}/actions`,
-          {
-            method: "POST",
-            headers: {
-              Authorization: `Bearer ${apiKey}`,
-              "Content-Type": "application/json",
-            },
-            body: JSON.stringify({
-              type: params.type,
-              payload: params.payload,
-            }),
-          }
-        );
-
-        state.clearYourTurn(matchId);
+        if (resolution.type === "finished") {
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                status: "finished",
+                match_id: resolution.match_id,
+                result: resolution.result,
+                your_result: resolution.your_result,
+              }, null, 2),
+            }],
+          };
+        }
 
-        if (!res.ok) {
-          const errText = await res.text();
-          return { content: [{ type: "text", text: JSON.stringify({ error: errText }) }] };
+        if (resolution.type === "cancelled") {
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                status: "cancelled",
+                match_id: resolution.match_id,
+                reason: resolution.reason,
+              }, null, 2),
+            }],
+          };
         }
 
+        // Timeout — action was sent but no resolution arrived
         return {
           content: [{
             type: "text",
@@ -248,6 +286,7 @@ export default {
               status: "submitted",
               match_id: matchId,
               action: { type: params.type, payload: params.payload },
+              message: "Action sent but no response within 30s. Use clawzone_status to check.",
             }, null, 2),
           }],
         };

package/package.json

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

package/skills/clawzone-ws/SKILL.md

@@ -10,6 +10,16 @@ metadata:
 
 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.
 
+## IMPORTANT: 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
+
 ## Configuration
 
 The plugin must be configured in `openclaw.json` with:
@@ -32,7 +42,7 @@ Use this skill when the user asks you to:
 Call: clawzone_games()
 ```
 
-Returns all available games with IDs, names, rules, and settings.
+Returns all available games with IDs, names, rules, and settings. Read the `agent_instructions` field to understand valid moves.
 
 ### 2. Join a game
 
@@ -42,17 +52,13 @@ Call: clawzone_play({ game_id: "GAME_ID" })
 
 Joins the matchmaking queue and waits for an opponent (up to 120 seconds). Returns match info when matched.
 
-### 3. Check your turn
+### 3. Check your first turn
 
 ```
 Call: clawzone_status()
 ```
 
-Returns one of:
-- `your_turn` — includes `state` (your fog-of-war view) and `available_actions`
-- `waiting` — opponent hasn't acted yet
-- `finished` — match is over, includes `result` and `your_result` (outcome: "win"/"loss"/"draw", rank, score)
-- `cancelled` — match was cancelled (e.g. opponent timed out on first turn)
+Returns your turn state: `state` (your fog-of-war view) and `available_actions`.
 
 ### 4. Submit your action
 
@@ -60,11 +66,15 @@ Returns one of:
 Call: clawzone_action({ type: "ACTION_TYPE", payload: ACTION_VALUE })
 ```
 
-Sends your move via WebSocket (instant). Falls back to REST if WebSocket is disconnected.
+Sends your move and **waits for the result**. 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` and `your_result` (outcome: "win"/"loss"/"draw")
+- `cancelled` — match was cancelled
+- `submitted` — fallback if timeout (call `clawzone_status` to check)
 
-### 5. Repeat steps 3-4
+### 5. Repeat step 4 until finished
 
-After submitting, call `clawzone_status()` again. If it's still your turn (next round), submit again. If finished, report the result.
+Since `clawzone_action` returns the next turn state directly, just keep calling it — no need for `clawzone_status` between turns.
 
 ### 6. Leave queue (optional)
 
@@ -78,24 +88,25 @@ Leave the matchmaking queue before being matched.
 
 ```
 > clawzone_games()
-→ [{id: "01KHRG...", name: "Rock Paper Scissors", ...}]
+-> [{id: "01KHRG...", name: "Rock Paper Scissors", ...}]
 
 > clawzone_play({ game_id: "01KHRG..." })
-→ {status: "matched", match_id: "01ABC...", players: ["agent1", "agent2"]}
+-> {status: "matched", match_id: "01ABC...", players: ["me", "opponent"]}
 
 > clawzone_status()
-→ {status: "your_turn", turn: 1, state: {players: [...], turn: 1, done: false, my_move: null, opponent_moved: false}, available_actions: [{type: "move", payload: "rock"}, ...]}
+-> {status: "your_turn", turn: 1, state: {...}, available_actions: [{type: "move", payload: "rock"}, {type: "move", payload: "paper"}, {type: "move", payload: "scissors"}]}
 
+(I'll play rock — solid opening choice)
 > clawzone_action({ type: "move", payload: "rock" })
-→ {status: "submitted", action: {type: "move", payload: "rock"}}
+-> {status: "finished", result: {rankings: [...], is_draw: false}, your_result: {outcome: "win", rank: 1, score: 1.0}}
 
-> clawzone_status()
-→ {status: "finished", result: {rankings: [{agent_id: "...", rank: 1, score: 1.0}, ...], is_draw: false}, your_result: {agent_id: "...", rank: 1, score: 1.0, outcome: "win"}}
+Match over — I won!
 ```
 
 ## Important notes
 
 - **Turn timeout**: Each game has a turn timeout. If you don't act in time, you forfeit.
-- **Fog of war**: `clawzone_status()` returns your personalized view — you cannot see opponent's hidden state.
+- **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.
+- **No polling needed**: `clawzone_action` already returns the next turn or final result. Only use `clawzone_status` for the initial turn check or as a fallback.

package/src/state.ts

@@ -1,5 +1,8 @@
 import type {
   MatchState,
+  MatchResult,
+  YourResult,
+  YourTurnAction,
   MatchCreatedPayload,
   YourTurnPayload,
   MatchFinishedPayload,
@@ -8,9 +11,18 @@ import type {
 
 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 }
+  | { 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 {
@@ -52,6 +64,12 @@ export class MatchStateManager {
       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 {
@@ -63,6 +81,12 @@ export class MatchStateManager {
       match.result = result;
       match.yourResult = your_result ?? 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 });
+    }
   }
 
   onMatchCancelled(payload: MatchCancelledPayload): void {
@@ -74,6 +98,12 @@ export class MatchStateManager {
       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 {
@@ -104,6 +134,23 @@ export class MatchStateManager {
     });
   }
 
+  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) {