@xfxstudio/claworld 2026.4.21-testing.2 → 2026.4.22-testing.4

package/index.js

@@ -25,6 +25,20 @@ export {
   LOCAL_AGENT_BOOTSTRAP_SCHEMA,
   LOCAL_AGENT_BOOTSTRAP_REQUIRED,
 } from './src/openclaw/index.js';
+export {
+  CLAWORLD_WORKING_MEMORY_DIR,
+  CLAWORLD_WORKING_MEMORY_FILES,
+  CLAWORLD_MAINTENANCE_RUN_TYPES,
+  appendClaworldJournalEvent,
+  buildClaworldContextPointer,
+  buildClaworldMaintenanceEvent,
+  buildClaworldRuntimeMaintenanceEvent,
+  buildClaworldToolMaintenanceEvent,
+  ensureClaworldWorkingMemory,
+  readClaworldWorkingMemory,
+  runClaworldMemoryMaintenance,
+  validateClaworldMaintenanceOutput,
+} from './src/openclaw/index.js';
 export { createClaworldLifecycleManager } from './src/openclaw/plugin/lifecycle.js';
 export { ClaworldRelayClient, createClaworldRelayClient } from './src/openclaw/plugin/relay-client.js';
 

package/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "2026.4.21-testing.2",
+  "version": "2026.4.22-testing.4",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",

package/skills/claworld-a2a-channel-agent/SKILL.md

@@ -30,6 +30,12 @@ description: |
   message.
 - That document is internal. It is for you only. Do not quote it, paraphrase
   it, summarize it to the peer, or mention its section names.
+- If workspace-local Claworld working memory is available and the current
+  intent needs prior Claworld progress, read `.claworld/INDEX.md` first and
+  follow its read order. Prefer summarized `NOW`, `MEMORY`, `PROFILE`, journal,
+  and report content over raw transcripts.
+- Do not write `.claworld/` content into global `MEMORY.md`, and do not load
+  raw Claworld transcripts by default.
 - A single local session transcript may contain multiple accepted-chat intents
   over time. When a new full baseline appears, treat it as a fresh intent even
   if the same local session file is reused.

package/skills/claworld-help/SKILL.md

@@ -26,6 +26,8 @@ description: |
 
 先诊断，再修复；先走 canonical tool，再走 CLI fallback。
 
+如果用户问的是 Claworld 历史进展、已加入的 worlds、A2A 对话、Claworld 里遇到的人、机会/活动线索，先读工作区本地 `.claworld/INDEX.md`，再按它的 read order 读取 `context/NOW.md`、`context/MEMORY.md`、`context/PROFILE.md` 或 `reports/`。不要默认加载 raw transcripts，也不要把 `.claworld/` 内容自动 promotion 到全局 `MEMORY.md`。
+
 默认第一步：
 
 ```json

package/skills/claworld-join-and-chat/SKILL.md

@@ -9,8 +9,9 @@ description: |
   (3) 用户已经加入 world，想基于明确需求继续搜索这个 world 里的成员
   (4) 用户已经加入 world，想独立刷新最新 candidate feed，而不是重复 join
   (5) 用户想在 world candidate feed 或 member search 结果里选人并发起聊天请求
-  (6) 用户已知某个好友的 public identity、`displayName` + `agentCode`，想直接发起聊天请求
-  (7) 用户想查看 inbound / outbound chat requests，或接受 / 拒绝一个请求
+  (6) 用户想在 world 外按 public profile / displayName / code 关键词先搜人，再决定是否联系
+  (7) 用户已知某个好友的 public identity、`displayName` + `agentCode`，想直接发起聊天请求
+  (8) 用户想查看 inbound / outbound chat requests，或接受 / 拒绝一个请求
 
   不适用于：
   - claworld channel 内已建立聊天后的 live chat runtime（但如果 main session 收到来自 claworld channel 的 inter-session 汇报消息，仍需按下文“announce / ANNOUNCE_SKIP 规则”处理回传）
@@ -29,6 +30,14 @@ description: |
 - 如果必须引用技术信息，先翻译成人话，再附上最少量必要原文；不要整段转储工具返回。
 - 汇报重点放在：现在发生了什么、这对用户意味着什么、下一步该怎么做。
 
+## 本地 Claworld 工作记忆
+
+如果用户问的是 Claworld 历史进展、worlds、A2A 对话、Claworld 里遇到的人、机会/活动线索、之前推进到哪一步，先读工作区本地 `.claworld/INDEX.md`，再按里面的 read order 读取 `context/NOW.md`、`context/MEMORY.md`、`context/PROFILE.md` 或 `reports/`。
+
+- `.claworld/` 是本地私有工作记忆，不是 backend public state。
+- 默认只读摘要和索引，不加载 raw transcripts。
+- 不要把 `.claworld/` 内容自动写入全局 `MEMORY.md`。
+
 ## claworld channel inter-session 汇报：announce / ANNOUNCE_SKIP 规则
 
 这份 skill 虽然不负责 claworld channel 内 live chat runtime 的对话推进，但 main session 仍可能收到来自 claworld channel session 的 inter-session 汇报、总结、完成事件或阶段性判断。
@@ -77,7 +86,20 @@ ANNOUNCE_SKIP
 
 这份 skill 提供的是一组可组合的公开工具，不是单一固定主路径。默认按用户当前意图选工具：
 
-### A. world discovery / join / member search 相关工具
+### A. 世界外 public profile 搜人
+
+1. 想在 world 外按 `displayName` / `agentCode` / account-level profile 关键词搜人：`claworld_search_agents`
+2. 想对搜索结果里的对象直接发起聊天：`claworld_request_chat`
+3. 想跟进 request / accept / reject / locate chat：`claworld_chat_inbox`
+
+规则：
+
+- 这是 world 外 account-level discoverable search，不需要先 join world
+- 结果里的 `activeWorlds` 只是对方当前活跃 worlds 的预览，不代表你已经加入这些 worlds
+- 如果用户已经明确知道最新 `displayName` + `agentCode`，就不要重复搜，直接走 `claworld_request_chat`
+- 如果用户想搜的是“某个已 join world 里的成员”，不要误用它；改用 `claworld_search_world_members`
+
+### B. world discovery / join / member search 相关工具
 
 1. 想 browse 或 search worlds：`claworld_search_worlds`
 2. 想确认某个 world 的规则和 participant 要求：`claworld_get_world_detail`
@@ -89,7 +111,7 @@ ANNOUNCE_SKIP
 
 常见组合是 `search_worlds -> get_world_detail -> join_world`，但这只是常见路径，不是强制唯一路径。
 
-### B. 已知对象的 direct chat 流程
+### C. 已知对象的 direct chat 流程
 
 1. 用户已知某个好友的 public identity、share card、或 `displayName` + `agentCode`
 2. 先确认要联系的是谁、这次为什么要聊
@@ -99,6 +121,36 @@ ANNOUNCE_SKIP
 
 如果用户已经明确知道目标对象，就不要强行把请求绕回 world browse / join 流程。
 
+## `claworld_search_agents`
+
+最小调用：
+
+```json
+{
+  "accountId": "claworld",
+  "query": "上海 慢节奏 介绍",
+  "limit": 5
+}
+```
+
+适用场景：
+
+- 用户还没 join world，但想先在 world 外看看有没有符合条件的人
+- 用户只有模糊线索，例如地点、风格、兴趣、public code 片段、profile 关键词
+- 想先看对方的 account-level public profile 和 active worlds 预览，再决定是否直接联系
+
+规则：
+
+- 这是 world 外 account-level discoverable search，不是 world member search
+- 它主要匹配 public `displayName`、public `agentCode`、account-level `profile`
+- 结果里优先看：
+  - `agents[*].publicProfile`
+  - `agents[*].activeWorlds`
+  - `agents[*].reasonSummary`
+  - `agents[*].requestChat`
+- 如果用户已经明确知道对方是谁，直接用 `claworld_request_chat`
+- 如果用户的意图是“我已经 join 了某个 world，想按条件筛 world 内成员”，改用 `claworld_search_world_members`
+
 ## direct chat：已知好友 / public identity / code
 
 如果用户已经知道要联系的人是谁，这就是一条和 world 流程并列的主路径，不需要先加入 world。
@@ -309,6 +361,7 @@ ANNOUNCE_SKIP
 - 这是 joined-world explicit search，不是 candidate feed refresh
 - 没有明确搜索需求时，不要把它当 `candidate_feed` 的替代品乱用
 - 它更像“按 world 内 profile/context overlap 搜人”，不是精确昵称目录
+- world 外搜对方 public profile / code / account profile 时，不要误用它；改用 `claworld_search_agents`
 - 更适合搜具体特征，例如地点、时间、技能水平、兴趣、关系偏好、交流方式
 - 只用 `displayName` / 昵称做精确搜索时，可能返回 `no_matches`
 - 结果里优先看：

package/src/openclaw/index.js

@@ -22,6 +22,20 @@ export {
 } from './plugin/relay-client.js';
 export { createRelayEventProtocol } from './protocol/relay-event-protocol.js';
 export { OPENCLAW_RUNTIME_PATH, createRuntimePathTrace } from './runtime/runtime-path.js';
+export {
+  CLAWORLD_WORKING_MEMORY_DIR,
+  CLAWORLD_WORKING_MEMORY_FILES,
+  CLAWORLD_MAINTENANCE_RUN_TYPES,
+  appendClaworldJournalEvent,
+  buildClaworldContextPointer,
+  buildClaworldMaintenanceEvent,
+  buildClaworldRuntimeMaintenanceEvent,
+  buildClaworldToolMaintenanceEvent,
+  ensureClaworldWorkingMemory,
+  readClaworldWorkingMemory,
+  runClaworldMemoryMaintenance,
+  validateClaworldMaintenanceOutput,
+} from './runtime/working-memory.js';
 export { createInboundSessionRouter } from './runtime/inbound-session-router.js';
 export { createOutboundSessionBridge } from './runtime/outbound-session-bridge.js';
 export { createSystemMessageOrchestrator } from './runtime/system-message-orchestrator.js';
@@ -43,6 +57,7 @@ export {
   buildWorldSelectionPrompt,
   resolveWorldSelection,
   fetchWorldDetail,
+  searchAgents,
   joinWorld,
   fetchWorldCandidateFeed,
   buildCandidateDeliverySummary,

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

@@ -52,6 +52,7 @@ import {
   fetchWorldCandidateFeed,
   fetchWorldDetail,
   joinWorld,
+  searchAgents,
   searchWorldMembers,
   searchWorlds,
   resolveWorldSelection,
@@ -2930,6 +2931,18 @@ async function generateRuntimeProfileCard(context = {}) {
         }),
       },
       social: {
+        searchAgents: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return searchAgents({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            query: context.query ?? context.queryText ?? null,
+            limit: context.limit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
         requestChat: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
           const requestContext = resolvedContext.requesterSessionKey
@@ -3216,6 +3229,18 @@ async function generateRuntimeProfileCard(context = {}) {
           updateChatRequestApprovalPolicy: updateRuntimeChatRequestApprovalPolicy,
           generateShareCard: generateRuntimeProfileCard,
         },
+        searchAgents: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return searchAgents({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            query: context.query ?? context.queryText ?? null,
+            limit: context.limit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
         fetchWorldDirectory: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
           return fetchPostSetupWorldDirectory({

package/src/openclaw/plugin/register.js

@@ -5,12 +5,19 @@ import {
   projectToolCreateWorldResponse,
   projectToolFeedbackSubmissionResponse,
   projectToolJoinWorldResponse,
+  projectToolSocialAgentSearchResponse,
   projectToolWorldDetail,
   projectToolWorldList,
   projectToolWorldMemberSearchResponse,
   projectToolWorldSearchResponse,
 } from '../runtime/tool-contracts.js';
 import { CLAWORLD_TOOL_CONTRACT_VERSION } from '../runtime/tool-inventory.js';
+import {
+  appendClaworldJournalEvent,
+  buildClaworldContextPointer,
+  buildClaworldToolMaintenanceEvent,
+  ensureClaworldWorkingMemory,
+} from '../runtime/working-memory.js';
 import { setClaworldRuntime } from './runtime.js';
 import {
   CHAT_REQUEST_APPROVAL_POLICY_MODES,
@@ -72,6 +79,74 @@ function buildClaworldStatusRoute(plugin) {
   };
 }
 
+function firstWorkspaceCandidate(...sources) {
+  for (const source of sources) {
+    if (!source || typeof source !== 'object') continue;
+    const candidates = [
+      source.workspaceRoot,
+      source.workspaceDir,
+      source.workspacePath,
+      source.workspace,
+      source.cwd,
+      source.agent?.workspaceRoot,
+      source.agent?.workspaceDir,
+      source.agent?.workspace,
+      source.context?.workspaceRoot,
+      source.context?.workspaceDir,
+      source.context?.workspace,
+      source.session?.workspaceRoot,
+      source.session?.workspaceDir,
+      source.session?.workspace,
+    ];
+    for (const candidate of candidates) {
+      const normalized = normalizeText(candidate, null);
+      if (normalized) return normalized;
+    }
+  }
+  return null;
+}
+
+async function resolveHookWorkspaceRoot(api, event = {}, ctx = {}) {
+  const directCandidate = firstWorkspaceCandidate(event, ctx);
+  if (directCandidate) return directCandidate;
+  const agentId = normalizeText(ctx?.agentId ?? event?.agentId, null);
+  if (!agentId) return null;
+  const cfg = await loadCurrentConfig(api);
+  const agentEntry = cfg?.agents?.list?.[agentId] || cfg?.agents?.[agentId] || null;
+  return firstWorkspaceCandidate(agentEntry);
+}
+
+function getHookLogger(api) {
+  return api?.logger || api?.runtime?.logger || console;
+}
+
+function parseHookToolPayload(result) {
+  if (!result || typeof result !== 'object') return null;
+  const text = Array.isArray(result.content)
+    ? result.content.find((entry) => entry?.type === 'text' && typeof entry.text === 'string')?.text
+    : null;
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function isSuccessfulHookToolCall(event = {}) {
+  if (event?.error || event?.isError === true) return false;
+  const result = event?.result ?? event?.output ?? event?.response ?? null;
+  if (result?.isError === true) return false;
+  const payload = parseHookToolPayload(result);
+  if (normalizeText(payload?.status, null) === 'error') return false;
+  return true;
+}
+
+function hookToolResult(event = {}) {
+  return event?.result ?? event?.output ?? event?.response ?? null;
+}
+
 const CHAT_INBOX_FILTER_DIRECTIONS = Object.freeze([
   'inbound',
   'outbound',
@@ -1331,6 +1406,65 @@ function buildRegisteredTools(api, plugin) {
         return buildToolResult(projectToolFeedbackSubmissionResponse(payload));
       },
     },
+    {
+      name: 'claworld_search_agents',
+      label: 'Claworld Search Agents',
+      description: 'World-external public profile discovery tool. Search discoverable Claworld accounts by public display name, public code, or account-level profile keywords before joining a world.',
+      metadata: buildToolMetadata({
+        category: 'social_discovery',
+        usageNotes: [
+          'Use this when the user wants to find a person outside world membership search.',
+          'This searches discoverable account-level public identity and profile text, not joined-world membership context.',
+          'Expected behavior: returns public profile summaries, active world previews, and direct request_chat follow-up payloads.',
+          'If the user already knows the exact target displayName + agentCode, you can skip this tool and call claworld_request_chat directly.',
+        ],
+        examples: [
+          {
+            title: 'Search outside worlds by profile keywords',
+            input: {
+              accountId: 'claworld',
+              query: '上海 慢节奏 介绍',
+              limit: 5,
+            },
+            outcome: 'Returns matching public profiles plus request_chat payloads for follow-up.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'World-external discoverable agent search payload.',
+        required: ['accountId', 'query'],
+        properties: {
+          accountId: accountIdProperty,
+          query: stringParam({
+            description: 'Required free-form search text. Best for public display name, public code, hobby, location, style, or account-level profile keywords.',
+            minLength: 1,
+            examples: ['上海 慢节奏 介绍', 'ZX82QP', 'running shanghai'],
+          }),
+          limit: integerParam({
+            description: 'Optional maximum number of profiles to return.',
+            minimum: 1,
+            maximum: 25,
+            examples: [5],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            query: '上海 慢节奏 介绍',
+            limit: 5,
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.searchAgents({
+          ...context,
+          query: params.query || null,
+          limit: params.limit ?? null,
+        });
+        return buildToolResult(projectToolSocialAgentSearchResponse(payload, { accountId: context.accountId }));
+      },
+    },
     {
       name: 'claworld_account',
       label: 'Claworld Account',
@@ -1573,6 +1707,21 @@ export function registerClaworldPluginFull(api, plugin) {
     throw new Error('registerClaworldPluginFull requires a plugin instance');
   }
   if (typeof api.on === 'function') {
+    api.on('before_prompt_build', async (event = {}, ctx = {}) => {
+      const logger = getHookLogger(api);
+      try {
+        const workspaceRoot = await resolveHookWorkspaceRoot(api, event, ctx);
+        if (workspaceRoot) {
+          await ensureClaworldWorkingMemory(workspaceRoot);
+        }
+      } catch (error) {
+        logger?.warn?.('[claworld:working-memory] unable to ensure workspace memory', error);
+      }
+      return {
+        appendSystemContext: buildClaworldContextPointer(),
+      };
+    });
+
     api.on('before_tool_call', async (event, ctx) => {
       if (event?.toolName !== 'claworld_request_chat') return;
       const requesterSessionKey = normalizeText(ctx?.sessionKey, null);
@@ -1584,6 +1733,27 @@ export function registerClaworldPluginFull(api, plugin) {
         },
       };
     });
+
+    api.on('after_tool_call', async (event = {}, ctx = {}) => {
+      if (!isSuccessfulHookToolCall(event)) return;
+      const toolName = normalizeText(event?.toolName ?? ctx?.toolName, null);
+      if (!toolName || !toolName.startsWith('claworld_')) return;
+      const logger = getHookLogger(api);
+      try {
+        const workspaceRoot = await resolveHookWorkspaceRoot(api, event, ctx);
+        if (!workspaceRoot) return;
+        const maintenanceEvent = buildClaworldToolMaintenanceEvent({
+          toolName,
+          params: event?.params || {},
+          result: hookToolResult(event),
+          timestamp: event?.timestamp || ctx?.timestamp || null,
+        });
+        if (!maintenanceEvent) return;
+        await appendClaworldJournalEvent(workspaceRoot, maintenanceEvent);
+      } catch (error) {
+        logger?.warn?.('[claworld:working-memory] unable to append tool event', error);
+      }
+    });
   }
   if (typeof api.registerHttpRoute === 'function') {
     api.registerHttpRoute(buildClaworldStatusRoute(plugin));

package/src/openclaw/runtime/product-shell-helper.js

@@ -517,6 +517,75 @@ export function normalizeWorldMemberSearchResponse(payload = {}, { accountId = n
   };
 }
 
+function normalizeSocialPublicProfile(profile = {}) {
+  return {
+    identity: normalizeText(profile.identity, null),
+    displayName: normalizeText(profile.displayName, null),
+    code: normalizeText(profile.code, null)?.toUpperCase() || null,
+    profile: normalizeText(profile.profile, null),
+    discoverable: typeof profile.discoverable === 'boolean' ? profile.discoverable : null,
+    contactable: typeof profile.contactable === 'boolean' ? profile.contactable : null,
+  };
+}
+
+function normalizeSocialActiveWorldItem(world = {}) {
+  return {
+    worldId: normalizeText(world.worldId, null),
+    displayName: normalizeText(world.displayName, null),
+    summary: normalizeText(world.summary, null),
+    category: normalizeText(world.category, null),
+  };
+}
+
+function normalizeSocialRequestChat(requestChat = null, publicProfile = {}) {
+  const candidate = requestChat && typeof requestChat === 'object' && !Array.isArray(requestChat)
+    ? requestChat
+    : {};
+  const displayName = normalizeText(candidate.displayName, normalizeText(publicProfile.displayName, null));
+  const agentCode = normalizeText(candidate.agentCode, normalizeText(publicProfile.code, null))?.toUpperCase() || null;
+  if (!displayName || !agentCode) return null;
+  return {
+    displayName,
+    agentCode,
+  };
+}
+
+function normalizeSocialAgentSearchItem(item = {}) {
+  const publicProfile = normalizeSocialPublicProfile(item.publicProfile || {});
+  const activeWorldItems = item.activeWorlds?.items && Array.isArray(item.activeWorlds.items)
+    ? item.activeWorlds.items.map((world) => normalizeSocialActiveWorldItem(world))
+    : [];
+
+  return {
+    publicProfile,
+    activeWorlds: {
+      totalCount: normalizeInteger(item.activeWorlds?.totalCount, activeWorldItems.length),
+      items: activeWorldItems,
+    },
+    requestChat: normalizeSocialRequestChat(item.requestChat, publicProfile),
+    score: normalizeInteger(item.score, 0),
+    matchedFieldIds: normalizeStringList(item.matchedFieldIds),
+    reasonSummary: normalizeText(item.reasonSummary, null),
+  };
+}
+
+export function normalizeSocialAgentSearchResponse(payload = {}, { accountId = null } = {}) {
+  const items = Array.isArray(payload.items)
+    ? payload.items.map((item) => normalizeSocialAgentSearchItem(item))
+    : [];
+
+  return {
+    status: normalizeText(payload.status, items.length > 0 ? 'search_ready' : 'no_matches'),
+    source: 'product_shell',
+    accountId: normalizeText(accountId, null),
+    query: normalizeText(payload.query, null),
+    limit: normalizeInteger(payload.limit, items.length > 0 ? items.length : 10),
+    totalMatches: normalizeInteger(payload.totalMatches, items.length),
+    nextAction: normalizeText(payload.nextAction, items.length > 0 ? 'review_profiles_or_request_chat' : 'refine_agent_search'),
+    items,
+  };
+}
+
 export function resolveWorldSelection(worldDirectory = {}, selection = null) {
   return resolveBackendWorldSelection(worldDirectory, selection);
 }
@@ -681,6 +750,56 @@ export async function searchWorlds({
   });
 }
 
+export async function searchAgents({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  query = null,
+  limit = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell social search helper');
+  }
+
+  const normalizedQuery = normalizeText(query, null);
+  if (!normalizedQuery) {
+    throw new Error('claworld product-shell social search helper requires query');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const searchResult = await fetchJson(fetchImpl, `${baseUrl}/v1/social/agents/search`, {
+    method: 'POST',
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+    }),
+    body: JSON.stringify({
+      query: normalizedQuery,
+      limit: limit == null ? null : normalizeInteger(limit, 0),
+    }),
+  });
+
+  if (!searchResult.ok) {
+    logger.error?.('[claworld:product-shell] social agent search failed', {
+      status: searchResult.status,
+      query: normalizedQuery,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: searchResult.body,
+    });
+    throw createProductShellHttpError('social_agent_search', searchResult, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+    });
+  }
+
+  return normalizeSocialAgentSearchResponse(searchResult.body, {
+    accountId: resolvedRuntimeConfig.accountId || accountId || null,
+  });
+}
+
 export async function joinWorld({
   cfg = {},
   accountId = null,

package/src/openclaw/runtime/tool-contracts.js

@@ -122,21 +122,21 @@ function projectRequestChatPayload(
   } = {},
 ) {
   if (!requestChat || typeof requestChat !== 'object' || Array.isArray(requestChat)) return null;
-  const worldId = normalizeText(requestChat.worldId, null);
   const displayName = normalizeText(requestChat.displayName, null);
   const agentCode = normalizeText(requestChat.agentCode, null)?.toUpperCase() || null;
-  if (!worldId || !displayName || !agentCode) return null;
+  const worldId = normalizeText(requestChat.worldId, null);
+  if (!displayName || !agentCode) return null;
 
   const normalizedAccountId = normalizeText(accountId, null);
 
   return {
-    worldId,
+    ...(worldId ? { worldId } : {}),
     displayName,
     agentCode,
     requestTool: normalizeText(requestToolName, null),
     requestPayload: {
       ...(normalizedAccountId ? { accountId: normalizedAccountId } : {}),
-      worldId,
+      ...(worldId ? { worldId } : {}),
       displayName,
       agentCode,
     },
@@ -675,6 +675,54 @@ export function projectToolWorldMemberSearchResponse(payload = {}, { accountId =
   };
 }
 
+function projectToolSocialActiveWorldSummary(world = {}) {
+  return {
+    worldId: normalizeText(world.worldId, null),
+    displayName: normalizeText(world.displayName, null),
+    summary: normalizeText(world.summary, null),
+    category: normalizeText(world.category, null),
+  };
+}
+
+function projectToolSocialPublicProfile(profile = {}) {
+  return {
+    identity: normalizeText(profile.identity, null),
+    displayName: normalizeText(profile.displayName, null),
+    code: normalizeText(profile.code, null)?.toUpperCase() || null,
+    profile: normalizeText(profile.profile, null),
+    discoverable: typeof profile.discoverable === 'boolean' ? profile.discoverable : null,
+    contactable: typeof profile.contactable === 'boolean' ? profile.contactable : null,
+  };
+}
+
+export function projectToolSocialAgentSearchResponse(payload = {}, { accountId = null } = {}) {
+  const items = Array.isArray(payload.items)
+    ? payload.items.map((item) => ({
+      publicProfile: projectToolSocialPublicProfile(item.publicProfile || {}),
+      activeWorlds: {
+        totalCount: normalizeInteger(item.activeWorlds?.totalCount, Array.isArray(item.activeWorlds?.items) ? item.activeWorlds.items.length : 0),
+        items: Array.isArray(item.activeWorlds?.items)
+          ? item.activeWorlds.items.map((world) => projectToolSocialActiveWorldSummary(world))
+          : [],
+      },
+      matchedFieldIds: normalizeStringList(item.matchedFieldIds),
+      reasonSummary: normalizeText(item.reasonSummary, null),
+      score: normalizeInteger(item.score, 0),
+      requestChat: projectRequestChatPayload(item.requestChat, { accountId }),
+    }))
+    : [];
+
+  return {
+    accountId: normalizeText(accountId, null),
+    status: normalizeText(payload.status, items.length > 0 ? 'search_ready' : 'no_matches'),
+    query: normalizeText(payload.query, null),
+    limit: normalizeInteger(payload.limit, items.length > 0 ? items.length : 10),
+    totalMatches: normalizeInteger(payload.totalMatches, items.length),
+    nextAction: normalizeText(payload.nextAction, items.length > 0 ? 'review_profiles_or_request_chat' : 'refine_agent_search'),
+    agents: items,
+  };
+}
+
 export function projectToolFeedbackSubmissionResponse(result = {}) {
   const feedback = result.feedback && typeof result.feedback === 'object' ? result.feedback : {};
   const reporter = feedback.reporter && typeof feedback.reporter === 'object' ? feedback.reporter : {};