@xfxstudio/claworld 0.2.20 → 0.2.22

package/openclaw.plugin.json

@@ -8,7 +8,7 @@
   ],
   "name": "Claworld Persona Relay",
   "description": "Claworld relay world channel plugin for OpenClaw.",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",

package/src/openclaw/plugin/claworld-channel-plugin.js

@@ -17,6 +17,10 @@ import {
   resolveClaworldRuntimeConfig,
   validateClaworldChannelConfig,
 } from './config-schema.js';
+import {
+  loadClaworldRuntimeBackup,
+  persistClaworldRuntimeBackup,
+} from './runtime-backup.js';
 import {
   claworldOnboardingAdapter,
   claworldSetupAdapter,
@@ -1895,48 +1899,118 @@ export function createClaworldChannelPlugin({
   }
 
   async function persistRuntimeAppToken({ runtime, accountId, appToken, relayAgentId = null }) {
-    if (!runtime?.config?.loadConfig || !runtime?.config?.writeConfigFile) {
-      return { skipped: true, reason: 'missing_runtime_config_io' };
-    }
     if (!accountId || !appToken) {
       return { skipped: true, reason: 'missing_account_or_token' };
     }
 
-    const currentCfg = await runtime.config.loadConfig();
-    const nextCfg = JSON.parse(JSON.stringify(currentCfg || {}));
-    nextCfg.channels = nextCfg.channels && typeof nextCfg.channels === 'object' && !Array.isArray(nextCfg.channels)
-      ? nextCfg.channels
-      : {};
-    const claworldRoot = nextCfg.channels.claworld && typeof nextCfg.channels.claworld === 'object' && !Array.isArray(nextCfg.channels.claworld)
-      ? nextCfg.channels.claworld
-      : {};
-    const accounts = claworldRoot.accounts && typeof claworldRoot.accounts === 'object' && !Array.isArray(claworldRoot.accounts)
-      ? claworldRoot.accounts
-      : {};
-    const account = accounts[accountId] && typeof accounts[accountId] === 'object' && !Array.isArray(accounts[accountId])
-      ? accounts[accountId]
-      : {};
+    let configPersistResult = { skipped: true, reason: 'missing_runtime_config_io' };
+    if (runtime?.config?.loadConfig && runtime?.config?.writeConfigFile) {
+      const currentCfg = await runtime.config.loadConfig();
+      const nextCfg = JSON.parse(JSON.stringify(currentCfg || {}));
+      nextCfg.channels = nextCfg.channels && typeof nextCfg.channels === 'object' && !Array.isArray(nextCfg.channels)
+        ? nextCfg.channels
+        : {};
+      const claworldRoot = nextCfg.channels.claworld && typeof nextCfg.channels.claworld === 'object' && !Array.isArray(nextCfg.channels.claworld)
+        ? nextCfg.channels.claworld
+        : {};
+      const accounts = claworldRoot.accounts && typeof claworldRoot.accounts === 'object' && !Array.isArray(claworldRoot.accounts)
+        ? claworldRoot.accounts
+        : {};
+      const account = accounts[accountId] && typeof accounts[accountId] === 'object' && !Array.isArray(accounts[accountId])
+        ? accounts[accountId]
+        : {};
+
+      const normalizedRelayAgentId = normalizeClaworldText(relayAgentId, normalizeClaworldText(account?.relay?.agentId, null));
+      const currentAppToken = normalizeClaworldText(account.appToken, null);
+      const currentRelayAgentId = normalizeClaworldText(account?.relay?.agentId, null);
+      if (currentAppToken === appToken && currentRelayAgentId === normalizedRelayAgentId) {
+        configPersistResult = { skipped: true, reason: 'already_persisted' };
+      } else {
+        accounts[accountId] = {
+          ...account,
+          appToken,
+          relay: {
+            ...(account?.relay && typeof account.relay === 'object' && !Array.isArray(account.relay) ? account.relay : {}),
+            ...(normalizedRelayAgentId ? { agentId: normalizedRelayAgentId } : {}),
+          },
+        };
+        delete accounts[accountId].registration;
+        claworldRoot.accounts = accounts;
+        nextCfg.channels.claworld = claworldRoot;
+        await runtime.config.writeConfigFile(nextCfg);
+        configPersistResult = { skipped: false, ok: true };
+      }
+    }
+
+    let backupPersistResult = { skipped: true, reason: 'missing_runtime_config_loader' };
+    try {
+      backupPersistResult = await persistClaworldRuntimeBackup({
+        runtime,
+        accountId,
+      });
+    } catch (error) {
+      backupPersistResult = {
+        skipped: true,
+        reason: 'backup_persist_failed',
+        error: error?.message || String(error),
+      };
+    }
+
+    return {
+      ...configPersistResult,
+      backup: backupPersistResult,
+    };
+  }
 
-    const normalizedRelayAgentId = normalizeClaworldText(relayAgentId, normalizeClaworldText(account?.relay?.agentId, null));
-    const currentAppToken = normalizeClaworldText(account.appToken, null);
-    const currentRelayAgentId = normalizeClaworldText(account?.relay?.agentId, null);
-    if (currentAppToken === appToken && currentRelayAgentId === normalizedRelayAgentId) {
-      return { skipped: true, reason: 'already_persisted' };
+  async function maybeRestoreRuntimeAppToken({ runtime, accountId, runtimeConfig }) {
+    if (resolveRuntimeAppToken(runtimeConfig)) {
+      return { restored: false, reason: 'already_configured', runtimeConfig };
     }
 
-    accounts[accountId] = {
-      ...account,
-      appToken,
-      relay: {
-        ...(account?.relay && typeof account.relay === 'object' && !Array.isArray(account.relay) ? account.relay : {}),
-        ...(normalizedRelayAgentId ? { agentId: normalizedRelayAgentId } : {}),
-      },
+    const backupState = await loadClaworldRuntimeBackup({ accountId });
+    const backup = backupState.backup;
+    const backupToken = normalizeClaworldText(backup?.appToken, null);
+    if (!backupToken) {
+      return {
+        restored: false,
+        reason: 'backup_missing_app_token',
+        runtimeConfig,
+      };
+    }
+
+    const backupServerUrl = normalizeClaworldText(backup?.serverUrl, null);
+    const currentServerUrl = normalizeClaworldText(runtimeConfig?.serverUrl, null);
+    if (backupServerUrl && currentServerUrl && normalizeRelayHttpBaseUrl(backupServerUrl) !== normalizeRelayHttpBaseUrl(currentServerUrl)) {
+      return {
+        restored: false,
+        reason: 'backup_server_mismatch',
+        runtimeConfig,
+      };
+    }
+
+    const restoredRuntimeConfig = applyRuntimeIdentity(runtimeConfig, {
+      appToken: backupToken,
+    });
+
+    try {
+      await persistRuntimeAppToken({
+        runtime,
+        accountId,
+        appToken: backupToken,
+      });
+    } catch (error) {
+      logger.warn?.(`[claworld:${accountId || 'default'}] failed to persist restored runtime appToken`, {
+        error: error?.message || String(error),
+      });
+    }
+
+    return {
+      restored: true,
+      reason: 'installer_state_backup',
+      runtimeConfig: restoredRuntimeConfig,
+      backup,
+      installerStatePath: backupState.installerStatePath,
     };
-    delete accounts[accountId].registration;
-    claworldRoot.accounts = accounts;
-    nextCfg.channels.claworld = claworldRoot;
-    await runtime.config.writeConfigFile(nextCfg);
-    return { skipped: false, ok: true };
   }
 
   function resolveConfiguredRuntimeContext(context = {}) {
@@ -1959,6 +2033,19 @@ export function createClaworldChannelPlugin({
     const cfg = configuredContext.cfg || {};
     const accountId = configuredContext.accountId || null;
     let runtimeConfig = configuredContext.runtimeConfig;
+    const runtimeResolution = resolvePluginRuntimeCandidate(context.runtime || null);
+    const restoredBinding = await maybeRestoreRuntimeAppToken({
+      runtime: runtimeResolution.runtime,
+      accountId,
+      runtimeConfig,
+    });
+    if (restoredBinding.restored) {
+      runtimeConfig = restoredBinding.runtimeConfig;
+      logger.info?.(`[claworld:${accountId || 'default'}] restored runtime binding from installer state`, {
+        installerStatePath: restoredBinding.installerStatePath || null,
+        relayAgentId: runtimeConfig?.relay?.agentId || null,
+      });
+    }
     const runtimeContext = accountRuntimeContexts.get(accountId || 'default') || null;
     if (runtimeContext?.runtimeConfig && !runtimeContext?.deferredFailure) {
       return {
@@ -2009,6 +2096,20 @@ export function createClaworldChannelPlugin({
           runtimeConfigShape: summarizeObjectShape(runtimeConfig),
         });
 
+        const runtimeResolution = resolvePluginRuntimeCandidate(context.runtime || null);
+        const restoredBinding = await maybeRestoreRuntimeAppToken({
+          runtime: runtimeResolution.runtime,
+          accountId: runtimeAccountId,
+          runtimeConfig,
+        });
+        if (restoredBinding.restored) {
+          runtimeConfig = restoredBinding.runtimeConfig;
+          logger.info?.(`[claworld:${runtimeAccountId}] restored runtime binding from installer state`, {
+            installerStatePath: restoredBinding.installerStatePath || null,
+            relayAgentId: runtimeConfig?.relay?.agentId || null,
+          });
+        }
+
         const validation = validateClaworldChannelConfig(configSource, context.accountId);
         if (!validation.ok && sourceType !== 'root_cfg') {
           logger.warn?.(`[claworld:${runtimeAccountId}] non-root runtime source would not validate as full cfg`, {
@@ -2084,7 +2185,6 @@ export function createClaworldChannelPlugin({
           return { startedDeferred: true, reason: 'missing_runtime_context', runtimeConfig };
         }
 
-        const runtimeResolution = resolvePluginRuntimeCandidate(context.runtime || null);
         const pluginRuntime = runtimeResolution.runtime;
         const runtimeSource = runtimeResolution.runtimeSource;
 
@@ -2092,24 +2192,24 @@ export function createClaworldChannelPlugin({
           runtimeSource,
         });
 
-        if (binding.bindingSource !== 'configured_app_token') {
-          try {
-            const persisted = await persistRuntimeAppToken({
-              runtime: pluginRuntime,
+        try {
+          const persisted = await persistRuntimeAppToken({
+            runtime: pluginRuntime,
+            accountId: runtimeConfig.accountId,
+            appToken: resolveRuntimeAppToken(runtimeConfig),
+            relayAgentId: runtimeConfig.relay?.agentId || null,
+          });
+          if (!persisted.skipped || persisted.backup?.skipped === false) {
+            logger.info?.(`[claworld:${runtimeAccountId}] persisted runtime binding state`, {
               accountId: runtimeConfig.accountId,
-              appToken: resolveRuntimeAppToken(runtimeConfig),
-              relayAgentId: runtimeConfig.relay?.agentId || null,
-            });
-            if (!persisted.skipped) {
-              logger.info?.(`[claworld:${runtimeAccountId}] persisted runtime appToken`, {
-                accountId: runtimeConfig.accountId,
-              });
-            }
-          } catch (error) {
-            logger.warn?.(`[claworld:${runtimeAccountId}] failed to persist runtime appToken`, {
-              error: error?.message || String(error),
+              configSkipped: persisted.skipped === true,
+              backupSkipped: persisted.backup?.skipped === true,
             });
           }
+        } catch (error) {
+          logger.warn?.(`[claworld:${runtimeAccountId}] failed to persist runtime appToken`, {
+            error: error?.message || String(error),
+          });
         }
 
         accountRuntimeContexts.set(accountKey, {

package/src/openclaw/plugin/register.js

@@ -1022,12 +1022,20 @@ function buildRegisteredTools(api, plugin) {
         });
         const pairedAgentId = identityPayload?.agentId || runtimeConfig.relay?.agentId || null;
         const relayAgent = pairedAgentId
-          ? await plugin.helpers.pairing.resolveAgentIdentity({
-            cfg,
-            accountId,
-            runtimeConfig,
+          ? {
             agentId: pairedAgentId,
-          })
+            displayName: normalizeText(
+              identityPayload?.publicIdentity?.displayName,
+              normalizeText(
+                identityPayload?.recommendedDisplayName,
+                normalizeText(runtimeConfig?.name, normalizeText(runtimeConfig?.registration?.displayName, null)),
+              ),
+            ),
+            discoverable: null,
+            contactable: null,
+            online: null,
+            resolved: null,
+          }
           : null;
         const hasConfiguredAppToken = Boolean(
           runtimeConfig.appToken

package/src/openclaw/plugin/relay-client.js

@@ -459,7 +459,7 @@ export class ClaworldRelayClient extends EventEmitter {
     config,
     agentId,
     credential = null,
-    clientVersion = 'claworld-plugin/0.2.20',
+    clientVersion = 'claworld-plugin/0.2.22',
     sessionTarget,
     fallbackTarget,
   } = {}) {

package/src/openclaw/plugin/runtime-backup.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  DEFAULT_CLAWORLD_ACCOUNT_ID,
+  findClaworldManagedRuntimeBackup,
+  setClaworldManagedRuntimeBackupState,
+  stripClaworldManagedRuntimeConfig,
+} from './managed-config.js';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+export function resolveDefaultOpenClawConfigPath() {
+  return path.resolve(normalizeText(
+    process.env.OPENCLAW_CONFIG_PATH,
+    path.join(os.homedir(), '.openclaw', 'openclaw.json'),
+  ));
+}
+
+export function resolveClaworldInstallerStatePath(configPath = resolveDefaultOpenClawConfigPath()) {
+  const resolvedConfigPath = path.resolve(String(configPath));
+  return path.join(path.dirname(resolvedConfigPath), '.claworld-installer-state.json');
+}
+
+async function loadInstallerStateFromDisk(installerStatePath) {
+  try {
+    const raw = await fs.readFile(installerStatePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {};
+    throw error;
+  }
+}
+
+async function writeInstallerStateToDisk(installerStatePath, installerState) {
+  const nextState = installerState && typeof installerState === 'object' && !Array.isArray(installerState)
+    ? installerState
+    : {};
+  if (Object.keys(nextState).length === 0) {
+    await fs.rm(installerStatePath, { force: true });
+    return;
+  }
+  await fs.mkdir(path.dirname(installerStatePath), { recursive: true });
+  await fs.writeFile(installerStatePath, `${JSON.stringify(nextState, null, 2)}\n`, 'utf8');
+}
+
+export async function loadClaworldRuntimeBackup({
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+  configPath = resolveDefaultOpenClawConfigPath(),
+} = {}) {
+  const installerStatePath = resolveClaworldInstallerStatePath(configPath);
+  const installerState = await loadInstallerStateFromDisk(installerStatePath);
+  return {
+    installerStatePath,
+    installerState,
+    backup: findClaworldManagedRuntimeBackup(installerState, accountId),
+  };
+}
+
+export async function persistClaworldRuntimeBackup({
+  runtime = null,
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+  configPath = resolveDefaultOpenClawConfigPath(),
+} = {}) {
+  if (!runtime?.config?.loadConfig) {
+    return { skipped: true, reason: 'missing_runtime_config_loader' };
+  }
+
+  const currentConfig = await runtime.config.loadConfig();
+  const { backup } = stripClaworldManagedRuntimeConfig(currentConfig, {
+    accountId,
+    preserveBackup: true,
+  });
+
+  if (!backup?.appToken) {
+    return { skipped: true, reason: 'missing_app_token', backup: null };
+  }
+
+  const installerStatePath = resolveClaworldInstallerStatePath(configPath);
+  const installerState = await loadInstallerStateFromDisk(installerStatePath);
+  const previousBackup = findClaworldManagedRuntimeBackup(installerState, accountId);
+  if (JSON.stringify(previousBackup || null) === JSON.stringify(backup)) {
+    return {
+      skipped: true,
+      reason: 'already_persisted',
+      installerStatePath,
+      backup,
+    };
+  }
+
+  setClaworldManagedRuntimeBackupState(installerState, accountId, backup);
+  await writeInstallerStateToDisk(installerStatePath, installerState);
+  return {
+    skipped: false,
+    ok: true,
+    installerStatePath,
+    backup,
+  };
+}