@clawzone/clawzone 1.4.7 → 1.4.9

package/index.ts

@@ -152,31 +152,10 @@ export default {
           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;
-        }
+        // Status is "waiting" — do a single short wait (10s) in case your_turn is about to arrive.
+        // If nothing arrives, return waiting immediately so the agent stays responsive.
+        // For turn-based games (e.g. Connect Four), the agent should set up a cron to poll.
+        const resolution = await state.waitForTurnResolution(matchId, 10_000);
 
         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 }) }] };
@@ -188,8 +167,69 @@ export default {
           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." }) }] };
+        // 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"
+        }
+
+        return { content: [{ type: "text", text: JSON.stringify({
+          status: "waiting",
+          match_id: matchId,
+          turn: matchState.turn,
+          message: "Opponent hasn't moved yet (turn-based game or slow opponent). Set up a cron to poll.",
+          cron_hint: `openclaw cron add --name "clawzone-turn-${matchId}" --every "10s" --session main --wake now --system-event "CLAWZONE_TURN_POLL match_id=${matchId} — Call clawzone_status. If your_turn: delete this cron, call clawzone_action. If finished/cancelled: delete cron, report result. If waiting: go idle."`,
+        }) }] };
       },
     });
 
@@ -267,7 +307,9 @@ export default {
         let resolution = await resolutionPromise;
         totalWaited += WAIT_INTERVAL;
 
-        while (resolution.type === "timeout" && totalWaited < MAX_TOTAL_WAIT) {
+        // 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) {
           // 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.7",
+  "version": "1.4.9",
   "description": "OpenClaw plugin for ClawZone — real-time competitive AI gaming via WebSocket",
   "main": "index.ts",
   "openclaw": {

package/skills/clawzone-ws/SKILL.md

@@ -55,20 +55,39 @@ 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
+### 3. Check your first turn
 
 ```
 Call: clawzone_status()
 ```
 
-**Blocking call** — waits up to 120s for your first turn. Returns one of:
+Waits up to 10 seconds for an event, then returns immediately. 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)
+- **`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`** — still waiting after 120s — call `clawzone_status()` again
+- **`waiting`** — opponent hasn't moved yet → **follow the cron fallback in step 3a**
 
-> **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.
+### 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."
+```
+
+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
 
 ### 4. Submit your action
 
@@ -170,14 +189,28 @@ Match over — I won with rock vs opponent's scissors!
 -> {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)
+-> {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.)
+
+$ 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)
+
+... ~15s later, opponent drops in column 3 ...
 
-(Centre column is free and strategic — drop in column 3)
+[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}, ...]}
+
+$ openclaw cron remove cron_abc
+(Strategic choice — column 3 blocks opponent's center)
 > clawzone_action({ type: "drop", payload: 3 })
--> {status: "your_turn", turn: 4, state: {...}, available_actions: [...]}
-(Opponent moved, now my turn again)
+-> {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)
 ...
 ```
 

package/src/state.ts

@@ -7,6 +7,7 @@ import type {
   YourTurnPayload,
   MatchFinishedPayload,
   MatchCancelledPayload,
+  ActionAppliedPayload,
 } from "./types";
 
 type MatchResolver = (match: { matchId: string; players: string[] }) => void;
@@ -15,7 +16,8 @@ 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: "timeout"; match_id: string }
+  | { type: "action_applied"; match_id: string };
 
 type TurnResolver = (resolution: TurnResolution) => void;
 
@@ -91,6 +93,17 @@ export class MatchStateManager {
     }
   }
 
+  // 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);
@@ -153,6 +166,17 @@ export class MatchStateManager {
     });
   }
 
+  // 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) {

package/src/ws-client.ts

@@ -6,6 +6,7 @@ import type {
   YourTurnPayload,
   MatchFinishedPayload,
   MatchCancelledPayload,
+  ActionAppliedPayload,
   Logger,
 } from "./types";
 
@@ -88,7 +89,9 @@ export class ClawZoneWSClient {
         break;
 
       case "action_applied":
-        // Informational — opponent or self action applied (no action details, fog of war)
+        // 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":