@xfxstudio/claworld 0.2.9 → 0.2.10-beta.0

package/src/openclaw/plugin/config-schema.js

@@ -13,8 +13,6 @@ import {
 const REQUIRED_KEYS = ['enabled', 'serverUrl', 'apiKey', 'accountId'];
 
 export const CLAWORLD_CHANNEL_ID = 'claworld';
-const LOCAL_AGENT_CODE_PATTERN = '^[A-Za-z0-9._:+~-]+(?:@[A-Za-z0-9._:+~-]+)?$';
-const LOCAL_AGENT_CODE_REGEX = new RegExp(LOCAL_AGENT_CODE_PATTERN, 'i');
 
 const AGENT_REGISTRATION_SCHEMA = {
   type: 'object',
@@ -25,22 +23,16 @@ const AGENT_REGISTRATION_SCHEMA = {
       description: 'Enable relay agent registration when this account does not already have an app token.',
       default: false,
     },
-    agentCode: {
-      type: 'string',
-      minLength: 1,
-      pattern: LOCAL_AGENT_CODE_PATTERN,
-      description: 'Unique Claworld identity handle. Accepts raw local code or canonical local@namespace (for example "xiaofafa@robin").',
-    },
     displayName: {
       type: 'string',
       minLength: 1,
-      description: 'Display name to use when the relay agent is created or refreshed.',
+      description: 'Public display name to use when the relay agent is created or refreshed.',
     },
   },
 };
 
 export const LOCAL_AGENT_BOOTSTRAP_SCHEMA = AGENT_REGISTRATION_SCHEMA;
-export const LOCAL_AGENT_BOOTSTRAP_REQUIRED = ['agentCode'];
+export const LOCAL_AGENT_BOOTSTRAP_REQUIRED = ['displayName'];
 
 export const MANUAL_RELAY_BINDING_SCHEMA = {
   type: 'object',
@@ -61,10 +53,10 @@ export const MANUAL_RELAY_BINDING_SCHEMA = {
       minLength: 1,
       description: 'Legacy alias for appToken.',
     },
-    defaultToAddress: {
+    defaultTargetAgentId: {
       type: 'string',
       minLength: 1,
-      description: 'Default relay target address (for example alice@robin) for minimal outbound testing.',
+      description: 'Default relay target agentId for minimal outbound testing.',
     },
   },
 };
@@ -183,7 +175,6 @@ const SINGLE_ACCOUNT_PROPERTIES = {
     },
   },
   registration: AGENT_REGISTRATION_SCHEMA,
-  localAgent: LOCAL_AGENT_BOOTSTRAP_SCHEMA,
   relay: MANUAL_RELAY_BINDING_SCHEMA,
 };
 
@@ -213,10 +204,10 @@ export const claworldChannelConfigJsonSchema = {
 export const claworldChannelConfigSchema = {
   channelId: CLAWORLD_CHANNEL_ID,
   required: REQUIRED_KEYS,
-  optional: ['name', 'heartbeatSeconds', 'reconnect', 'routing', 'approval', 'testing', 'appToken', 'registration', 'localAgent', 'relay', 'toolProfile', 'defaultAccount', 'accounts'],
+  optional: ['name', 'heartbeatSeconds', 'reconnect', 'routing', 'approval', 'testing', 'appToken', 'registration', 'relay', 'toolProfile', 'defaultAccount', 'accounts'],
   jsonSchema: claworldChannelConfigJsonSchema,
   description:
-    '最小 OpenClaw claworld channel 配置；支持单账号或 accounts.<id> 多账号模式。canonical flow uses appToken + registration, while relay/localAgent fields remain compatibility aliases.',
+    '最小 OpenClaw claworld channel 配置；支持单账号或 accounts.<id> 多账号模式。canonical flow uses appToken + registration.displayName bootstrap.',
   routingShape: {
     sessionTarget: 'mainagent',
     fallbackTarget: 'mainagent',
@@ -341,11 +332,8 @@ export function validateClaworldChannelConfig(config = {}, accountId = null) {
     errors.push({ code: 'invalid_fallback_target', value: fallbackTarget });
   }
 
-  if (registration.enabled && !registration.agentCode) {
-    errors.push({ code: 'missing_local_agent_code' });
-  }
-  if (registration.enabled && registration.agentCode && !LOCAL_AGENT_CODE_REGEX.test(String(registration.agentCode).trim())) {
-    errors.push({ code: 'invalid_local_agent_code', value: registration.agentCode });
+  if (registration.enabled && !registration.displayName) {
+    errors.push({ code: 'missing_registration_display_name' });
   }
 
   if (candidate.relay?.agentId && !appToken) {
@@ -375,7 +363,7 @@ export function validateClaworldChannelConfig(config = {}, accountId = null) {
       agentId: candidate.relay?.agentId || null,
       appToken,
       credentialToken: appToken,
-      defaultToAddress: candidate.relay?.defaultToAddress || null,
+      defaultTargetAgentId: candidate.relay?.defaultTargetAgentId || null,
     },
   });
 
@@ -407,7 +395,6 @@ export function inspectClaworldChannelAccount(config = {}, accountId = null) {
     testing: normalized.testing,
     appToken: normalized.appToken || null,
     registration: normalized.registration,
-    localAgent: normalized.localAgent,
     relay: normalized.relay,
     defaultAccount: normalized.defaultAccount,
     bindingStatus,
@@ -435,7 +422,6 @@ export function resolveClaworldRuntimeConfig(config = {}, accountId = null) {
     ...result.normalized,
     accountId: result.normalized.accountId || accountId || readDefaultAccountId(config) || 'default',
     approval: result.normalized.approval,
-    localAgent: result.normalized.localAgent,
     relay: result.normalized.relay,
   };
 }

package/src/openclaw/plugin/managed-config.js

@@ -25,6 +25,8 @@ export const DEFAULT_CLAWORLD_FALLBACK_TARGET = 'mainagent';
 export const CLAWORLD_PLUGIN_TOOL_ALLOW_ENTRY = 'claworld';
 export const MIN_MANAGED_SESSION_VISIBILITY = 'agent';
 export const REQUIRED_SANDBOX_SESSION_TOOLS_VISIBILITY = 'all';
+export const CLAWORLD_INSTALLER_STATE_ROOT_KEY = 'claworldInstaller';
+export const CLAWORLD_MANAGED_RUNTIME_BACKUP_VERSION = 1;
 
 export const TOOL_PROFILES = CLAWORLD_TOOL_PROFILES;
 
@@ -49,9 +51,9 @@ export function ensureObject(value) {
   return value;
 }
 
-function normalizeRegistrationAgentCode(value, fallback = null) {
+function normalizeRegistrationDisplayName(value, fallback = null) {
   const normalized = normalizeText(value, fallback);
-  return normalized ? normalized.toLowerCase() : fallback;
+  return normalized || fallback;
 }
 
 export function expandUserPath(input, homeDir = os.homedir()) {
@@ -103,14 +105,6 @@ function mergeManagedPluginToolExposure(existingTools = {}) {
   };
 }
 
-function inferRelayDomain(defaultToAddress = null) {
-  const normalized = normalizeText(defaultToAddress, null);
-  if (!normalized) return 'relay.local';
-  const atIndex = normalized.indexOf('@');
-  if (atIndex <= 0 || atIndex >= normalized.length - 1) return 'relay.local';
-  return normalized.slice(atIndex + 1).trim().toLowerCase() || 'relay.local';
-}
-
 function findAgentIndex(agentList = [], agentId) {
   return agentList.findIndex((item) => ensureObject(item).id === agentId);
 }
@@ -130,6 +124,72 @@ function findManagedAccountEntry(config = {}, accountId) {
   return {};
 }
 
+function ensureMutableInstallerStateRoot(installerState = {}) {
+  installerState[CLAWORLD_INSTALLER_STATE_ROOT_KEY] = ensureObject(installerState[CLAWORLD_INSTALLER_STATE_ROOT_KEY]);
+  const rootState = ensureObject(installerState[CLAWORLD_INSTALLER_STATE_ROOT_KEY]);
+  rootState.managedRuntime = ensureObject(rootState.managedRuntime);
+  rootState.managedRuntime.accounts = ensureObject(rootState.managedRuntime.accounts);
+  installerState[CLAWORLD_INSTALLER_STATE_ROOT_KEY] = rootState;
+  return rootState.managedRuntime.accounts;
+}
+
+function trimInstallerStateRoot(installerState = {}) {
+  const rootState = ensureObject(installerState[CLAWORLD_INSTALLER_STATE_ROOT_KEY]);
+  const managedRuntime = ensureObject(rootState.managedRuntime);
+  const accounts = ensureObject(managedRuntime.accounts);
+  if (Object.keys(accounts).length === 0) {
+    delete managedRuntime.accounts;
+  } else {
+    managedRuntime.accounts = accounts;
+  }
+  if (Object.keys(managedRuntime).length === 0) {
+    delete rootState.managedRuntime;
+  } else {
+    rootState.managedRuntime = managedRuntime;
+  }
+  if (Object.keys(rootState).length === 0) {
+    delete installerState[CLAWORLD_INSTALLER_STATE_ROOT_KEY];
+  } else {
+    installerState[CLAWORLD_INSTALLER_STATE_ROOT_KEY] = rootState;
+  }
+}
+
+export function findClaworldManagedRuntimeBackup(installerState = {}, accountId = DEFAULT_CLAWORLD_ACCOUNT_ID) {
+  const normalizedAccountId = normalizeText(accountId, DEFAULT_CLAWORLD_ACCOUNT_ID);
+  const rootState = ensureObject(installerState?.[CLAWORLD_INSTALLER_STATE_ROOT_KEY]);
+  const managedRuntime = ensureObject(rootState.managedRuntime);
+  const accounts = ensureObject(managedRuntime.accounts);
+  return ensureObject(accounts[normalizedAccountId]);
+}
+
+export function setClaworldManagedRuntimeBackupState(
+  installerState = {},
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+  value = null,
+) {
+  const normalizedAccountId = normalizeText(accountId, DEFAULT_CLAWORLD_ACCOUNT_ID);
+  const accounts = ensureMutableInstallerStateRoot(installerState);
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    accounts[normalizedAccountId] = JSON.parse(JSON.stringify(value));
+  } else {
+    delete accounts[normalizedAccountId];
+  }
+  trimInstallerStateRoot(installerState);
+  return installerState;
+}
+
+function removeManagedPluginToolExposure(existingTools = {}) {
+  const tools = ensureObject(existingTools);
+  const allow = asStringArray(tools.allow).filter((toolName) => toolName !== CLAWORLD_PLUGIN_TOOL_ALLOW_ENTRY);
+  const alsoAllow = asStringArray(tools.alsoAllow).filter((toolName) => toolName !== CLAWORLD_PLUGIN_TOOL_ALLOW_ENTRY);
+  const nextTools = { ...tools };
+  if (allow.length > 0) nextTools.allow = uniqueStrings(allow);
+  else delete nextTools.allow;
+  if (alsoAllow.length > 0) nextTools.alsoAllow = uniqueStrings(alsoAllow);
+  else delete nextTools.alsoAllow;
+  return Object.keys(nextTools).length > 0 ? nextTools : null;
+}
+
 const SESSION_VISIBILITY_RANK = Object.freeze({
   self: 0,
   tree: 1,
@@ -298,19 +358,18 @@ function buildManagedAccountEntry(options = {}) {
   } else {
     base.registration = {
       enabled: true,
-      agentCode: options.registrationAgentCode,
-      displayName: options.displayName,
+      displayName: normalizeText(options.registrationDisplayName, options.displayName),
     };
   }
 
-  if (!options.defaultToAddress) {
+  if (!options.defaultTargetAgentId) {
     return base;
   }
 
   return {
     ...base,
     relay: {
-      defaultToAddress: options.defaultToAddress,
+      defaultTargetAgentId: options.defaultTargetAgentId,
     },
   };
 }
@@ -331,11 +390,11 @@ function buildMergedAccountEntry(existingAccount = {}, options = {}) {
       ...existingApproval,
       mode: normalizeChatRequestApprovalMode(options.approvalMode, DEFAULT_CLAWORLD_APPROVAL_MODE),
     },
-    ...(options.defaultToAddress
+    ...(options.defaultTargetAgentId
       ? {
           relay: {
             ...existingRelay,
-            defaultToAddress: options.defaultToAddress,
+            defaultTargetAgentId: options.defaultTargetAgentId,
           },
         }
       : existingAccount.relay
@@ -356,19 +415,11 @@ function buildMergedAccountEntry(existingAccount = {}, options = {}) {
     registration: {
       ...existingRegistration,
       enabled: true,
-      agentCode: options.registrationAgentCode,
-      displayName: options.displayName,
+      displayName: normalizeText(options.registrationDisplayName, options.displayName),
     },
   };
 }
 
-export function canonicalRelayAgentCode(registrationAgentCode, defaultToAddress = null) {
-  const normalizedAgentCode = normalizeRegistrationAgentCode(registrationAgentCode, null);
-  if (!normalizedAgentCode) return null;
-  if (normalizedAgentCode.includes('@')) return normalizedAgentCode;
-  return `${normalizedAgentCode}@${inferRelayDomain(defaultToAddress)}`;
-}
-
 export function normalizeClaworldToolProfile(toolProfile = DEFAULT_CLAWORLD_TOOL_PROFILE) {
   const normalized = normalizeText(toolProfile, DEFAULT_CLAWORLD_TOOL_PROFILE);
   if (normalized === 'world') return 'default';
@@ -455,16 +506,13 @@ function describeToolAllowEntries(toolNames = []) {
 export function buildWorkspaceAgentsContent({
   agentId,
   accountId,
-  registrationAgentCode,
+  registrationDisplayName,
   appToken = null,
-  defaultToAddress = null,
+  defaultTargetAgentId = null,
 } = {}) {
-  const canonicalCode = canonicalRelayAgentCode(registrationAgentCode, defaultToAddress);
-  const identityLine = canonicalCode
-    ? `- canonical relay agentCode after bootstrap: \`${canonicalCode}\``
-    : appToken
-      ? '- relay identity is resolved from the configured appToken at runtime'
-      : '- relay identity is resolved during runtime bootstrap';
+  const identityLine = appToken
+    ? '- relay binding is resolved from the configured appToken at runtime'
+    : '- relay binding is created during runtime bootstrap and persists as backend-issued credentials';
 
   return `# Claworld Channel Agent
 
@@ -474,8 +522,9 @@ Routing contract:
 
 - local OpenClaw agent id: \`${agentId}\`
 - claworld account id: \`${accountId}\`
-${registrationAgentCode ? `- registration.agentCode: \`${registrationAgentCode}\`` : '- credential mode: appToken/manual binding'}
+${registrationDisplayName ? `- bootstrap display name: \`${registrationDisplayName}\`` : '- credential mode: appToken/manual binding'}
 ${identityLine}
+${defaultTargetAgentId ? `- default outbound target agentId: \`${defaultTargetAgentId}\`` : '- outbound sends require explicit target agentId inputs'}
 
 Operating rules:
 
@@ -498,22 +547,21 @@ function buildBoundAgentEntry(existingAgent = {}, agentId) {
 export function buildWorkspaceMemoryContent({
   agentId,
   accountId,
-  registrationAgentCode,
+  registrationDisplayName,
   appToken = null,
-  defaultToAddress = null,
+  defaultTargetAgentId = null,
 } = {}) {
-  const canonicalCode = canonicalRelayAgentCode(registrationAgentCode, defaultToAddress);
-  const identityLine = canonicalCode
-    ? `- relay identity: \`${canonicalCode}\``
-    : appToken
-      ? '- relay identity: resolved from appToken at runtime'
-      : '- relay identity: assigned during runtime bootstrap';
+  const identityLine = appToken
+    ? '- relay binding: resolved from appToken at runtime'
+    : '- relay binding: assigned during runtime bootstrap';
 
   return `# Claworld Memory
 
 - workspace owner: \`${agentId}\`
 - claworld account: \`${accountId}\`
+${registrationDisplayName ? `- bootstrap display name: \`${registrationDisplayName}\`` : ''}
 ${identityLine}
+${defaultTargetAgentId ? `- default outbound target agentId: \`${defaultTargetAgentId}\`` : ''}
 
 Use this file for durable Claworld-specific notes only.
 
@@ -527,10 +575,6 @@ export function resolveDefaultManagedWorkspace(agentId = DEFAULT_CLAWORLD_AGENT_
   return `~/.openclaw/workspace-${agentId}`;
 }
 
-export function resolveDefaultManagedRegistrationAgentCode(accountId = DEFAULT_CLAWORLD_ACCOUNT_ID) {
-  return null;
-}
-
 export function resolveDefaultManagedDisplayName(accountId = DEFAULT_CLAWORLD_ACCOUNT_ID) {
   return `${titleCase(accountId)} Channel Agent`;
 }
@@ -551,10 +595,13 @@ export function resolveClaworldManagedRuntimeOptions({
   accountId = null,
   input = {},
   overrides = {},
+  installerState = null,
 } = {}) {
   const resolvedAccountId = normalizeText(accountId, DEFAULT_CLAWORLD_ACCOUNT_ID);
   const attachToExistingAgent = overrides.attachToExistingAgent !== false;
-  const inferredAgentId = inferExistingAgentId(cfg, resolvedAccountId);
+  const existingBackup = findClaworldManagedRuntimeBackup(installerState, resolvedAccountId);
+  const inferredAgentId = inferExistingAgentId(cfg, resolvedAccountId)
+    || normalizeText(existingBackup.agentId, null);
   const agentId = normalizeText(overrides.agentId, inferredAgentId);
   const existingAgent = findAgentEntry(cfg, agentId);
   const existingAccount = findManagedAccountEntry(cfg, resolvedAccountId);
@@ -570,23 +617,23 @@ export function resolveClaworldManagedRuntimeOptions({
   const workspace = normalizeText(
     explicitWorkspace,
     replaceManagedRuntime
-      ? normalizeText(existingAgent?.workspace, defaultWorkspace)
-      : normalizeText(existingAgent?.workspace, defaultWorkspace),
+      ? normalizeText(existingAgent?.workspace, normalizeText(existingBackup.workspace, defaultWorkspace))
+      : normalizeText(existingAgent?.workspace, normalizeText(existingBackup.workspace, defaultWorkspace)),
   );
   const serverUrl = normalizeText(
     overrides.serverUrl,
-    normalizeText(input.httpUrl, normalizeText(input.url, DEFAULT_CLAWORLD_SERVER_URL)),
+    normalizeText(input.httpUrl, normalizeText(input.url, normalizeText(existingBackup.serverUrl, DEFAULT_CLAWORLD_SERVER_URL))),
   );
-  const apiKey = normalizeText(overrides.apiKey, DEFAULT_CLAWORLD_API_KEY);
+  const apiKey = normalizeText(overrides.apiKey, normalizeText(existingBackup.apiKey, DEFAULT_CLAWORLD_API_KEY));
   const explicitAppToken = normalizeText(
     overrides.appToken,
     normalizeText(input.appToken, null),
   );
-  const explicitRegistrationAgentCode = normalizeRegistrationAgentCode(
-    overrides.registrationAgentCode,
-    normalizeRegistrationAgentCode(input.code, null),
+  const explicitRegistrationDisplayName = normalizeRegistrationDisplayName(
+    overrides.registrationDisplayName,
+    normalizeRegistrationDisplayName(input.name, null),
   );
-  const appToken = explicitRegistrationAgentCode && !explicitAppToken
+  const appToken = explicitRegistrationDisplayName && !explicitAppToken
     ? null
     : normalizeText(
         explicitAppToken,
@@ -594,35 +641,39 @@ export function resolveClaworldManagedRuntimeOptions({
           existingAccount.appToken,
           normalizeText(
             existingAccount?.relay?.appToken,
-            normalizeText(existingAccount?.relay?.credentialToken, null),
+            normalizeText(existingAccount?.relay?.credentialToken, normalizeText(existingBackup.appToken, null)),
           ),
         ),
       );
   const displayName = normalizeText(
     overrides.displayName,
-    normalizeText(input.name, resolveDefaultManagedDisplayName(resolvedAccountId)),
+    normalizeText(input.name, normalizeText(existingBackup.displayName, resolveDefaultManagedDisplayName(resolvedAccountId))),
   );
-  const name = normalizeText(overrides.name, displayName);
-  const existingRegistrationAgentCode = normalizeRegistrationAgentCode(
-    existingAccount?.registration?.agentCode,
-    normalizeRegistrationAgentCode(existingAccount?.localAgent?.agentCode, null),
+  const name = normalizeText(overrides.name, normalizeText(existingBackup.name, displayName));
+  const existingRegistrationDisplayName = normalizeRegistrationDisplayName(
+    existingAccount?.registration?.displayName,
+    normalizeRegistrationDisplayName(
+      existingAccount?.localAgent?.displayName,
+      normalizeRegistrationDisplayName(existingBackup.registrationDisplayName, null),
+    ),
   );
-  const registrationAgentCode = appToken && !explicitRegistrationAgentCode
+  const registrationDisplayName = appToken && !explicitRegistrationDisplayName
     ? null
-    : normalizeRegistrationAgentCode(
-        explicitRegistrationAgentCode,
-        normalizeRegistrationAgentCode(
-          normalizeRegistrationAgentCode(
-            resolveDefaultManagedRegistrationAgentCode(resolvedAccountId),
-            existingRegistrationAgentCode,
-          ),
+    : normalizeRegistrationDisplayName(
+        explicitRegistrationDisplayName,
+        normalizeRegistrationDisplayName(
+          existingRegistrationDisplayName,
+          displayName,
         ),
       );
   const approvalMode = normalizeChatRequestApprovalMode(
     normalizeText(overrides.approvalMode, null),
     typeof overrides.autoAccept === 'boolean'
       ? (overrides.autoAccept ? 'open' : DEFAULT_CLAWORLD_APPROVAL_MODE)
-      : resolveStoredApprovalMode(existingAccount),
+      : normalizeChatRequestApprovalMode(
+          normalizeText(existingBackup.approvalMode, null),
+          resolveStoredApprovalMode(existingAccount),
+        ),
   );
 
   return {
@@ -638,14 +689,14 @@ export function resolveClaworldManagedRuntimeOptions({
     serverUrl,
     apiKey,
     appToken,
-    registrationAgentCode,
+    registrationDisplayName,
     displayName,
     name,
-    defaultToAddress: normalizeText(overrides.defaultToAddress, null),
+    defaultTargetAgentId: normalizeText(overrides.defaultTargetAgentId, null),
     approvalMode,
     sessionDmScope: normalizeText(
       overrides.sessionDmScope,
-      DEFAULT_CLAWORLD_DM_SCOPE,
+      normalizeText(existingBackup.sessionDmScope, DEFAULT_CLAWORLD_DM_SCOPE),
     ),
     replaceManagedRuntime,
     preserveDefaultAccount: overrides.preserveDefaultAccount === true,
@@ -665,8 +716,8 @@ export function applyClaworldManagedRuntimeConfig(inputConfig = {}, options = {}
   const sessionDmScope = normalizeText(options.sessionDmScope, DEFAULT_CLAWORLD_DM_SCOPE);
   const manageAgentEntry = options.manageAgentEntry === true;
 
-  if (!options.appToken && !normalizeText(options.registrationAgentCode, null)) {
-    throw new Error('claworld registration agentCode is required when appToken is absent');
+  if (!options.appToken && !normalizeText(options.registrationDisplayName, null)) {
+    throw new Error('claworld registration displayName is required when appToken is absent');
   }
 
   const removedManagedToolNames = new Set([
@@ -829,10 +880,164 @@ export function applyClaworldManagedRuntimeConfig(inputConfig = {}, options = {}
   return {
     config,
     summary,
-    canonicalAgentCode: canonicalRelayAgentCode(
-      options.registrationAgentCode,
-      options.defaultToAddress,
-    ),
+    bootstrapDisplayName: normalizeText(options.registrationDisplayName, null),
+  };
+}
+
+export function stripClaworldManagedRuntimeConfig(inputConfig = {}, {
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+  agentId = null,
+  preserveBackup = true,
+} = {}) {
+  const config = JSON.parse(JSON.stringify(ensureObject(inputConfig)));
+  const summary = [];
+  const resolvedAccountId = normalizeText(accountId, DEFAULT_CLAWORLD_ACCOUNT_ID);
+  const resolvedAgentId = normalizeText(agentId, inferExistingAgentId(config, resolvedAccountId));
+  const existingAgent = findAgentEntry(config, resolvedAgentId);
+  const existingAccount = findManagedAccountEntry(config, resolvedAccountId);
+  const existingToolProfile = resolveStoredClaworldToolProfile(existingAccount) || inferClaworldToolProfile(config);
+  const backup = preserveBackup
+    ? {
+        version: CLAWORLD_MANAGED_RUNTIME_BACKUP_VERSION,
+        accountId: resolvedAccountId,
+        agentId: resolvedAgentId,
+        workspace: normalizeText(existingAgent?.workspace, null),
+        serverUrl: normalizeText(existingAccount.serverUrl, null),
+        apiKey: normalizeText(existingAccount.apiKey, null),
+        appToken: normalizeText(
+          existingAccount.appToken,
+          normalizeText(existingAccount?.relay?.appToken, normalizeText(existingAccount?.relay?.credentialToken, null)),
+        ),
+        displayName: normalizeText(existingAccount.name, normalizeText(existingAgent?.name, null)),
+        name: normalizeText(existingAccount.name, null),
+        registrationDisplayName: normalizeRegistrationDisplayName(existingAccount?.registration?.displayName, null),
+        approvalMode: normalizeChatRequestApprovalMode(existingAccount?.approval?.mode, DEFAULT_CLAWORLD_APPROVAL_MODE),
+        sessionDmScope: normalizeText(config?.session?.dmScope, DEFAULT_CLAWORLD_DM_SCOPE),
+        toolProfile: existingToolProfile,
+        preservedAt: new Date().toISOString(),
+      }
+    : null;
+  if (backup) {
+    summary.push(`prepared managed claworld runtime backup for ${resolvedAccountId}`);
+  }
+
+  if (resolvedAgentId) {
+    const agentList = Array.isArray(config?.agents?.list) ? [...config.agents.list] : [];
+    const agentIndex = findAgentIndex(agentList, resolvedAgentId);
+    if (agentIndex >= 0) {
+      const nextAgent = { ...ensureObject(agentList[agentIndex]) };
+      const nextTools = removeManagedPluginToolExposure(nextAgent.tools);
+      if (nextTools) nextAgent.tools = nextTools;
+      else delete nextAgent.tools;
+      agentList[agentIndex] = nextAgent;
+      config.agents = ensureObject(config.agents);
+      config.agents.list = agentList;
+      summary.push(`removed managed claworld tool exposure from agent ${resolvedAgentId}`);
+    }
+  }
+
+  const claworldRoot = ensureObject(config?.channels?.claworld);
+  const accounts = ensureObject(claworldRoot.accounts);
+  if (Object.prototype.hasOwnProperty.call(accounts, resolvedAccountId)) {
+    delete accounts[resolvedAccountId];
+    summary.push(`removed channels.claworld.accounts.${resolvedAccountId}`);
+  }
+  const nextClaworldRoot = { ...claworldRoot };
+  if (Object.keys(accounts).length > 0) {
+    nextClaworldRoot.accounts = accounts;
+    const currentDefaultAccount = normalizeText(nextClaworldRoot.defaultAccount, null);
+    if (currentDefaultAccount === resolvedAccountId) {
+      nextClaworldRoot.defaultAccount = Object.keys(accounts)[0];
+      summary.push(`repointed channels.claworld.defaultAccount to ${nextClaworldRoot.defaultAccount}`);
+    }
+  } else {
+    delete nextClaworldRoot.accounts;
+    delete nextClaworldRoot.defaultAccount;
+  }
+  if (Object.keys(nextClaworldRoot).length > 0) {
+    config.channels = ensureObject(config.channels);
+    config.channels.claworld = nextClaworldRoot;
+  } else if (config.channels && typeof config.channels === 'object' && !Array.isArray(config.channels)) {
+    delete config.channels.claworld;
+    if (Object.keys(config.channels).length === 0) {
+      delete config.channels;
+    }
+    summary.push('removed channels.claworld root');
+  }
+
+  if (Array.isArray(config.bindings)) {
+    const nextBindings = config.bindings.filter((binding) => {
+      const candidate = ensureObject(binding);
+      const match = ensureObject(candidate.match);
+      const bindingChannel = normalizeText(match.channel, null);
+      const bindingAccountId = normalizeText(match.accountId, null);
+      const bindingAgentId = normalizeText(candidate.agentId, null);
+      if (bindingChannel !== 'claworld') return true;
+      if (bindingAccountId === resolvedAccountId) return false;
+      if (!bindingAccountId && resolvedAgentId && bindingAgentId === resolvedAgentId) return false;
+      return true;
+    });
+    if (nextBindings.length !== config.bindings.length) {
+      config.bindings = nextBindings;
+      summary.push(`removed claworld bindings for ${resolvedAccountId}`);
+    }
+    if (config.bindings.length === 0) {
+      delete config.bindings;
+    }
+  }
+
+  config.plugins = ensureObject(config.plugins);
+  const nextPluginAllow = asStringArray(config.plugins.allow).filter((pluginId) => pluginId !== 'claworld');
+  if (nextPluginAllow.length > 0) config.plugins.allow = uniqueStrings(nextPluginAllow);
+  else delete config.plugins.allow;
+
+  const nextPluginEntries = ensureObject(config.plugins.entries);
+  if (Object.prototype.hasOwnProperty.call(nextPluginEntries, 'claworld')) {
+    delete nextPluginEntries.claworld;
+    summary.push('removed plugins.entries.claworld');
+  }
+  if (Object.keys(nextPluginEntries).length > 0) config.plugins.entries = nextPluginEntries;
+  else delete config.plugins.entries;
+
+  const nextPluginInstalls = ensureObject(config.plugins.installs);
+  const claworldInstallRecord = ensureObject(nextPluginInstalls.claworld);
+  if (Object.prototype.hasOwnProperty.call(nextPluginInstalls, 'claworld')) {
+    delete nextPluginInstalls.claworld;
+    summary.push('removed plugins.installs.claworld');
+  }
+  if (Object.keys(nextPluginInstalls).length > 0) config.plugins.installs = nextPluginInstalls;
+  else delete config.plugins.installs;
+
+  const nextPluginLoad = ensureObject(config.plugins.load);
+  const sourcePath = normalizeText(claworldInstallRecord.sourcePath, null);
+  const filteredLoadPaths = asStringArray(nextPluginLoad.paths).filter((entry) => entry !== sourcePath);
+  if (sourcePath && filteredLoadPaths.length !== asStringArray(nextPluginLoad.paths).length) {
+    if (filteredLoadPaths.length > 0) {
+      nextPluginLoad.paths = uniqueStrings(filteredLoadPaths);
+    } else {
+      delete nextPluginLoad.paths;
+    }
+    summary.push('removed plugins.load.paths claworld sourcePath');
+  }
+  if (Object.keys(nextPluginLoad).length > 0) config.plugins.load = nextPluginLoad;
+  else delete config.plugins.load;
+
+  const nextPluginSlots = ensureObject(config.plugins.slots);
+  if (normalizeText(nextPluginSlots.memory, null) === 'claworld') {
+    delete nextPluginSlots.memory;
+    summary.push('removed plugins.slots.memory claworld');
+  }
+  if (Object.keys(nextPluginSlots).length > 0) config.plugins.slots = nextPluginSlots;
+  else delete config.plugins.slots;
+
+  if (Object.keys(config.plugins).length === 0) {
+    delete config.plugins;
+  }
+
+  return {
+    config,
+    summary,
+    backup,
   };
 }