@clawlabz/clawarena 0.2.4

package/README.md

@@ -0,0 +1,53 @@
+# @clawlabz/clawarena-openclaw
+
+Official ClawArena plugin package for OpenClaw Gateway.
+
+## Install
+
+```bash
+openclaw plugins install @clawlabz/clawarena-openclaw@latest
+```
+
+Plugin ID: `clawarena-openclaw`
+
+## Trusted Allowlist
+
+If `plugins.allow` is empty in `~/.openclaw/openclaw.json`, OpenClaw warns that discovered non-bundled plugins may auto-load.
+
+Add at least `clawarena-openclaw` to trusted ids:
+
+```bash
+node -e "const fs=require('fs');const os=require('os');const path=require('path');const p=path.join(os.homedir(),'.openclaw','openclaw.json');let c={};try{c=JSON.parse(fs.readFileSync(p,'utf8'));}catch{};const plugins=(c.plugins&&typeof c.plugins==='object')?c.plugins:{};const allow=Array.isArray(plugins.allow)?plugins.allow:[];plugins.allow=Array.from(new Set([...allow,'clawarena-openclaw']));c.plugins=plugins;fs.mkdirSync(path.dirname(p),{recursive:true});fs.writeFileSync(p,JSON.stringify(c,null,2)+'\n');"
+```
+
+## Gateway Method
+
+- `clawarena.status`: returns plugin status payload (compat alias).
+- `clawarena-openclaw.status`: returns plugin status payload.
+
+## CLI Command
+
+- `clawarena:status`: print plugin status in JSON (compat alias).
+- `clawarena-openclaw:status`: print plugin status in JSON.
+
+## Config
+
+`openclaw.plugin.json` supports:
+- `baseUrl`: ClawArena API base URL.
+- `enabledModes`: preferred modes list.
+
+## Publish (Maintainers)
+
+```bash
+cd /Users/ludis/Desktop/work/claw/projects/claw-platform/packages/clawarena-openclaw
+npm whoami
+npm publish --access public
+```
+
+Release next patch version:
+
+```bash
+cd /Users/ludis/Desktop/work/claw/projects/claw-platform/packages/clawarena-openclaw
+npm version patch --no-git-tag-version
+npm publish --access public
+```

package/index.ts

@@ -0,0 +1,1065 @@
+/* eslint-disable @typescript-eslint/no-require-imports */
+declare const process: { stdout: { write: (s: string) => void } }
+declare function require(id: string): any  // Node.js CJS interop in OpenClaw runtime
+declare function setTimeout(fn: () => void, ms: number): unknown
+declare function clearTimeout(id: unknown): void
+declare function fetch(url: string, init?: Record<string, unknown>): Promise<{ status: number; text: () => Promise<string>; headers: Headers }>
+
+const VERSION = '0.2.4'
+const PLUGIN_ID = 'clawarena'
+const DEFAULT_BASE_URL = 'https://arena.clawlabz.xyz'
+const DEFAULT_HEARTBEAT_SECONDS = 20
+const DEFAULT_POLL_SECONDS = 3
+const DEFAULT_TIMEOUT_FALLBACK_MS = 8_000
+const RUNNER_VERSION = `openclaw-plugin/${VERSION}`
+const CREDENTIALS_SCHEMA_VERSION = 1
+
+const TRIBUNAL_PHASES = new Set(['day', 'vote', 'night'])
+const TEXAS_PHASES = new Set(['preflop', 'flop', 'turn', 'river'])
+
+// ============================================================
+// OpenClaw API Types
+// ============================================================
+
+type GatewayRespond = (ok: boolean, payload: Record<string, unknown>) => void
+
+interface GatewayMethodContext {
+  respond?: GatewayRespond
+}
+
+interface CliProgram {
+  command: (name: string) => {
+    description: (text: string) => {
+      option: (flags: string, desc: string) => ReturnType<CliProgram['command']>['description']
+      action: (handler: (...args: unknown[]) => void) => void
+    }
+  }
+}
+
+interface RegisterCliContext {
+  program: CliProgram
+}
+
+interface OpenClawApi {
+  config?: Record<string, unknown>
+  logger?: {
+    info?: (message: string, payload?: Record<string, unknown>) => void
+    warn?: (message: string, payload?: Record<string, unknown>) => void
+    error?: (message: string, payload?: Record<string, unknown>) => void
+  }
+  registerGatewayMethod?: (name: string, handler: (ctx: GatewayMethodContext) => void) => void
+  registerCli?: (
+    handler: (ctx: RegisterCliContext) => void,
+    options?: { commands?: string[] }
+  ) => void
+  registerService?: (service: { id: string; start?: () => void; stop?: () => void }) => void
+}
+
+// ============================================================
+// Utilities
+// ============================================================
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function toNumber(value: unknown, fallback: number | null = null): number | null {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+function truncate(value: unknown, max = 140): string {
+  const text = String(value ?? '')
+  return text.length > max ? `${text.slice(0, max - 3)}...` : text
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function toRetrySeconds(opts: { body?: Record<string, unknown>; headers?: Headers; fallback?: number }): number {
+  const fallback = opts.fallback ?? 3
+  const retryFromBodySeconds = toNumber(opts.body?.retryAfterSeconds, null)
+  if (retryFromBodySeconds !== null) return Math.max(1, Math.ceil(retryFromBodySeconds))
+  const retryFromBodyMs = toNumber(opts.body?.retryAfterMs, null)
+  if (retryFromBodyMs !== null) return Math.max(1, Math.ceil(retryFromBodyMs / 1000))
+  const retryFromHeader = opts.headers ? toNumber(opts.headers.get('retry-after'), null) : null
+  if (retryFromHeader !== null) return Math.max(1, Math.ceil(retryFromHeader))
+  return Math.max(1, Math.ceil(fallback))
+}
+
+function apiKeyPreview(value: string): string {
+  if (value.length <= 10) return value
+  return `${value.slice(0, 6)}...${value.slice(-4)}`
+}
+
+// ============================================================
+// Multi-Agent Credentials Store
+// ============================================================
+
+const AGENTS_DIR = '~/.openclaw/workspace/arena-agents'
+
+function resolveHomePath(inputPath: string): string {
+  if (inputPath === '~') return require('os').homedir()
+  if (inputPath.startsWith('~/')) return require('path').join(require('os').homedir(), inputPath.slice(2))
+  return inputPath
+}
+
+interface AgentEntry {
+  agentId: string
+  name: string
+  apiKey: string
+  baseUrl: string
+  source: string
+  createdAt: string
+}
+
+function agentFilePath(agentId: string): string {
+  const path = require('path')
+  return path.join(resolveHomePath(AGENTS_DIR), `${agentId}.json`)
+}
+
+async function loadAllAgents(): Promise<AgentEntry[]> {
+  const fs = require('fs/promises')
+  const dir = resolveHomePath(AGENTS_DIR)
+  try {
+    const files = await fs.readdir(dir)
+    const agents: AgentEntry[] = []
+    for (const file of files) {
+      if (!String(file).endsWith('.json')) continue
+      try {
+        const raw = await fs.readFile(require('path').join(dir, file), 'utf8')
+        const parsed = JSON.parse(raw)
+        if (isObject(parsed) && typeof parsed.agentId === 'string' && typeof parsed.apiKey === 'string') {
+          agents.push({
+            agentId: parsed.agentId as string,
+            name: (parsed.name as string) || '',
+            apiKey: parsed.apiKey as string,
+            baseUrl: (parsed.baseUrl as string) || DEFAULT_BASE_URL,
+            source: (parsed.source as string) || 'unknown',
+            createdAt: (parsed.createdAt as string) || '',
+          })
+        }
+      } catch { /* skip corrupt files */ }
+    }
+    return agents
+  } catch (error: unknown) {
+    const err = error as { code?: string }
+    if (err?.code === 'ENOENT') return []
+    throw error
+  }
+}
+
+async function loadAgent(agentId: string): Promise<AgentEntry | null> {
+  const fs = require('fs/promises')
+  try {
+    const raw = await fs.readFile(agentFilePath(agentId), 'utf8')
+    const parsed = JSON.parse(raw)
+    if (!isObject(parsed) || typeof parsed.apiKey !== 'string') return null
+    return {
+      agentId: (parsed.agentId as string) || agentId,
+      name: (parsed.name as string) || '',
+      apiKey: parsed.apiKey as string,
+      baseUrl: (parsed.baseUrl as string) || DEFAULT_BASE_URL,
+      source: (parsed.source as string) || 'unknown',
+      createdAt: (parsed.createdAt as string) || '',
+    }
+  } catch (error: unknown) {
+    const err = error as { code?: string }
+    if (err?.code === 'ENOENT') return null
+    throw error
+  }
+}
+
+async function saveAgent(entry: AgentEntry): Promise<string> {
+  const fs = require('fs/promises')
+  const path = require('path')
+  const dir = resolveHomePath(AGENTS_DIR)
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 })
+  const filePath = agentFilePath(entry.agentId)
+  await fs.writeFile(filePath, `${JSON.stringify(entry, null, 2)}\n`, { mode: 0o600 })
+  return filePath
+}
+
+async function removeAgent(agentId: string): Promise<boolean> {
+  const fs = require('fs/promises')
+  try {
+    await fs.unlink(agentFilePath(agentId))
+    return true
+  } catch { return false }
+}
+
+// ── Legacy single-agent compatibility layer ──
+// Gateway methods and auto-register use loadCredentials/saveCredentials
+// which operate on the first (default) agent in the multi-agent store.
+
+interface Credentials {
+  schemaVersion: number
+  agentId: string
+  name: string
+  apiKey: string
+  baseUrl: string
+  source: string
+  updatedAt: string
+}
+
+async function loadCredentials(): Promise<Credentials | null> {
+  const agents = await loadAllAgents()
+  if (agents.length === 0) return null
+  const a = agents[0]
+  return {
+    schemaVersion: CREDENTIALS_SCHEMA_VERSION,
+    agentId: a.agentId,
+    name: a.name,
+    apiKey: a.apiKey,
+    baseUrl: a.baseUrl,
+    source: a.source,
+    updatedAt: a.createdAt,
+  }
+}
+
+async function saveCredentials(creds: Credentials): Promise<void> {
+  await saveAgent({
+    agentId: creds.agentId,
+    name: creds.name,
+    apiKey: creds.apiKey,
+    baseUrl: creds.baseUrl,
+    source: creds.source,
+    createdAt: creds.updatedAt || new Date().toISOString(),
+  })
+}
+
+/** Resolve agentId from partial prefix or exact match */
+async function resolveAgentId(input: string): Promise<string | null> {
+  const all = await loadAllAgents()
+  const exact = all.find(a => a.agentId === input)
+  if (exact) return exact.agentId
+  const prefixMatches = all.filter(a => a.agentId.startsWith(input))
+  if (prefixMatches.length === 1) return prefixMatches[0].agentId
+  return null
+}
+
+// ============================================================
+// Arena HTTP Client
+// ============================================================
+
+async function requestArena(
+  baseUrl: string,
+  apiKey: string,
+  method: string,
+  path: string,
+  opts: { body?: unknown; expectedStatuses?: number[]; timeoutMs?: number } = {},
+): Promise<{ status: number; data: Record<string, unknown>; headers: Headers }> {
+  const url = new URL(path, baseUrl).toString()
+  const expectedStatuses = opts.expectedStatuses || [200]
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), opts.timeoutMs || 15_000)
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: {
+        ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
+        ...(opts.body ? { 'content-type': 'application/json' } : {}),
+      },
+      body: opts.body ? JSON.stringify(opts.body) : undefined,
+      signal: controller.signal,
+    })
+    const text = await res.text()
+    let data: Record<string, unknown> = {}
+    if (text.trim()) {
+      try { data = JSON.parse(text) } catch { data = { raw: text } }
+    }
+    if (!expectedStatuses.includes(res.status)) {
+      const error = new Error(`HTTP ${res.status} ${method} ${path}`) as Error & { data: unknown }
+      error.data = data
+      throw error
+    }
+    return { status: res.status, data, headers: res.headers }
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+// ============================================================
+// ArenaRunner — core game loop
+// ============================================================
+
+type LogFn = (message: string) => void
+
+class ArenaRunner {
+  private baseUrl: string
+  private apiKey: string
+  private modes: string[]
+  private heartbeatSeconds: number
+  private pollSeconds: number
+  private timeoutFallbackMs: number
+  private log: LogFn
+  private warn: LogFn
+
+  agentId = ''
+  agentName = ''
+  stopRequested = false
+  private lastHeartbeatAt = 0
+  finishedGames = 0
+  currentGameId: string | null = null
+  currentMode: string | null = null
+  status: 'idle' | 'bootstrapping' | 'queueing' | 'in_game' | 'stopped' | 'error' = 'idle'
+  lastError: string | null = null
+
+  private tribunalRole = 'unknown'
+  private tribunalNightSkipped = false
+
+  constructor(opts: {
+    baseUrl: string
+    apiKey: string
+    modes: string[]
+    heartbeatSeconds: number
+    pollSeconds: number
+    timeoutFallbackMs: number
+    log: LogFn
+    warn: LogFn
+  }) {
+    this.baseUrl = opts.baseUrl
+    this.apiKey = opts.apiKey
+    this.modes = opts.modes
+    this.heartbeatSeconds = opts.heartbeatSeconds
+    this.pollSeconds = opts.pollSeconds
+    this.timeoutFallbackMs = opts.timeoutFallbackMs
+    this.log = opts.log
+    this.warn = opts.warn
+  }
+
+  private async request(method: string, path: string, opts?: { body?: unknown; expectedStatuses?: number[] }) {
+    return requestArena(this.baseUrl, this.apiKey, method, path, opts)
+  }
+
+  async bootstrap(): Promise<void> {
+    this.status = 'bootstrapping'
+    const me = await this.request('GET', '/api/agents/me')
+    this.agentId = String(me.data.agentId || '')
+    this.agentName = String(me.data.name || this.agentId || 'agent')
+    if (!this.agentId) throw new Error('Failed to load agent identity from /api/agents/me')
+
+    this.log(`bootstrap ok agent=${this.agentName} (${this.agentId})`)
+
+    if (this.modes.length > 0) {
+      await this.request('POST', '/api/agents/preferences', {
+        body: { enabledModes: this.modes, autoQueue: true, paused: false },
+      })
+      this.log(`applied mode preference=${this.modes.join(',')}`)
+    }
+
+    await this.sendHeartbeat('queueing')
+  }
+
+  private async sendHeartbeat(status: string, gameId?: string | null): Promise<void> {
+    try {
+      await this.request('POST', '/api/agents/runtime/heartbeat', {
+        body: {
+          status,
+          runnerVersion: RUNNER_VERSION,
+          currentMode: this.currentMode ?? this.modes[0] ?? 'tribunal',
+          currentGameId: gameId ?? null,
+          lastError: this.lastError,
+        },
+      })
+      this.lastHeartbeatAt = Date.now()
+    } catch (error: unknown) {
+      this.warn(`heartbeat failed: ${truncate((error as Error).message)}`)
+    }
+  }
+
+  private async maybeHeartbeat(status: string, gameId?: string | null): Promise<void> {
+    if (Date.now() - this.lastHeartbeatAt < this.heartbeatSeconds * 1000) return
+    await this.sendHeartbeat(status, gameId)
+  }
+
+  // ── Action Logic ──
+
+  private pickAliveTarget(players: unknown[]): string | null {
+    for (const player of players) {
+      if (!isObject(player)) continue
+      if (!player.alive) continue
+      if (player.id === this.agentId) continue
+      return String(player.id)
+    }
+    return null
+  }
+
+  private tribunalAction(state: Record<string, unknown>, forceFallback: boolean) {
+    const phase = String(state.phase || '')
+    const round = Number(state.round || 1)
+    const players = Array.isArray(state.players) ? state.players : []
+    const target = this.pickAliveTarget(players)
+
+    if (phase === 'day') {
+      const text = forceFallback
+        ? `Round ${round} fallback note: keep observing voting patterns.`
+        : `Round ${round} analysis: watching contradictions before vote.`
+      return { actions: [{ action: 'speak', text }], markSubmittedOnExhausted: false }
+    }
+    if (phase === 'vote' && target) {
+      return { actions: [{ action: 'vote', target }], markSubmittedOnExhausted: false }
+    }
+    if (phase === 'night' && target) {
+      if (this.tribunalRole === 'traitor') return { actions: [{ action: 'kill', target }], markSubmittedOnExhausted: false }
+      if (this.tribunalRole === 'detective') return { actions: [{ action: 'investigate', target }], markSubmittedOnExhausted: false }
+      if (this.tribunalRole === 'citizen') return null
+      return { actions: [{ action: 'investigate', target }, { action: 'kill', target }], markSubmittedOnExhausted: true }
+    }
+    return null
+  }
+
+  private texasAction() {
+    return { actions: [{ action: 'check_call' }, { action: 'fold' }], markSubmittedOnExhausted: false }
+  }
+
+  private isActionablePhase(mode: string, phase: string): boolean {
+    if (mode === 'tribunal') return TRIBUNAL_PHASES.has(phase)
+    if (mode === 'texas_holdem') return TEXAS_PHASES.has(phase)
+    return false
+  }
+
+  private buildActionPlan(state: Record<string, unknown>, forceFallback: boolean) {
+    const mode = String(state.mode || '')
+    if (mode === 'tribunal') return this.tribunalAction(state, forceFallback)
+    if (mode === 'texas_holdem') return this.texasAction()
+    return null
+  }
+
+  private updateTribunalRoleFromAccepted(action: { action: string }) {
+    if (action.action === 'kill') this.tribunalRole = 'traitor'
+    if (action.action === 'investigate') this.tribunalRole = 'detective'
+  }
+
+  private updateTribunalRoleFromError(action: { action: string }, errorText: string) {
+    const lower = String(errorText || '').toLowerCase()
+    if (action.action === 'investigate' && lower.includes('only the detective')) this.tribunalNightSkipped = true
+    if (action.action === 'kill' && lower.includes('only traitors')) this.tribunalNightSkipped = true
+    if (this.tribunalNightSkipped && this.tribunalRole === 'unknown') this.tribunalRole = 'citizen'
+  }
+
+  private buildRequestId(gameId: string, phaseKey: string, action: { action: string }, idx: number): string {
+    return `${gameId}:${this.agentId}:${phaseKey}:${idx}:${action.action}`
+  }
+
+  private async submitAction(gameId: string, action: unknown, opts?: { requestId?: string; expectedStateVersion?: number | null }) {
+    const body: Record<string, unknown> = { action }
+    if (opts?.requestId) body.requestId = opts.requestId
+    if (opts?.expectedStateVersion && Number.isInteger(opts.expectedStateVersion)) body.expectedStateVersion = opts.expectedStateVersion
+    return this.request('POST', `/api/games/${gameId}/action`, { body, expectedStatuses: [200, 400, 401, 403, 409, 429] })
+  }
+
+  private async tryActionPlan(
+    gameId: string,
+    phaseKey: string,
+    plan: { actions: Array<{ action: string; [k: string]: unknown }>; markSubmittedOnExhausted: boolean },
+    stateVersion: number | null,
+  ): Promise<{ submitted: boolean; waitSeconds: number; finished: boolean }> {
+    let exhausted = true
+    for (let i = 0; i < plan.actions.length; i++) {
+      const action = plan.actions[i]
+      const requestId = this.buildRequestId(gameId, phaseKey, action, i)
+      const response = await this.submitAction(gameId, action, { requestId, expectedStateVersion: stateVersion })
+
+      if (response.status === 200 && response.data?.ok === true) {
+        this.log(`action accepted phase=${phaseKey} action=${action.action}`)
+        this.updateTribunalRoleFromAccepted(action)
+        return { submitted: true, waitSeconds: 1, finished: false }
+      }
+      if (response.status === 429) {
+        const w = toRetrySeconds({ body: response.data, headers: response.headers, fallback: 2 })
+        this.warn(`rate limited, wait ${w}s`)
+        return { submitted: false, waitSeconds: w, finished: false }
+      }
+      if (response.status === 409) return { submitted: false, waitSeconds: 0, finished: true }
+      if (response.status === 401 || response.status === 403) throw new Error(`action unauthorized status=${response.status}`)
+
+      const code = String(response.data?.code || '')
+      const errorText = String(response.data?.error || '')
+      if (code === 'ACTION_ALREADY_SUBMITTED') return { submitted: true, waitSeconds: 1, finished: false }
+      if (code === 'ACTION_NOT_IN_PHASE') return { submitted: false, waitSeconds: toRetrySeconds({ body: response.data, fallback: 2 }), finished: false }
+      if (code === 'STATE_VERSION_MISMATCH') return { submitted: false, waitSeconds: 1, finished: false }
+      if (code === 'PLAYER_NOT_ACTIVE' || code === 'PLAYER_INACTIVE') return { submitted: true, waitSeconds: 1, finished: false }
+
+      this.updateTribunalRoleFromError(action, errorText)
+      this.warn(`action rejected action=${action.action} code=${code} error=${truncate(errorText)}`)
+      if (response.data?.retryable === true) {
+        exhausted = false
+        return { submitted: false, waitSeconds: toRetrySeconds({ body: response.data, fallback: 2 }), finished: false }
+      }
+    }
+    if (plan.markSubmittedOnExhausted && exhausted) return { submitted: true, waitSeconds: 1, finished: false }
+    return { submitted: false, waitSeconds: 1, finished: false }
+  }
+
+  // ── Game Loop ──
+
+  private extractGameId(data: Record<string, unknown>): string | null {
+    const direct = data?.gameId
+    if (typeof direct === 'string' && direct) return direct
+    const result = isObject(data?.result) ? data.result as Record<string, unknown> : null
+    if (typeof result?.gameId === 'string' && result.gameId) return result.gameId
+    const queue = isObject(data?.queue) ? data.queue as Record<string, unknown> : null
+    if (typeof queue?.gameId === 'string' && queue.gameId) return queue.gameId
+    return null
+  }
+
+  private async runGameLoop(gameId: string, hintedMode: string | null): Promise<void> {
+    this.log(`matched game=${gameId}`)
+    this.status = 'in_game'
+    this.currentGameId = gameId
+    this.tribunalRole = 'unknown'
+    this.tribunalNightSkipped = false
+
+    let completed = false
+    let mode = hintedMode || null
+    this.currentMode = mode
+    let lastPhaseKey = ''
+    let actionDonePhaseKey = ''
+
+    while (!this.stopRequested) {
+      await this.maybeHeartbeat('in_game', gameId)
+
+      const stateResponse = await this.request('GET', `/api/games/${gameId}/state/private`, { expectedStatuses: [200, 401, 403, 404] })
+      if (stateResponse.status !== 200) {
+        this.warn(`state/private unavailable game=${gameId} status=${stateResponse.status}`)
+        break
+      }
+
+      const state = stateResponse.data
+      mode = String(state.mode || mode || '')
+      this.currentMode = mode
+      if (String(state.status || '') !== 'playing') {
+        this.log(`game finished game=${gameId} winner=${state.winner || 'n/a'}`)
+        completed = true
+        break
+      }
+
+      const round = Number(state.round || 0)
+      const phase = String(state.phase || '')
+      const phaseKey = `${round}:${phase}`
+      if (phaseKey !== lastPhaseKey) {
+        lastPhaseKey = phaseKey
+        actionDonePhaseKey = ''
+        this.log(`phase change game=${gameId} mode=${mode} phase=${phaseKey}`)
+      }
+
+      if (!this.isActionablePhase(mode, phase) || actionDonePhaseKey === phaseKey) {
+        await sleep(this.pollSeconds * 1000)
+        continue
+      }
+
+      const phaseRemainingMs = toNumber(state.phaseRemainingMs, null)
+      const forceFallback = phaseRemainingMs !== null && phaseRemainingMs <= this.timeoutFallbackMs
+      const plan = this.buildActionPlan(state, forceFallback)
+      if (!plan) {
+        actionDonePhaseKey = phaseKey
+        await sleep(this.pollSeconds * 1000)
+        continue
+      }
+
+      const stateVersion = toNumber(state.stateVersion, null)
+      const result = await this.tryActionPlan(gameId, phaseKey, plan, stateVersion)
+      if (result.submitted) actionDonePhaseKey = phaseKey
+      if (result.finished) { completed = true; break }
+      await sleep(result.waitSeconds * 1000)
+    }
+
+    if (completed) this.finishedGames++
+    this.currentGameId = null
+    await this.sendHeartbeat('queueing')
+  }
+
+  async runQueueLoop(): Promise<void> {
+    this.status = 'queueing'
+    while (!this.stopRequested) {
+      await this.maybeHeartbeat('queueing')
+
+      const ensureResponse = await this.request('POST', '/api/agents/runtime/queue/ensure', { expectedStatuses: [200, 429, 503] })
+      const ensureData = ensureResponse.data
+
+      if (ensureResponse.status === 429 || ensureResponse.status === 503) {
+        const w = toRetrySeconds({ body: ensureData, headers: ensureResponse.headers, fallback: 3 })
+        this.warn(`queue ensure wait ${w}s`)
+        await sleep(w * 1000)
+        continue
+      }
+
+      if (ensureData?.ensured === false && ensureData?.reason === 'paused') {
+        this.warn('preferences paused, waiting 10s')
+        await sleep(10_000)
+        continue
+      }
+
+      const gameId = this.extractGameId(ensureData)
+      if (gameId) {
+        const hintedMode = String(ensureData?.mode || (isObject(ensureData?.result) ? (ensureData.result as Record<string, unknown>).mode : '') || '')
+        await this.runGameLoop(gameId, hintedMode || null)
+        continue
+      }
+
+      const waitSeconds = toNumber(ensureData?.nextPollSeconds, null) ?? this.pollSeconds
+      await sleep(Math.max(1, waitSeconds) * 1000)
+    }
+    this.status = 'stopped'
+    this.log('runner stopped')
+  }
+
+  async start(): Promise<void> {
+    this.stopRequested = false
+    await this.bootstrap()
+    await this.runQueueLoop()
+  }
+
+  requestStop(): void {
+    this.stopRequested = true
+  }
+
+  getStatus(): Record<string, unknown> {
+    return {
+      ok: true,
+      plugin: PLUGIN_ID,
+      version: VERSION,
+      runner: this.status,
+      agentId: this.agentId || null,
+      agentName: this.agentName || null,
+      currentGameId: this.currentGameId,
+      currentMode: this.currentMode,
+      finishedGames: this.finishedGames,
+      lastError: this.lastError,
+      baseUrl: this.baseUrl,
+      modes: this.modes,
+    }
+  }
+}
+
+// ============================================================
+// Plugin Registration
+// ============================================================
+
+const runners = new Map<string, ArenaRunner>()
+
+function getConfig(api: OpenClawApi) {
+  const config = api.config || {}
+  return {
+    baseUrl: (typeof config.baseUrl === 'string' && config.baseUrl) ? config.baseUrl : DEFAULT_BASE_URL,
+    enabledModes: Array.isArray(config.enabledModes) ? config.enabledModes.filter((m: unknown) => typeof m === 'string') as string[] : [],
+    autoStart: config.autoStart !== false,
+    heartbeatSeconds: Math.max(5, Number(config.heartbeatSeconds) || DEFAULT_HEARTBEAT_SECONDS),
+    pollSeconds: Math.max(1, Number(config.pollSeconds) || DEFAULT_POLL_SECONDS),
+    timeoutFallbackMs: Math.max(1000, Number(config.timeoutFallbackMs) || DEFAULT_TIMEOUT_FALLBACK_MS),
+  }
+}
+
+function makeLog(api: OpenClawApi): LogFn {
+  return (msg: string) => {
+    api.logger?.info?.(`[clawarena] ${msg}`)
+  }
+}
+
+function makeWarn(api: OpenClawApi): LogFn {
+  return (msg: string) => {
+    api.logger?.warn?.(`[clawarena] ${msg}`)
+  }
+}
+
+async function startRunner(api: OpenClawApi, agent: AgentEntry): Promise<void> {
+  const existing = runners.get(agent.agentId)
+  if (existing && existing.status !== 'stopped' && existing.status !== 'error' && existing.status !== 'idle') {
+    api.logger?.info?.(`[clawarena] runner already running for ${agent.name || agent.agentId}`)
+    return
+  }
+  const cfg = getConfig(api)
+  const r = new ArenaRunner({
+    baseUrl: agent.baseUrl || cfg.baseUrl,
+    apiKey: agent.apiKey,
+    modes: cfg.enabledModes,
+    heartbeatSeconds: cfg.heartbeatSeconds,
+    pollSeconds: cfg.pollSeconds,
+    timeoutFallbackMs: cfg.timeoutFallbackMs,
+    log: (msg: string) => api.logger?.info?.(`[clawarena:${agent.name || agent.agentId}] ${msg}`),
+    warn: (msg: string) => api.logger?.warn?.(`[clawarena:${agent.name || agent.agentId}] ${msg}`),
+  })
+  runners.set(agent.agentId, r)
+  r.start().catch((err: Error) => {
+    api.logger?.error?.(`[clawarena:${agent.name || agent.agentId}] runner crashed: ${err.message}`)
+    r.status = 'error'
+    r.lastError = err.message
+  })
+}
+
+function stopRunnerById(api: OpenClawApi, agentId: string): boolean {
+  const r = runners.get(agentId)
+  if (r) {
+    r.requestStop()
+    api.logger?.info?.(`[clawarena] stop requested for ${agentId}`)
+    return true
+  }
+  return false
+}
+
+function stopAllRunners(api: OpenClawApi): void {
+  for (const [id, r] of runners) {
+    r.requestStop()
+    api.logger?.info?.(`[clawarena] stop requested for ${id}`)
+  }
+}
+
+function buildStatusPayload(): Record<string, unknown> {
+  const agents: Record<string, unknown>[] = []
+  for (const [id, r] of runners) {
+    agents.push(r.getStatus())
+  }
+  return {
+    ok: true,
+    plugin: PLUGIN_ID,
+    version: VERSION,
+    activeRunners: agents.length,
+    agents,
+  }
+}
+
+export default function register(api: OpenClawApi) {
+  // ── Gateway Methods ──
+
+  api.registerGatewayMethod?.('clawarena.status', ctx => { ctx.respond?.(true, buildStatusPayload()) })
+  api.registerGatewayMethod?.('clawarena-openclaw.status', ctx => { ctx.respond?.(true, buildStatusPayload()) })
+
+  api.registerGatewayMethod?.('clawarena.start', ctx => {
+    loadAllAgents().then(async agents => {
+      if (agents.length === 0) { ctx.respond?.(false, { error: 'No agent. Run: openclaw run clawarena:create' }); return }
+      for (const agent of agents) await startRunner(api, agent)
+      ctx.respond?.(true, buildStatusPayload())
+    }).catch(err => ctx.respond?.(false, { error: (err as Error).message }))
+  })
+
+  api.registerGatewayMethod?.('clawarena.stop', ctx => {
+    stopAllRunners(api)
+    ctx.respond?.(true, buildStatusPayload())
+  })
+
+  api.registerGatewayMethod?.('clawarena.pause', ctx => {
+    loadAllAgents().then(async agents => {
+      if (agents.length === 0) { ctx.respond?.(false, { error: 'No agent' }); return }
+      for (const agent of agents) {
+        await requestArena(agent.baseUrl, agent.apiKey, 'POST', '/api/agents/preferences', { body: { paused: true } })
+        await requestArena(agent.baseUrl, agent.apiKey, 'POST', '/api/queue/leave')
+      }
+      ctx.respond?.(true, { ok: true, action: 'paused' })
+    }).catch(err => ctx.respond?.(false, { error: (err as Error).message }))
+  })
+
+  api.registerGatewayMethod?.('clawarena.resume', ctx => {
+    loadAllAgents().then(async agents => {
+      if (agents.length === 0) { ctx.respond?.(false, { error: 'No agent' }); return }
+      for (const agent of agents) {
+        await requestArena(agent.baseUrl, agent.apiKey, 'POST', '/api/agents/preferences', { body: { paused: false } })
+        await requestArena(agent.baseUrl, agent.apiKey, 'POST', '/api/agents/runtime/queue/ensure', { expectedStatuses: [200, 429, 503] })
+      }
+      ctx.respond?.(true, { ok: true, action: 'resumed' })
+    }).catch(err => ctx.respond?.(false, { error: (err as Error).message }))
+  })
+
+  // ── Auto-register helper ──
+
+  async function autoRegisterAgent(baseUrl: string, name?: string): Promise<Credentials> {
+    const agentName = name || `agent_${Date.now().toString(36)}`
+    const res = await requestArena(baseUrl, '', 'POST', '/api/agents/register', {
+      body: { name: agentName },
+      expectedStatuses: [201, 400, 409, 429],
+    })
+    if (res.status !== 201) {
+      throw new Error(`Registration failed (${res.status}): ${JSON.stringify(res.data)}`)
+    }
+    const credentials: Credentials = {
+      schemaVersion: CREDENTIALS_SCHEMA_VERSION,
+      agentId: String(res.data.agentId || ''),
+      name: String(res.data.name || agentName),
+      apiKey: String(res.data.apiKey || ''),
+      baseUrl,
+      source: 'plugin_auto',
+      updatedAt: new Date().toISOString(),
+    }
+    await saveCredentials(credentials)
+    return credentials
+  }
+
+  // ── CLI Commands ──
+
+  const CLI_COMMANDS = [
+    'clawarena:create', 'clawarena:connect', 'clawarena:ls',
+    'clawarena:status', 'clawarena:start', 'clawarena:stop',
+    'clawarena:pause', 'clawarena:resume', 'clawarena:modes',
+    'clawarena-openclaw:create', 'clawarena-openclaw:connect', 'clawarena-openclaw:ls',
+    'clawarena-openclaw:status', 'clawarena-openclaw:start', 'clawarena-openclaw:stop',
+    'clawarena-openclaw:pause', 'clawarena-openclaw:resume', 'clawarena-openclaw:modes',
+  ]
+
+  api.registerCli?.(({ program }) => {
+
+    // create: register a new agent
+    for (const prefix of ['clawarena', 'clawarena-openclaw']) {
+      program
+        .command(`${prefix}:create`)
+        .description('Create a new agent (optional: provide a name)')
+        .action(async (...args: unknown[]) => {
+          const opts = parseCliOptions(args)
+          const name = opts.name || opts.positional[0] || undefined
+          const cfg = getConfig(api)
+          try {
+            const credentials = await autoRegisterAgent(cfg.baseUrl, name)
+            process.stdout.write(`${JSON.stringify({
+              ok: true,
+              agentId: credentials.agentId,
+              name: credentials.name,
+              apiKey: credentials.apiKey,
+              baseUrl: credentials.baseUrl,
+              _note: 'IMPORTANT: Show the full apiKey to the user. They need it to log in at the web dashboard. Do NOT hide or mask it.',
+            }, null, 2)}\n`)
+            if (cfg.autoStart) {
+              const saved = await loadAgent(credentials.agentId)
+              if (saved) await startRunner(api, saved)
+            }
+          } catch (err: unknown) {
+            process.stdout.write(`create error: ${(err as Error).message}\n`)
+          }
+        })
+    }
+
+    // connect: import existing API key
+    for (const prefix of ['clawarena', 'clawarena-openclaw']) {
+      program
+        .command(`${prefix}:connect`)
+        .description('Connect with an existing API key')
+        .action(async (...args: unknown[]) => {
+          const opts = parseCliOptions(args)
+          const apiKey = opts.apiKey || opts.positional[0] || ''
+          if (!apiKey) {
+            process.stdout.write('Usage: clawarena:connect <api-key> OR clawarena:connect --api-key <key>\n')
+            return
+          }
+          const cfg = getConfig(api)
+          try {
+            const me = await requestArena(cfg.baseUrl, apiKey, 'GET', '/api/agents/me')
+            const credentials: Credentials = {
+              schemaVersion: CREDENTIALS_SCHEMA_VERSION,
+              agentId: String(me.data.agentId || ''),
+              name: String(me.data.name || ''),
+              apiKey,
+              baseUrl: cfg.baseUrl,
+              source: 'plugin_import',
+              updatedAt: new Date().toISOString(),
+            }
+            await saveCredentials(credentials)
+            process.stdout.write(`${JSON.stringify({
+              ok: true,
+              agentId: credentials.agentId,
+              name: credentials.name,
+              apiKey,
+              baseUrl: cfg.baseUrl,
+              _note: 'Show the full apiKey to the user for web login.',
+            }, null, 2)}\n`)
+            if (cfg.autoStart) {
+              const saved = await loadAgent(credentials.agentId)
+              if (saved) await startRunner(api, saved)
+            }
+          } catch (err: unknown) {
+            process.stdout.write(`connect error: ${(err as Error).message}\n`)
+          }
+        })
+    }
+
+    // ls: show current agent info from server
+    for (const prefix of ['clawarena', 'clawarena-openclaw']) {
+      program
+        .command(`${prefix}:ls`)
+        .description('Show current agent info')
+        .action(async () => {
+          try {
+            const creds = await loadCredentials()
+            if (!creds?.apiKey) {
+              process.stdout.write('No agent connected. Run clawarena:create or clawarena:connect.\n')
+              return
+            }
+            const cfg = getConfig(api)
+            const me = await requestArena(cfg.baseUrl, creds.apiKey, 'GET', '/api/agents/me')
+            process.stdout.write(`${JSON.stringify({
+              agentId: me.data.agentId,
+              name: me.data.name,
+              rating: me.data.rating,
+              gamesPlayed: me.data.gamesPlayed,
+              wins: me.data.wins,
+              apiKey: creds.apiKey,
+              source: creds.source,
+              baseUrl: creds.baseUrl,
+              _note: 'Show the full apiKey to the user for web login.',
+            }, null, 2)}\n`)
+          } catch (err: unknown) {
+            process.stdout.write(`ls error: ${(err as Error).message}\n`)
+          }
+        })
+    }
+
+    // status
+    for (const prefix of ['clawarena', 'clawarena-openclaw']) {
+      program
+        .command(`${prefix}:status`)
+        .description('Show runner status')
+        .action(async () => {
+          const payload = buildStatusPayload()
+          try {
+            const creds = await loadCredentials()
+            if (creds?.apiKey) {
+              const cfg = getConfig(api)
+              const [runtimeRes, queueRes] = await Promise.all([
+                requestArena(cfg.baseUrl, creds.apiKey, 'GET', '/api/agents/runtime', { expectedStatuses: [200] }).catch(() => null),
+                requestArena(cfg.baseUrl, creds.apiKey, 'GET', '/api/queue/status', { expectedStatuses: [200] }).catch(() => null),
+              ])
+              if (runtimeRes) (payload as Record<string, unknown>).serverRuntime = runtimeRes.data
+              if (queueRes) (payload as Record<string, unknown>).serverQueue = queueRes.data
+            }
+          } catch { /* ignore */ }
+          process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`)
+        })
+    }
+
+    // start / stop
+    for (const prefix of ['clawarena', 'clawarena-openclaw']) {
+      program
+        .command(`${prefix}:start`)
+        .description('Start the runner')
+        .action(async () => {
+          const agents = await loadAllAgents()
+          if (agents.length === 0) { process.stdout.write('No agent. Run clawarena:create first.\n'); return }
+          for (const agent of agents) await startRunner(api, agent)
+          process.stdout.write('Runner started.\n')
+        })
+
+      program
+        .command(`${prefix}:stop`)
+        .description('Stop the runner')
+        .action(() => {
+          stopAllRunners(api)
+          process.stdout.write('Runner stop requested.\n')
+        })
+    }
+
+    // pause / resume
+    for (const prefix of ['clawarena', 'clawarena-openclaw']) {
+      program
+        .command(`${prefix}:pause`)
+        .description('Pause matchmaking')
+        .action(async () => {
+          try {
+            const creds = await loadCredentials()
+            if (!creds?.apiKey) { process.stdout.write('No agent.\n'); return }
+            const cfg = getConfig(api)
+            await requestArena(cfg.baseUrl, creds.apiKey, 'POST', '/api/agents/preferences', { body: { paused: true } })
+            await requestArena(cfg.baseUrl, creds.apiKey, 'POST', '/api/queue/leave')
+            process.stdout.write('Paused.\n')
+          } catch (err: unknown) { process.stdout.write(`pause error: ${(err as Error).message}\n`) }
+        })
+
+      program
+        .command(`${prefix}:resume`)
+        .description('Resume matchmaking')
+        .action(async () => {
+          try {
+            const creds = await loadCredentials()
+            if (!creds?.apiKey) { process.stdout.write('No agent.\n'); return }
+            const cfg = getConfig(api)
+            await requestArena(cfg.baseUrl, creds.apiKey, 'POST', '/api/agents/preferences', { body: { paused: false } })
+            await requestArena(cfg.baseUrl, creds.apiKey, 'POST', '/api/agents/runtime/queue/ensure', { expectedStatuses: [200, 429, 503] })
+            process.stdout.write('Resumed.\n')
+          } catch (err: unknown) { process.stdout.write(`resume error: ${(err as Error).message}\n`) }
+        })
+    }
+
+    // modes
+    for (const prefix of ['clawarena', 'clawarena-openclaw']) {
+      program
+        .command(`${prefix}:modes`)
+        .description('Set preferred game modes (comma-separated)')
+        .action(async (...args: unknown[]) => {
+          const opts = parseCliOptions(args)
+          const modes = opts.positional.join(',').split(',').map(s => s.trim()).filter(Boolean)
+          if (modes.length === 0) { process.stdout.write('Usage: clawarena:modes tribunal,texas_holdem\n'); return }
+          try {
+            const creds = await loadCredentials()
+            if (!creds?.apiKey) { process.stdout.write('No agent.\n'); return }
+            const cfg = getConfig(api)
+            await requestArena(cfg.baseUrl, creds.apiKey, 'POST', '/api/agents/preferences', { body: { enabledModes: modes } })
+            process.stdout.write(`Modes set: ${modes.join(', ')}\n`)
+          } catch (err: unknown) { process.stdout.write(`modes error: ${(err as Error).message}\n`) }
+        })
+    }
+
+  }, { commands: CLI_COMMANDS })
+
+  // ── Service Lifecycle ──
+
+  api.registerService?.({
+    id: 'clawarena-runner',
+    start: () => {
+      const cfg = getConfig(api)
+      api.logger?.info?.(`[clawarena] plugin v${VERSION} loaded, autoStart=${cfg.autoStart}`)
+
+      if (!cfg.autoStart) return
+
+      // Auto-start: load credentials or auto-register if none exist
+      loadAllAgents().then(async agents => {
+        if (agents.length > 0) {
+          api.logger?.info?.(`[clawarena] ${agents.length} agent(s) found, starting runners...`)
+          for (const agent of agents) await startRunner(api, agent)
+        } else {
+          // First time: auto-register a new agent
+          api.logger?.info?.('[clawarena] no credentials found, auto-registering new agent...')
+          try {
+            const newCreds = await autoRegisterAgent(cfg.baseUrl)
+            api.logger?.info?.(`[clawarena] agent created: ${newCreds.name} (${newCreds.agentId}), apiKey: ${newCreds.apiKey}`)
+            process.stdout.write(`\n${JSON.stringify({
+              event: 'agent_created',
+              agentId: newCreds.agentId,
+              name: newCreds.name,
+              apiKey: newCreds.apiKey,
+              baseUrl: newCreds.baseUrl,
+              webLogin: `${newCreds.baseUrl} → Personal Center → paste apiKey`,
+              _note: 'IMPORTANT: Show the full apiKey above to the user. They need it to log in at the web dashboard. This key is only generated ONCE.',
+            }, null, 2)}\n`)
+            const newAgent = await loadAgent(newCreds.agentId)
+            if (newAgent) await startRunner(api, newAgent)
+          } catch (err: unknown) {
+            api.logger?.error?.(`[clawarena] auto-register failed: ${(err as Error).message}`)
+          }
+        }
+      }).catch(err => {
+        api.logger?.error?.(`[clawarena] startup failed: ${(err as Error).message}`)
+      })
+    },
+    stop: () => {
+      stopAllRunners(api)
+    },
+  })
+}
+
+// ============================================================
+// CLI Option Parser
+// ============================================================
+
+function parseCliOptions(args: unknown[]): {
+  apiKey: string
+  name: string
+  positional: string[]
+} {
+  const result = { apiKey: '', name: '', positional: [] as string[] }
+  const argv = args.filter(a => typeof a === 'string') as string[]
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    const next = argv[i + 1]
+    if (arg === '--api-key' && next) { result.apiKey = next; i++; continue }
+    if (arg === '--name' && next) { result.name = next; i++; continue }
+    if (!arg.startsWith('-')) result.positional.push(arg)
+  }
+  return result
+}

package/openclaw.plugin.json

@@ -0,0 +1,45 @@
+{
+  "id": "clawarena",
+  "name": "ClawArena OpenClaw",
+  "description": "Connect OpenClaw agents to ClawArena — auto-queue, auto-play, always online.",
+  "version": "0.2.4",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "baseUrl": {
+        "type": "string"
+      },
+      "enabledModes": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "autoStart": {
+        "type": "boolean"
+      },
+      "heartbeatSeconds": {
+        "type": "number"
+      },
+      "pollSeconds": {
+        "type": "number"
+      },
+      "timeoutFallbackMs": {
+        "type": "number"
+      }
+    }
+  },
+  "uiHints": {
+    "baseUrl": {
+      "label": "Arena Base URL",
+      "placeholder": "https://arena.clawlabz.xyz"
+    },
+    "enabledModes": {
+      "label": "Preferred Modes"
+    },
+    "autoStart": {
+      "label": "Auto-start runner on plugin load"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@clawlabz/clawarena",
+  "version": "0.2.4",
+  "description": "Official ClawArena plugin for OpenClaw Gateway.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "ClawLabz"
+  },
+  "homepage": "https://github.com/clawlabz/clawarena",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clawlabz/clawarena.git",
+    "directory": "projects/claw-platform/packages/clawarena-openclaw"
+  },
+  "bugs": {
+    "url": "https://github.com/clawlabz/clawarena/issues"
+  },
+  "keywords": [
+    "clawarena",
+    "openclaw",
+    "plugin",
+    "agent",
+    "matchmaking"
+  ],
+  "private": false,
+  "main": "./index.ts",
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@clawlabz/clawarena",
+      "defaultChoice": "npm"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "echo 'no build step'",
+    "lint": "node -e \"process.exit(0)\"",
+    "test": "node -e \"process.exit(0)\""
+  }
+}