@myclaw163/clawclaw-cli 0.6.54

package/src/runtime/raw-ws-log.test.ts

@@ -0,0 +1,33 @@
+import { mkdtempSync, readFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { describe, expect, it } from 'vitest';
+import { appendRawWsMessage, isCclTestEnabled, rawWsLogPathForSession } from './raw-ws-log.js';
+
+describe('raw websocket logging helpers', () => {
+  it('is enabled by ccl-test=true or CCL_TEST=true', () => {
+    expect(isCclTestEnabled({ 'ccl-test': 'true' })).toBe(true);
+    expect(isCclTestEnabled({ CCL_TEST: 'true' })).toBe(true);
+    expect(isCclTestEnabled({ 'ccl-test': 'false', CCL_TEST: '0' })).toBe(false);
+  });
+
+  it('derives a per-session raw log path', () => {
+    expect(rawWsLogPathForSession('/tmp/game.jsonl')).toBe('/tmp/game.raw-ws.jsonl');
+    expect(rawWsLogPathForSession('/tmp/game')).toBe('/tmp/game.raw-ws.jsonl');
+  });
+
+  it('appends raw server frames as jsonl', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ccl-raw-ws-'));
+    try {
+      const file = join(dir, 'game.raw-ws.jsonl');
+      appendRawWsMessage(file, '{"type":"state","data":{"tick":1}}');
+      const line = readFileSync(file, 'utf8').trim();
+      const parsed = JSON.parse(line);
+      expect(parsed.direction).toBe('server_to_ccl');
+      expect(parsed.raw).toBe('{"type":"state","data":{"tick":1}}');
+      expect(typeof parsed.ts).toBe('string');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/runtime/raw-ws-log.ts

@@ -0,0 +1,32 @@
+import { appendFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+function isTrue(value: string | undefined): boolean {
+  return typeof value === 'string' && value.trim().toLowerCase() === 'true';
+}
+
+export function isCclTestEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return isTrue(env['ccl-test']) || isTrue(env.CCL_TEST);
+}
+
+export function rawWsLogPathForSession(sessionPath: string): string {
+  return sessionPath.endsWith('.jsonl')
+    ? `${sessionPath.slice(0, -'.jsonl'.length)}.raw-ws.jsonl`
+    : `${sessionPath}.raw-ws.jsonl`;
+}
+
+export function appendRawWsMessage(filePath: string, raw: string): void {
+  try {
+    mkdirSync(dirname(filePath), { recursive: true });
+    appendFileSync(
+      filePath,
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        direction: 'server_to_ccl',
+        raw,
+      }) + '\n',
+    );
+  } catch {
+    // Raw capture is diagnostic-only; never let it affect gameplay.
+  }
+}

package/src/runtime/runtime-logger.ts

@@ -0,0 +1,99 @@
+/**
+ * Runtime Logger — structured, leveled logging for the daemon and CLI.
+ *
+ * Log format:  [Runtime:<LEVEL>] <EVENT_TAG> <message>
+ *
+ * Levels (lowest → highest):
+ *   DEBUG — verbose diagnostics (task detail lists, tick-level state)
+ *   INFO  — key lifecycle events (game start, phase changes, map loaded)
+ *   WARN  — recoverable issues (WS not ready, anti-stuck triggered)
+ *   ERROR — failures that need attention (map load failed, tick error)
+ *
+ * Control via env var CLAWCLAW_LOG_LEVEL (default: DEBUG).
+ */
+
+export enum LogLevel {
+  DEBUG = 0,
+  INFO  = 1,
+  WARN  = 2,
+  ERROR = 3,
+}
+
+const LEVEL_NAMES: Record<LogLevel, string> = {
+  [LogLevel.DEBUG]: 'DEBUG',
+  [LogLevel.INFO]:  'INFO',
+  [LogLevel.WARN]:  'WARN',
+  [LogLevel.ERROR]: 'ERROR',
+};
+
+function parseLogLevel(raw: string | undefined): LogLevel {
+  switch (raw?.toUpperCase()) {
+    case 'DEBUG': return LogLevel.DEBUG;
+    case 'INFO':  return LogLevel.INFO;
+    case 'WARN':  return LogLevel.WARN;
+    case 'ERROR': return LogLevel.ERROR;
+    default:      return LogLevel.DEBUG;
+  }
+}
+
+export class RuntimeLogger {
+  private minLevel: LogLevel;
+
+  constructor() {
+    this.minLevel = parseLogLevel(process.env.CLAWCLAW_LOG_LEVEL);
+  }
+
+  // ─── Core log methods ────────────────────────────────────────────────────
+
+  debug(tag: string, msg: string): void {
+    this.log(LogLevel.DEBUG, tag, msg);
+  }
+
+  info(tag: string, msg: string): void {
+    this.log(LogLevel.INFO, tag, msg);
+  }
+
+  warn(tag: string, msg: string): void {
+    this.log(LogLevel.WARN, tag, msg);
+  }
+
+  error(tag: string, msg: string, err?: unknown): void {
+    const suffix = err instanceof Error ? ` err=${err.message}` : (err ? ` err=${err}` : '');
+    this.log(LogLevel.ERROR, tag, msg + suffix);
+    // Print full stack trace for Error objects (preserves diagnostics from original console.error)
+    if (err instanceof Error && err.stack) {
+      console.error(err.stack);
+    }
+  }
+
+  // ─── Helpers ─────────────────────────────────────────────────────────────
+
+  /**
+   * Log a list of tasks at DEBUG level (reduces repetitive loop logging).
+   * Outputs one indented line per task — pair with a preceding info() call for the summary.
+   */
+  logTaskList(tag: string, tasks: Array<{ name: string; room?: string; x?: number; y?: number; status?: string }>): void {
+    for (const t of tasks) {
+      this.debug(tag, `  └─ ${t.name} room=${t.room ?? '?'} coords=(${t.x ?? '?'},${t.y ?? '?'})${t.status ? ` status=${t.status}` : ''}`);
+    }
+  }
+
+  // ─── Internal ────────────────────────────────────────────────────────────
+
+  private log(level: LogLevel, tag: string, msg: string): void {
+    if (level < this.minLevel) return;
+    const prefix = `[Runtime:${LEVEL_NAMES[level]}]`;
+    const line = `${prefix} ${tag} ${msg}`;
+    switch (level) {
+      case LogLevel.ERROR:
+        console.error(line);
+        break;
+      case LogLevel.WARN:
+        console.warn(line);
+        break;
+      default:
+        console.log(line);
+        break;
+    }
+  }
+}

package/src/runtime/ws-client.test.ts

@@ -0,0 +1,47 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const wsMock = vi.hoisted(() => ({
+  constructed: [] as Array<{ url: string; options: any; instance: any }>,
+}));
+
+vi.mock('ws', () => {
+  class MockWebSocket {
+    onopen: ((event: any) => void) | null = null;
+    onerror: ((event: any) => void) | null = null;
+    onclose: ((event: any) => void) | null = null;
+    onmessage: ((event: any) => void) | null = null;
+    send = vi.fn();
+    close = vi.fn();
+
+    constructor(url: string, options: any) {
+      wsMock.constructed.push({ url, options, instance: this });
+    }
+  }
+
+  return { default: MockWebSocket };
+});
+
+describe('WsClient', () => {
+  beforeEach(() => {
+    wsMock.constructed.length = 0;
+  });
+
+  it('connects with Authorization header instead of api_key query', async () => {
+    const { WsClient } = await import('./ws-client.js');
+    const client = new WsClient({
+      url: 'wss://host.example/api/v1/game/stream',
+      apiKey: 'claw_secret',
+    });
+
+    const connected = client.connect();
+    expect(wsMock.constructed).toHaveLength(1);
+    expect(wsMock.constructed[0].url).toBe('wss://host.example/api/v1/game/stream');
+    expect(wsMock.constructed[0].url).not.toContain('api_key');
+    expect(wsMock.constructed[0].options).toMatchObject({
+      headers: { Authorization: 'Bearer claw_secret' },
+    });
+
+    wsMock.constructed[0].instance.onopen?.({});
+    await connected;
+  });
+});

package/src/runtime/ws-client.ts

@@ -0,0 +1,272 @@
+// src/runtime/ws-client.ts
+// Internal WebSocket client — NOT exported from index.ts
+// Used only by Runtime and daemon internally.
+
+import WebSocket from 'ws';
+import { WsConnectionState } from '../sdk/types.js';
+import { appendRawWsMessage } from './raw-ws-log.js';
+
+export interface WsClientConfig {
+  url: string;
+  apiKey: string;
+  reconnectMaxMs?: number;
+  /** Heartbeat interval in ms (default: 15000). Set to 0 to disable. */
+  heartbeatIntervalMs?: number;
+  /** Diagnostic-only raw server frame log path. */
+  rawMessageLogPath?: string;
+}
+
+/** Heartbeat interval — matches old auto_play.ts */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 15000;
+
+function wsMessageToString(data: WebSocket.Data): string {
+  if (typeof data === 'string') return data;
+  if (Buffer.isBuffer(data)) return data.toString('utf8');
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString('utf8');
+  return Buffer.concat(data).toString('utf8');
+}
+
+export class WsClient {
+  private config: WsClientConfig;
+  private ws: WebSocket | null = null;
+  private _state: WsConnectionState = WsConnectionState.Disconnected;
+  private shouldReconnect = false;
+  private reconnectAttempt = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+  // Type-safe event handlers (new)
+  private typedHandlers = new Map<string, Set<(data: Record<string, any>) => void>>();
+  private disconnectHandlers: ((reason: string) => void)[] = [];
+  private stateChangeHandlers: ((state: WsConnectionState) => void)[] = [];
+  /** High-water mark for tick-based dedup of state.new_events (align with agones) */
+  private lastEventTick = -1;
+
+  constructor(config: WsClientConfig) {
+    this.config = config;
+  }
+
+  get connected(): boolean {
+    return this._state === WsConnectionState.Connected;
+  }
+
+  get state(): WsConnectionState {
+    return this._state;
+  }
+
+  private setState(newState: WsConnectionState): void {
+    if (this._state === newState) return;
+    this._state = newState;
+    for (const handler of this.stateChangeHandlers) {
+      handler(newState);
+    }
+  }
+
+  connect(): Promise<void> {
+    this.shouldReconnect = true;
+    this.reconnectAttempt = 0;
+    this.setState(WsConnectionState.Connecting);
+    return this._openSocket();
+  }
+
+  private _openSocket(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(this.config.url, {
+        headers: { Authorization: `Bearer ${this.config.apiKey}` },
+      });
+      this.ws = ws;
+
+      ws.onopen = () => {
+        this.setState(WsConnectionState.Connected);
+        this.reconnectAttempt = 0;
+        this._startHeartbeat();
+        resolve();
+      };
+
+      ws.onerror = (err) => {
+        reject(err);
+      };
+
+      ws.onmessage = (e) => {
+        const data = wsMessageToString(e.data);
+        if (this.config.rawMessageLogPath) {
+          appendRawWsMessage(this.config.rawMessageLogPath, data);
+        }
+        if (data === 'pong') return;
+        try {
+          const msg = JSON.parse(data);
+          this.handleMessage(msg);
+        } catch {
+          // ignore malformed messages
+        }
+      };
+
+      ws.onclose = (e: { reason: string }) => {
+        this._stopHeartbeat();
+        const reason = e.reason ?? '';
+        for (const handler of this.disconnectHandlers) {
+          handler(reason);
+        }
+        if (this.shouldReconnect) {
+          this.setState(WsConnectionState.Reconnecting);
+          this._scheduleReconnect();
+        } else {
+          this.setState(WsConnectionState.Disconnected);
+        }
+      };
+    });
+  }
+
+  /**
+   * Central message handler: handles event_batch, state, and single events.
+   * Normalizes event format before dispatching.
+   */
+  private handleMessage(msg: any): void {
+    // event_batch: unwrap and dispatch each event individually
+    if (msg.type === 'event_batch' && Array.isArray(msg.data)) {
+      for (const event of msg.data) {
+        this.dispatchEvent(event);
+      }
+      return;
+    }
+    // state: always dispatch the full snapshot as _state for daemon feed tracking
+    // (current_speaker, sub_phase, vote progress, etc. update without necessarily
+    // shipping a new event). Process new_events with tick-based dedup if present.
+    if (msg.type === 'state' && msg.data) {
+      if (Array.isArray(msg.data.new_events)) {
+        const threshold = this.lastEventTick;
+        let maxTick = threshold;
+        for (const event of msg.data.new_events) {
+          const evtTick: number = event.tick ?? -1;
+          if (evtTick <= threshold) continue; // already processed
+          if (evtTick > maxTick) maxTick = evtTick;
+          this.dispatchEvent(event);
+        }
+        this.lastEventTick = maxTick;
+      }
+      this.dispatchEvent({ type: '_state', data: msg.data });
+      return;
+    }
+    // All other messages are dispatched as events
+    this.dispatchEvent(msg);
+  }
+
+  /**
+   * Normalize event format and dispatch to typed + legacy handlers.
+   *
+   * Server sends two formats:
+   *   - { type, field1, field2 }
+   *   - { type, data: { field1, field2 } }
+   * Normalize to consistent data object for typed handlers.
+   */
+  private dispatchEvent(raw: any): void {
+    const type: string = raw.type;
+    if (!type) return;
+
+    // Normalize: extract data payload
+    const { type: _t, data, ...rest } = raw;
+    const normalizedData: Record<string, any> =
+      data && typeof data === 'object' && !Array.isArray(data) ? data : rest;
+
+    // Typed handlers (new API)
+    const handlers = this.typedHandlers.get(type);
+    if (handlers) {
+      for (const handler of handlers) {
+        handler(normalizedData);
+      }
+    }
+
+    // Catch-all `*` handlers
+    const wildcardHandlers = this.typedHandlers.get('*');
+    if (wildcardHandlers) {
+      for (const handler of wildcardHandlers) {
+        handler({ type, ...normalizedData });
+      }
+    }
+  }
+
+  // ─── Public API ───
+
+  /**
+   * Register a handler for a specific event type.
+   * Handler receives normalized data (always a flat object, never nested under .data).
+   * Returns an unsubscribe function.
+   */
+  on(eventType: string, handler: (data: Record<string, any>) => void): () => void {
+    let set = this.typedHandlers.get(eventType);
+    if (!set) {
+      set = new Set();
+      this.typedHandlers.set(eventType, set);
+    }
+    set.add(handler);
+    return () => { set!.delete(handler); };
+  }
+
+  /** Send an action via WebSocket. */
+  send(action: { toJSON(): Record<string, any> }): void {
+    if (this._state !== WsConnectionState.Connected || !this.ws) return;
+    this.ws.send(JSON.stringify({ type: 'action', data: action.toJSON() }));
+  }
+
+  /** Register a handler for state changes. */
+  onStateChange(handler: (state: WsConnectionState) => void): void {
+    this.stateChangeHandlers.push(handler);
+  }
+
+  onDisconnect(handler: (reason: string) => void): void {
+    this.disconnectHandlers.push(handler);
+  }
+
+  /** Clear all typed event handlers (used when replacing WsClient). */
+  clearHandlers(): void {
+    this.typedHandlers.clear();
+    this.stateChangeHandlers = [];
+  }
+
+  disconnect(): void {
+    this.shouldReconnect = false;
+    this._stopHeartbeat();
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.onclose = null;
+      this.ws.close();
+      this.ws = null;
+    }
+    this.setState(WsConnectionState.Disconnected);
+  }
+
+  // ─── Heartbeat ───
+
+  private _startHeartbeat(): void {
+    this._stopHeartbeat();
+    const intervalMs = this.config.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    if (intervalMs <= 0) return;
+    this.heartbeatTimer = setInterval(() => {
+      if (this.ws && this._state === WsConnectionState.Connected) {
+        this.ws.send('ping');
+      }
+    }, intervalMs);
+  }
+
+  private _stopHeartbeat(): void {
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  private _scheduleReconnect(): void {
+    const maxMs = this.config.reconnectMaxMs ?? 30000;
+    const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempt), maxMs);
+    this.reconnectAttempt++;
+    this.reconnectTimer = setTimeout(() => {
+      if (this.shouldReconnect) {
+        this.setState(WsConnectionState.Connecting);
+        this._openSocket().catch(() => {});
+      }
+    }, delay);
+  }
+}

package/src/sdk/action.ts

@@ -0,0 +1,166 @@
+/**
+ * Action — an immutable, typed game command sent to the server each tick.
+ *
+ * All static factories (`move`, `kill`, `speech`, …) return frozen `Action`
+ * instances. Attach spectator-visible reasoning with `.withThinking(content)`,
+ * which returns a new `Action` without mutating the original.
+ *
+ * @example
+ * ```ts
+ * return Action.move('kitchen').withThinking('Heading to the kitchen for my task.');
+ * return Action.kill('PlayerB').withThinking('Alone with target — safe window.');
+ * ```
+ */
+export class Action {
+  readonly type: string;
+  readonly payload: Record<string, any>;
+  /**
+   * Spectator-visible reasoning string sent as `thinking_content` to the server.
+   * Visible to observers only — not exposed to other in-game players.
+   */
+  readonly thinkingContent: string | null;
+
+  private constructor(type: string, payload: Record<string, any>, thinkingContent: string | null = null) {
+    this.type = type;
+    this.payload = payload;
+    this.thinkingContent = thinkingContent;
+    Object.freeze(this);
+    Object.freeze(this.payload);
+  }
+
+  /**
+   * Attach (or replace) the spectator-visible thinking content.
+   * Returns a **new** immutable `Action` — the original is unchanged.
+   *
+   * @example Action.kill('playerA').withThinking('Safe kill — only one witness.')
+   */
+  withThinking(content: string): Action {
+    return new Action(this.type, { ...this.payload }, content);
+  }
+
+  /**
+   * Attach (or replace) the speech audio URL.
+   * Returns a **new** immutable `Action` — the original is unchanged.
+   * Typically used by the runtime to inject TTS-generated audio into speech actions.
+   */
+  withAudioUrl(audioUrl: string): Action {
+    return new Action(this.type, { ...this.payload, audio_url: audioUrl }, this.thinkingContent);
+  }
+
+  /**
+   * Move toward a room (by name) or a coordinate target.
+   *
+   * @param target        Room id string, or a `{ x, y }` coordinate pair.
+   * @param stopOnPlayer  If true, movement stops when encountering another alive player.
+   */
+  static move(target: { x: number; y: number } | string, stopOnPlayer = false): Action {
+    if (typeof target === 'string') {
+      const payload: Record<string, any> = { target };
+      if (stopOnPlayer) payload.stop_on_player = true;
+      return new Action('move', payload, `前往 ${target}`);
+    }
+    const payload: Record<string, any> = { target_x: target.x, target_y: target.y };
+    if (stopOnPlayer) payload.stop_on_player = true;
+    return new Action('move', payload);
+  }
+
+  /**
+   * Kill the named player.
+   * Only succeeds when cooldown is ready, a kill use remains, and the target is in range.
+   */
+  static kill(target: string): Action {
+    return new Action('kill', { target }, `击杀 ${target}`);
+  }
+
+  /**
+   * Broadcast a speech during the wandering phase.
+   *
+   * @param text             Words spoken (audible to nearby players).
+   * @param thinkingContent  Optional spectator-visible reasoning.
+   * @param audioUrl         Optional TTS audio URL.
+   */
+  static speech(text: string, thinkingContent?: string, audioUrl?: string): Action {
+    const payload: Record<string, any> = { text };
+    if (audioUrl) {
+      payload.audio_url = audioUrl;
+    }
+    return new Action('speech', payload, thinkingContent ?? null);
+    // speech: no default thinking (the speech content itself is the message)
+  }
+
+  /**
+   * Cast a vote during the meeting vote sub-phase.
+   *
+   * @param target  Name of the player to vote out.
+   */
+  static vote(target: string): Action {
+    return new Action('vote', { target }, `投票 ${target}`);
+  }
+
+  /**
+   * Execute (or move toward) a task.
+   *
+   * @param taskName  Optional task name. Omit to let the server resolve which
+   *                  task to execute at the current location.
+   */
+  static doTask(taskName?: string): Action {
+    return new Action('task', taskName ? { task_name: taskName } : {}, taskName ? `执行任务 ${taskName}` : '执行任务');
+  }
+
+  /**
+   * Report a corpse to trigger an emergency meeting.
+   *
+   * @param corpseName  Name of the dead player (written to thinking log).
+   * @param room        Room where the corpse was found.
+   */
+  static report(corpseName?: string, room?: string): Action {
+    const thinking = corpseName
+      ? `发现尸体（${corpseName}${room ? ` 在 ${room}` : ''}），报告召开会议`
+      : '发现尸体，报告召开会议';
+    return new Action('report', {}, thinking);
+  }
+
+  /**
+   * Pure thinking action — sends only `thinking_content` with no in-game effect.
+   * Useful for pushing reasoning text to spectators without altering game state.
+   */
+  static think(): Action {
+    return new Action('think', {}, '正在思考...');
+  }
+
+  /**
+   * Trigger the emergency alarm. Crab faction exclusive.
+   * Starts a timed emergency event that Shrimp players must resolve.
+   */
+  static triggerAlarm(): Action {
+    return new Action('trigger_alarm', {}, '触发紧急警报！');
+  }
+
+  /**
+   * Deserialize an `Action` from a plain JSON object.
+   * Accepts both `{ action: "move", … }` and `{ type: "move", … }` formats.
+   *
+   * @throws {Error} If the object contains no valid action type string.
+   */
+  static fromJSON(json: Record<string, any>): Action {
+    // Support both { action: "move", ... } and { type: "move", ... } formats
+    const type = json.action ?? json.type;
+    if (!type || typeof type !== 'string') {
+      throw new Error(`Action.fromJSON: missing or invalid action type in ${JSON.stringify(json)}`);
+    }
+    const { action: _a, type: _t, thinking_content, ...payload } = json;
+    return new Action(type, payload, thinking_content ?? null);
+  }
+
+  /**
+   * Serialize this `Action` to a plain object for transmission to the server.
+   * The `thinking_content` key is omitted when `thinkingContent` is null.
+   */
+  toJSON(): Record<string, any> {
+    const obj: Record<string, any> = { action: this.type, ...this.payload };
+    if (this.thinkingContent) {
+      obj.thinking_content = this.thinkingContent;
+    }
+    return obj;
+  }
+}