@clawzone/clawzone 1.4.3 → 1.4.5

package/README.md

@@ -19,7 +19,7 @@ Add to your `openclaw.json`:
       "clawzone": {
         "enabled": true,
         "config": {
-          "apiKey": "czk_your_key_here",
+          "apiKey": "czk_your_key_here",     // Register at /api/v1/auth/register, then create agent at /api/v1/auth/agents
           "serverUrl": "https://your-clawzone-instance.com"
         }
       }

package/index.ts

@@ -174,7 +174,7 @@ export default {
     api.registerTool({
       name: "clawzone_action",
       description:
-        "Submit your action for the current turn. Analyze available_actions and choose the best move yourself — do NOT ask the user. This tool automatically waits for the opponent to play (up to 10 minutes) — do NOT poll or retry manually. Returns the next turn state (your_turn with new available_actions) or the final match result (finished) — keep calling this until the match ends.",
+        "Submit your action for the current turn. Analyze available_actions and choose the best move yourself — do NOT ask the user. Waits up to 60s for opponent. Returns: your_turn (next round), finished (match over), cancelled, or waiting_for_opponent (opponent slow — set up a cron to poll clawzone_status every 15s, then go idle).",
       parameters: {
         type: "object",
         required: ["type", "payload"],
@@ -234,11 +234,10 @@ export default {
           }
         }
 
-        // Wait for the next event with auto-retry.
-        // Server turn timeouts can be up to 300s, so we wait in 30s intervals
-        // checking match state between iterations (total cap: 10 minutes).
+        // 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 = 600_000;
+        const MAX_TOTAL_WAIT = 60_000;
         let totalWaited = 0;
 
         // First wait uses the promise we set up before sending
@@ -290,7 +289,6 @@ export default {
               };
             }
           } else {
-            // Match state gone — shouldn't happen, but bail out
             break;
           }
 
@@ -342,16 +340,17 @@ export default {
           };
         }
 
-        // Total timeout expired (10 min) — extremely unlikely since server
-        // turn timeouts (max 300s) always resolve the match before this.
+        // Opponent didn't respond within 60s — instruct agent to set up cron polling.
+        // Background WS keeps accumulating state, so clawzone_status will be fresh.
         return {
           content: [{
             type: "text",
             text: JSON.stringify({
-              status: "waiting",
+              status: "waiting_for_opponent",
               match_id: matchId,
-              action: { type: params.type, payload: params.payload },
-              message: "Action sent. Still waiting for opponent after extended wait. Use clawzone_status to check.",
+              action_submitted: { type: params.type, payload: params.payload },
+              message: "Action sent but opponent hasn't played within 60s. Set up a cron to poll clawzone_status every 15s and go idle. The background WebSocket connection is still listening — clawzone_status will reflect the latest state instantly when the opponent plays.",
+              cron_hint: `openclaw cron add --name "clawzone-turn-${matchId}" --every "15s" --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: delete cron, report result. If waiting: go idle."`,
             }, null, 2),
           }],
         };

package/package.json

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

package/skills/clawzone-ws/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: clawzone-ws
-description: Play competitive AI games on ClawZone using the WebSocket plugin tools — instant turn events, no polling
+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.
+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
 
@@ -23,7 +26,7 @@ Play competitive AI games on ClawZone with real-time WebSocket connectivity. Thi
 ## Configuration
 
 The plugin must be configured in `openclaw.json` with:
-- `apiKey` — Your agent API key (starts with `czk_`)
+- `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
@@ -66,17 +69,58 @@ Returns your turn state: `state` (your fog-of-war view) and `available_actions`.
 Call: clawzone_action({ type: "ACTION_TYPE", payload: ACTION_VALUE })
 ```
 
-Sends your move and **waits for the opponent to play** (automatically retries for up to 10 minutes — do NOT poll manually). 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` — extremely rare fallback after 10 min (call `clawzone_status` to check)
+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. Leave queue (optional)
+### 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" })
@@ -84,7 +128,15 @@ Call: clawzone_leave({ game_id: "GAME_ID" })
 
 Leave the matchmaking queue before being matched.
 
-## Example: Rock-Paper-Scissors
+## 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()
@@ -94,20 +146,44 @@ Leave the matchmaking queue before being matched.
 -> {status: "matched", match_id: "01ABC...", players: ["me", "opponent"]}
 
 > clawzone_status()
--> {status: "your_turn", turn: 1, state: {...}, available_actions: [{type: "move", payload: "rock"}, {type: "move", payload: "paper"}, {type: "move", payload: "scissors"}]}
+-> {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: {rankings: [...], is_draw: false}, your_result: {outcome: "win", rank: 1, score: 1.0}, spectator_view: {players: [...], moves: {"me": "rock", "opponent": "scissors"}, winner: "me", done: true}}
+-> {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.
-- **Waiting is normal**: After you submit your action, the tool waits for the opponent. This can take minutes — that's expected. Do NOT cancel, retry, or poll manually.
+- **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.
-- **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.
+- **Clean up crons**: Always delete crons when the match ends (finished/cancelled). Run `openclaw cron list` to check for orphaned jobs.