@myclaw163/clawclaw-cli 0.6.64 → 0.6.66

package/src/lib/game-client.ts

@@ -1,391 +1,391 @@
-// src/lib/game-client.ts
-import type { GameState } from '../sdk/types.js';
-import { AuthStore } from './auth.js';
-import { ServerRegistry } from './server-registry.js';
-import { HttpTransport, ApiError } from './http-transport.js';
-import { WsClient } from '../runtime/ws-client.js';
-import { normalizeGameState } from './normalize.js';
-import { RuntimeLogger } from '../runtime/runtime-logger.js';
-
-export { ApiError } from './http-transport.js';
-
-export interface GameClientConfig {
-  lobbyUrl: string;
-  gameServerUrl?: string;
-  apiKey: string;
-  agentName?: string;
-  enableWs?: boolean;
-  rawWsLogPath?: string;
-}
-
-export class GameClient {
-  private http: HttpTransport;
-  private ws: WsClient | null = null;
-  private wsHandlers: Array<{
-    eventType: string;
-    handler: (data: Record<string, any>) => void;
-    unsubscribe?: () => void;
-  }> = [];
-  private registry: ServerRegistry;
-  private apiKey: string;
-  private enableWs: boolean;
-  private rawWsLogPath?: string;
-  private log = new RuntimeLogger();
-
-  constructor(config: GameClientConfig) {
-    this.apiKey = config.apiKey;
-    this.enableWs = config.enableWs ?? false;
-    this.rawWsLogPath = config.rawWsLogPath;
-    this.registry = new ServerRegistry({
-      lobbyUrl: config.lobbyUrl,
-      gameServerUrl: config.gameServerUrl,
-      agentName: config.agentName,
-    });
-    this.http = new HttpTransport(config.apiKey, this.registry);
-  }
-
-  // ─── Factory Methods ───
-
-  /**
-   * Create GameClient from active auth profile.
-   * Used by both runtime listeners (ws: true) and CLI commands (ws: false).
-   */
-  static fromAuth(opts?: { ws?: boolean; authStore?: AuthStore; rawWsLogPath?: string }): GameClient {
-    const store = opts?.authStore ?? new AuthStore();
-    const profile = store.getActive();
-
-    if (!profile) {
-      throw new Error('No active auth profile. Run: clawclaw-cli account register');
-    }
-
-    return new GameClient({
-      lobbyUrl: profile.serverUrl,
-      gameServerUrl: profile.gameServerUrl,
-      apiKey: profile.apiKey,
-      agentName: profile.agentName,
-      enableWs: opts?.ws ?? false,
-      rawWsLogPath: opts?.rawWsLogPath,
-    });
-  }
-
-  /** Get current server addresses. */
-  get addresses() {
-    return this.registry.addresses;
-  }
-
-  // ─── Game API (→ game server) ───
-  async getGameState(): Promise<GameState | null> {
-    try {
-      const res = await this.http.get<any>('/api/v1/game/current');
-      return normalizeGameState(res.data ?? res);
-    } catch (err: any) {
-      if (err instanceof ApiError && err.body?.includes('NO_ACTIVE_GAME')) return null;
-      throw err; // unexpected error — let caller decide
-    }
-  }
-
-  /**
-   * Submit a game action.
-   * If WS is connected, sends via WebSocket (lower latency).
-   * Otherwise falls back to HTTP POST.
-   */
-  async submitAction(action: {
-    action: string; target?: string; target_x?: number; target_y?: number;
-    task_name?: string; text?: string; thinking_content?: string; audio_url?: string;
-  }): Promise<any> {
-    if (this.ws?.connected) {
-      this.ws.send({ toJSON: () => action });
-      return;
-    }
-    return this.http.post('/api/v1/game/action', action);
-  }
-
-  /**
-   * Fetch the game map (rooms, tasks, spawn points).
-   * Returns null on failure — callers should handle gracefully since
-   * map data is supplementary (game loop continues without it).
-   */
-  async getMap(): Promise<any> {
-    try {
-      const res = await this.http.get<any>('/api/v1/game/map');
-      return res.data ?? res;
-    } catch (err: any) {
-      this.log.error('HTTP_GET_MAP', 'getMap failed', err);
-      return null;
-    }
-  }
-
-  // ─── Audio Upload (→ lobby) ───
-
-  /**
-   * Upload an audio file to the Lobby server.
-   * Returns the audio URL to use in speech actions.
-   *
-   * @param filePathOrBuffer - Absolute file path (string) or Buffer of the audio file
-   * @param filename - Optional filename (required when passing Buffer, defaults to 'audio.mp3')
-   * @param contentType - Optional MIME type, defaults to audio/mpeg
-   * @returns Object with `audio_url` field
-   */
-  async uploadAudio(
-    filePathOrBuffer: string | Buffer,
-    filename?: string,
-    contentType = 'audio/mpeg',
-  ): Promise<{ audio_url: string }> {
-    const form = new FormData();
-
-    if (typeof filePathOrBuffer === 'string') {
-      // File path: read from disk
-      const fs = await import('fs');
-      const path = await import('path');
-      if (!fs.existsSync(filePathOrBuffer)) {
-        throw new Error(`Audio file not found: ${filePathOrBuffer}`);
-      }
-      const buffer = fs.readFileSync(filePathOrBuffer);
-      const name = filename ?? path.basename(filePathOrBuffer);
-      const blob = new Blob([buffer as any], { type: contentType });
-      form.append('file', blob, name);
-    } else {
-      // Buffer: wrap as Blob
-      const name = filename ?? 'audio.mp3';
-      const blob = new Blob([filePathOrBuffer as any], { type: contentType });
-      form.append('file', blob, name);
-    }
-
-    const result = await this.http.post<any>('/api/v1/agents/upload_audio', form);
-    const audioUrl = result?.audio_url ?? result?.data?.audio_url;
-    if (!audioUrl) {
-      throw new Error(`upload_audio: unexpected response: ${JSON.stringify(result)}`);
-    }
-    return { audio_url: audioUrl };
-  }
-
-  // ─── Agent API (→ lobby) ───
-
-  /**
-   * Register a new agent. No auth required.
-   * Server expects multipart/form-data with optional name/description/avatar fields.
-   */
-  async registerAgent(opts: {
-    name?: string;
-    description?: string;
-    avatarUrl?: string;
-    avatarFile?: string;
-    inviteCode?: string;
-  }): Promise<any> {
-    const form = new FormData();
-    if (opts.name) form.append('name', opts.name);
-    if (opts.description) form.append('description', opts.description);
-    if (opts.inviteCode) form.append('invite_code', opts.inviteCode);
-    if (opts.avatarUrl) form.append('avatar_url', opts.avatarUrl);
-    if (opts.avatarFile) {
-      const { readFileSync } = await import('fs');
-      const { basename } = await import('path');
-      const buf = readFileSync(opts.avatarFile);
-      form.append('avatar_file', new Blob([buf]), basename(opts.avatarFile));
-    }
-    return this.http.post('/api/v1/agents/register', form);
-  }
-
-  async renameAgent(name: string): Promise<any> {
-    return this.http.request('PATCH', '/api/v1/agents/name', { name });
-  }
-
-  async login(apiKey: string): Promise<any> {
-    return this.http.post('/api/v1/agents/login', { api_key: apiKey });
-  }
-
-  async getMe(): Promise<any> {
-    return this.http.get('/api/v1/agents/me');
-  }
-
-  // ─── Queue API (→ lobby, auto game server discovery) ───
-
-
-
-  async joinQueue(gameType: string = 'clawclaw'): Promise<any> {
-    const result = await this.http.post('/api/v1/queue/join', { game_type: gameType });
-    this.registry.updateFromQueueResponse(result);
-    return result;
-  }
-
-  async getQueueStatus(gameType?: string): Promise<any> {
-    const query = gameType ? `?game_type=${encodeURIComponent(gameType)}` : '';
-    const result = await this.http.get(`/api/v1/queue/status${query}`);
-    this.registry.updateFromQueueResponse(result);
-    return result;
-  }
-
-
-  async leaveQueue(gameType?: string): Promise<any> {
-    const query = gameType ? `?game_type=${encodeURIComponent(gameType)}` : '';
-    return this.http.post(`/api/v1/queue/leave${query}`);
-  }
-
-  /** Leave the active game. Only callable when dead — server returns STILL_ALIVE error otherwise. Clears allocation so the agent can re-queue. */
-  async leaveGame(): Promise<any> {
-    return this.http.post('/api/v1/game/leave');
-  }
-
-  async getRoleInfo(): Promise<any> {
-    return this.http.get('/api/v1/game/role_info');
-  }
-
-  // ─── Economy / Leaderboard ───
-
-  async getLeaderboard(page?: number, limit?: number): Promise<any> {
-    const params = new URLSearchParams();
-    if (page != null) params.set('page', String(page));
-    if (limit != null) params.set('limit', String(limit));
-    const query = params.toString() ? `?${params.toString()}` : '';
-    return this.http.get(`/api/v1/leaderboard${query}`);
-  }
-
-  async getSettlement(): Promise<any> {
-    return this.http.get('/api/v1/game/settlement');
-  }
-
-  async getGameHistory(page?: number, limit?: number): Promise<any> {
-    const params = new URLSearchParams();
-    if (page != null) params.set('page', String(page));
-    if (limit != null) params.set('limit', String(limit));
-    const query = params.toString() ? `?${params.toString()}` : '';
-    return this.http.get(`/api/v1/game/history${query}`);
-  }
-
-  // ─── Connection Management ───
-
-  /** Connect WebSocket to the current server (game server or lobby). */
-  async connectWs(): Promise<boolean> {
-    if (!this.enableWs) return false;
-    if (this.wsConnected) return true;
-
-    const wsUrl = this.registry.wsUrl;
-    if (!wsUrl) {
-      this.log.warn('WS_CONNECT', 'no game server URL for WebSocket');
-      return false;
-    }
-
-    if (this.ws) {
-      this.ws.clearHandlers();
-      this.ws.disconnect();
-      this.markWsHandlersDetached();
-    }
-
-    const newWs = new WsClient({
-      url: wsUrl,
-      apiKey: this.apiKey,
-      rawMessageLogPath: this.rawWsLogPath,
-    });
-    this.ws = newWs;
-    this.attachWsHandlers();
-    try {
-      await newWs.connect();
-      return true;
-    } catch {
-      this.log.warn('WS_CONNECT', 'event WebSocket connection failed; runtime will retry');
-      newWs.disconnect();
-      this.ws = null;
-      this.markWsHandlersDetached();
-      return false;
-    }
-  }
-
-  /** Disconnect WebSocket. */
-  disconnectWs(): void {
-    if (this.ws) {
-      this.ws.disconnect();
-      this.ws = null;
-    }
-  }
-
-  /**
-   * Try to discover game server from /queue/status.
-   * If found and WS is enabled, reconnects WS to the game server.
-   * Returns true if a game server was discovered.
-   *
-   * Note: uses http.get directly instead of getQueueStatus() to avoid
-   * double-calling registry.updateFromQueueResponse().
-   */
-  async discoverGameServer(): Promise<boolean> {
-    try {
-      const result = await this.http.get<any>('/api/v1/queue/status');
-      const changed = this.registry.updateFromQueueResponse(result);
-      if (changed && this._gameServerUrl) {
-        this.log.info('GAME_SERVER_DISCOVERED', `url=${this._gameServerUrl}`);
-        if (this.enableWs) {
-          await this.reconnectWsToGameServer();
-        }
-        return true;
-      }
-    } catch { /* queue/status unavailable */ }
-    return false;
-  }
-
-  /** Reconnect WS to the current game server address. */
-  async reconnectWsToGameServer(): Promise<void> {
-    const wsUrl = this.registry.wsUrl;
-    if (!wsUrl) return;
-
-    // Disconnect old WS
-    if (this.ws) {
-      this.ws.clearHandlers();
-      this.ws.disconnect();
-      this.markWsHandlersDetached();
-    }
-
-    const newWs = new WsClient({
-      url: wsUrl,
-      apiKey: this.apiKey,
-      rawMessageLogPath: this.rawWsLogPath,
-    });
-    this.ws = newWs;
-    this.attachWsHandlers();
-    try {
-      await newWs.connect();
-      this.log.info('WS_RECONNECT', `connected to ${wsUrl}`);
-    } catch {
-      this.log.warn('WS_RECONNECT', 'event WebSocket reconnect failed; runtime will retry');
-      newWs.disconnect();
-      this.ws = null;
-      this.markWsHandlersDetached();
-    }
-  }
-
-  /** Get the current game server URL. */
-  get _gameServerUrl(): string | null {
-    return this.registry.gameServerUrl;
-  }
-
-  // ─── WS Event Proxy ───
-
-  /** Register a handler for a specific WS event type. Returns unsubscribe function. */
-  on(eventType: string, handler: (data: Record<string, any>) => void): () => void {
-    const entry = { eventType, handler, unsubscribe: undefined as (() => void) | undefined };
-    this.wsHandlers.push(entry);
-    if (this.ws) {
-      entry.unsubscribe = this.ws.on(eventType, handler);
-    }
-    return () => {
-      entry.unsubscribe?.();
-      const idx = this.wsHandlers.indexOf(entry);
-      if (idx >= 0) this.wsHandlers.splice(idx, 1);
-    };
-  }
-
-  get wsConnected(): boolean {
-    return this.ws?.connected ?? false;
-  }
-
-  private attachWsHandlers(): void {
-    if (!this.ws) return;
-    for (const entry of this.wsHandlers) {
-      entry.unsubscribe = this.ws.on(entry.eventType, entry.handler);
-    }
-  }
-
-  private markWsHandlersDetached(): void {
-    for (const entry of this.wsHandlers) {
-      entry.unsubscribe = undefined;
-    }
-  }
-}
+// src/lib/game-client.ts
+import type { GameState } from '../sdk/types.js';
+import { AuthStore } from './auth.js';
+import { ServerRegistry } from './server-registry.js';
+import { HttpTransport, ApiError } from './http-transport.js';
+import { WsClient } from '../runtime/ws-client.js';
+import { normalizeGameState } from './normalize.js';
+import { RuntimeLogger } from '../runtime/runtime-logger.js';
+
+export { ApiError } from './http-transport.js';
+
+export interface GameClientConfig {
+  lobbyUrl: string;
+  gameServerUrl?: string;
+  apiKey: string;
+  agentName?: string;
+  enableWs?: boolean;
+  rawWsLogPath?: string;
+}
+
+export class GameClient {
+  private http: HttpTransport;
+  private ws: WsClient | null = null;
+  private wsHandlers: Array<{
+    eventType: string;
+    handler: (data: Record<string, any>) => void;
+    unsubscribe?: () => void;
+  }> = [];
+  private registry: ServerRegistry;
+  private apiKey: string;
+  private enableWs: boolean;
+  private rawWsLogPath?: string;
+  private log = new RuntimeLogger();
+
+  constructor(config: GameClientConfig) {
+    this.apiKey = config.apiKey;
+    this.enableWs = config.enableWs ?? false;
+    this.rawWsLogPath = config.rawWsLogPath;
+    this.registry = new ServerRegistry({
+      lobbyUrl: config.lobbyUrl,
+      gameServerUrl: config.gameServerUrl,
+      agentName: config.agentName,
+    });
+    this.http = new HttpTransport(config.apiKey, this.registry);
+  }
+
+  // ─── Factory Methods ───
+
+  /**
+   * Create GameClient from active auth profile.
+   * Used by both runtime listeners (ws: true) and CLI commands (ws: false).
+   */
+  static fromAuth(opts?: { ws?: boolean; authStore?: AuthStore; rawWsLogPath?: string }): GameClient {
+    const store = opts?.authStore ?? new AuthStore();
+    const profile = store.getActive();
+
+    if (!profile) {
+      throw new Error('No active auth profile. Run: clawclaw-cli account register');
+    }
+
+    return new GameClient({
+      lobbyUrl: profile.serverUrl,
+      gameServerUrl: profile.gameServerUrl,
+      apiKey: profile.apiKey,
+      agentName: profile.agentName,
+      enableWs: opts?.ws ?? false,
+      rawWsLogPath: opts?.rawWsLogPath,
+    });
+  }
+
+  /** Get current server addresses. */
+  get addresses() {
+    return this.registry.addresses;
+  }
+
+  // ─── Game API (→ game server) ───
+  async getGameState(): Promise<GameState | null> {
+    try {
+      const res = await this.http.get<any>('/api/v1/game/current');
+      return normalizeGameState(res.data ?? res);
+    } catch (err: any) {
+      if (err instanceof ApiError && err.body?.includes('NO_ACTIVE_GAME')) return null;
+      throw err; // unexpected error — let caller decide
+    }
+  }
+
+  /**
+   * Submit a game action.
+   * If WS is connected, sends via WebSocket (lower latency).
+   * Otherwise falls back to HTTP POST.
+   */
+  async submitAction(action: {
+    action: string; target?: string; target_x?: number; target_y?: number;
+    task_name?: string; text?: string; thinking_content?: string; audio_url?: string;
+  }): Promise<any> {
+    if (this.ws?.connected) {
+      this.ws.send({ toJSON: () => action });
+      return;
+    }
+    return this.http.post('/api/v1/game/action', action);
+  }
+
+  /**
+   * Fetch the game map (rooms, tasks, spawn points).
+   * Returns null on failure — callers should handle gracefully since
+   * map data is supplementary (game loop continues without it).
+   */
+  async getMap(): Promise<any> {
+    try {
+      const res = await this.http.get<any>('/api/v1/game/map');
+      return res.data ?? res;
+    } catch (err: any) {
+      this.log.error('HTTP_GET_MAP', 'getMap failed', err);
+      return null;
+    }
+  }
+
+  // ─── Audio Upload (→ lobby) ───
+
+  /**
+   * Upload an audio file to the Lobby server.
+   * Returns the audio URL to use in speech actions.
+   *
+   * @param filePathOrBuffer - Absolute file path (string) or Buffer of the audio file
+   * @param filename - Optional filename (required when passing Buffer, defaults to 'audio.mp3')
+   * @param contentType - Optional MIME type, defaults to audio/mpeg
+   * @returns Object with `audio_url` field
+   */
+  async uploadAudio(
+    filePathOrBuffer: string | Buffer,
+    filename?: string,
+    contentType = 'audio/mpeg',
+  ): Promise<{ audio_url: string }> {
+    const form = new FormData();
+
+    if (typeof filePathOrBuffer === 'string') {
+      // File path: read from disk
+      const fs = await import('fs');
+      const path = await import('path');
+      if (!fs.existsSync(filePathOrBuffer)) {
+        throw new Error(`Audio file not found: ${filePathOrBuffer}`);
+      }
+      const buffer = fs.readFileSync(filePathOrBuffer);
+      const name = filename ?? path.basename(filePathOrBuffer);
+      const blob = new Blob([buffer as any], { type: contentType });
+      form.append('file', blob, name);
+    } else {
+      // Buffer: wrap as Blob
+      const name = filename ?? 'audio.mp3';
+      const blob = new Blob([filePathOrBuffer as any], { type: contentType });
+      form.append('file', blob, name);
+    }
+
+    const result = await this.http.post<any>('/api/v1/agents/upload_audio', form);
+    const audioUrl = result?.audio_url ?? result?.data?.audio_url;
+    if (!audioUrl) {
+      throw new Error(`upload_audio: unexpected response: ${JSON.stringify(result)}`);
+    }
+    return { audio_url: audioUrl };
+  }
+
+  // ─── Agent API (→ lobby) ───
+
+  /**
+   * Register a new agent. No auth required.
+   * Server expects multipart/form-data with optional name/description/avatar fields.
+   */
+  async registerAgent(opts: {
+    name?: string;
+    description?: string;
+    avatarUrl?: string;
+    avatarFile?: string;
+    inviteCode?: string;
+  }): Promise<any> {
+    const form = new FormData();
+    if (opts.name) form.append('name', opts.name);
+    if (opts.description) form.append('description', opts.description);
+    if (opts.inviteCode) form.append('invite_code', opts.inviteCode);
+    if (opts.avatarUrl) form.append('avatar_url', opts.avatarUrl);
+    if (opts.avatarFile) {
+      const { readFileSync } = await import('fs');
+      const { basename } = await import('path');
+      const buf = readFileSync(opts.avatarFile);
+      form.append('avatar_file', new Blob([buf]), basename(opts.avatarFile));
+    }
+    return this.http.post('/api/v1/agents/register', form);
+  }
+
+  async renameAgent(name: string): Promise<any> {
+    return this.http.request('PATCH', '/api/v1/agents/name', { name });
+  }
+
+  async login(apiKey: string): Promise<any> {
+    return this.http.post('/api/v1/agents/login', { api_key: apiKey });
+  }
+
+  async getMe(): Promise<any> {
+    return this.http.get('/api/v1/agents/me');
+  }
+
+  // ─── Queue API (→ lobby, auto game server discovery) ───
+
+
+
+  async joinQueue(gameType: string = 'clawclaw'): Promise<any> {
+    const result = await this.http.post('/api/v1/queue/join', { game_type: gameType });
+    this.registry.updateFromQueueResponse(result);
+    return result;
+  }
+
+  async getQueueStatus(gameType?: string): Promise<any> {
+    const query = gameType ? `?game_type=${encodeURIComponent(gameType)}` : '';
+    const result = await this.http.get(`/api/v1/queue/status${query}`);
+    this.registry.updateFromQueueResponse(result);
+    return result;
+  }
+
+
+  async leaveQueue(gameType?: string): Promise<any> {
+    const query = gameType ? `?game_type=${encodeURIComponent(gameType)}` : '';
+    return this.http.post(`/api/v1/queue/leave${query}`);
+  }
+
+  /** Leave the active game. Only callable when dead — server returns STILL_ALIVE error otherwise. Clears allocation so the agent can re-queue. */
+  async leaveGame(): Promise<any> {
+    return this.http.post('/api/v1/game/leave');
+  }
+
+  async getRoleInfo(): Promise<any> {
+    return this.http.get('/api/v1/game/role_info');
+  }
+
+  // ─── Economy / Leaderboard ───
+
+  async getLeaderboard(page?: number, limit?: number): Promise<any> {
+    const params = new URLSearchParams();
+    if (page != null) params.set('page', String(page));
+    if (limit != null) params.set('limit', String(limit));
+    const query = params.toString() ? `?${params.toString()}` : '';
+    return this.http.get(`/api/v1/leaderboard${query}`);
+  }
+
+  async getSettlement(): Promise<any> {
+    return this.http.get('/api/v1/game/settlement');
+  }
+
+  async getGameHistory(page?: number, limit?: number): Promise<any> {
+    const params = new URLSearchParams();
+    if (page != null) params.set('page', String(page));
+    if (limit != null) params.set('limit', String(limit));
+    const query = params.toString() ? `?${params.toString()}` : '';
+    return this.http.get(`/api/v1/game/history${query}`);
+  }
+
+  // ─── Connection Management ───
+
+  /** Connect WebSocket to the current server (game server or lobby). */
+  async connectWs(): Promise<boolean> {
+    if (!this.enableWs) return false;
+    if (this.wsConnected) return true;
+
+    const wsUrl = this.registry.wsUrl;
+    if (!wsUrl) {
+      this.log.warn('WS_CONNECT', 'no game server URL for WebSocket');
+      return false;
+    }
+
+    if (this.ws) {
+      this.ws.clearHandlers();
+      this.ws.disconnect();
+      this.markWsHandlersDetached();
+    }
+
+    const newWs = new WsClient({
+      url: wsUrl,
+      apiKey: this.apiKey,
+      rawMessageLogPath: this.rawWsLogPath,
+    });
+    this.ws = newWs;
+    this.attachWsHandlers();
+    try {
+      await newWs.connect();
+      return true;
+    } catch {
+      this.log.warn('WS_CONNECT', 'event WebSocket connection failed; runtime will retry');
+      newWs.disconnect();
+      this.ws = null;
+      this.markWsHandlersDetached();
+      return false;
+    }
+  }
+
+  /** Disconnect WebSocket. */
+  disconnectWs(): void {
+    if (this.ws) {
+      this.ws.disconnect();
+      this.ws = null;
+    }
+  }
+
+  /**
+   * Try to discover game server from /queue/status.
+   * If found and WS is enabled, reconnects WS to the game server.
+   * Returns true if a game server was discovered.
+   *
+   * Note: uses http.get directly instead of getQueueStatus() to avoid
+   * double-calling registry.updateFromQueueResponse().
+   */
+  async discoverGameServer(): Promise<boolean> {
+    try {
+      const result = await this.http.get<any>('/api/v1/queue/status');
+      const changed = this.registry.updateFromQueueResponse(result);
+      if (changed && this._gameServerUrl) {
+        this.log.info('GAME_SERVER_DISCOVERED', `url=${this._gameServerUrl}`);
+        if (this.enableWs) {
+          await this.reconnectWsToGameServer();
+        }
+        return true;
+      }
+    } catch { /* queue/status unavailable */ }
+    return false;
+  }
+
+  /** Reconnect WS to the current game server address. */
+  async reconnectWsToGameServer(): Promise<void> {
+    const wsUrl = this.registry.wsUrl;
+    if (!wsUrl) return;
+
+    // Disconnect old WS
+    if (this.ws) {
+      this.ws.clearHandlers();
+      this.ws.disconnect();
+      this.markWsHandlersDetached();
+    }
+
+    const newWs = new WsClient({
+      url: wsUrl,
+      apiKey: this.apiKey,
+      rawMessageLogPath: this.rawWsLogPath,
+    });
+    this.ws = newWs;
+    this.attachWsHandlers();
+    try {
+      await newWs.connect();
+      this.log.info('WS_RECONNECT', `connected to ${wsUrl}`);
+    } catch {
+      this.log.warn('WS_RECONNECT', 'event WebSocket reconnect failed; runtime will retry');
+      newWs.disconnect();
+      this.ws = null;
+      this.markWsHandlersDetached();
+    }
+  }
+
+  /** Get the current game server URL. */
+  get _gameServerUrl(): string | null {
+    return this.registry.gameServerUrl;
+  }
+
+  // ─── WS Event Proxy ───
+
+  /** Register a handler for a specific WS event type. Returns unsubscribe function. */
+  on(eventType: string, handler: (data: Record<string, any>) => void): () => void {
+    const entry = { eventType, handler, unsubscribe: undefined as (() => void) | undefined };
+    this.wsHandlers.push(entry);
+    if (this.ws) {
+      entry.unsubscribe = this.ws.on(eventType, handler);
+    }
+    return () => {
+      entry.unsubscribe?.();
+      const idx = this.wsHandlers.indexOf(entry);
+      if (idx >= 0) this.wsHandlers.splice(idx, 1);
+    };
+  }
+
+  get wsConnected(): boolean {
+    return this.ws?.connected ?? false;
+  }
+
+  private attachWsHandlers(): void {
+    if (!this.ws) return;
+    for (const entry of this.wsHandlers) {
+      entry.unsubscribe = this.ws.on(entry.eventType, entry.handler);
+    }
+  }
+
+  private markWsHandlersDetached(): void {
+    for (const entry of this.wsHandlers) {
+      entry.unsubscribe = undefined;
+    }
+  }
+}