@clawzone/clawzone 1.4.6 → 1.4.7

package/index.ts

@@ -1,397 +1,412 @@
-import { ClawZoneWSClient } from "./src/ws-client";
-import { MatchStateManager } from "./src/state";
-import type { PluginAPI } from "./src/types";
-
-export default {
-  id: "clawzone",
-  name: "ClawZone Gaming",
-
-  register(api: PluginAPI) {
-    const state = new MatchStateManager();
-    let wsClient: ClawZoneWSClient | null = null;
-
-    const config = api.pluginConfig as { apiKey?: string; serverUrl?: string };
-
-    // Background service: maintains WebSocket connection
-    api.registerService({
-      id: "clawzone-ws",
-      start: () => {
-        const { apiKey, serverUrl } = config;
-        if (!apiKey || !serverUrl) {
-          api.logger.warn("ClawZone plugin: missing apiKey or serverUrl in config");
-          return;
-        }
-
-        const wsProtocol = serverUrl.startsWith("https") ? "wss" : "ws";
-        const host = serverUrl.replace(/^https?:\/\//, "");
-        const wsUrl = `${wsProtocol}://${host}/api/v1/ws?api_key=${apiKey}`;
-
-        wsClient = new ClawZoneWSClient(wsUrl, state, api.logger);
-        wsClient.connect();
-      },
-      stop: () => {
-        wsClient?.disconnect();
-      },
-    });
-
-    // Tool: List available games
-    api.registerTool({
-      name: "clawzone_games",
-      description:
-        "List available games on ClawZone with rules and agent_instructions. Call once per session.",
-      parameters: { type: "object", properties: {} },
-      execute: async () => {
-        const res = await fetch(`${config.serverUrl}/api/v1/games`);
-        const data = await res.json();
-        // Filter to essential fields to reduce context size
-        const games = Array.isArray(data) ? data : (data.games ?? data);
-        const filtered = (Array.isArray(games) ? games : []).map((g: Record<string, unknown>) => ({
-          id: g.id,
-          name: g.name,
-          description: g.description,
-          agent_instructions: g.agent_instructions,
-          min_players: g.min_players,
-          max_players: g.max_players,
-        }));
-        return { content: [{ type: "text", text: JSON.stringify(filtered) }] };
-      },
-    });
-
-    // Tool: Join matchmaking and wait for a match
-    api.registerTool({
-      name: "clawzone_play",
-      description:
-        "Join the matchmaking queue and wait for an opponent (up to 120s). After matching, call clawzone_status then clawzone_action to play.",
-      parameters: {
-        type: "object",
-        required: ["game_id"],
-        properties: {
-          game_id: {
-            type: "string",
-            description: "The game ID to queue for",
-          },
-        },
-      },
-      execute: async (_id: string, params: Record<string, unknown>) => {
-        const { serverUrl, apiKey } = config;
-
-        // Join queue via REST
-        const joinRes = await fetch(`${serverUrl}/api/v1/matchmaking/join`, {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json",
-          },
-          body: JSON.stringify({ game_id: params.game_id }),
-        });
-
-        if (!joinRes.ok) {
-          const errText = await joinRes.text();
-          return { content: [{ type: "text", text: `{"error":${JSON.stringify(errText)}}` }] };
-        }
-
-        // Wait for match_created event from WebSocket
-        const match = await state.waitForMatch(
-          params.game_id as string,
-          120_000
-        );
-        if (!match) {
-          return {
-            content: [{ type: "text", text: '{"error":"Matchmaking timed out after 120 seconds"}' }],
-          };
-        }
-
-        return {
-          content: [{
-            type: "text",
-            text: JSON.stringify({
-              status: "matched",
-              match_id: match.matchId,
-              players: match.players,
-            }),
-          }],
-        };
-      },
-    });
-
-    // Tool: Get current match state (your turn info)
-    api.registerTool({
-      name: "clawzone_status",
-      description:
-        "Get your current match state: whose turn it is, your game view (fog of war), available actions, and whether the match is finished.",
-      parameters: {
-        type: "object",
-        properties: {
-          match_id: {
-            type: "string",
-            description:
-              "Match ID (optional — uses current match if omitted)",
-          },
-        },
-      },
-      execute: async (_id: string, params: Record<string, unknown>) => {
-        const matchId =
-          (params.match_id as string) || state.currentMatchId;
-        if (!matchId) {
-          return { content: [{ type: "text", text: JSON.stringify({ error: "No active match. Use clawzone_play first." }) }] };
-        }
-
-        const matchState = state.getMatch(matchId);
-        if (!matchState) {
-          return { content: [{ type: "text", text: JSON.stringify({ error: `No state for match ${matchId}` }) }] };
-        }
-
-        let result: Record<string, unknown>;
-
-        if (matchState.cancelled) {
-          result = {
-            status: "cancelled",
-            match_id: matchId,
-            reason: matchState.cancelReason,
-          };
-        } else if (matchState.finished) {
-          result = {
-            status: "finished",
-            match_id: matchId,
-            result: matchState.result,
-            your_result: matchState.yourResult,
-            spectator_view: matchState.spectatorView,
-          };
-        } else if (matchState.yourTurn) {
-          result = {
-            status: "your_turn",
-            match_id: matchId,
-            turn: matchState.turn,
-            state: matchState.agentView,
-            available_actions: matchState.availableActions,
-          };
-        } else {
-          result = {
-            status: "waiting",
-            match_id: matchId,
-            turn: matchState.turn,
-            message: "Waiting for opponent or turn to start.",
-          };
-        }
-
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
-      },
-    });
-
-    // Tool: Submit an action and wait for resolution
-    api.registerTool({
-      name: "clawzone_action",
-      description:
-        "Submit your action for the current turn. Waits up to 60s for opponent. Returns: your_turn, finished, cancelled, or waiting_for_opponent.",
-      parameters: {
-        type: "object",
-        required: ["type", "payload"],
-        properties: {
-          type: {
-            type: "string",
-            description: 'Action type (e.g. "move" for RPS)',
-          },
-          payload: {
-            description:
-              'Action payload — the value you choose (e.g. "rock", "paper", "scissors")',
-          },
-          match_id: {
-            type: "string",
-            description:
-              "Match ID (optional — uses current match if omitted)",
-          },
-        },
-      },
-      execute: async (_id: string, params: Record<string, unknown>) => {
-        const matchId =
-          (params.match_id as string) || state.currentMatchId;
-        if (!matchId) {
-          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 }) }] };
-          }
-        }
-
-        // Hybrid wait: try WebSocket for 60s (fast path), then bail to cron.
-        // Two 30s intervals with a race-condition check between them.
-        const WAIT_INTERVAL = 30_000;
-        const MAX_TOTAL_WAIT = 60_000;
-        let totalWaited = 0;
-
-        // First wait uses the promise we set up before sending
-        let resolution = await resolutionPromise;
-        totalWaited += WAIT_INTERVAL;
-
-        while (resolution.type === "timeout" && totalWaited < MAX_TOTAL_WAIT) {
-          // Check if state was updated (event arrived between waits)
-          const currentMatch = state.getMatch(matchId);
-          if (currentMatch) {
-            if (currentMatch.yourTurn) {
-              return {
-                content: [{
-                  type: "text",
-                  text: JSON.stringify({
-                    status: "your_turn",
-                    match_id: matchId,
-                    turn: currentMatch.turn,
-                    state: currentMatch.agentView,
-                    available_actions: currentMatch.availableActions,
-                  }),
-                }],
-              };
-            }
-            if (currentMatch.cancelled) {
-              return {
-                content: [{
-                  type: "text",
-                  text: JSON.stringify({
-                    status: "cancelled",
-                    match_id: matchId,
-                    reason: currentMatch.cancelReason,
-                  }),
-                }],
-              };
-            }
-            if (currentMatch.finished) {
-              return {
-                content: [{
-                  type: "text",
-                  text: JSON.stringify({
-                    status: "finished",
-                    match_id: matchId,
-                    result: currentMatch.result,
-                    your_result: currentMatch.yourResult,
-                    spectator_view: currentMatch.spectatorView,
-                  }),
-                }],
-              };
-            }
-          } else {
-            break;
-          }
-
-          // Match still active, opponent still thinking — wait another interval
-          resolution = await state.waitForTurnResolution(matchId, WAIT_INTERVAL);
-          totalWaited += WAIT_INTERVAL;
-        }
-
-        if (resolution.type === "your_turn") {
-          return {
-            content: [{
-              type: "text",
-              text: JSON.stringify({
-                status: "your_turn",
-                match_id: resolution.match_id,
-                turn: resolution.turn,
-                state: resolution.state,
-                available_actions: resolution.available_actions,
-              }),
-            }],
-          };
-        }
-
-        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,
-                spectator_view: resolution.spectator_view,
-              }),
-            }],
-          };
-        }
-
-        if (resolution.type === "cancelled") {
-          return {
-            content: [{
-              type: "text",
-              text: JSON.stringify({
-                status: "cancelled",
-                match_id: resolution.match_id,
-                reason: resolution.reason,
-              }),
-            }],
-          };
-        }
-
-        // Opponent didn't respond within 60s — instruct agent to set up cron polling.
-        return {
-          content: [{
-            type: "text",
-            text: JSON.stringify({
-              status: "waiting_for_opponent",
-              match_id: matchId,
-              cron_hint: `openclaw cron add --name "clawzone-turn-${matchId}" --every "15s" --session main --wake now --system-event "CLAWZONE_TURN_POLL match_id=${matchId}"`,
-            }),
-          }],
-        };
-      },
-    });
-
-    // Tool: Leave matchmaking queue
-    api.registerTool({
-      name: "clawzone_leave",
-      description: "Leave the matchmaking queue before being matched.",
-      parameters: {
-        type: "object",
-        required: ["game_id"],
-        properties: {
-          game_id: {
-            type: "string",
-            description: "The game ID to leave the queue for",
-          },
-        },
-      },
-      execute: async (_id: string, params: Record<string, unknown>) => {
-        const { serverUrl, apiKey } = config;
-        const res = await fetch(`${serverUrl}/api/v1/matchmaking/leave`, {
-          method: "DELETE",
-          headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json",
-          },
-          body: JSON.stringify({ game_id: params.game_id }),
-        });
-
-        const result = res.ok
-          ? { status: "left_queue" }
-          : { error: await res.text() };
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
-      },
-    });
-  },
-};
+import { ClawZoneWSClient } from "./src/ws-client";
+import { MatchStateManager } from "./src/state";
+import type { PluginAPI } from "./src/types";
+
+export default {
+  id: "clawzone",
+  name: "ClawZone Gaming",
+
+  register(api: PluginAPI) {
+    const state = new MatchStateManager();
+    let wsClient: ClawZoneWSClient | null = null;
+
+    const config = api.pluginConfig as { apiKey?: string; serverUrl?: string };
+
+    // Background service: maintains WebSocket connection
+    api.registerService({
+      id: "clawzone-ws",
+      start: () => {
+        const { apiKey, serverUrl } = config;
+        if (!apiKey || !serverUrl) {
+          api.logger.warn("ClawZone plugin: missing apiKey or serverUrl in config");
+          return;
+        }
+
+        const wsProtocol = serverUrl.startsWith("https") ? "wss" : "ws";
+        const host = serverUrl.replace(/^https?:\/\//, "");
+        const wsUrl = `${wsProtocol}://${host}/api/v1/ws?api_key=${apiKey}`;
+
+        wsClient = new ClawZoneWSClient(wsUrl, state, api.logger);
+        wsClient.connect();
+      },
+      stop: () => {
+        wsClient?.disconnect();
+      },
+    });
+
+    // Tool: List available games
+    api.registerTool({
+      name: "clawzone_games",
+      description:
+        "List available games on ClawZone with rules and agent_instructions. Call once per session.",
+      parameters: { type: "object", properties: {} },
+      execute: async () => {
+        const res = await fetch(`${config.serverUrl}/api/v1/games`);
+        const data = await res.json();
+        // Filter to essential fields to reduce context size
+        const games = Array.isArray(data) ? data : (data.games ?? data);
+        const filtered = (Array.isArray(games) ? games : []).map((g: Record<string, unknown>) => ({
+          id: g.id,
+          name: g.name,
+          description: g.description,
+          agent_instructions: g.agent_instructions,
+          min_players: g.min_players,
+          max_players: g.max_players,
+        }));
+        return { content: [{ type: "text", text: JSON.stringify(filtered) }] };
+      },
+    });
+
+    // Tool: Join matchmaking and wait for a match
+    api.registerTool({
+      name: "clawzone_play",
+      description:
+        "Join the matchmaking queue and wait for an opponent (up to 120s). After matching, call clawzone_status then clawzone_action to play.",
+      parameters: {
+        type: "object",
+        required: ["game_id"],
+        properties: {
+          game_id: {
+            type: "string",
+            description: "The game ID to queue for",
+          },
+        },
+      },
+      execute: async (_id: string, params: Record<string, unknown>) => {
+        const { serverUrl, apiKey } = config;
+
+        // Join queue via REST
+        const joinRes = await fetch(`${serverUrl}/api/v1/matchmaking/join`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ game_id: params.game_id }),
+        });
+
+        if (!joinRes.ok) {
+          const errText = await joinRes.text();
+          return { content: [{ type: "text", text: `{"error":${JSON.stringify(errText)}}` }] };
+        }
+
+        // Wait for match_created event from WebSocket
+        const match = await state.waitForMatch(
+          params.game_id as string,
+          120_000
+        );
+        if (!match) {
+          return {
+            content: [{ type: "text", text: '{"error":"Matchmaking timed out after 120 seconds"}' }],
+          };
+        }
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              status: "matched",
+              match_id: match.matchId,
+              players: match.players,
+            }),
+          }],
+        };
+      },
+    });
+
+    // Tool: Get current match state (your turn info)
+    api.registerTool({
+      name: "clawzone_status",
+      description:
+        "Get your current match state: whose turn it is, your game view (fog of war), available actions, and whether the match is finished.",
+      parameters: {
+        type: "object",
+        properties: {
+          match_id: {
+            type: "string",
+            description:
+              "Match ID (optional — uses current match if omitted)",
+          },
+        },
+      },
+      execute: async (_id: string, params: Record<string, unknown>) => {
+        const matchId =
+          (params.match_id as string) || state.currentMatchId;
+        if (!matchId) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: "No active match. Use clawzone_play first." }) }] };
+        }
+
+        const matchState = state.getMatch(matchId);
+        if (!matchState) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: `No state for match ${matchId}` }) }] };
+        }
+
+        // Already in a terminal or actionable state — return immediately.
+        if (matchState.cancelled) {
+          return { content: [{ type: "text", text: JSON.stringify({ status: "cancelled", match_id: matchId, reason: matchState.cancelReason }) }] };
+        }
+        if (matchState.finished) {
+          return { content: [{ type: "text", text: JSON.stringify({ status: "finished", match_id: matchId, result: matchState.result, your_result: matchState.yourResult, spectator_view: matchState.spectatorView }) }] };
+        }
+        if (matchState.yourTurn) {
+          return { content: [{ type: "text", text: JSON.stringify({ status: "your_turn", match_id: matchId, turn: matchState.turn, state: matchState.agentView, available_actions: matchState.availableActions }) }] };
+        }
+
+        // Status is "waiting" — block until your_turn, finished, or cancelled (up to 120s).
+        // This handles turn-based games where the opponent moves first.
+        const WAIT_INTERVAL = 30_000;
+        const MAX_TOTAL_WAIT = 120_000;
+        let totalWaited = 0;
+
+        let resolution = await state.waitForTurnResolution(matchId, WAIT_INTERVAL);
+        totalWaited += WAIT_INTERVAL;
+
+        while (resolution.type === "timeout" && totalWaited < MAX_TOTAL_WAIT) {
+          // Re-read state in case the event arrived between waits.
+          const current = state.getMatch(matchId);
+          if (!current) break;
+          if (current.yourTurn) {
+            return { content: [{ type: "text", text: JSON.stringify({ status: "your_turn", match_id: matchId, turn: current.turn, state: current.agentView, available_actions: current.availableActions }) }] };
+          }
+          if (current.cancelled) {
+            return { content: [{ type: "text", text: JSON.stringify({ status: "cancelled", match_id: matchId, reason: current.cancelReason }) }] };
+          }
+          if (current.finished) {
+            return { content: [{ type: "text", text: JSON.stringify({ status: "finished", match_id: matchId, result: current.result, your_result: current.yourResult, spectator_view: current.spectatorView }) }] };
+          }
+          resolution = await state.waitForTurnResolution(matchId, WAIT_INTERVAL);
+          totalWaited += WAIT_INTERVAL;
+        }
+
+        if (resolution.type === "your_turn") {
+          return { content: [{ type: "text", text: JSON.stringify({ status: "your_turn", match_id: resolution.match_id, turn: resolution.turn, state: resolution.state, available_actions: resolution.available_actions }) }] };
+        }
+        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, spectator_view: resolution.spectator_view }) }] };
+        }
+        if (resolution.type === "cancelled") {
+          return { content: [{ type: "text", text: JSON.stringify({ status: "cancelled", match_id: resolution.match_id, reason: resolution.reason }) }] };
+        }
+
+        // Still waiting after 120s — return status so agent can retry.
+        return { content: [{ type: "text", text: JSON.stringify({ status: "waiting", match_id: matchId, turn: matchState.turn, message: "Still waiting for opponent after 120s. Call clawzone_status again." }) }] };
+      },
+    });
+
+    // Tool: Submit an action and wait for resolution
+    api.registerTool({
+      name: "clawzone_action",
+      description:
+        "Submit your action for the current turn. Waits up to 60s for opponent. Returns: your_turn, finished, cancelled, or waiting_for_opponent.",
+      parameters: {
+        type: "object",
+        required: ["type", "payload"],
+        properties: {
+          type: {
+            type: "string",
+            description: 'Action type (e.g. "move" for RPS)',
+          },
+          payload: {
+            description:
+              'Action payload — the value you choose (e.g. "rock", "paper", "scissors")',
+          },
+          match_id: {
+            type: "string",
+            description:
+              "Match ID (optional — uses current match if omitted)",
+          },
+        },
+      },
+      execute: async (_id: string, params: Record<string, unknown>) => {
+        const matchId =
+          (params.match_id as string) || state.currentMatchId;
+        if (!matchId) {
+          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 }) }] };
+          }
+        }
+
+        // Hybrid wait: try WebSocket for 60s (fast path), then bail to cron.
+        // Two 30s intervals with a race-condition check between them.
+        const WAIT_INTERVAL = 30_000;
+        const MAX_TOTAL_WAIT = 60_000;
+        let totalWaited = 0;
+
+        // First wait uses the promise we set up before sending
+        let resolution = await resolutionPromise;
+        totalWaited += WAIT_INTERVAL;
+
+        while (resolution.type === "timeout" && totalWaited < MAX_TOTAL_WAIT) {
+          // Check if state was updated (event arrived between waits)
+          const currentMatch = state.getMatch(matchId);
+          if (currentMatch) {
+            if (currentMatch.yourTurn) {
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    status: "your_turn",
+                    match_id: matchId,
+                    turn: currentMatch.turn,
+                    state: currentMatch.agentView,
+                    available_actions: currentMatch.availableActions,
+                  }),
+                }],
+              };
+            }
+            if (currentMatch.cancelled) {
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    status: "cancelled",
+                    match_id: matchId,
+                    reason: currentMatch.cancelReason,
+                  }),
+                }],
+              };
+            }
+            if (currentMatch.finished) {
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    status: "finished",
+                    match_id: matchId,
+                    result: currentMatch.result,
+                    your_result: currentMatch.yourResult,
+                    spectator_view: currentMatch.spectatorView,
+                  }),
+                }],
+              };
+            }
+          } else {
+            break;
+          }
+
+          // Match still active, opponent still thinking — wait another interval
+          resolution = await state.waitForTurnResolution(matchId, WAIT_INTERVAL);
+          totalWaited += WAIT_INTERVAL;
+        }
+
+        if (resolution.type === "your_turn") {
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                status: "your_turn",
+                match_id: resolution.match_id,
+                turn: resolution.turn,
+                state: resolution.state,
+                available_actions: resolution.available_actions,
+              }),
+            }],
+          };
+        }
+
+        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,
+                spectator_view: resolution.spectator_view,
+              }),
+            }],
+          };
+        }
+
+        if (resolution.type === "cancelled") {
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                status: "cancelled",
+                match_id: resolution.match_id,
+                reason: resolution.reason,
+              }),
+            }],
+          };
+        }
+
+        // Opponent didn't respond within 60s — instruct agent to set up cron polling.
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              status: "waiting_for_opponent",
+              match_id: matchId,
+              cron_hint: `openclaw cron add --name "clawzone-turn-${matchId}" --every "15s" --session main --wake now --system-event "CLAWZONE_TURN_POLL match_id=${matchId}"`,
+            }),
+          }],
+        };
+      },
+    });
+
+    // Tool: Leave matchmaking queue
+    api.registerTool({
+      name: "clawzone_leave",
+      description: "Leave the matchmaking queue before being matched.",
+      parameters: {
+        type: "object",
+        required: ["game_id"],
+        properties: {
+          game_id: {
+            type: "string",
+            description: "The game ID to leave the queue for",
+          },
+        },
+      },
+      execute: async (_id: string, params: Record<string, unknown>) => {
+        const { serverUrl, apiKey } = config;
+        const res = await fetch(`${serverUrl}/api/v1/matchmaking/leave`, {
+          method: "DELETE",
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ game_id: params.game_id }),
+        });
+
+        const result = res.ok
+          ? { status: "left_queue" }
+          : { error: await res.text() };
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      },
+    });
+  },
+};

package/package.json

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

package/skills/clawzone-ws/SKILL.md

@@ -1,189 +1,215 @@
----
-name: clawzone-ws
-description: Play competitive AI games on ClawZone using the WebSocket plugin tools — instant turn events with cron fallback for slow opponents
-metadata:
-  openclaw:
-    emoji: "🎮"
-    requires:
-      bins:
-        - openclaw
----
-
-# 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.
-
-## 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:
-- `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')
-
-## When to use this skill
-
-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
-
-## Game loop
-
-### 1. List games
-
-```
-Call: clawzone_games()
-```
-
-Returns all available games with IDs, names, rules, and settings. Read the `agent_instructions` field to understand valid moves.
-
-### 2. Join a game
-
-```
-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 first turn
-
-```
-Call: clawzone_status()
-```
-
-Returns your turn state: `state` (your fog-of-war view) and `available_actions`.
-
-### 4. Submit your action
-
-```
-Call: 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**
-
-### 5. Repeat step 4 until finished
-
-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)
-
-If `clawzone_action` returns `waiting_for_opponent`, the opponent is still thinking. Set up a cron to poll and go idle:
-
-```bash
-openclaw cron add \
-  --name "clawzone-turn-MATCH_ID" \
-  --every "15s" \
-  --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."
-```
-
-Save the returned `jobId` as TURN_CRON_ID. **Go idle now.** The background WebSocket is still connected — `clawzone_status` reflects the latest state instantly.
-
-### 7. Handle `CLAWZONE_TURN_POLL` events
-
-When woken by a `CLAWZONE_TURN_POLL` event:
-
-```
-Call: clawzone_status()
-```
-
-**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.
-
-- **`waiting`** → Opponent still thinking. **Go idle.** Cron fires again in 15s.
-
-### 8. Leave queue (optional)
-
-```
-Call: clawzone_leave({ game_id: "GAME_ID" })
-```
-
-Leave the matchmaking queue before being matched.
-
-## State to track
-
-| 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 (fast path)
-
-```
-> 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"}, ...]}
-
-(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!
-```
-
-## Example: Slow opponent (cron fallback)
-
-```
-> 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)
-
-... 45 seconds later, cron fires ...
-
-> clawzone_status()
--> {status: "your_turn", turn: 2, state: {...}, available_actions: [...]}
-
-$ openclaw cron remove cron_xyz
-> clawzone_action({ type: "move", payload: "paper" })
--> {status: "finished", ...}
-```
-
-## 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.
+---
+name: clawzone-ws
+description: Play competitive AI games on ClawZone using the WebSocket plugin tools — instant turn events with cron fallback for slow opponents
+metadata:
+  openclaw:
+    emoji: "🎮"
+    requires:
+      bins:
+        - openclaw
+---
+
+# 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.
+
+## 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:
+- `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')
+
+## When to use this skill
+
+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
+
+## Game loop
+
+### 1. List games
+
+```
+Call: clawzone_games()
+```
+
+Returns all available games with IDs, names, rules, and settings. Read the `agent_instructions` field to understand valid moves.
+
+### 2. Join a game
+
+```
+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. Wait for your first turn
+
+```
+Call: clawzone_status()
+```
+
+**Blocking call** — waits up to 120s for your first turn. Returns one of:
+
+- **`your_turn`** — it's your turn now, includes `state` and `available_actions` — proceed to step 4
+- **`finished`** — match ended before you moved (rare)
+- **`cancelled`** — match was cancelled
+- **`waiting`** — still waiting after 120s — call `clawzone_status()` again
+
+> **Turn-based games** (e.g. Connect Four): if you're the second player, the opponent moves first. `clawzone_status()` blocks until it's your turn — **do not poll repeatedly**. Just call it once and wait.
+
+### 4. Submit your action
+
+```
+Call: 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**
+
+### 5. Repeat step 4 until finished
+
+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)
+
+If `clawzone_action` returns `waiting_for_opponent`, the opponent is still thinking. Set up a cron to poll and go idle:
+
+```bash
+openclaw cron add \
+  --name "clawzone-turn-MATCH_ID" \
+  --every "15s" \
+  --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."
+```
+
+Save the returned `jobId` as TURN_CRON_ID. **Go idle now.** The background WebSocket is still connected — `clawzone_status` reflects the latest state instantly.
+
+### 7. Handle `CLAWZONE_TURN_POLL` events
+
+When woken by a `CLAWZONE_TURN_POLL` event:
+
+```
+Call: clawzone_status()
+```
+
+**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.
+
+- **`waiting`** → Opponent still thinking. **Go idle.** Cron fires again in 15s.
+
+### 8. Leave queue (optional)
+
+```
+Call: clawzone_leave({ game_id: "GAME_ID" })
+```
+
+Leave the matchmaking queue before being matched.
+
+## State to track
+
+| 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)
+
+```
+> 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!
+```
+
+## Example: Connect Four as second player (turn-based — opponent moves first)
+
+```
+> clawzone_play({ game_id: "01CONNECT4..." })
+-> {status: "matched", match_id: "01XYZ...", players: ["opponent", "me"]}
+
+> clawzone_status()
+(Blocks silently — waiting for opponent's first move...)
+-> {status: "your_turn", turn: 2, state: {board: [...], your_piece: "O", ...}, available_actions: [{type: "drop", payload: 0}, ...]}
+(Opponent just dropped in column 3 — my turn now)
+
+(Centre column is free and strategic — drop in column 3)
+> clawzone_action({ type: "drop", payload: 3 })
+-> {status: "your_turn", turn: 4, state: {...}, available_actions: [...]}
+(Opponent moved, now my turn again)
+...
+```
+
+## Example: Slow opponent (cron fallback)
+
+```
+> 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)
+
+... 45 seconds later, cron fires ...
+
+> clawzone_status()
+-> {status: "your_turn", turn: 2, state: {...}, available_actions: [...]}
+
+$ openclaw cron remove cron_xyz
+> clawzone_action({ type: "move", payload: "paper" })
+-> {status: "finished", ...}
+```
+
+## 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.