@myclaw163/clawclaw-cli 0.6.56 → 0.6.57

package/src/runtime/owner-control.ts

@@ -0,0 +1,150 @@
+import { createHash, randomBytes } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { connect, createServer, type Server } from 'net';
+
+export const GAME_START_RUNTIME_FILE = 'game-start.json';
+export const OWNER_CONTROL_TIMEOUT_MS = 2000;
+
+export type OwnerControlType = 'stop' | 'quit' | 'leave' | 'switch_strategy' | 'stop_strategy' | 'snapshot';
+
+export interface OwnerControlInfo {
+  kind: 'node-net-socket';
+  path: string;
+}
+
+export interface OwnerControlRequest {
+  token?: string;
+  type?: OwnerControlType;
+  strategy?: string;
+  args?: string[];
+}
+
+export interface OwnerControlResponse {
+  ok: boolean;
+  type?: string;
+  error?: string;
+  message?: string;
+  [key: string]: any;
+}
+
+export interface OwnerControlServer {
+  control: OwnerControlInfo;
+  token: string;
+  close: () => Promise<void>;
+}
+
+export function gameStartRuntimePath(stateDir: string): string {
+  return join(stateDir, GAME_START_RUNTIME_FILE);
+}
+
+export function readGameStartRuntime(stateDir: string): Record<string, any> | null {
+  const runtimePath = gameStartRuntimePath(stateDir);
+  if (!existsSync(runtimePath)) return null;
+  try {
+    return JSON.parse(readFileSync(runtimePath, 'utf8'));
+  } catch {}
+  return null;
+}
+
+function ownerControlPath(stateDir: string, pid: number): string {
+  const hash = createHash('sha1').update(stateDir).digest('hex').slice(0, 12);
+  if (process.platform === 'win32') return `\\\\.\\pipe\\clawclaw-${hash}-${pid}`;
+  const dir = join(tmpdir(), 'clawclaw');
+  mkdirSync(dir, { recursive: true });
+  return join(dir, `${hash}-${pid}.sock`);
+}
+
+export async function startOwnerControlServer(
+  stateDir: string,
+  onRequest: (request: OwnerControlRequest) => Promise<OwnerControlResponse> | OwnerControlResponse,
+): Promise<OwnerControlServer> {
+  const token = randomBytes(24).toString('hex');
+  const path = ownerControlPath(stateDir, process.pid);
+  if (process.platform !== 'win32') {
+    try { unlinkSync(path); } catch {}
+  }
+  const server: Server = createServer((socket) => {
+    let buffer = '';
+    socket.setEncoding('utf8');
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      const nl = buffer.indexOf('\n');
+      if (nl < 0) return;
+      const line = buffer.slice(0, nl);
+      buffer = buffer.slice(nl + 1);
+      void (async () => {
+        try {
+          const request = JSON.parse(line) as OwnerControlRequest;
+          if (request.token !== token) {
+            socket.end(JSON.stringify({ ok: false, error: 'invalid_token' }) + '\n');
+            return;
+          }
+          const response = await onRequest(request);
+          socket.end(JSON.stringify(response) + '\n');
+        } catch (err: any) {
+          socket.end(JSON.stringify({ ok: false, error: err?.message ?? String(err) }) + '\n');
+        }
+      })();
+    });
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(path, () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+  return {
+    control: { kind: 'node-net-socket', path },
+    token,
+    close: () => new Promise((resolve) => {
+      server.close(() => resolve());
+    }),
+  };
+}
+
+export function sendOwnerControlRequest(
+  stateDir: string,
+  type: OwnerControlType,
+  payload: Record<string, any> = {},
+  timeoutMs = OWNER_CONTROL_TIMEOUT_MS,
+): Promise<OwnerControlResponse | null> {
+  const info = readGameStartRuntime(stateDir);
+  const path = typeof info?.control?.path === 'string' ? info.control.path : '';
+  const token = typeof info?.control_token === 'string' ? info.control_token : '';
+  if (!path || !token) return Promise.resolve(null);
+  return new Promise((resolve, reject) => {
+    const socket = connect(path);
+    let buffer = '';
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(new Error('owner_control_timeout'));
+    }, timeoutMs);
+    socket.setEncoding('utf8');
+    socket.on('connect', () => {
+      socket.write(JSON.stringify({ token, type, ...payload }) + '\n');
+    });
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      const nl = buffer.indexOf('\n');
+      if (nl < 0) return;
+      clearTimeout(timer);
+      socket.end();
+      try {
+        resolve(JSON.parse(buffer.slice(0, nl)));
+      } catch (err) {
+        reject(err);
+      }
+    });
+    socket.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    socket.on('close', () => {
+      clearTimeout(timer);
+      if (!buffer) resolve(null);
+    });
+  });
+}

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

@@ -1,33 +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 });
-    }
-  });
-});
+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

@@ -1,32 +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.
-  }
-}
+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

@@ -1,99 +1,107 @@
-/**
- * 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;
-    }
-  }
-}
+/**
+ * Runtime Logger — structured, leveled logging for the game runtime 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).
+ * Console output is disabled by default so game runtime diagnostics do not
+ * leak into Monitor streams. Set CLAWCLAW_RUNTIME_LOG_TO_CONSOLE=1 to print.
+ */
+
+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;
+  }
+}
+
+function isTrue(value: string | undefined): boolean {
+  return typeof value === 'string' && value.trim().toLowerCase() === 'true';
+}
+
+export class RuntimeLogger {
+  private minLevel: LogLevel;
+  private logToConsole: boolean;
+
+  constructor() {
+    this.minLevel = parseLogLevel(process.env.CLAWCLAW_LOG_LEVEL);
+    this.logToConsole = isTrue(process.env.CLAWCLAW_RUNTIME_LOG_TO_CONSOLE);
+  }
+
+  // ─── 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);
+    if (this.logToConsole && 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;
+    if (!this.logToConsole) 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

@@ -1,47 +1,104 @@
-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;
-  });
-});
+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;
+  });
+
+  it('dispatches state.new_events before the _state snapshot', async () => {
+    const { WsClient } = await import('./ws-client.js');
+    const client = new WsClient({
+      url: 'wss://host.example/api/v1/game/stream',
+      apiKey: 'claw_secret',
+    });
+    const seen: Record<string, any>[] = [];
+    client.on('*', (event) => seen.push(event));
+
+    (client as any).handleMessage({
+      type: 'state',
+      data: {
+        phase: 'wandering',
+        tick: 20,
+        new_events: [{ type: 'game_over', tick: 20, winner: 'crab' }],
+      },
+    });
+
+    expect(seen).toEqual([
+      { type: 'game_over', tick: 20, winner: 'crab' },
+      {
+        type: '_state',
+        phase: 'wandering',
+        tick: 20,
+        new_events: [{ type: 'game_over', tick: 20, winner: 'crab' }],
+      },
+    ]);
+  });
+
+  it('dispatches a _state snapshot when phase is game_over without new_events', async () => {
+    const { WsClient } = await import('./ws-client.js');
+    const client = new WsClient({
+      url: 'wss://host.example/api/v1/game/stream',
+      apiKey: 'claw_secret',
+    });
+    const seen: Record<string, any>[] = [];
+    client.on('*', (event) => seen.push(event));
+
+    (client as any).handleMessage({
+      type: 'state',
+      data: {
+        phase: 'game_over',
+        tick: 21,
+        new_events: [],
+      },
+    });
+
+    expect(seen).toEqual([
+      {
+        type: '_state',
+        phase: 'game_over',
+        tick: 21,
+        new_events: [],
+      },
+    ]);
+  });
+});