@myclaw163/clawclaw-cli 0.6.54

package/src/lib/match-state.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { mkdtempSync, existsSync, readFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import {
+  startMatch,
+  endMatch,
+  readMatchState,
+  markWaitingEmitted,
+  shouldEmitWaiting,
+  getWaitedSecs,
+  hasMatchTimedOut,
+  DEFAULT_WAITING_HEARTBEAT_MS,
+  DEFAULT_MATCH_TIMEOUT_MS,
+} from './match-state.js';
+
+function tmpDir(): string {
+  return mkdtempSync(join(tmpdir(), 'match-state-'));
+}
+
+describe('match-state — startMatch / readMatchState / endMatch', () => {
+  it('startMatch persists started_at with last_waiting_emit=0', () => {
+    const dir = tmpDir();
+    const now = 1_700_000_000_000;
+    const state = startMatch(dir, now);
+    expect(state).toEqual({ started_at: now, last_waiting_emit: 0 });
+    expect(readMatchState(dir)).toEqual(state);
+  });
+
+  it('startMatch overwrites an existing state (new queue session)', () => {
+    const dir = tmpDir();
+    startMatch(dir, 1_000_000);
+    markWaitingEmitted(dir, 1_500_000);
+    const fresh = startMatch(dir, 2_000_000);
+    expect(fresh).toEqual({ started_at: 2_000_000, last_waiting_emit: 0 });
+    expect(readMatchState(dir)).toEqual(fresh);
+  });
+
+  it('readMatchState returns null when no state file exists', () => {
+    expect(readMatchState(tmpDir())).toBeNull();
+  });
+
+  it('readMatchState returns null on corrupt JSON (does not throw)', () => {
+    const dir = tmpDir();
+    // Simulate a half-written file from a previous crash.
+    const fs = require('fs');
+    fs.writeFileSync(join(dir, 'match-state.json'), '{"started_at": 1');
+    expect(readMatchState(dir)).toBeNull();
+  });
+
+  it('endMatch removes the file; idempotent on missing', () => {
+    const dir = tmpDir();
+    startMatch(dir, 1_000_000);
+    expect(existsSync(join(dir, 'match-state.json'))).toBe(true);
+    endMatch(dir);
+    expect(existsSync(join(dir, 'match-state.json'))).toBe(false);
+    expect(() => endMatch(dir)).not.toThrow();
+  });
+});
+
+describe('match-state — atomic write', () => {
+  it('does not leave a .tmp sibling after a successful write', () => {
+    const dir = tmpDir();
+    startMatch(dir, 1_000_000);
+    markWaitingEmitted(dir, 1_100_000);
+    expect(existsSync(join(dir, 'match-state.json.tmp'))).toBe(false);
+  });
+});
+
+describe('match-state — shouldEmitWaiting', () => {
+  it('returns true when last_waiting_emit is 0 (sentinel: never emitted)', () => {
+    const state = { started_at: 1_000_000, last_waiting_emit: 0 };
+    expect(shouldEmitWaiting(state, 1_000_001)).toBe(true);
+  });
+
+  it('returns true when the elapsed since last emit reaches the heartbeat', () => {
+    const state = { started_at: 1_000_000, last_waiting_emit: 1_000_000 };
+    expect(shouldEmitWaiting(state, 1_000_000 + DEFAULT_WAITING_HEARTBEAT_MS)).toBe(true);
+  });
+
+  it('returns false when below the heartbeat interval', () => {
+    const state = { started_at: 1_000_000, last_waiting_emit: 1_000_000 };
+    expect(shouldEmitWaiting(state, 1_000_000 + DEFAULT_WAITING_HEARTBEAT_MS - 1)).toBe(false);
+  });
+
+  it('honors a custom heartbeatMs', () => {
+    const state = { started_at: 0, last_waiting_emit: 1_000 };
+    expect(shouldEmitWaiting(state, 2_000, 1_000)).toBe(true);  // elapsed 1000ms == hb
+    expect(shouldEmitWaiting(state, 2_500, 1_000)).toBe(true);  // elapsed 1500ms > hb
+    expect(shouldEmitWaiting(state, 1_999, 1_000)).toBe(false); // elapsed 999ms < hb
+    expect(shouldEmitWaiting(state, 5_000, 5_000)).toBe(false); // elapsed 4000ms < hb 5000
+  });
+});
+
+describe('match-state — markWaitingEmitted', () => {
+  it('updates last_waiting_emit while preserving started_at', () => {
+    const dir = tmpDir();
+    startMatch(dir, 1_000_000);
+    markWaitingEmitted(dir, 1_200_000);
+    expect(readMatchState(dir)).toEqual({ started_at: 1_000_000, last_waiting_emit: 1_200_000 });
+  });
+
+  it('no-ops when state file is missing', () => {
+    const dir = tmpDir();
+    expect(() => markWaitingEmitted(dir, 1_000_000)).not.toThrow();
+    expect(readMatchState(dir)).toBeNull();
+  });
+});
+
+describe('match-state — getWaitedSecs / hasMatchTimedOut', () => {
+  it('getWaitedSecs returns floor of seconds since started_at', () => {
+    const state = { started_at: 1_000_000, last_waiting_emit: 0 };
+    expect(getWaitedSecs(state, 1_000_999)).toBe(0);
+    expect(getWaitedSecs(state, 1_001_000)).toBe(1);
+    expect(getWaitedSecs(state, 1_120_500)).toBe(120);
+  });
+
+  it('getWaitedSecs clamps to 0 if clock skews backwards', () => {
+    const state = { started_at: 2_000_000, last_waiting_emit: 0 };
+    expect(getWaitedSecs(state, 1_000_000)).toBe(0);
+  });
+
+  it('hasMatchTimedOut flips at the default 10-minute threshold', () => {
+    const state = { started_at: 0, last_waiting_emit: 0 };
+    expect(hasMatchTimedOut(state, DEFAULT_MATCH_TIMEOUT_MS - 1)).toBe(false);
+    expect(hasMatchTimedOut(state, DEFAULT_MATCH_TIMEOUT_MS)).toBe(true);
+  });
+
+  it('honors a custom timeoutMs', () => {
+    const state = { started_at: 0, last_waiting_emit: 0 };
+    expect(hasMatchTimedOut(state, 999, 1_000)).toBe(false);
+    expect(hasMatchTimedOut(state, 1_000, 1_000)).toBe(true);
+  });
+});

package/src/lib/match-state.ts

@@ -0,0 +1,94 @@
+/**
+ * match-state — 记录单次匹配等待的进度,用于 `ccl game queue` 跨进程协调
+ * `match_waiting` / `match_timeout` 合成事件的发射节奏。
+ *
+ * 每次 `ccl game queue` 是一个新进程,跨进程的"上次心跳时间"必须落盘。
+ * 持久化在 `${profileStateDir}/match-state.json`,生命周期:
+ *   - `ccl game join`           → startMatch() 创建
+ *   - `ccl game queue` 匹配成功 → endMatch() 删除
+ *   - `ccl game queue` 心跳到点 → markWaitingEmitted() 更新 last_waiting_emit
+ *   - 用户主动 leave/quit      → endMatch() 删除
+ */
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'fs';
+import { join } from 'path';
+
+export interface MatchState {
+  started_at: number;       // ms epoch — 进入队列的时刻
+  last_waiting_emit: number; // ms epoch — 最近一次 emit match_waiting 的时刻 (0 = 从未)
+}
+
+/** 默认匹配等待心跳间隔:5 分钟 */
+export const DEFAULT_WAITING_HEARTBEAT_MS = 300_000;
+
+/** 默认匹配总超时阈值:600 秒 (10 分钟) */
+export const DEFAULT_MATCH_TIMEOUT_MS = 600_000;
+
+function statePath(stateDir: string): string {
+  return join(stateDir, 'match-state.json');
+}
+
+/**
+ * 原子写: 先写到 .tmp 再 rename。
+ * rename 在 NTFS / ext4 / APFS 上都是原子操作,避免半写文件被 JSON.parse 时
+ * 误判为"无匹配进行中"而把累计等待计数重置。
+ */
+function atomicWriteJSON(path: string, value: unknown): void {
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value));
+  renameSync(tmp, path);
+}
+
+export function readMatchState(stateDir: string): MatchState | null {
+  const p = statePath(stateDir);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf8')) as MatchState;
+  } catch {
+    return null;
+  }
+}
+
+/** 开始一轮新匹配。即使旧 state 残留也覆盖。 */
+export function startMatch(stateDir: string, now: number = Date.now()): MatchState {
+  const state: MatchState = { started_at: now, last_waiting_emit: 0 };
+  atomicWriteJSON(statePath(stateDir), state);
+  return state;
+}
+
+/** 匹配成功或被取消时清理。幂等。 */
+export function endMatch(stateDir: string): void {
+  const p = statePath(stateDir);
+  if (!existsSync(p)) return;
+  try { unlinkSync(p); } catch {}
+}
+
+export function markWaitingEmitted(stateDir: string, now: number = Date.now()): void {
+  const cur = readMatchState(stateDir);
+  if (!cur) return;
+  const next: MatchState = { ...cur, last_waiting_emit: now };
+  atomicWriteJSON(statePath(stateDir), next);
+}
+
+/** 距离上次 emit match_waiting 是否够久 (或从未 emit)。 */
+export function shouldEmitWaiting(
+  state: MatchState,
+  now: number = Date.now(),
+  heartbeatMs: number = DEFAULT_WAITING_HEARTBEAT_MS,
+): boolean {
+  if (state.last_waiting_emit === 0) return true;
+  return now - state.last_waiting_emit >= heartbeatMs;
+}
+
+export function getWaitedSecs(state: MatchState, now: number = Date.now()): number {
+  return Math.max(0, Math.floor((now - state.started_at) / 1000));
+}
+
+/** 累计等待是否已到总超时阈值。 */
+export function hasMatchTimedOut(
+  state: MatchState,
+  now: number = Date.now(),
+  timeoutMs: number = DEFAULT_MATCH_TIMEOUT_MS,
+): boolean {
+  return now - state.started_at >= timeoutMs;
+}

package/src/lib/netease-tts.ts

@@ -0,0 +1,83 @@
+export class NeteaseTTSError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NeteaseTTSError';
+  }
+}
+
+export interface NeteaseTTSOptions {
+  apiKey: string;
+  text: string;
+  voice: string;
+  model?: string;
+  speed?: number;
+  url?: string;
+  timeoutMs?: number;
+}
+
+export interface NeteaseTTSResult {
+  audio: Buffer;
+  contentType: string;
+}
+
+const DEFAULT_TTS_URL = 'https://ai.leihuo.netease.com/v1/audio/speech';
+const DEFAULT_TTS_MODEL = 'speech-2.8-hd';
+const DEFAULT_TTS_SPEED = 1.3;
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+async function extractErrorMessage(response: Response): Promise<string> {
+  const text = await response.text();
+  try {
+    const payload = JSON.parse(text);
+    const message = payload?.error?.message ?? payload?.message;
+    if (typeof message === 'string' && message.trim()) return message;
+  } catch {}
+  return text.trim() || `TTS request failed with status ${response.status}`;
+}
+
+export async function synthesizeNeteaseTTS(opts: NeteaseTTSOptions): Promise<NeteaseTTSResult> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  try {
+    const response = await fetch(opts.url ?? DEFAULT_TTS_URL, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${opts.apiKey}`,
+        'Content-Type': 'application/json; charset=utf-8',
+      },
+      body: JSON.stringify({
+        model: opts.model ?? DEFAULT_TTS_MODEL,
+        input: opts.text,
+        voice: opts.voice,
+        speed: opts.speed ?? DEFAULT_TTS_SPEED,
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new NeteaseTTSError(await extractErrorMessage(response));
+    }
+
+    const contentType = (response.headers.get('content-type') ?? 'audio/mpeg')
+      .split(';', 1)[0]
+      .trim()
+      .toLowerCase();
+    if (!contentType.startsWith('audio/')) {
+      throw new NeteaseTTSError(`Unexpected TTS content type: ${contentType || 'unknown'}`);
+    }
+
+    const audio = Buffer.from(await response.arrayBuffer());
+    if (audio.length === 0) {
+      throw new NeteaseTTSError('TTS returned empty audio');
+    }
+
+    return { audio, contentType };
+  } catch (err: any) {
+    if (err instanceof NeteaseTTSError) throw err;
+    if (err?.name === 'AbortError') throw new NeteaseTTSError('TTS request timed out');
+    throw new NeteaseTTSError(err?.message ?? String(err));
+  } finally {
+    clearTimeout(timer);
+  }
+}
+

package/src/lib/normalize.ts

@@ -0,0 +1,42 @@
+// src/lib/normalize.ts
+import type { GameState } from '../sdk/types.js';
+
+/**
+ * Normalize raw game state response from server.
+ *
+ * Handles field renaming (visible_players → players, nearby_corpses → corpses),
+ * task field normalization when task data is present, and default empty arrays.
+ */
+export function normalizeGameState(data: any): GameState {
+  const result = { ...data };
+
+  // visible_players → players
+  if (result.visible_players !== undefined && result.players === undefined) {
+    result.players = result.visible_players;
+  }
+  // nearby_corpses → corpses
+  if (result.nearby_corpses !== undefined && result.corpses === undefined) {
+    result.corpses = result.nearby_corpses;
+  }
+
+  // Default empty arrays
+  if (result.corpses === undefined) result.corpses = [];
+  if (result.players === undefined) result.players = [];
+  if (result.new_events === undefined) result.new_events = [];
+  if (result.tick === undefined) result.tick = 0;
+
+  // Normalize task fields: server returns { name }, SDK expects { task_id, task_name }
+  if (Array.isArray(result.your_tasks)) {
+    result.your_tasks = result.your_tasks.map((t: any) => ({
+      task_id: t.task_id ?? t.name ?? '',
+      task_name: t.task_name ?? t.name ?? '',
+      room: t.room ?? '',
+      status: t.status ?? 'normal',
+      x: t.x,
+      y: t.y,
+      is_fake_shrimp: t.is_fake_shrimp ?? false,
+    }));
+  }
+
+  return result;
+}

package/src/lib/persona.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import {
+  applyPersonaPreset,
+  findPersonaPreset,
+  listPersonaPresets,
+} from './persona.js';
+
+describe('persona presets', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'clawclaw-personas-'));
+    mkdirSync(join(dir, 'nested'));
+    writeFileSync(join(dir, '温和.md'), 'warm');
+    writeFileSync(join(dir, '野性.md'), 'wild');
+    writeFileSync(join(dir, 'ignore.txt'), 'nope');
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('lists markdown presets from the preset directory', () => {
+    expect(listPersonaPresets(dir).map(item => item.name).sort()).toEqual(['温和', '野性']);
+  });
+
+  it('finds presets with or without .md suffix', () => {
+    expect(findPersonaPreset('温和', dir)?.name).toBe('温和');
+    expect(findPersonaPreset('温和.md', dir)?.name).toBe('温和');
+  });
+
+  it('copies preset content into the active account persona file', () => {
+    const target = join(dir, 'account', 'persona.md');
+    const preset = applyPersonaPreset('野性', target, dir);
+    expect(preset.name).toBe('野性');
+    expect(readFileSync(target, 'utf8')).toBe('wild');
+  });
+});

package/src/lib/persona.ts

@@ -0,0 +1,72 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
+import { dirname, join, resolve, basename } from 'path';
+import { fileURLToPath } from 'url';
+import { AuthStore } from './auth.js';
+import { getProfilePersonaFile } from './init-command.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export interface PersonaPreset {
+  id: string;
+  name: string;
+  path: string;
+}
+
+export function getBundledPersonaDir(): string {
+  return resolve(__dirname, '..', '..', 'personas');
+}
+
+export function listPersonaPresets(dir = getBundledPersonaDir()): PersonaPreset[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.toLowerCase().endsWith('.md'))
+    .map(entry => {
+      const name = entry.name.slice(0, -3);
+      return {
+        id: name,
+        name,
+        path: join(dir, entry.name),
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name, 'zh-Hans-CN'));
+}
+
+export function findPersonaPreset(name: string, dir = getBundledPersonaDir()): PersonaPreset | null {
+  const normalized = normalizePersonaName(name);
+  return listPersonaPresets(dir).find(preset =>
+    normalizePersonaName(preset.id) === normalized ||
+    normalizePersonaName(preset.name) === normalized ||
+    normalizePersonaName(basename(preset.path)) === normalized,
+  ) ?? null;
+}
+
+export function getActivePersonaFile(authStore = new AuthStore()): string {
+  const profile = authStore.getActive();
+  if (!profile) throw new Error('Not logged in.');
+  return getProfilePersonaFile(profile);
+}
+
+export function ensurePersonaFile(path: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  if (!existsSync(path)) writeFileSync(path, '');
+}
+
+export function readPersonaFile(path: string): string {
+  return existsSync(path) ? readFileSync(path, 'utf8') : '';
+}
+
+export function applyPersonaPreset(name: string, targetPath: string, dir = getBundledPersonaDir()): PersonaPreset {
+  const preset = findPersonaPreset(name, dir);
+  if (!preset) {
+    const available = listPersonaPresets(dir).map(item => item.name).join(', ') || 'none';
+    throw new Error(`Persona preset "${name}" not found. Available: ${available}`);
+  }
+  ensurePersonaFile(targetPath);
+  copyFileSync(preset.path, targetPath);
+  return preset;
+}
+
+function normalizePersonaName(value: string): string {
+  return value.trim().replace(/\.md$/i, '').toLowerCase();
+}

package/src/lib/server-registry.ts

@@ -0,0 +1,152 @@
+// src/lib/server-registry.ts
+import { AuthStore } from './auth.js';
+
+export interface ServerAddresses {
+  lobbyUrl: string;
+  gameServerUrl: string | null;
+  wsUrl: string | null;
+}
+
+export class ServerRegistry {
+  private lobbyUrl: string;
+  private _gameServerUrl: string | null;
+  private _gatewayWsUrl: string | null;
+  private agentName: string | undefined;
+  /** True when gameServerUrl was pre-configured (e.g. from auth) — prevents
+   *  discoverGameServer() from clearing it during queue status polling. */
+  private _urlPreconfigured: boolean;
+
+  constructor(opts: { lobbyUrl: string; gameServerUrl?: string; agentName?: string }) {
+    this.lobbyUrl = opts.lobbyUrl.replace(/\/$/, '');
+    this._gatewayWsUrl = null;
+    if (opts.gameServerUrl) {
+      const raw = opts.gameServerUrl.replace(/\/$/, '');
+      try {
+        const u = new URL(raw);
+        if (u.pathname && u.pathname !== '/') {
+          // Gateway URL — restore _gatewayWsUrl so wsUrl path prefix is preserved
+          this._gatewayWsUrl = raw;
+          this._gameServerUrl = raw;
+        } else {
+          this._gameServerUrl = raw.replace(/^https:\/\//, 'http://');
+        }
+      } catch {
+        this._gameServerUrl = raw.replace(/^https:\/\//, 'http://');
+      }
+      this._urlPreconfigured = true;
+    } else {
+      this._gameServerUrl = null;
+      this._urlPreconfigured = false;
+    }
+    this.agentName = opts.agentName;
+  }
+
+  get addresses(): ServerAddresses {
+    return {
+      lobbyUrl: this.lobbyUrl,
+      gameServerUrl: this._gameServerUrl,
+      wsUrl: this.wsUrl,
+    };
+  }
+
+  get gameServerUrl(): string | null {
+    return this._gameServerUrl;
+  }
+
+  /**
+   * Determine the correct base URL for a given API path.
+   *
+   * Game Server routes: /api/v1/game/current, /api/v1/game/action, /api/v1/game/map, /api/v1/game/leave, /api/v1/game/role_info
+   * Lobby routes: everything else (/api/v1/agents/*, /api/v1/queue/*, etc.)
+   */
+  baseUrlFor(path: string): string {
+    if (
+      path.startsWith('/api/v1/game/current') ||
+      path.startsWith('/api/v1/game/action') ||
+      path.startsWith('/api/v1/game/map') ||
+      path.startsWith('/api/v1/game/leave') ||
+      path.startsWith('/api/v1/game/role_info')
+    ) {
+      const base = this._gatewayWsUrl ?? this._gameServerUrl;
+      if (!base) throw new Error('No game server allocated');
+      return base;
+    }
+    return this.lobbyUrl;
+  }
+
+  /**
+   * Extract game server address from a queue response and update gameServerUrl.
+   * Prefers ws_url (Gateway route) over raw address:port.
+   * Returns true if the address changed.
+   */
+  updateFromQueueResponse(data: any): boolean {
+    if (!data || typeof data !== 'object') return false;
+    const qs = data.data ?? data;
+    if (qs.status && qs.status !== 'allocated') {
+      // Never clear a pre-configured URL just because queue status changed —
+      // the game may already be in progress. Only clear if the URL was
+      // originally discovered via queue (not pre-set from auth).
+      if (this._urlPreconfigured) return false;
+      if (this._gameServerUrl !== null || this._gatewayWsUrl !== null) {
+        this._gameServerUrl = null;
+        this._gatewayWsUrl = null;
+        this.persistGameServerUrl();
+        return true;
+      }
+      return false;
+    }
+
+    const wsUrl = qs.ws_url;
+    if (wsUrl && typeof wsUrl === 'string') {
+      const httpUrl = wsUrl.replace(/^wss:/, 'https:').replace(/^ws:/, 'http:');
+      if (this._gatewayWsUrl !== httpUrl) {
+        this._gatewayWsUrl = httpUrl;
+        this._gameServerUrl = httpUrl;
+        this.persistGameServerUrl();
+        return true;
+      }
+      return false;
+    }
+
+    const addr = qs.address ?? qs.game_server?.address;
+    const port = qs.port ?? qs.game_server?.port;
+    if (addr && port) {
+      const url = `http://${addr}:${port}`;
+      if (this._gameServerUrl !== url) {
+        this._gameServerUrl = url;
+        this._gatewayWsUrl = null;
+        this.persistGameServerUrl();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** Manually set the game server URL. */
+  setGameServerUrl(url: string): void {
+    this._gameServerUrl = url.replace(/\/$/, '');
+    this._urlPreconfigured = true;
+    this.persistGameServerUrl();
+  }
+
+  /** WS URL derived from gameServerUrl (Gateway or direct). */
+  get wsUrl(): string | null {
+    if (!this._gameServerUrl) return null;
+    try {
+      const u = new URL(this._gameServerUrl);
+      const protocol = u.protocol === 'https:' || u.protocol === 'wss:' ? 'wss:' : 'ws:';
+      const basePath = this._gatewayWsUrl ? u.pathname.replace(/\/$/, '') : '';
+      return `${protocol}//${u.host}${basePath}/api/v1/game/stream`;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Persist gameServerUrl to auth profile (best-effort). */
+  private persistGameServerUrl(): void {
+    if (!this.agentName) return;
+    try {
+      new AuthStore().updateGameServerUrl(this._gameServerUrl ?? undefined, this.agentName);
+    } catch { /* non-critical */ }
+  }
+}

package/src/lib/skill-version.test.ts

@@ -0,0 +1,48 @@
+import { mkdtempSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { describe, expect, it } from 'vitest';
+import { parseSkillVersion, readSkillVersion } from './skill-version.js';
+
+describe('parseSkillVersion', () => {
+  it('returns version from a normal frontmatter block', () => {
+    const md = '---\nname: clawclaw\ndescription: x\nversion: 3.2.8\n---\n\n# body\n';
+    expect(parseSkillVersion(md)).toBe('3.2.8');
+  });
+
+  it('handles CRLF line endings', () => {
+    const md = '---\r\nname: x\r\nversion: 1.0.0\r\n---\r\nbody';
+    expect(parseSkillVersion(md)).toBe('1.0.0');
+  });
+
+  it('returns null when frontmatter is missing', () => {
+    expect(parseSkillVersion('# just a heading\n')).toBeNull();
+  });
+
+  it('returns null when version key is absent', () => {
+    expect(parseSkillVersion('---\nname: x\n---\nbody')).toBeNull();
+  });
+
+  it('ignores a version: outside the frontmatter block', () => {
+    const md = '---\nname: x\n---\n\nversion: 9.9.9 (in body)\n';
+    expect(parseSkillVersion(md)).toBeNull();
+  });
+
+  it('strips surrounding whitespace from the value', () => {
+    const md = '---\nversion:    2.1.0   \n---\nbody';
+    expect(parseSkillVersion(md)).toBe('2.1.0');
+  });
+});
+
+describe('readSkillVersion', () => {
+  it('reads version from a file on disk', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'skill-version-'));
+    const path = join(dir, 'SKILL.md');
+    writeFileSync(path, '---\nversion: 4.0.0\n---\nbody');
+    expect(readSkillVersion(path)).toBe('4.0.0');
+  });
+
+  it('returns null when file does not exist', () => {
+    expect(readSkillVersion('/nonexistent/path/SKILL.md')).toBeNull();
+  });
+});

package/src/lib/skill-version.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from 'fs';
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+const VERSION_RE = /^version:\s*(\S.*?)\s*$/m;
+
+export function parseSkillVersion(content: string): string | null {
+  const fm = FRONTMATTER_RE.exec(content);
+  if (!fm) return null;
+  const v = VERSION_RE.exec(fm[1]);
+  return v ? v[1] : null;
+}
+
+export function readSkillVersion(path: string): string | null {
+  try {
+    return parseSkillVersion(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}