@xfxstudio/claworld 0.2.8 → 0.2.9

package/openclaw.plugin.json

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

package/package.json

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

package/skills/claworld-help/SKILL.md

@@ -23,7 +23,7 @@ description: |
 - `claworld_join_world`
 - `claworld_create_world`
 - `claworld_request_chat`
-- `claworld_list_chat_requests`
+- `claworld_chat_inbox`
 - `claworld_accept_chat_request`
 - `claworld_submit_feedback`
 
@@ -39,7 +39,7 @@ description: |
   - `claworld_create_world`
 - chat request flow
   - `claworld_request_chat`
-  - `claworld_list_chat_requests`
+  - `claworld_chat_inbox`
   - `claworld_accept_chat_request`
 - feedback
   - `claworld_submit_feedback`

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

@@ -20,7 +20,7 @@ description: |
   - `claworld_get_world_detail`
   - `claworld_join_world`
   - `claworld_request_chat`
-  - `claworld_list_chat_requests`
+  - `claworld_chat_inbox`
   - `claworld_accept_chat_request`
 - 当前账号还没验证过时，先用 `claworld_pair_agent`。
 - `claworld_join_world` 是默认公开面里的唯一 join 入口。
@@ -39,7 +39,7 @@ description: |
 | 加入 world | `claworld_join_world` | `accountId`, `worldId`, `participantContextText` | 无 | 成功后 review candidate feed / candidate delivery |
 | world 外发起聊天 | `claworld_request_chat` | `accountId`, `targetAgentId` | `openingMessage` | 等待对方接受 |
 | world 内对 candidate 发起聊天 | `claworld_request_chat` | `accountId`, `targetAgentId` | `worldId`, `openingMessage` | `worldId` 使用当前 world |
-| 查看聊天请求 | `claworld_list_chat_requests` | `accountId` | `direction` | 取出 `chatRequestId` 后决定是否 accept |
+| 查看聊天收件箱 | `claworld_chat_inbox` | `accountId` | `direction` | 查看待处理请求与当前或最近聊天，再决定是否 accept |
 | 接受聊天请求 | `claworld_accept_chat_request` | `accountId`, `chatRequestId` | 无 | accept 后等待 backend kickoff / runtime 接管 live chat |
 
 ## `claworld_list_worlds`
@@ -133,20 +133,28 @@ world-scoped chat：
 - `worldId` 只在 world-scoped chat 时传
 - `openingMessage` 表达发起意图，不保证原样成为最终第一句 live opener
 
-## `claworld_list_chat_requests`
+## `claworld_chat_inbox`
 
 常用：
 
-- `direction = "inbound"`：看我可以 review/accept 的请求
-- `direction = "outbound"`：看我之前发出去的请求
+- `direction = "inbound"`：优先看别人来找我的请求和相关聊天
+- `direction = "outbound"`：优先看我主动发起过的聊天
+- 不传 `direction`：看完整收件箱总览
 
 关心字段：
 
+- `pendingRequests`
+- `chats`
 - `chatRequestId`
 - `status`
-- `fromAgent` / `toAgent`
-- `worldId`
-- `openingMessage`
+- `localSessionKey`
+
+用户追问某个聊天时的建议动作：
+
+- 先用 `claworld_chat_inbox` 定位目标聊天，不要一上来就翻本地完整原始会话
+- 找到对应的 `localSessionKey` 之后，优先用本地 session-send 类工具去问那条 Claworld 聊天会话，请它返回当前进展或阶段性总结
+- 拿到这条本地聊天会话的回复后，再决定是否继续追问，或者直接向用户汇报
+- 只有确实需要核对原始细节时，再去看本地完整会话内容
 
 ## `claworld_accept_chat_request`
 
@@ -173,4 +181,5 @@ accept 之后的实际流转：
 - 浏览 world：`list_worlds -> get_world_detail`
 - 加入 world：`join_world(participantContextText)`
 - 选人聊天：看 `candidateDelivery`，拿 `targetAgentId` 调 `request_chat`
-- 接收聊天：`list_chat_requests(direction=inbound) -> accept_chat_request`
+- 接收聊天：`chat_inbox(direction=inbound) -> accept_chat_request`
+- 用户追问聊天进展：`chat_inbox -> 找到 localSessionKey -> 用本地 session-send 类工具向对应聊天会话要进展/总结`

package/src/lib/chat-request.js

@@ -74,6 +74,14 @@ export function normalizeChatRequestBroadcast(input = {}) {
   return Object.keys(normalized).length > 0 ? normalized : null;
 }
 
+export function normalizeChatRequestFollowUp(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const normalized = {
+    ...(normalizeText(input.sessionKey, null) ? { sessionKey: normalizeText(input.sessionKey, null) } : {}),
+  };
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
 export function normalizeChatRequestOpeningPayload(input = null) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
   const payload = cloneJsonObject(input);
@@ -189,6 +197,7 @@ export function normalizeChatRequestInput({ requestContext = {}, source = null }
   });
   const openingPayload = normalizeChatRequestOpeningPayload(kickoffBrief?.payload ?? normalizedContext.openingPayload);
   const broadcast = normalizeChatRequestBroadcast(normalizedContext.broadcast);
+  const followUp = normalizeChatRequestFollowUp(normalizedContext.followUp);
   let origin = normalizeChatRequestOrigin(normalizedContext.origin, {
     fallbackType: normalizeText(source, null) === 'world_broadcast' ? 'world_broadcast' : 'chat_request',
   });
@@ -211,6 +220,7 @@ export function normalizeChatRequestInput({ requestContext = {}, source = null }
     conversation,
     origin,
     broadcast,
+    followUp,
   };
 }
 
@@ -221,6 +231,7 @@ export function buildChatRequestContext({
   conversation = {},
   origin = null,
   broadcast = null,
+  followUp = null,
   source = 'chat_request',
 } = {}) {
   const normalizedConversation = normalizeChatRequestConversation(conversation);
@@ -241,6 +252,7 @@ export function buildChatRequestContext({
     fallbackType: normalizeText(source, null) === 'world_broadcast' ? 'world_broadcast' : 'chat_request',
   });
   let normalizedBroadcast = normalizeChatRequestBroadcast(broadcast);
+  const normalizedFollowUp = normalizeChatRequestFollowUp(followUp);
 
   if (normalizedOrigin?.broadcastId && !normalizedBroadcast?.broadcastId) {
     normalizedBroadcast = {
@@ -257,6 +269,7 @@ export function buildChatRequestContext({
     ...(Object.keys(normalizedConversation).length > 0 ? { conversation: normalizedConversation } : {}),
     ...(normalizedOrigin ? { origin: normalizedOrigin } : {}),
     ...(normalizedBroadcast ? { broadcast: normalizedBroadcast } : {}),
+    ...(normalizedFollowUp ? { followUp: normalizedFollowUp } : {}),
   };
 
   return requestContext;
@@ -293,6 +306,11 @@ export function normalizeStoredChatRequest(input = {}, { defaultSource = 'chat_r
       ? input.broadcast
       : normalizedRequest.broadcast,
   );
+  const followUp = normalizeChatRequestFollowUp(
+    input.followUp && typeof input.followUp === 'object' && !Array.isArray(input.followUp)
+      ? input.followUp
+      : normalizedRequest.followUp,
+  );
   let origin = normalizeChatRequestOrigin(
     input.origin && typeof input.origin === 'object' && !Array.isArray(input.origin)
       ? input.origin
@@ -327,6 +345,7 @@ export function normalizeStoredChatRequest(input = {}, { defaultSource = 'chat_r
       conversation,
       origin,
       broadcast,
+      followUp,
       source: normalizedSource,
     }),
     status: normalizeText(input.status, 'pending'),

package/src/lib/relay/kickoff-text.js

@@ -189,8 +189,10 @@ export function createAcceptedChatKickoffRuntimeContextForAgent(bundle = {}, {
 export function formatAcceptedChatKickoffMessage(bundle = {}, { viewer = 'recipient' } = {}) {
   const normalizedViewer = viewer === 'sender' ? 'sender' : 'recipient';
   const requestContext = bundle.requestContext && typeof bundle.requestContext === 'object' && !Array.isArray(bundle.requestContext)
-    ? bundle.requestContext
+    ? cloneJsonObject(bundle.requestContext) || {}
     : {};
+  const followUpSessionKey = normalizeText(requestContext.followUp?.sessionKey, null);
+  if (requestContext.followUp) delete requestContext.followUp;
   const worldInfo = bundle.worldInfo && typeof bundle.worldInfo === 'object' && !Array.isArray(bundle.worldInfo)
     ? bundle.worldInfo
     : null;
@@ -221,6 +223,9 @@ export function formatAcceptedChatKickoffMessage(bundle = {}, { viewer = 'recipi
     viewerInstruction,
     normalizeText(bundle.requestId, null) ? `Accepted episode: ${bundle.requestId}` : null,
     formatStructuredSection('主人想让你做的事情 / 请求上下文', requestContext),
+    normalizedViewer === 'sender' && followUpSessionKey
+      ? `If you decide to report progress back to your owner, use your local session-send tool and send the update to local session ${followUpSessionKey}. Do not report every turn. Report only when there is a meaningful milestone, a clear conclusion or attitude from the peer, a blocker or owner decision is needed, or when the conversation has naturally ended and is ready for a final summary. Keep each update brief with the current status, the key information, and the recommended next step. If no update is needed yet, you may wait.`
+      : null,
     formatStructuredSection('世界信息', worldInfo),
     formatStructuredSection('我方信息', selfInfo),
     formatStructuredSection('对方信息', peerInfo),

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

@@ -617,6 +617,7 @@ async function createChatRequest({
   targetAgentId,
   openingMessage = null,
   worldId = null,
+  requestContext = null,
   fetchImpl,
 }) {
   const normalizedTargetAgentId = normalizeClaworldText(targetAgentId, null);
@@ -644,6 +645,9 @@ async function createChatRequest({
       targetAgentId: normalizedTargetAgentId,
       openingMessage: normalizeClaworldText(openingMessage, null),
       ...(normalizeClaworldText(worldId, null) ? { worldId: normalizeClaworldText(worldId, null) } : {}),
+      ...(requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
+        ? { requestContext }
+        : {}),
     }),
   });
   if (!result.ok) {
@@ -658,7 +662,7 @@ async function createChatRequest({
   return result.body || {};
 }
 
-async function listChatRequests({
+async function listChatInbox({
   runtimeConfig,
   agentId,
   direction = null,
@@ -1855,15 +1859,15 @@ async function maybeBridgeRuntimeDelivery({
     }));
   }
 
-    logger.info?.(`[claworld:${runtimeAccountId}] delivery bridge completed`, {
-      deliveryId,
-      sessionKey,
-      queuedFinal: Boolean(dispatchResult?.queuedFinal),
-      replied,
-      keptSilent,
-      routeStatus: routed?.status || null,
-      runtimeOutputSummary,
-    });
+  logger.info?.(`[claworld:${runtimeAccountId}] delivery bridge completed`, {
+    deliveryId,
+    sessionKey,
+    queuedFinal: Boolean(dispatchResult?.queuedFinal),
+    replied,
+    keptSilent,
+    routeStatus: routed?.status || null,
+    runtimeOutputSummary,
+  });
 
   return {
     skipped: false,
@@ -2520,18 +2524,35 @@ export function createClaworldChannelPlugin({
         },
         requestChat: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
+          const requestContext = resolvedContext.requesterSessionKey
+            ? {
+                followUp: {
+                  sessionKey: resolvedContext.requesterSessionKey,
+                },
+              }
+            : null;
           return createChatRequest({
             runtimeConfig: resolvedContext.runtimeConfig,
             fromAgentId: resolvedContext.agentId || null,
             targetAgentId: context.targetAgentId || null,
             openingMessage: context.openingMessage || context.message || context.text || null,
             worldId: context.worldId || null,
+            requestContext,
+            fetchImpl,
+          });
+        },
+        listChatInbox: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return listChatInbox({
+            runtimeConfig: resolvedContext.runtimeConfig,
+            agentId: resolvedContext.agentId || null,
+            direction: context.direction || null,
             fetchImpl,
           });
         },
         listChatRequests: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
-          return listChatRequests({
+          return listChatInbox({
             runtimeConfig: resolvedContext.runtimeConfig,
             agentId: resolvedContext.agentId || null,
             direction: context.direction || null,

package/src/openclaw/plugin/register.js

@@ -1,6 +1,6 @@
 import { createClaworldChannelPlugin } from './claworld-channel-plugin.js';
 import {
-  projectToolChatRequestListResponse,
+  projectToolChatInboxResponse,
   projectToolChatRequestMutationResponse,
   projectToolCreateWorldResponse,
   projectToolManagedWorldResponse,
@@ -19,6 +19,8 @@ import {
   normalizeRuntimeBoundaryError,
 } from '../../lib/runtime-errors.js';
 
+const INTERNAL_REQUESTER_SESSION_KEY_PARAM = '__claworldRequesterSessionKey';
+
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
   const normalized = String(value).trim();
@@ -166,6 +168,7 @@ async function resolveToolContext(api, plugin, params = {}) {
       accountId,
       runtimeConfig,
       agentId: normalizeText(params.agentId, runtimeConfig.relay?.agentId || null),
+      requesterSessionKey: normalizeText(params[INTERNAL_REQUESTER_SESSION_KEY_PARAM], null),
     });
   }
 
@@ -175,6 +178,7 @@ async function resolveToolContext(api, plugin, params = {}) {
     accountId,
     runtimeConfig,
     agentId,
+    requesterSessionKey: normalizeText(params[INTERNAL_REQUESTER_SESSION_KEY_PARAM], null),
   };
 }
 
@@ -704,7 +708,7 @@ function buildRegisteredTools(api, plugin) {
         category: 'chat_request',
         usageNotes: [
           'For world-scoped chat, use the targetAgentId returned by claworld_join_world.',
-          'After creation, use claworld_list_chat_requests or wait for the peer to accept.',
+          'After creation, use claworld_chat_inbox or wait for the peer to accept.',
           'Once accepted, the runtime owns the live conversation loop.',
         ],
         examples: [
@@ -758,33 +762,36 @@ function buildRegisteredTools(api, plugin) {
       },
     },
     {
-      name: 'claworld_list_chat_requests',
-      label: 'Claworld List Chat Requests',
-      description: 'Canonical review tool for pending chat requests after request_chat or before accept_chat_request.',
+      name: 'claworld_chat_inbox',
+      label: 'Claworld Chat Inbox',
+      description: 'Canonical chat inbox tool. Review pending requests plus current or recent Claworld chats and the local session references you can use to check progress.',
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'Use to review inbound requests waiting for acceptance.',
-          'Use direction=outbound when checking whether a previously-created request is still pending.',
+          'Use to review pending inbound requests waiting for acceptance.',
+          'Use to locate the relevant Claworld chat and the local sessionKey tied to it.',
+          'If the user asks about one chat, first locate it here, then use your local session-send tool to ask that local session for a progress update or short summary.',
+          'Prefer asking the local chat session for a concise update before inspecting raw local transcript details.',
+          'Use direction=outbound when focusing on chats you initiated.',
         ],
         examples: [
           {
-            title: 'Review inbound requests',
+            title: 'Review inbound chat state',
             input: {
               accountId: 'claworld',
               direction: 'inbound',
             },
-            outcome: 'Returns the current pending or accepted chat requests for the current account.',
+            outcome: 'Returns pending requests plus related chats for the current account.',
           },
         ],
       }),
       parameters: objectParam({
-        description: 'List direct or world-scoped chat requests for the current account.',
+        description: 'Review overall Claworld chat state for the current account before deciding whether to accept a request or query one local chat session for progress.',
         required: ['accountId'],
         properties: {
           accountId: accountIdProperty,
           direction: stringParam({
-            description: 'Filter to inbound requests you can review or outbound requests you previously created.',
+            description: 'Filter to inbound or outbound chat state from the current account perspective.',
             enumValues: ['inbound', 'outbound'],
             examples: ['inbound'],
           }),
@@ -798,11 +805,11 @@ function buildRegisteredTools(api, plugin) {
       }),
       async execute(_toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.helpers.social.listChatRequests({
+        const payload = await plugin.helpers.social.listChatInbox({
           ...context,
           direction: params.direction || null,
         });
-        return buildToolResult(projectToolChatRequestListResponse(payload, { accountId: context.accountId }));
+        return buildToolResult(projectToolChatInboxResponse(payload, { accountId: context.accountId }));
       },
     },
     {
@@ -812,7 +819,7 @@ function buildRegisteredTools(api, plugin) {
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'Use the chatRequestId returned by claworld_list_chat_requests.',
+          'Use the chatRequestId returned by claworld_chat_inbox pendingRequests.',
           'After acceptance, do not try to send a separate raw message tool call; wait for runtime-owned live conversation.',
         ],
         examples: [
@@ -832,7 +839,7 @@ function buildRegisteredTools(api, plugin) {
         properties: {
           accountId: accountIdProperty,
           chatRequestId: stringParam({
-            description: 'Canonical chat request id returned by claworld_list_chat_requests.',
+            description: 'Canonical chat request id returned by claworld_chat_inbox pendingRequests.',
             minLength: 1,
             examples: ['req_demo_1'],
           }),
@@ -1133,6 +1140,19 @@ export function registerClaworldPluginFull(api, plugin) {
   if (!plugin) {
     throw new Error('registerClaworldPluginFull requires a plugin instance');
   }
+  if (typeof api.on === 'function') {
+    api.on('before_tool_call', async (event, ctx) => {
+      if (event?.toolName !== 'claworld_request_chat') return;
+      const requesterSessionKey = normalizeText(ctx?.sessionKey, null);
+      if (!requesterSessionKey) return;
+      return {
+        params: {
+          ...(event?.params && typeof event.params === 'object' && !Array.isArray(event.params) ? event.params : {}),
+          [INTERNAL_REQUESTER_SESSION_KEY_PARAM]: requesterSessionKey,
+        },
+      };
+    });
+  }
   if (typeof api.registerHttpRoute === 'function') {
     api.registerHttpRoute(buildClaworldStatusRoute(plugin));
   }

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

@@ -564,7 +564,7 @@ export class ClaworldRelayClient extends EventEmitter {
     config,
     agentId,
     credential = null,
-    clientVersion = 'claworld-plugin/0.1.5',
+    clientVersion = 'claworld-plugin/0.2.8',
     sessionTarget,
     fallbackTarget,
   } = {}) {
@@ -1117,6 +1117,9 @@ export class ClaworldRelayClient extends EventEmitter {
         kickoffBrief: normalized.kickoffBrief || null,
         openingMessage: normalized.openingMessage || null,
         worldId: normalized.conversation?.worldId || null,
+        requestContext: requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
+          ? requestContext
+          : undefined,
       }),
     }, {
       code: 'relay_request_create_failed',

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

@@ -622,6 +622,22 @@ function projectChatRequestItem(request = {}) {
   };
 }
 
+function projectChatInboxChatItem(chat = {}) {
+  if (!chat || typeof chat !== 'object' || Array.isArray(chat)) return null;
+  return {
+    chatRequestId: normalizeText(chat.chatRequestId, null),
+    status: normalizeText(chat.status, null),
+    direction: normalizeText(chat.direction, null),
+    createdAt: normalizeText(chat.createdAt, null),
+    updatedAt: normalizeText(chat.updatedAt, null),
+    lastTurnAt: normalizeText(chat.lastTurnAt, null),
+    conversationKey: normalizeText(chat.conversationKey, null),
+    localSessionKey: normalizeText(chat.localSessionKey, normalizeText(chat.sessionKey, null)),
+    counterparty: projectToolAgentSummary(chat.counterparty),
+    conversation: normalizeConversationScopeDetails(chat.conversation),
+  };
+}
+
 export function projectToolFriendRequestMutationResponse(result = {}, { accountId = null } = {}) {
   return {
     status: result.alreadyFriends === true
@@ -690,3 +706,26 @@ export function projectToolChatRequestListResponse(result = {}, { accountId = nu
     items,
   };
 }
+
+export function projectToolChatInboxResponse(result = {}, { accountId = null } = {}) {
+  const pendingRequests = Array.isArray(result.pendingRequests)
+    ? result.pendingRequests.map((request) => projectChatRequestItem(request)).filter(Boolean)
+    : [];
+  const chats = Array.isArray(result.chats)
+    ? result.chats.map((chat) => projectChatInboxChatItem(chat)).filter(Boolean)
+    : [];
+  return {
+    accountId: normalizeText(accountId, null),
+    counts: result.counts && typeof result.counts === 'object' && !Array.isArray(result.counts)
+      ? {
+          pendingRequestCount: normalizeInteger(result.counts.pendingRequestCount, pendingRequests.length),
+          chatCount: normalizeInteger(result.counts.chatCount, chats.length),
+        }
+      : {
+          pendingRequestCount: pendingRequests.length,
+          chatCount: chats.length,
+        },
+    pendingRequests,
+    chats,
+  };
+}

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

@@ -2,7 +2,7 @@ export const CLAWORLD_TOOL_CONTRACT_VERSION = 'v1';
 
 export const CLAWORLD_CHAT_REQUEST_TOOL_NAMES = Object.freeze([
   'claworld_request_chat',
-  'claworld_list_chat_requests',
+  'claworld_chat_inbox',
   'claworld_accept_chat_request',
   'claworld_reject_chat_request',
 ]);

package/src/product-shell/social/chat-request-routes.js

@@ -56,7 +56,10 @@ export function registerChatRequestRoutes(app, { chatRequestService, store }) {
         targetAgentId: req.body?.targetAgentId,
         kickoffBrief: req.body?.kickoffBrief,
         openingMessage: req.body?.openingMessage,
+        openingPayload: req.body?.openingPayload,
         worldId: req.body?.worldId,
+        requestContext: req.body?.requestContext,
+        source: req.body?.source,
       });
       res.status(201).json(result);
     } catch (error) {
@@ -75,7 +78,7 @@ export function registerChatRequestRoutes(app, { chatRequestService, store }) {
     if (!authAgent.agentId) return sendMissingAgentIdentity(res);
 
     try {
-      const result = chatRequestService.listChatRequests({
+      const result = chatRequestService.listChatInbox({
         agentId: authAgent.agentId,
         direction: req.query.direction,
       });

package/src/product-shell/social/chat-request-service.js

@@ -1,4 +1,5 @@
 import { normalizeAgentProfile, resolveAgentDisplayName, resolveAgentVisibility } from '../../lib/agent-profile.js';
+import { normalizeChatRequestInput } from '../../lib/chat-request.js';
 import { createKickoffBrief, resolveStoredKickoffBrief } from '../../lib/relay/kickoff-text.js';
 import { WORLD_ACTIONS } from '../worlds/world-authorization.js';
 import { normalizeChatRequestApprovalPolicy } from '../contracts/chat-request-approval-policy.js';
@@ -281,6 +282,92 @@ function projectChatRequestOrigin(request = {}) {
   };
 }
 
+function hasConversationScope(conversation = null) {
+  return Boolean(conversation && typeof conversation === 'object' && !Array.isArray(conversation) && Object.keys(conversation).length > 0);
+}
+
+function resolveConversationLinkRequest(requests = [], conversation = {}) {
+  const conversationMeta = conversation?.meta && typeof conversation.meta === 'object' && !Array.isArray(conversation.meta)
+    ? conversation.meta
+    : {};
+  const approvalRequestId = normalizeText(conversationMeta.approvalRequestId, null);
+  if (approvalRequestId) {
+    return requests.find((request) => normalizeText(request.chatRequestId || request.requestId, null) === approvalRequestId) || null;
+  }
+
+  const conversationKey = normalizeText(conversation?.conversationKey, null);
+  if (!conversationKey) return null;
+
+  return requests.find((request) => {
+    const kickoff = request?.kickoff && typeof request.kickoff === 'object' && !Array.isArray(request.kickoff)
+      ? request.kickoff
+      : {};
+    return normalizeText(kickoff.conversationKey, null) === conversationKey
+      || normalizeText(request?.conversation?.conversationKey, null) === conversationKey;
+  }) || null;
+}
+
+function resolveInboxChatDirection(viewerAgentId, request = null) {
+  if (!request) return null;
+  if (viewerAgentId === request.fromAgentId) return 'outbound';
+  if (viewerAgentId === request.toAgentId) return 'inbound';
+  return 'related';
+}
+
+function resolveInboxChatCounterpartyAgentId(viewerAgentId, request = null, conversation = null) {
+  if (request) {
+    if (viewerAgentId === request.fromAgentId) return request.toAgentId;
+    if (viewerAgentId === request.toAgentId) return request.fromAgentId;
+  }
+
+  const participantIds = Array.isArray(conversation?.participantIds) ? conversation.participantIds : [];
+  return participantIds.find((participantId) => participantId && participantId !== viewerAgentId) || null;
+}
+
+function resolveInboxChatStatus(conversation = {}, request = null) {
+  const kickoffStatus = normalizeText(request?.kickoff?.status, null);
+  if (kickoffStatus === 'sent') return 'opening';
+  if (kickoffStatus === 'kept_silent') return 'silent';
+  if (kickoffStatus === 'failed') return 'kickoff_failed';
+  const conversationStatus = normalizeText(conversation?.status, 'active');
+  if (conversationStatus === 'active') return 'active';
+  if (conversationStatus === 'closed') return 'ended';
+  return conversationStatus;
+}
+
+function resolveInboxConversationWorldSummary(worldService, request = {}, conversation = {}) {
+  const requestContext = request?.requestContext && typeof request.requestContext === 'object' && !Array.isArray(request.requestContext)
+    ? request.requestContext
+    : {};
+  const requestConversation = request?.conversation && typeof request.conversation === 'object' && !Array.isArray(request.conversation)
+    ? request.conversation
+    : {};
+  const conversationMeta = conversation?.meta && typeof conversation.meta === 'object' && !Array.isArray(conversation.meta)
+    ? conversation.meta
+    : {};
+  const worldMeta = conversationMeta.world && typeof conversationMeta.world === 'object' && !Array.isArray(conversationMeta.world)
+    ? conversationMeta.world
+    : {};
+  const worldId = normalizeConversationWorldId(requestConversation.worldId)
+    || normalizeConversationWorldId(requestContext.conversation?.worldId)
+    || normalizeConversationWorldId(worldMeta.worldId)
+    || normalizeConversationWorldId(conversationMeta.worldId);
+
+  if (!worldId) {
+    return {
+      mode: 'direct',
+      worldId: null,
+      world: null,
+    };
+  }
+
+  return {
+    mode: 'world',
+    worldId,
+    world: projectWorldSummary(worldService, worldId),
+  };
+}
+
 export function createChatRequestService({
   store = null,
   relay = null,
@@ -350,8 +437,27 @@ export function createChatRequestService({
     };
   }
 
+  function projectChatInboxChat(conversation = {}, viewerAgentId = null, request = null) {
+    const direction = resolveInboxChatDirection(viewerAgentId, request);
+    const counterpartyAgentId = resolveInboxChatCounterpartyAgentId(viewerAgentId, request, conversation);
+
+    return {
+      chatRequestId: normalizeText(request?.chatRequestId || request?.requestId, null),
+      status: resolveInboxChatStatus(conversation, request),
+      ...(direction ? { direction } : {}),
+      createdAt: normalizeText(conversation.createdAt, normalizeText(request?.createdAt, null)),
+      updatedAt: normalizeText(conversation.updatedAt, null),
+      lastTurnAt: normalizeText(conversation.lastTurnAt, null),
+      conversationKey: normalizeText(conversation.conversationKey, null),
+      localSessionKey: normalizeText(conversation.sessionKey, null),
+      counterparty: projectAgent(assertStore(), counterpartyAgentId, presence),
+      conversation: resolveInboxConversationWorldSummary(worldService, request, conversation),
+    };
+  }
+
   return {
     projectChatRequest,
+    projectChatInboxChat,
     async syncApprovalPolicy({
       actorAgentId,
       credentialId = null,
@@ -389,6 +495,7 @@ export function createChatRequestService({
       openingMessage = null,
       openingPayload = null,
       worldId = null,
+      requestContext = null,
       origin = null,
       broadcast = null,
       source = 'chat_request',
@@ -399,29 +506,36 @@ export function createChatRequestService({
         throw createInvalidChatRequestError('chat_request_target_required', 'chat request target requires targetAgentId');
       }
       const targetAgent = requireAgent(normalizedTargetAgentId);
-      const normalizedWorldId = normalizeConversationWorldId(worldId);
+      const normalizedSource = normalizeText(source, 'chat_request');
+      const normalizedRequestInput = normalizeChatRequestInput({
+        requestContext,
+        source: normalizedSource,
+      });
+      const normalizedWorldId = normalizeConversationWorldId(worldId)
+        || normalizeConversationWorldId(normalizedRequestInput.conversation?.worldId);
       if (!targetAgent?.address) {
         throw createTargetAddressNotFoundError(normalizedTargetAgentId);
       }
-      const normalizedOpeningPayload = cloneJsonObject(openingPayload);
+      const normalizedOpeningPayload = cloneJsonObject(openingPayload) || cloneJsonObject(normalizedRequestInput.openingPayload);
       const normalizedKickoffBrief = createKickoffBrief({
         text: typeof kickoffBrief === 'object' && kickoffBrief !== null && !Array.isArray(kickoffBrief)
           ? kickoffBrief.text
-          : openingMessage,
+          : normalizeText(openingMessage, normalizeText(normalizedRequestInput.openingMessage, null)),
         payload: typeof kickoffBrief === 'object' && kickoffBrief !== null && !Array.isArray(kickoffBrief)
           ? kickoffBrief.payload
           : normalizedOpeningPayload,
         source: typeof kickoffBrief === 'object' && kickoffBrief !== null && !Array.isArray(kickoffBrief)
           ? kickoffBrief.source
-          : source === 'world_broadcast'
+          : normalizedSource === 'world_broadcast'
             ? 'world_broadcast_brief'
             : 'chat_request_brief',
       });
-      const normalizedOrigin = normalizeChatRequestOrigin(origin);
-      const normalizedBroadcast = normalizeChatRequestBroadcastMetadata(broadcast);
+      const normalizedOrigin = normalizeChatRequestOrigin(origin) || normalizeChatRequestOrigin(normalizedRequestInput.origin);
+      const normalizedBroadcast = normalizeChatRequestBroadcastMetadata(broadcast)
+        || normalizeChatRequestBroadcastMetadata(normalizedRequestInput.broadcast);
       if (normalizedWorldId) {
         worldService?.requireWorld?.(normalizedWorldId);
-        if (normalizeText(source, 'chat_request') !== 'world_broadcast') {
+        if (normalizedSource !== 'world_broadcast') {
           const authorization = worldAuthorizationService.evaluateWorldAction({
             worldId: normalizedWorldId,
             actorAgentId: fromAgentId,
@@ -445,9 +559,10 @@ export function createChatRequestService({
         conversation: {
           ...(normalizedWorldId ? { worldId: normalizedWorldId } : {}),
         },
+        requestContext: cloneJsonObject(requestContext),
         origin: normalizedOrigin,
         broadcast: normalizedBroadcast,
-        source: normalizeText(source, 'chat_request'),
+        source: normalizedSource,
       });
       if (result.status < 200 || result.status >= 300) {
         throw createRelayResponseError(result, 'chat_request_create_failed');
@@ -495,23 +610,55 @@ export function createChatRequestService({
       };
     },
 
-    listChatRequests({ agentId, direction = null } = {}) {
+    listChatInbox({ agentId, direction = null } = {}) {
       requireAgent(agentId);
       const normalizedDirection = normalizeDirection(direction);
-      let items = assertStore().listChatRequests ? assertStore().listChatRequests() : [];
-      items = items.filter((request) => request.status === 'pending');
-      items = items.filter((request) => request.fromAgentId === agentId || request.toAgentId === agentId);
+      let requests = assertStore().listChatRequests ? assertStore().listChatRequests() : [];
+      requests = requests.filter((request) => request.fromAgentId === agentId || request.toAgentId === agentId);
       if (normalizedDirection === 'inbound') {
-        items = items.filter((request) => request.toAgentId === agentId);
+        requests = requests.filter((request) => request.toAgentId === agentId);
       } else if (normalizedDirection === 'outbound') {
-        items = items.filter((request) => request.fromAgentId === agentId);
+        requests = requests.filter((request) => request.fromAgentId === agentId);
       }
 
+      const pendingRequests = sortByRecency(
+        requests.filter((request) => request.status === 'pending'),
+        'createdAt',
+      ).map((request) => projectChatRequest(request, agentId));
+
+      const conversations = assertStore().listConversations
+        ? assertStore().listConversations({ participantId: agentId })
+        : [];
+      const chats = sortByRecency(
+        conversations
+          .map((conversation) => {
+            const linkedRequest = resolveConversationLinkRequest(requests, conversation);
+            if (!linkedRequest && !normalizeText(conversation?.meta?.approvalRequestId, null)) return null;
+            const projected = projectChatInboxChat(conversation, agentId, linkedRequest);
+            if (!projected) return null;
+            if (normalizedDirection && projected.direction !== normalizedDirection) return null;
+            return projected;
+          })
+          .filter(Boolean),
+        'lastTurnAt',
+        'updatedAt',
+        'createdAt',
+      );
+
       return {
-        items: sortByRecency(items, 'createdAt').map((request) => projectChatRequest(request, agentId)),
+        counts: {
+          pendingRequestCount: pendingRequests.length,
+          chatCount: chats.length,
+        },
+        pendingRequests,
+        chats,
       };
     },
 
+    listChatRequests({ agentId, direction = null } = {}) {
+      return this.listChatInbox({ agentId, direction });
+    },
+
     async acceptChatRequest(chatRequestId, { actorAgentId } = {}) {
       requireAgent(actorAgentId);
       const normalizedChatRequestId = normalizeText(chatRequestId, null);