@myclaw163/clawclaw-cli 0.6.71 → 0.6.76

package/src/lib/auth.test.ts

@@ -1,74 +1,86 @@
-import { describe, expect, it, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, rmSync, writeFileSync, readFileSync } from 'fs';
-import { tmpdir } from 'os';
-import { join } from 'path';
-import { AuthStore } from './auth.js';
-import { TTS_PROVIDER_LEIHUO } from './tts-keys.js';
-
-describe('AuthStore TTS config', () => {
-  let dir: string;
-  let authFile: string;
-
-  beforeEach(() => {
-    dir = mkdtempSync(join(tmpdir(), 'clawclaw-auth-'));
-    authFile = join(dir, '.auth.json');
-  });
-
-  afterEach(() => {
-    rmSync(dir, { recursive: true, force: true });
-  });
-
-  it('stores leihuo TTS key under the active profile', () => {
-    const store = new AuthStore(authFile);
-    store.addProfile({ agentName: 'lobster-1', apiKey: 'claw_1', serverUrl: 'https://example.com' });
-    store.setTtsKey(TTS_PROVIDER_LEIHUO, 'sk-test');
-    expect(store.getTtsKey(TTS_PROVIDER_LEIHUO)).toBe('sk-test');
-
-    const raw = JSON.parse(readFileSync(authFile, 'utf8'));
-    expect(raw.profiles['lobster-1'].tts.keys.leihuo).toBe('sk-test');
-    expect(raw.ttsKeys).toBeUndefined();
-  });
-
-  it('stores default TTS voice under the active profile', () => {
-    const store = new AuthStore(authFile);
-    store.addProfile({ agentName: 'lobster-1', apiKey: 'claw_1', serverUrl: 'https://example.com' });
-    store.setTtsDefaultVoice('male-qn-qingse');
-    expect(store.getTtsDefaultVoice()).toBe('male-qn-qingse');
-
-    const raw = JSON.parse(readFileSync(authFile, 'utf8'));
-    expect(raw.profiles['lobster-1'].tts.defaultVoice).toBe('male-qn-qingse');
-  });
-
-  it('clears cached game server URL when set to undefined', () => {
-    const store = new AuthStore(authFile);
-    store.addProfile({
-      agentName: 'lobster-1',
-      apiKey: 'claw_1',
-      serverUrl: 'https://example.com',
-      gameServerUrl: 'https://example.com/gs/old-game-server',
-    });
-
-    store.updateGameServerUrl(undefined);
-
-    const raw = JSON.parse(readFileSync(authFile, 'utf8'));
-    expect(raw.profiles['lobster-1'].gameServerUrl).toBeUndefined();
-  });
-
-  it('migrates legacy neteaseTtsKey to each profile tts keys', () => {
-    writeFileSync(authFile, JSON.stringify({
-      activeProfile: 'lobster-1',
-      profiles: {
-        'lobster-1': { agentName: 'lobster-1', apiKey: 'claw_1', serverUrl: 'https://example.com' },
-        'lobster-2': { agentName: 'lobster-2', apiKey: 'claw_2', serverUrl: 'https://example.com' },
-      },
-      neteaseTtsKey: 'sk-legacy',
-    }));
-    const store = new AuthStore(authFile);
-    expect(store.getTtsKey(TTS_PROVIDER_LEIHUO)).toBe('sk-legacy');
-    const raw = JSON.parse(readFileSync(authFile, 'utf8'));
-    expect(raw.profiles['lobster-1'].tts.keys.leihuo).toBe('sk-legacy');
-    expect(raw.profiles['lobster-2'].tts.keys.leihuo).toBe('sk-legacy');
-    expect(raw.ttsKeys).toBeUndefined();
-    expect(raw.neteaseTtsKey).toBeUndefined();
-  });
-});
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { AuthStore } from './auth.js';
+import { TTS_PROVIDER_LEIHUO } from './tts-keys.js';
+
+describe('AuthStore TTS config', () => {
+  let dir: string;
+  let authFile: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'clawclaw-auth-'));
+    authFile = join(dir, '.auth.json');
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('stores leihuo TTS key under the active profile', () => {
+    const store = new AuthStore(authFile);
+    store.addProfile({ agentName: 'lobster-1', apiKey: 'claw_1', serverUrl: 'https://example.com' });
+    store.setTtsKey(TTS_PROVIDER_LEIHUO, 'sk-test');
+    expect(store.getTtsKey(TTS_PROVIDER_LEIHUO)).toBe('sk-test');
+
+    const raw = JSON.parse(readFileSync(authFile, 'utf8'));
+    expect(raw.profiles['lobster-1'].tts.keys.leihuo).toBe('sk-test');
+    expect(raw.ttsKeys).toBeUndefined();
+  });
+
+  it('stores default TTS voice under the active profile', () => {
+    const store = new AuthStore(authFile);
+    store.addProfile({ agentName: 'lobster-1', apiKey: 'claw_1', serverUrl: 'https://example.com' });
+    store.setTtsDefaultVoice('male-qn-qingse');
+    expect(store.getTtsDefaultVoice()).toBe('male-qn-qingse');
+
+    const raw = JSON.parse(readFileSync(authFile, 'utf8'));
+    expect(raw.profiles['lobster-1'].tts.defaultVoice).toBe('male-qn-qingse');
+  });
+
+  it('clears cached game server URL when set to undefined', () => {
+    const store = new AuthStore(authFile);
+    store.addProfile({
+      agentName: 'lobster-1',
+      apiKey: 'claw_1',
+      serverUrl: 'https://example.com',
+      gameServerUrl: 'https://example.com/gs/old-game-server',
+    });
+
+    store.updateGameServerUrl(undefined);
+
+    const raw = JSON.parse(readFileSync(authFile, 'utf8'));
+    expect(raw.profiles['lobster-1'].gameServerUrl).toBeUndefined();
+  });
+
+  it('removes runtime game server state when removing a profile', () => {
+    const runtimeFile = join(dir, 'auth-state.json');
+    const store = new AuthStore(authFile, runtimeFile);
+    store.addProfile({ agentName: 'lobster-1', apiKey: 'claw_1', serverUrl: 'https://example.com' });
+    store.updateGameServerUrl('https://example.com/gs/current');
+
+    store.removeProfile('lobster-1');
+
+    const runtime = JSON.parse(readFileSync(runtimeFile, 'utf8'));
+    expect(runtime.profiles['lobster-1']).toBeUndefined();
+  });
+
+  it('migrates legacy neteaseTtsKey to each profile tts keys', () => {
+    writeFileSync(authFile, JSON.stringify({
+      activeProfile: 'lobster-1',
+      profiles: {
+        'lobster-1': { agentName: 'lobster-1', apiKey: 'claw_1', serverUrl: 'https://example.com' },
+        'lobster-2': { agentName: 'lobster-2', apiKey: 'claw_2', serverUrl: 'https://example.com' },
+      },
+      neteaseTtsKey: 'sk-legacy',
+    }));
+    const store = new AuthStore(authFile);
+    expect(store.getTtsKey(TTS_PROVIDER_LEIHUO)).toBe('sk-legacy');
+    const raw = JSON.parse(readFileSync(authFile, 'utf8'));
+    expect(raw.profiles['lobster-1'].tts.keys.leihuo).toBe('sk-legacy');
+    expect(raw.profiles['lobster-2'].tts.keys.leihuo).toBe('sk-legacy');
+    expect(raw.ttsKeys).toBeUndefined();
+    expect(raw.neteaseTtsKey).toBeUndefined();
+  });
+});

package/src/lib/auth.ts

@@ -1,186 +1,223 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { join, dirname } from 'path';
-import { getWorkspaceDir } from './init-command.js';
-import { TTS_PROVIDER_LEIHUO } from './tts-keys.js';
-
-export interface AuthTtsConfig {
-  keys?: Record<string, string>;
-  defaultVoice?: string;
-}
-
-export interface AuthProfile {
-  agentName: string;
-  apiKey: string;
-  /** Lobby server URL (e.g. https://myclaw.163.com/claw) */
-  serverUrl: string;
-  /** Game server URL (e.g. http://{address}:{port}), obtained from /queue/status after match */
-  gameServerUrl?: string;
-  /** Per-account TTS configuration. */
-  tts?: AuthTtsConfig;
-}
-
-export interface AuthData {
-  activeProfile: string;
-  profiles: Record<string, AuthProfile>;
-  /** @deprecated Migrated to each profile's `tts.keys` on load. */
-  ttsKeys?: Record<string, string>;
-  /** @deprecated Migrated to `ttsKeys.leihuo` on load. */
-  neteaseTtsKey?: string;
-}
-
-const EMPTY_AUTH: AuthData = { activeProfile: '', profiles: {} };
-
-export class AuthStore {
-  private authFile: string;
-
-  constructor(authFile?: string) {
-    this.authFile = authFile ?? join(getWorkspaceDir(), '.auth.json');
-  }
-
-  load(): AuthData {
-    if (!existsSync(this.authFile)) return { ...EMPTY_AUTH, profiles: {} };
-    try {
-      const data = JSON.parse(readFileSync(this.authFile, 'utf8')) as AuthData;
-      return this.normalizeTtsConfig(data);
-    } catch {
-      return { ...EMPTY_AUTH, profiles: {} };
-    }
-  }
-
-  private normalizeTtsConfig(data: AuthData): AuthData {
-    let changed = false;
-    if (data.neteaseTtsKey) {
-      data.ttsKeys = { ...data.ttsKeys, [TTS_PROVIDER_LEIHUO]: data.neteaseTtsKey };
-      delete data.neteaseTtsKey;
-      changed = true;
-    }
-
-    const legacyTtsKeys = data.ttsKeys;
-    const profiles = Object.values(data.profiles ?? {});
-    if (legacyTtsKeys && profiles.length > 0) {
-      for (const profile of profiles) {
-        profile.tts = {
-          ...profile.tts,
-          keys: {
-            ...legacyTtsKeys,
-            ...profile.tts?.keys,
-          },
-        };
-      }
-      delete data.ttsKeys;
-      changed = true;
-    }
-    if (changed) this.save(data);
-    return data;
-  }
-
-  save(data: AuthData): void {
-    const dir = dirname(this.authFile);
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    writeFileSync(this.authFile, JSON.stringify(data, null, 2));
-  }
-
-  addProfile(profile: AuthProfile): void {
-    const data = this.load();
-    if (data.ttsKeys && !profile.tts?.keys) {
-      profile.tts = {
-        ...profile.tts,
-        keys: { ...data.ttsKeys },
-      };
-      delete data.ttsKeys;
-    }
-    data.profiles[profile.agentName] = profile;
-    data.activeProfile = profile.agentName;
-    this.save(data);
-  }
-
-  removeProfile(name: string): void {
-    const data = this.load();
-    delete data.profiles[name];
-    if (data.activeProfile === name) {
-      const remaining = Object.keys(data.profiles);
-      data.activeProfile = remaining[0] ?? '';
-    }
-    this.save(data);
-  }
-
-  switchProfile(name: string): void {
-    const data = this.load();
-    if (!data.profiles[name]) {
-      throw new Error(`Profile "${name}" not found. Available: ${Object.keys(data.profiles).join(', ') || 'none'}`);
-    }
-    data.activeProfile = name;
-    this.save(data);
-  }
-
-  listProfiles(): string[] {
-    return Object.keys(this.load().profiles);
-  }
-
-  getActive(): AuthProfile | null {
-    const data = this.load();
-    if (!data.activeProfile || !data.profiles[data.activeProfile]) return null;
-    return data.profiles[data.activeProfile];
-  }
-
-  updateGameServerUrl(url: string | undefined, name?: string): void {
-    const data = this.load();
-    const profileName = name ?? data.activeProfile;
-    const profile = data.profiles[profileName];
-    if (!profile) return;
-    profile.gameServerUrl = url;
-    this.save(data);
-  }
-
-  setTtsKey(provider: string, key: string, profileName?: string): void {
-    const data = this.load();
-    const profile = this.getProfileForTts(data, profileName);
-    profile.tts = {
-      ...profile.tts,
-      keys: { ...profile.tts?.keys, [provider]: key },
-    };
-    delete data.neteaseTtsKey;
-    this.save(data);
-  }
-
-  getTtsKey(provider: string, profileName?: string): string | undefined {
-    const data = this.load();
-    return this.getProfileForTts(data, profileName).tts?.keys?.[provider];
-  }
-
-  setTtsDefaultVoice(voice: string, profileName?: string): void {
-    const data = this.load();
-    const profile = this.getProfileForTts(data, profileName);
-    profile.tts = { ...profile.tts, defaultVoice: voice };
-    this.save(data);
-  }
-
-  getTtsDefaultVoice(profileName?: string): string | undefined {
-    const data = this.load();
-    return this.getProfileForTts(data, profileName).tts?.defaultVoice;
-  }
-
-  getTtsConfig(profileName?: string): AuthTtsConfig | undefined {
-    const data = this.load();
-    return this.getProfileForTts(data, profileName).tts;
-  }
-
-  private getProfileForTts(data: AuthData, profileName?: string): AuthProfile {
-    const name = profileName ?? data.activeProfile;
-    const profile = name ? data.profiles[name] : undefined;
-    if (!profile) {
-      throw new Error('No active account. Run `clawclaw-cli account register` or `clawclaw-cli account switch <apiKey>` first.');
-    }
-    return profile;
-  }
-
-  /** @deprecated Use {@link setTtsKey} with `TTS_PROVIDER_LEIHUO`. */
-  setGlobalTtsKey(key: string): void {
-    this.setTtsKey(TTS_PROVIDER_LEIHUO, key);
-  }
-
-  /** @deprecated Use {@link getTtsKey} with `TTS_PROVIDER_LEIHUO`. */
-  getGlobalTtsKey(): string | undefined {
-    return this.getTtsKey(TTS_PROVIDER_LEIHUO);
-  }
-}
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { getWorkspaceDir } from './init-command.js';
+import { TTS_PROVIDER_LEIHUO } from './tts-keys.js';
+import {
+  ensureUserDataLayout,
+  getRuntimeAuthStateFile,
+  getUserDataAuthFile,
+  readRuntimeAuthState,
+  splitAuthData,
+  writeRuntimeAuthState,
+  type RuntimeAuthState,
+} from './user-data.js';
+
+export interface AuthTtsConfig {
+  keys?: Record<string, string>;
+  defaultVoice?: string;
+}
+
+export interface AuthProfile {
+  agentName: string;
+  apiKey: string;
+  /** Lobby server URL (e.g. https://myclaw.163.com/claw) */
+  serverUrl: string;
+  /** Game server URL (e.g. http://{address}:{port}), obtained from /queue/status after match */
+  gameServerUrl?: string;
+  /** Per-account TTS configuration. */
+  tts?: AuthTtsConfig;
+}
+
+export interface AuthData {
+  activeProfile: string;
+  profiles: Record<string, AuthProfile>;
+  /** @deprecated Migrated to each profile's `tts.keys` on load. */
+  ttsKeys?: Record<string, string>;
+  /** @deprecated Migrated to `ttsKeys.leihuo` on load. */
+  neteaseTtsKey?: string;
+}
+
+const EMPTY_AUTH: AuthData = { activeProfile: '', profiles: {} };
+
+export class AuthStore {
+  private authFile: string;
+  private runtimeAuthStateFile: string;
+
+  constructor(authFile?: string, runtimeAuthStateFile?: string) {
+    if (authFile) {
+      this.authFile = authFile;
+      this.runtimeAuthStateFile = runtimeAuthStateFile ?? join(dirname(authFile), 'auth-state.json');
+      return;
+    }
+
+    const workspaceDir = getWorkspaceDir();
+    ensureUserDataLayout(workspaceDir);
+    this.authFile = getUserDataAuthFile(workspaceDir);
+    this.runtimeAuthStateFile = getRuntimeAuthStateFile(workspaceDir);
+  }
+
+  load(): AuthData {
+    if (!existsSync(this.authFile)) return { ...EMPTY_AUTH, profiles: {} };
+    try {
+      const data = JSON.parse(readFileSync(this.authFile, 'utf8')) as AuthData;
+      const { auth, runtime, changed } = splitAuthData(data);
+      this.mergeRuntimeState(runtime);
+      if (changed) this.writeAuth(auth);
+      return auth;
+    } catch {
+      return { ...EMPTY_AUTH, profiles: {} };
+    }
+  }
+
+  save(data: AuthData): void {
+    const { auth, runtime } = splitAuthData(data);
+    this.mergeRuntimeState(runtime);
+    this.writeAuth(auth);
+  }
+
+  private writeAuth(data: AuthData): void {
+    const dir = dirname(this.authFile);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(this.authFile, JSON.stringify(data, null, 2));
+  }
+
+  private mergeRuntimeState(incoming: RuntimeAuthState): void {
+    const incomingEntries = Object.entries(incoming.profiles ?? {}).filter(([, profile]) => profile.gameServerUrl);
+    if (incomingEntries.length === 0) return;
+    const current = readRuntimeAuthState(this.runtimeAuthStateFile);
+    let changed = false;
+    for (const [name, profile] of incomingEntries) {
+      if (current.profiles[name]?.gameServerUrl) continue;
+      current.profiles[name] = profile;
+      changed = true;
+    }
+    if (changed) writeRuntimeAuthState(this.runtimeAuthStateFile, current);
+  }
+
+  addProfile(profile: AuthProfile): void {
+    const data = this.load();
+    if (data.ttsKeys && !profile.tts?.keys) {
+      profile.tts = {
+        ...profile.tts,
+        keys: { ...data.ttsKeys },
+      };
+      delete data.ttsKeys;
+    }
+    data.profiles[profile.agentName] = profile;
+    data.activeProfile = profile.agentName;
+    this.save(data);
+  }
+
+  removeProfile(name: string): void {
+    const data = this.load();
+    delete data.profiles[name];
+    if (data.activeProfile === name) {
+      const remaining = Object.keys(data.profiles);
+      data.activeProfile = remaining[0] ?? '';
+    }
+    this.save(data);
+    const state = readRuntimeAuthState(this.runtimeAuthStateFile);
+    if (state.profiles[name]) {
+      delete state.profiles[name];
+      writeRuntimeAuthState(this.runtimeAuthStateFile, state);
+    }
+  }
+
+  switchProfile(name: string): void {
+    const data = this.load();
+    if (!data.profiles[name]) {
+      throw new Error(`Profile "${name}" not found. Available: ${Object.keys(data.profiles).join(', ') || 'none'}`);
+    }
+    data.activeProfile = name;
+    this.save(data);
+  }
+
+  listProfiles(): string[] {
+    return Object.keys(this.load().profiles);
+  }
+
+  getActive(): AuthProfile | null {
+    const data = this.load();
+    if (!data.activeProfile || !data.profiles[data.activeProfile]) return null;
+    const profile = data.profiles[data.activeProfile];
+    const gameServerUrl = this.getGameServerUrl(data.activeProfile);
+    return gameServerUrl ? { ...profile, gameServerUrl } : { ...profile };
+  }
+
+  updateGameServerUrl(url: string | undefined, name?: string): void {
+    const data = this.load();
+    const profileName = name ?? data.activeProfile;
+    const profile = data.profiles[profileName];
+    if (!profile) return;
+    const state = readRuntimeAuthState(this.runtimeAuthStateFile);
+    if (url) {
+      state.profiles[profileName] = { gameServerUrl: url, updatedAt: new Date().toISOString() };
+    } else {
+      delete state.profiles[profileName]?.gameServerUrl;
+      delete state.profiles[profileName]?.updatedAt;
+      if (state.profiles[profileName] && Object.keys(state.profiles[profileName]).length === 0) {
+        delete state.profiles[profileName];
+      }
+    }
+    writeRuntimeAuthState(this.runtimeAuthStateFile, state);
+  }
+
+  getGameServerUrl(profileName?: string): string | undefined {
+    const data = this.load();
+    const name = profileName ?? data.activeProfile;
+    if (!name) return undefined;
+    return readRuntimeAuthState(this.runtimeAuthStateFile).profiles[name]?.gameServerUrl;
+  }
+
+  setTtsKey(provider: string, key: string, profileName?: string): void {
+    const data = this.load();
+    const profile = this.getProfileForTts(data, profileName);
+    profile.tts = {
+      ...profile.tts,
+      keys: { ...profile.tts?.keys, [provider]: key },
+    };
+    delete data.neteaseTtsKey;
+    this.save(data);
+  }
+
+  getTtsKey(provider: string, profileName?: string): string | undefined {
+    const data = this.load();
+    return this.getProfileForTts(data, profileName).tts?.keys?.[provider];
+  }
+
+  setTtsDefaultVoice(voice: string, profileName?: string): void {
+    const data = this.load();
+    const profile = this.getProfileForTts(data, profileName);
+    profile.tts = { ...profile.tts, defaultVoice: voice };
+    this.save(data);
+  }
+
+  getTtsDefaultVoice(profileName?: string): string | undefined {
+    const data = this.load();
+    return this.getProfileForTts(data, profileName).tts?.defaultVoice;
+  }
+
+  getTtsConfig(profileName?: string): AuthTtsConfig | undefined {
+    const data = this.load();
+    return this.getProfileForTts(data, profileName).tts;
+  }
+
+  private getProfileForTts(data: AuthData, profileName?: string): AuthProfile {
+    const name = profileName ?? data.activeProfile;
+    const profile = name ? data.profiles[name] : undefined;
+    if (!profile) {
+      throw new Error('No active account. Run `clawclaw-cli account register` or `clawclaw-cli account switch <apiKey>` first.');
+    }
+    return profile;
+  }
+
+  /** @deprecated Use {@link setTtsKey} with `TTS_PROVIDER_LEIHUO`. */
+  setGlobalTtsKey(key: string): void {
+    this.setTtsKey(TTS_PROVIDER_LEIHUO, key);
+  }
+
+  /** @deprecated Use {@link getTtsKey} with `TTS_PROVIDER_LEIHUO`. */
+  getGlobalTtsKey(): string | undefined {
+    return this.getTtsKey(TTS_PROVIDER_LEIHUO);
+  }
+}

package/src/lib/command-meta.ts

@@ -1,37 +1,37 @@
-/**
- * command-meta — 给 commander Command 实例附加 adapter-facing 元数据。
- *
- * 用 WeakMap 而不是在 Command 上加属性,避免污染 commander 类型 + 自动 GC。
- * 此文件**不感知具体适配器**;它只是约定一组字段,由 adapter 决定如何用。
- *
- * 当前消费者:`src/commands/_schema.ts` 把 meta 写进输出,
- * `openclaw-clawclaw` 适配器读 meta 决定:
- *   · requiresConfirm → 自动给工具加 `confirm:boolean` 必填参数
- *   · longRunning + timeoutMs → 拉长 spawn timeout
- *   · sensitive → 在工具 description 加 ⚠️ 警示
- */
-
-import type { Command } from 'commander';
-
-export interface CommandMeta {
-  /** Adapter should add a mandatory `confirm: true` parameter before invocation. */
-  requiresConfirm?: boolean;
-  /** Adapter should expect this command to block; pair with `timeoutMs`. */
-  longRunning?: boolean;
-  /** Semantic flag: writes credentials / consumes quotas / etc. */
-  sensitive?: boolean;
-  /** Adapter should use this timeout (ms) for spawn instead of default. */
-  timeoutMs?: number;
-}
-
-const META = new WeakMap<Command, CommandMeta>();
-
-export function setMeta(cmd: Command, meta: CommandMeta): Command {
-  const existing = META.get(cmd) ?? {};
-  META.set(cmd, { ...existing, ...meta });
-  return cmd;
-}
-
-export function getMeta(cmd: Command): CommandMeta | undefined {
-  return META.get(cmd);
-}
+/**
+ * command-meta — 给 commander Command 实例附加 adapter-facing 元数据。
+ *
+ * 用 WeakMap 而不是在 Command 上加属性,避免污染 commander 类型 + 自动 GC。
+ * 此文件**不感知具体适配器**;它只是约定一组字段,由 adapter 决定如何用。
+ *
+ * 当前消费者:`src/commands/_schema.ts` 把 meta 写进输出,
+ * `openclaw-clawclaw` 适配器读 meta 决定:
+ *   · requiresConfirm → 自动给工具加 `confirm:boolean` 必填参数
+ *   · longRunning + timeoutMs → 拉长 spawn timeout
+ *   · sensitive → 在工具 description 加 ⚠️ 警示
+ */
+
+import type { Command } from 'commander';
+
+export interface CommandMeta {
+  /** Adapter should add a mandatory `confirm: true` parameter before invocation. */
+  requiresConfirm?: boolean;
+  /** Adapter should expect this command to block; pair with `timeoutMs`. */
+  longRunning?: boolean;
+  /** Semantic flag: writes credentials / consumes quotas / etc. */
+  sensitive?: boolean;
+  /** Adapter should use this timeout (ms) for spawn instead of default. */
+  timeoutMs?: number;
+}
+
+const META = new WeakMap<Command, CommandMeta>();
+
+export function setMeta(cmd: Command, meta: CommandMeta): Command {
+  const existing = META.get(cmd) ?? {};
+  META.set(cmd, { ...existing, ...meta });
+  return cmd;
+}
+
+export function getMeta(cmd: Command): CommandMeta | undefined {
+  return META.get(cmd);
+}