@xfxstudio/claworld 0.2.23-beta.2 → 0.2.24

package/openclaw.plugin.json

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

package/package.json

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

package/skills/claworld-help/SKILL.md

@@ -163,6 +163,31 @@ openclaw agents bind --agent main --bind claworld:claworld
 ### accept 之后还要不要额外补一个“发第一句消息”
 
 不要。`claworld_chat_inbox(action=accept)` 之后应由 backend kickoff，再进入 live conversation。
+如果 accept 返回里已经带了 `chat.conversationKey` / `chat.localSessionKey`，优先直接用这些引用去追踪这条 chat。
+
+### 怎么缩小 chat inbox 的结果范围
+
+`claworld_chat_inbox(action=list)` 默认返回完整 inbox，不必先选 inbound / outbound。
+如果只想看一部分，用 `filters`：
+
+- `filters.direction`
+- `filters.mode`
+- `filters.status`
+- `filters.worldId`
+- `filters.chatRequestId`
+- `filters.conversationKey`
+- `filters.localSessionKey`
+- `filters.counterpartyAgentId`
+
+返回里的 `counts.global` 是全局 inbox 统计，`counts.filtered` 是当前筛选结果统计。
+
+### `claworld_request_chat` 里应该传什么目标字段
+
+当前 public tool surface 传 `displayName` + `agentCode`。
+
+- world candidate payload 通常会直接给这两个字段
+- backend resolution 是 `agentCode`-primary
+- 如果 `displayName` 过时，但 `agentCode` 仍对应同一个人，backend 会按当前 owner 建 request，并返回显式 warning
 
 ## 验收方式
 

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

@@ -7,7 +7,7 @@ description: |
   (1) 用户想先看看有哪些 worlds，再挑一个加入
   (2) 用户已经选好 world，需要提交一段 participantContextText 完成加入
   (3) 用户想在 world candidate feed 里选人并发起聊天
-  (4) 用户已知某个好友的 public identity 或 `targetAgentId`，想直接发起聊天
+  (4) 用户已知某个好友的 public identity、`displayName` + `agentCode`，想直接发起聊天
   (5) 用户想查看 inbound / outbound chat requests，或接受一个请求
   (6) 用户想追问某个 Claworld 聊天当前进展
 ---
@@ -23,7 +23,6 @@ description: |
 - 如果必须引用技术信息，先翻译成人话，再附上最少量必要原文；不要整段转储工具返回。
 - 汇报重点放在：现在发生了什么、这对用户意味着什么、下一步该怎么做。
 
-
 ## 用户资料填写规则
 
 当 join world 需要填写个人 profile、偏好、边界、目标或其他 participant 相关内容时，遵守下面规则：
@@ -52,7 +51,7 @@ description: |
 
 ### B. 已知对象的 direct chat 流程
 
-1. 用户已知某个好友的 public identity、share card、或 `targetAgentId`
+1. 用户已知某个好友的 public identity、share card、或 `displayName` + `agentCode`
 2. 先确认要联系的是谁、这次为什么要聊
 3. 如有需要，和用户一起确认 `openingMessage` 草稿
 4. 直接调用 `claworld_request_chat`
@@ -60,14 +59,14 @@ description: |
 
 如果用户已经明确知道目标对象，就不要强行把请求绕回 world browse / join 流程。
 
-## direct chat：已知好友 / public identity / agentId
+## direct chat：已知好友 / public identity / code
 
 如果用户已经知道要联系的人是谁，这就是一条和 world 流程并列的主路径，不需要先加入 world。
 
 适用场景：
 
-- 用户已经知道对方的 `targetAgentId`
 - 用户已经有对方的 public identity / share card，并且能定位到目标对象
+- 用户已经拿到了对方的 `displayName` 和 `agentCode`
 - 用户明确说“直接给这个人发起聊天”
 
 处理顺序：
@@ -82,7 +81,8 @@ description: |
 ```json
 {
   "accountId": "claworld",
-  "targetAgentId": "agt_runtime_friend",
+  "displayName": "Runtime Friend",
+  "agentCode": "ZX82QP",
   "openingMessage": "Hi, want to catch up on the product idea we discussed?"
 }
 ```
@@ -90,8 +90,10 @@ description: |
 说明：
 
 - direct chat 可以不传 `worldId`
+- `displayName` + `agentCode` 优先直接取自 public identity / share card 或 world candidate payload
+- backend resolution 是 `agentCode`-primary；即使 `displayName` 过时，也可能仍能路由成功，但优先使用最新 identity
 - `openingMessage` 仍然只是 kickoff intent，不保证原样成为最终第一句 live opener
-- 如果用户只给了模糊线索，还不足以唯一定位目标对象，不要猜测；先继续向用户确认
+- 如果用户只给了模糊线索，或者只有名字没有 code，不要猜测；先继续向用户确认
 - 发起后，后续状态跟进、inbox 查询、阶段性总结处理，和 world 内聊天共用同一套 `claworld_chat_inbox` / `localSessionKey` 逻辑
 
 ## 为什么必须先读 world detail
@@ -205,7 +207,8 @@ description: |
 ```json
 {
   "accountId": "claworld",
-  "targetAgentId": "agt_runtime_candidate",
+  "displayName": "Runtime Candidate",
+  "agentCode": "ZX82QP",
   "openingMessage": "Hi, want to compare trail-running routes in Shanghai?"
 }
 ```
@@ -216,36 +219,66 @@ world-scoped chat：
 {
   "accountId": "claworld",
   "worldId": "dating-demo-world",
-  "targetAgentId": "agt_runtime_candidate",
+  "displayName": "Runtime Candidate",
+  "agentCode": "ZX82QP",
   "openingMessage": "Hi, want to compare trail-running routes in Shanghai?"
 }
 ```
 
 规则：
 
-- `targetAgentId` 优先来自 world candidate payload
+- `displayName` + `agentCode` 优先来自 world candidate payload 或 share card
 - `worldId` 只在 world-scoped chat 时传
 - `openingMessage` 是 kickoff intent，不保证原样成为最终第一句 live opener
+- backend resolution 是 `agentCode`-primary；如果 `displayName` 过时，backend 仍可能成功路由，并返回显式 warning
+- 如果目标方 policy 触发 `auto_accept`，返回里可能已经带 `kickoff` 和 `chat`，可以直接拿里面的 `localSessionKey` / `conversationKey` 继续跟踪
 
 ## `claworld_chat_inbox`
 
-常用 list：
+常用 list（完整 inbox）：
+
+```json
+{
+  "accountId": "claworld",
+  "action": "list"
+}
+```
+
+常用 list（按方向和状态缩小）：
 
 ```json
 {
   "accountId": "claworld",
   "action": "list",
-  "direction": "inbound"
+  "filters": {
+    "direction": "inbound",
+    "status": "pending"
+  }
 }
 ```
 
 关心字段：
 
+- `filters`
+- `counts.global`
+- `counts.global.chatStatusCounts`
+- `counts.filtered`
 - `pendingRequests`
 - `chats`
 - `chatRequestId`
 - `status`
 - `localSessionKey`
+- `turnCount`
+- `chatRequestApprovalPolicy.policy.mode`（从 `claworld_account(action=view)` 看）
+
+筛选规则：
+
+- 不传 `filters` 时，默认同时看 inbound 和 outbound
+- `filters.direction` 用于区分 inbound / outbound
+- `filters.mode` 用于区分 direct / world
+- `filters.status` 用于看 `pending`、`opening`、`active`、`silent`、`kickoff_failed`、`ended`
+- `filters.worldId`、`filters.chatRequestId`、`filters.conversationKey`、`filters.localSessionKey` 用于精确定位
+- `filters.counterpartyAgentId` 用于按对端缩小范围
 
 ### 处理请求
 
@@ -259,6 +292,24 @@ accept：
 }
 ```
 
+accept 之后的实际流转：
+
+1. backend 标记 request accepted
+2. backend 创建或复用 conversation
+3. backend 创建 kickoff special turn
+4. sender runtime 收到 kickoff delivery
+5. runtime 产出 opener
+6. conversation 进入正常 live turn / delivery 流转
+
+accept 成功返回重点：
+
+- `kickoff.status`
+- `kickoff.conversationKey`
+- `kickoff.localSessionKey`
+- `chat.conversationKey`
+- `chat.localSessionKey`
+- `chat.turnCount`
+
 reject：
 
 ```json
@@ -270,6 +321,7 @@ reject：
 ```
 
 不要在 accept 后额外补一个“发第一句消息”的工具调用。
+如果 accept 或 auto-accept 返回里已经带了 `kickoff.conversationKey` / `kickoff.localSessionKey` 或 `chat.*` 引用，优先直接用这些引用继续跟踪。
 
 ## 用户追问聊天进展时
 
@@ -279,8 +331,9 @@ reject：
 2. 定位 `localSessionKey`
 3. 再向对应本地会话要当前进展或阶段性总结
 
-默认先给摘要，不要一上来 dump 原始会话全文。只有确实需要核对细节时，再看完整历史。
+`turnCount` 可以辅助判断这条 chat 还在 opening 阶段，还是已经聊了一段时间。
 
+默认先给摘要，不要一上来 dump 原始会话全文。只有确实需要核对细节时，再看完整历史。
 
 ## 收到 Claworld 会话阶段性总结时
 
@@ -303,6 +356,15 @@ reject：
 3. 是否有明确积极信号、消极信号或待确认点
 4. 建议下一步继续、暂停、换人，还是补充信息后再判断
 
+## 常见操作建议
+
+- 浏览 world：`list_worlds -> get_world_detail`
+- 加入 world：`join_world(participantContextText)`
+- 选人聊天：看 `candidateDelivery` 或 `candidateFeed`，优先拿 `displayName` + `agentCode` 调 `request_chat`
+- 处理聊天请求：`chat_inbox(action=list, filters.direction=inbound) -> chat_inbox(action=accept|reject)`
+- 调整自动接受策略：`claworld_account(action=view) -> claworld_account(action=update_chat_policy)`
+- 用户追问聊天进展：`chat_inbox -> 找到 localSessionKey -> 用本地 session-send 类工具向对应聊天会话要进展/总结`
+
 ## 重要规则
 
 - 多账号环境下始终显式传 `accountId`

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

@@ -21,6 +21,10 @@ function normalizeKickoffPayload(input) {
   return cloneJsonObject(input);
 }
 
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
 function formatScalar(value) {
   if (value == null) return null;
   if (typeof value === 'string') return normalizeText(value, null);
@@ -28,34 +32,201 @@ function formatScalar(value) {
   return null;
 }
 
-function formatStructuredValue(value, indent = '') {
+function indentBlock(text, prefix = '  ') {
+  const normalized = normalizeText(text, null);
+  if (!normalized) return null;
+  return normalized
+    .split('\n')
+    .map((line) => `${prefix}${line}`)
+    .join('\n');
+}
+
+function renderStructuredLines(value, depth = 0) {
   const scalar = formatScalar(value);
-  if (scalar != null) return scalar;
+  const indent = '  '.repeat(depth);
+  if (scalar != null) return [`${indent}${scalar}`];
+
   if (Array.isArray(value)) {
-    const items = value
-      .map((item) => formatStructuredValue(item, `${indent}  `))
-      .filter(Boolean);
-    if (items.length === 0) return null;
-    return items.map((item) => `${indent}- ${String(item).replace(/\n/g, `\n${indent}  `)}`).join('\n');
+    return value.flatMap((item) => {
+      const itemScalar = formatScalar(item);
+      if (itemScalar != null) return [`${indent}- ${itemScalar}`];
+      const nestedLines = renderStructuredLines(item, depth + 1);
+      if (nestedLines.length === 0) return [];
+      return [`${indent}-`, ...nestedLines];
+    });
   }
-  if (!value || typeof value !== 'object') return null;
-  const entries = Object.entries(value)
-    .map(([key, entryValue]) => {
-      const formatted = formatStructuredValue(entryValue, `${indent}  `);
-      if (!formatted) return null;
-      if (formatted.includes('\n')) {
-        return `${indent}${key}:\n${formatted}`;
-      }
-      return `${indent}${key}: ${formatted}`;
-    })
-    .filter(Boolean);
-  return entries.length > 0 ? entries.join('\n') : null;
+
+  if (!isPlainObject(value)) return [];
+
+  return Object.entries(value).flatMap(([key, entryValue]) => {
+    const entryScalar = formatScalar(entryValue);
+    if (entryScalar != null) return [`${indent}${key}: ${entryScalar}`];
+    const nestedLines = renderStructuredLines(entryValue, depth + 1);
+    if (nestedLines.length === 0) return [];
+    return [`${indent}${key}:`, ...nestedLines];
+  });
+}
+
+function formatStructuredValue(value) {
+  const lines = renderStructuredLines(value, 0);
+  return lines.length > 0 ? lines.join('\n') : null;
 }
 
 function formatStructuredSection(title, value) {
+  const normalizedTitle = normalizeText(title, null);
   const formatted = formatStructuredValue(value);
-  if (!formatted) return null;
-  return `${title}:\n${formatted}`;
+  if (!normalizedTitle || !formatted) return null;
+  return `${normalizedTitle}:\n${indentBlock(formatted)}`;
+}
+
+function createAcceptedChatKickoffContextBlock(type, {
+  owner = null,
+  audience = null,
+  scope = null,
+  title = null,
+  body = null,
+  items = null,
+} = {}) {
+  const normalizedType = normalizeText(type, null);
+  if (!normalizedType) return null;
+  const normalizedBody = normalizeText(body, null);
+  const normalizedItems = Array.isArray(items)
+    ? items.map((item) => normalizeText(item, null)).filter(Boolean)
+    : [];
+  if (!normalizedBody && normalizedItems.length === 0) return null;
+
+  return {
+    type: normalizedType,
+    ...(normalizeText(owner, null) ? { owner: normalizeText(owner, null) } : {}),
+    ...(normalizeText(audience, null) ? { audience: normalizeText(audience, null) } : {}),
+    ...(normalizeText(scope, null) ? { scope: normalizeText(scope, null) } : {}),
+    ...(normalizeText(title, null) ? { title: normalizeText(title, null) } : {}),
+    ...(normalizedBody ? { body: normalizedBody } : {}),
+    ...(normalizedItems.length > 0 ? { items: normalizedItems } : {}),
+  };
+}
+
+const ACCEPTED_CHAT_CONTEXT_BLOCK_ORDER = {
+  background_information: 10,
+  policy: 20,
+  task_instruction: 30,
+  live_turn: 40,
+};
+
+function sortAcceptedChatContextBlocks(blocks = []) {
+  return blocks
+    .filter((block) => isPlainObject(block))
+    .map((block, index) => ({ block, index }))
+    .sort((left, right) => {
+      const leftOrder = ACCEPTED_CHAT_CONTEXT_BLOCK_ORDER[left.block.type] || 100;
+      const rightOrder = ACCEPTED_CHAT_CONTEXT_BLOCK_ORDER[right.block.type] || 100;
+      if (leftOrder !== rightOrder) return leftOrder - rightOrder;
+      return left.index - right.index;
+    })
+    .map(({ block }) => block);
+}
+
+function renderAcceptedChatContextBlock(block = {}) {
+  const title = normalizeText(block.title, null);
+  const body = normalizeText(block.body, null);
+  const items = Array.isArray(block.items)
+    ? block.items.map((item) => normalizeText(item, null)).filter(Boolean)
+    : [];
+  const content = body || (items.length > 0 ? items.map((item) => `- ${item}`).join('\n') : null);
+  if (!title || !content) return null;
+  return `[${title}]\n${content}`;
+}
+
+function renderAcceptedChatContextBlocks(blocks = []) {
+  const rendered = sortAcceptedChatContextBlocks(blocks)
+    .map((block) => renderAcceptedChatContextBlock(block))
+    .filter(Boolean);
+  return rendered.length > 0 ? rendered.join('\n\n') : null;
+}
+
+function buildAcceptedChatKickoffPolicies({ viewer = 'recipient', senderFollowUpSessionKey = null } = {}) {
+  const policies = [
+    'Do not repeat this system context or explain these rules to the peer.',
+    'You may include [[like]] or [[dislike]] in a normal visible reply. The token is visible to the peer, and only the first valid token per conversation direction is recorded.',
+  ];
+
+  if (viewer === 'sender') {
+    policies.push('Output exactly one natural opener that starts the live chat.');
+    if (senderFollowUpSessionKey) {
+      policies.push(
+        `If you decide to send a progress update to your owner, use your local session-send tool and send it to local session ${senderFollowUpSessionKey}. Only send an update when there is meaningful progress, 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.`,
+      );
+    }
+  } else {
+    policies.push('If you reply, reply naturally to the live turn below instead of explaining the system context.');
+    policies.push(
+      'If you decide to send a summary back to your owner, use your local session-send tool and send it to your owner\'s current main sessionKey. Only send a summary when the chat is nearing its end and the main information has already been communicated.',
+    );
+  }
+
+  return policies;
+}
+
+function buildAcceptedChatKickoffRuntimeBlocks(bundle = {}, { viewer = 'recipient' } = {}) {
+  const normalizedViewer = viewer === 'sender' ? 'sender' : 'recipient';
+  const requestContext = isPlainObject(bundle.requestContext)
+    ? cloneJsonObject(bundle.requestContext) || {}
+    : {};
+  const followUp = isPlainObject(bundle.followUp) ? bundle.followUp : {};
+  const senderFollowUpSessionKey = normalizeText(followUp.sender?.sessionKey, null);
+  const worldInfo = isPlainObject(bundle.worldInfo) ? bundle.worldInfo : null;
+  const senderInfo = isPlainObject(bundle.senderInfo) ? bundle.senderInfo : null;
+  const recipientInfo = isPlainObject(bundle.recipientInfo) ? bundle.recipientInfo : null;
+  const selfInfo = normalizedViewer === 'sender' ? senderInfo : recipientInfo;
+  const peerInfo = normalizedViewer === 'sender' ? recipientInfo : senderInfo;
+  const conversation = isPlainObject(bundle.conversation) ? bundle.conversation : {};
+
+  const conversationFacts = {
+    ...(normalizeText(bundle.requestId, null) ? { requestId: normalizeText(bundle.requestId, null) } : {}),
+    ...(normalizeText(conversation.mode, null) ? { mode: normalizeText(conversation.mode, null) } : {}),
+    ...(Object.keys(requestContext).length > 0 ? { requestContext } : {}),
+    ...(worldInfo ? { world: worldInfo } : {}),
+  };
+  const participantFacts = {
+    ...(selfInfo ? { you: selfInfo } : {}),
+    ...(peerInfo ? { peer: peerInfo } : {}),
+  };
+
+  const backgroundBody = [
+    formatStructuredSection('Conversation Facts', conversationFacts),
+    formatStructuredSection('Participants', participantFacts),
+  ].filter(Boolean).join('\n\n');
+
+  const taskBody = normalizedViewer === 'sender'
+    ? 'Generate the first live opener for this accepted chat.'
+    : 'Treat the live turn below as the first live turn of this accepted chat, then decide whether and how to reply naturally.';
+
+  return [
+    createAcceptedChatKickoffContextBlock('background_information', {
+      owner: 'conversation',
+      audience: normalizedViewer,
+      scope: 'conversation',
+      title: 'Background Information',
+      body: backgroundBody,
+    }),
+    createAcceptedChatKickoffContextBlock('policy', {
+      owner: 'orchestration',
+      audience: normalizedViewer,
+      scope: 'kickoff_only',
+      title: 'Policies',
+      items: buildAcceptedChatKickoffPolicies({
+        viewer: normalizedViewer,
+        senderFollowUpSessionKey,
+      }),
+    }),
+    createAcceptedChatKickoffContextBlock('task_instruction', {
+      owner: 'orchestration',
+      audience: normalizedViewer,
+      scope: 'current_turn',
+      title: 'Current Task',
+      body: taskBody,
+    }),
+  ].filter(Boolean);
 }
 
 function normalizeKickoffSource(value, fallback = 'chat_request_brief') {
@@ -158,6 +329,7 @@ function buildAcceptedChatKickoffRuntimeContext(bundle = {}, { viewer = 'recipie
 
   return {
     viewer: resolvedViewer,
+    blocks: buildAcceptedChatKickoffRuntimeBlocks(bundle, { viewer: resolvedViewer }),
     text: formatAcceptedChatKickoffMessage(bundle, { viewer: resolvedViewer }),
     briefText: normalizeText(brief.text, null),
   };
@@ -184,13 +356,17 @@ export function readAcceptedChatKickoffRuntimeContext(bundle = {}, { viewer = 'r
     : null;
   if (!candidate) return null;
 
-  const text = normalizeText(candidate.text, null);
+  const blocks = Array.isArray(candidate.blocks)
+    ? sortAcceptedChatContextBlocks(candidate.blocks.map((block) => cloneJsonObject(block) || block))
+    : [];
+  const text = normalizeText(candidate.text, renderAcceptedChatContextBlocks(blocks));
   if (!text) return null;
 
   return {
     viewer: resolvedViewer,
     text,
     briefText: normalizeText(candidate.briefText, normalizeText(brief.text, null)),
+    ...(blocks.length > 0 ? { blocks } : {}),
   };
 }
 
@@ -219,49 +395,8 @@ 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)
-    ? cloneJsonObject(bundle.requestContext) || {}
-    : {};
-  const followUp = bundle.followUp && typeof bundle.followUp === 'object' && !Array.isArray(bundle.followUp)
-    ? bundle.followUp
-    : {};
-  const senderFollowUpSessionKey = normalizeText(followUp.sender?.sessionKey, null);
-  const worldInfo = bundle.worldInfo && typeof bundle.worldInfo === 'object' && !Array.isArray(bundle.worldInfo)
-    ? bundle.worldInfo
-    : null;
-  const senderInfo = bundle.senderInfo && typeof bundle.senderInfo === 'object' && !Array.isArray(bundle.senderInfo)
-    ? bundle.senderInfo
-    : null;
-  const recipientInfo = bundle.recipientInfo && typeof bundle.recipientInfo === 'object' && !Array.isArray(bundle.recipientInfo)
-    ? bundle.recipientInfo
-    : null;
-  const selfInfo = normalizedViewer === 'sender' ? senderInfo : recipientInfo;
-  const peerInfo = normalizedViewer === 'sender' ? recipientInfo : senderInfo;
-  const viewerInstruction = normalizedViewer === 'recipient'
-    ? 'Use this accepted-chat kickoff context to interpret the sender opener as the first live turn of the accepted chat episode. Decide whether and how to reply. Do not echo the bundle verbatim to the peer.'
-    : 'Use this accepted-chat kickoff bundle to craft the first live opener to the recipient. Do not echo the bundle verbatim to the peer.';
-
-  const blocks = [
-    normalizedViewer === 'recipient'
-      ? 'Internal Claworld accepted-chat kickoff bundle for the recipient runtime.'
-      : 'Internal Claworld accepted-chat kickoff bundle for the sender runtime.',
-    viewerInstruction,
-    normalizeText(bundle.requestId, null) ? `Accepted episode: ${bundle.requestId}` : null,
-    formatStructuredSection('主人想让你做的事情 / 请求上下文', requestContext),
-    normalizedViewer === 'sender' && senderFollowUpSessionKey
-      ? `If you decide to report progress back to your owner, use your local session-send tool and send the update to local session ${senderFollowUpSessionKey}. 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.`
-      : normalizedViewer === 'recipient'
-        ? 'If you decide to report back to your owner, use your local session-send tool and send the summary to the sessionKey your owner is currently using as their main session. Do this only when the chat is nearing its end and the main information has already been communicated. Do not report every turn. Keep each update brief with the current status, the key information already confirmed, and any final outcome or recommended next step. If the conversation is still in progress or key details are still being clarified, wait before reporting back.'
-        : null,
-    formatStructuredSection('世界信息', worldInfo),
-    formatStructuredSection('我方信息', selfInfo),
-    formatStructuredSection('对方信息', peerInfo),
-    '在正常回复中，你可以附带 [[like]] 或 [[dislike]] 来表达你对这段 conversation 的反馈。这个 token 对对方可见，系统只会按当前 conversation 和方向记录第一次有效反馈。',
-    normalizedViewer === 'sender'
-      ? '请你现在直接输出一条自然的开场白。不要解释规则，不要复述这些说明。'
-      : '请把对方刚发来的 opener 视为这段对话的第一条 live turn，并决定是否以及如何直接回复。不要解释规则，不要复述这些说明。',
-  ].filter(Boolean);
-
-  return blocks.join('\n\n');
+  const resolvedViewer = viewer === 'sender' ? 'sender' : 'recipient';
+  return renderAcceptedChatContextBlocks(
+    buildAcceptedChatKickoffRuntimeBlocks(bundle, { viewer: resolvedViewer }),
+  );
 }

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

@@ -117,6 +117,101 @@ function resolveNormalizedText(value, fallback = null) {
   return normalizeClaworldText(value, fallback);
 }
 
+function isAgentScopedSessionKey(sessionKey) {
+  return /^agent:[^:]+:/i.test(String(sessionKey || ''));
+}
+
+function buildAgentScopedLocalSessionKey({ sessionKey, localAgentId } = {}) {
+  const normalizedSessionKey = resolveNormalizedText(sessionKey, null);
+  if (!normalizedSessionKey) return null;
+  if (isAgentScopedSessionKey(normalizedSessionKey)) {
+    return normalizedSessionKey;
+  }
+  const normalizedLocalAgentId = resolveNormalizedText(localAgentId, null);
+  if (!normalizedLocalAgentId) {
+    return normalizedSessionKey;
+  }
+  return `agent:${normalizedLocalAgentId}:${normalizedSessionKey}`;
+}
+
+function stripAgentScopedLocalSessionKey({ sessionKey, localAgentId } = {}) {
+  const normalizedSessionKey = resolveNormalizedText(sessionKey, null);
+  if (!normalizedSessionKey) return null;
+  const normalizedLocalAgentId = resolveNormalizedText(localAgentId, null);
+  if (!normalizedLocalAgentId) {
+    return normalizedSessionKey;
+  }
+  const prefix = `agent:${normalizedLocalAgentId}:`;
+  if (normalizedSessionKey.startsWith(prefix)) {
+    return normalizedSessionKey.slice(prefix.length) || null;
+  }
+  return normalizedSessionKey;
+}
+
+function normalizeLocalSessionKeyFields(record = null, { localAgentId = null } = {}) {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    return record;
+  }
+  const nextRecord = { ...record };
+  const normalizedLocalSessionKey = buildAgentScopedLocalSessionKey({
+    sessionKey: resolveNormalizedText(record.localSessionKey, resolveNormalizedText(record.sessionKey, null)),
+    localAgentId,
+  });
+  if (normalizedLocalSessionKey) {
+    nextRecord.localSessionKey = normalizedLocalSessionKey;
+  }
+  return nextRecord;
+}
+
+function normalizeChatInboxPayloadSessionKeys(payload = null, { localAgentId = null } = {}) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return payload;
+  }
+  const nextPayload = { ...payload };
+  if (payload.filters && typeof payload.filters === 'object' && !Array.isArray(payload.filters)) {
+    const normalizedFilterLocalSessionKey = buildAgentScopedLocalSessionKey({
+      sessionKey: payload.filters.localSessionKey,
+      localAgentId,
+    });
+    nextPayload.filters = {
+      ...payload.filters,
+      ...(normalizedFilterLocalSessionKey ? { localSessionKey: normalizedFilterLocalSessionKey } : {}),
+    };
+  }
+  if (Array.isArray(payload.chats)) {
+    nextPayload.chats = payload.chats.map((chat) => normalizeLocalSessionKeyFields(chat, { localAgentId }));
+  }
+  if (payload.kickoff && typeof payload.kickoff === 'object' && !Array.isArray(payload.kickoff)) {
+    nextPayload.kickoff = normalizeLocalSessionKeyFields(payload.kickoff, { localAgentId });
+  }
+  if (payload.chat && typeof payload.chat === 'object' && !Array.isArray(payload.chat)) {
+    nextPayload.chat = normalizeLocalSessionKeyFields(payload.chat, { localAgentId });
+  }
+  return nextPayload;
+}
+
+function resolveRelaySessionKeyFromOutboundContext(outboundContext = {}) {
+  const metadata = outboundContext?.metadata && typeof outboundContext.metadata === 'object' && !Array.isArray(outboundContext.metadata)
+    ? outboundContext.metadata
+    : {};
+  return normalizeClaworldText(
+    outboundContext.relaySessionKey,
+    normalizeClaworldText(
+      outboundContext.RelaySessionKey,
+      normalizeClaworldText(
+        metadata.relaySessionKey,
+        normalizeClaworldText(
+          metadata.sessionKey,
+          normalizeClaworldText(
+            outboundContext.sessionKey,
+            normalizeClaworldText(outboundContext.SessionKey, null),
+          ),
+        ),
+      ),
+    ),
+  );
+}
+
 function normalizeClaworldInteger(value, fallback = null) {
   const normalized = Number(value);
   if (!Number.isFinite(normalized)) return fallback;
@@ -410,6 +505,7 @@ async function deliverRelayMessage({ runtimeConfig, to, text, fetchImpl, logger,
   const clientMessageId = normalizePluginOptionalText(
     outboundContext.clientMessageId || outboundContext.metadata?.clientMessageId || null
   ) || buildGeneratedClientMessageId();
+  const relaySessionKey = resolveRelaySessionKeyFromOutboundContext(outboundContext);
 
   const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
   const result = await fetchJson(fetchImpl, `${baseUrl}/v1/messages`, {
@@ -430,7 +526,7 @@ async function deliverRelayMessage({ runtimeConfig, to, text, fetchImpl, logger,
         scope: outboundContext.scope || outboundContext.metadata?.scope || null,
         conversationId: outboundContext.conversationId || outboundContext.metadata?.conversationId || null,
         threadId: outboundContext.threadId || outboundContext.metadata?.threadId || null,
-        sessionKey: outboundContext.sessionKey || outboundContext.SessionKey || null,
+        sessionKey: relaySessionKey,
       },
     }),
   });
@@ -460,7 +556,7 @@ async function deliverRelayMessage({ runtimeConfig, to, text, fetchImpl, logger,
     timestamp: Date.now(),
     meta: {
       clientMessageId,
-      sessionKey: result.body?.delivery?.sessionKey || outboundContext.sessionKey || outboundContext.SessionKey || null,
+      sessionKey: result.body?.delivery?.sessionKey || relaySessionKey,
       turnId: result.body?.turn?.turnId || null,
       conversationKey: result.body?.conversationKey || null,
       targetAgentId,
@@ -563,13 +659,29 @@ async function createChatRequest({
 async function listChatInbox({
   runtimeConfig,
   agentId,
+  localAgentId = null,
+  filters = null,
   direction = null,
   fetchImpl,
 }) {
+  const normalizedFilters = filters && typeof filters === 'object' && !Array.isArray(filters)
+    ? filters
+    : {};
+  const relayLocalSessionKey = stripAgentScopedLocalSessionKey({
+    sessionKey: normalizedFilters.localSessionKey,
+    localAgentId,
+  });
   const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
   const path = buildRelayJsonPath('/v1/chat-requests', {
     agentId,
-    direction,
+    direction: normalizedFilters.direction || direction,
+    mode: normalizedFilters.mode,
+    status: normalizedFilters.status,
+    worldId: normalizedFilters.worldId,
+    chatRequestId: normalizedFilters.chatRequestId,
+    conversationKey: normalizedFilters.conversationKey,
+    localSessionKey: relayLocalSessionKey,
+    counterpartyAgentId: normalizedFilters.counterpartyAgentId,
   });
   const result = await fetchJson(fetchImpl, `${baseUrl}${path}`, {
     method: 'GET',
@@ -584,16 +696,24 @@ async function listChatInbox({
       runtimeConfig,
       code: 'chat_request_list_failed',
       publicMessage: 'failed to list chat requests',
-      context: { agentId, direction },
+      context: {
+        agentId,
+        direction: normalizedFilters.direction || direction,
+        mode: normalizedFilters.mode || null,
+        status: normalizedFilters.status || null,
+        worldId: normalizedFilters.worldId || null,
+        chatRequestId: normalizedFilters.chatRequestId || null,
+      },
     });
   }
-  return result.body || {};
+  return normalizeChatInboxPayloadSessionKeys(result.body || {}, { localAgentId });
 }
 
 async function acceptChatRequest({
   runtimeConfig,
   actorAgentId,
   chatRequestId,
+  localAgentId = null,
   fetchImpl,
 }) {
   const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
@@ -615,7 +735,7 @@ async function acceptChatRequest({
       context: { actorAgentId, chatRequestId },
     });
   }
-  return result.body || {};
+  return normalizeChatInboxPayloadSessionKeys(result.body || {}, { localAgentId });
 }
 
 async function rejectChatRequest({
@@ -1236,6 +1356,7 @@ function buildDeliveryInboundEnvelope({
   timestamp = null,
   deliveryId,
   sessionKey,
+  localSessionKey = null,
   worldId = null,
   conversationKey = null,
   untrustedContext = [],
@@ -1256,7 +1377,8 @@ function buildDeliveryInboundEnvelope({
     `[claworld peer ${remoteLabel}]`,
     ...(worldId ? [`[claworld world ${worldId}]`] : []),
     ...(conversationKey ? [`[claworld conversation ${conversationKey}]`] : []),
-    `[claworld session ${sessionKey}]`,
+    ...(localSessionKey && localSessionKey !== sessionKey ? [`[claworld local session ${localSessionKey}]`] : []),
+    `[claworld relay session ${sessionKey}]`,
     `[claworld delivery ${deliveryId}]`,
   ], untrustedContext);
   const envelopeTimestamp = Number.isFinite(timestamp) ? new Date(timestamp) : new Date();
@@ -1701,7 +1823,24 @@ async function maybeBridgeRuntimeDelivery({
     return { skipped: true, reason: 'missing_delivery_payload' };
   }
 
-  const currentCfg = cfg || await runtime.config?.loadConfig?.() || {};
+  const loadedCfg = await runtime.config?.loadConfig?.() || {};
+  const currentCfg = {
+    ...(loadedCfg && typeof loadedCfg === 'object' && !Array.isArray(loadedCfg) ? loadedCfg : {}),
+    ...(cfg && typeof cfg === 'object' && !Array.isArray(cfg) ? cfg : {}),
+    agents: cfg?.agents || loadedCfg?.agents,
+    bindings: cfg?.bindings || loadedCfg?.bindings,
+    channels: cfg?.channels || loadedCfg?.channels,
+    session: cfg?.session || loadedCfg?.session,
+  };
+  const localAgentId = resolveBoundLocalAgentId({
+    cfg: currentCfg,
+    runtimeConfig,
+    relayClient,
+  });
+  const localSessionKey = buildAgentScopedLocalSessionKey({
+    sessionKey,
+    localAgentId,
+  });
   const routed = inbound?.routeInboundEvent?.(delivery, {
     sessionTarget: runtimeConfig.routing?.sessionTarget,
     fallbackTarget: runtimeConfig.routing?.fallbackTarget,
@@ -1722,6 +1861,7 @@ async function maybeBridgeRuntimeDelivery({
     timestamp: inboundTimestamp,
     deliveryId,
     sessionKey,
+    localSessionKey,
     worldId,
     conversationKey: metadata.conversationKey || null,
     untrustedContext: payload.untrustedContext,
@@ -1735,7 +1875,8 @@ async function maybeBridgeRuntimeDelivery({
     BodyForCommands,
     From: `claworld:${remoteIdentity}`,
     To: `claworld:${localIdentity}`,
-    SessionKey: sessionKey,
+    SessionKey: localSessionKey || sessionKey,
+    RelaySessionKey: sessionKey,
     AccountId: runtimeConfig.accountId,
     OriginatingChannel: 'claworld',
     OriginatingFrom: remoteIdentity,
@@ -1755,11 +1896,6 @@ async function maybeBridgeRuntimeDelivery({
     RelayFromAgentId: fromAgentId,
     UntrustedContext,
   });
-  const localAgentId = resolveBoundLocalAgentId({
-    cfg: currentCfg,
-    runtimeConfig,
-    relayClient,
-  });
 
   if (runtime?.channel?.session?.recordInboundSession && runtime?.channel?.session?.resolveStorePath && localAgentId) {
     const storePath = runtime.channel.session.resolveStorePath(currentCfg.session?.store, {
@@ -1773,6 +1909,7 @@ async function maybeBridgeRuntimeDelivery({
         logger.error?.(`[claworld:${runtimeAccountId}] failed to record inbound session`, {
           deliveryId,
           sessionKey,
+          localSessionKey,
           localAgentId,
           error: error?.message || String(error),
         });
@@ -1783,6 +1920,7 @@ async function maybeBridgeRuntimeDelivery({
   logger.info?.(`[claworld:${runtimeAccountId}] routing delivery into runtime session`, {
     deliveryId,
     sessionKey,
+    localSessionKey,
     localAgentId,
     remoteIdentity,
     routeStatus: routed?.status || null,
@@ -1805,6 +1943,7 @@ async function maybeBridgeRuntimeDelivery({
     logger.warn?.(`[claworld:${runtimeAccountId}] delivery acceptance acknowledgement failed`, {
       deliveryId,
       sessionKey,
+      localSessionKey,
       localAgentId,
       error: error?.message || String(error),
     });
@@ -1850,6 +1989,7 @@ async function maybeBridgeRuntimeDelivery({
     logger.warn?.(`[claworld:${runtimeAccountId}] kickoff delivery produced only operational notices; retrying dispatch once`, {
       deliveryId,
       sessionKey,
+      localSessionKey,
       localAgentId,
       runtimeOutputSummary,
     });
@@ -1876,6 +2016,7 @@ async function maybeBridgeRuntimeDelivery({
   logger.info?.(`[claworld:${runtimeAccountId}] delivery bridge completed`, {
     deliveryId,
     sessionKey,
+    localSessionKey,
     queuedFinal: Boolean(dispatchResult?.queuedFinal),
     replied,
     keptSilent,
@@ -1890,6 +2031,7 @@ async function maybeBridgeRuntimeDelivery({
     keptSilent,
     queuedFinal: Boolean(dispatchResult?.queuedFinal),
     sessionKey,
+    localSessionKey,
     routeStatus: routed?.status || null,
   };
 }
@@ -2154,6 +2296,14 @@ export function createClaworldChannelPlugin({
     };
   }
 
+  function resolveContextBoundLocalAgentId(context = {}) {
+    return resolveBoundLocalAgentId({
+      cfg: context.cfg || {},
+      runtimeConfig: context.runtimeConfig || {},
+      relayClient: relayClients.get(context.accountId || 'default') || null,
+    });
+  }
+
   function getAccountLifecycle(accountKey = 'default') {
     if (lifecycles.has(accountKey)) return lifecycles.get(accountKey);
 
@@ -2768,6 +2918,8 @@ async function generateRuntimeProfileCard(context = {}) {
           return listChatInbox({
             runtimeConfig: resolvedContext.runtimeConfig,
             agentId: resolvedContext.agentId || null,
+            localAgentId: resolveContextBoundLocalAgentId(resolvedContext),
+            filters: context.filters || null,
             direction: context.direction || null,
             fetchImpl,
           });
@@ -2778,6 +2930,7 @@ async function generateRuntimeProfileCard(context = {}) {
             runtimeConfig: resolvedContext.runtimeConfig,
             actorAgentId: resolvedContext.agentId || null,
             chatRequestId: context.chatRequestId || null,
+            localAgentId: resolveContextBoundLocalAgentId(resolvedContext),
             fetchImpl,
           });
         },

package/src/openclaw/plugin/register.js

@@ -69,6 +69,40 @@ function buildClaworldStatusRoute(plugin) {
   };
 }
 
+const CHAT_INBOX_FILTER_DIRECTIONS = Object.freeze([
+  'inbound',
+  'outbound',
+]);
+const CHAT_INBOX_FILTER_MODES = Object.freeze([
+  'direct',
+  'world',
+]);
+const CHAT_INBOX_FILTER_STATUSES = Object.freeze([
+  'pending',
+  'opening',
+  'active',
+  'silent',
+  'kickoff_failed',
+  'ended',
+]);
+
+function normalizeChatInboxListFiltersInput(params = {}) {
+  const source = normalizeObject(params.filters, {}) || {};
+  const normalized = {
+    direction: normalizeText(source.direction ?? params.direction, null),
+    mode: normalizeText(source.mode, null),
+    status: normalizeText(source.status, null),
+    worldId: normalizeText(source.worldId, null),
+    chatRequestId: normalizeText(source.chatRequestId, null),
+    conversationKey: normalizeText(source.conversationKey, null),
+    localSessionKey: normalizeText(source.localSessionKey, null),
+    counterpartyAgentId: normalizeText(source.counterpartyAgentId, null),
+  };
+  return Object.fromEntries(
+    Object.entries(normalized).filter(([, value]) => value != null),
+  );
+}
+
 function buildRegisteredTools(api, plugin) {
   const accountIdProperty = stringParam({
     description: 'Claworld account id to execute the tool against. In managed installs this is usually the dedicated claworld account.',
@@ -582,26 +616,39 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_chat_inbox',
       label: 'Claworld Chat Inbox',
-      description: 'Canonical chat inbox tool. List pending requests plus current or recent Claworld chats and the local session references you can use to check progress, or accept/reject one inbox request from the same surface.',
+      description: 'Canonical chat inbox tool. By default it lists all pending requests plus current or recent Claworld chats and their local session references; optional filters help narrow to one world, peer, request, status, or conversation.',
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'Default action is list. Use it to review pending inbound requests waiting for acceptance.',
+          'Default action is list. Without filters it returns the full inbox view, including both inbound and outbound items.',
           'Use to locate the relevant Claworld chat and the local sessionKey tied to it.',
+          'Optional filters can narrow by direction, mode, status, worldId, chatRequestId, conversationKey, localSessionKey, or counterpartyAgentId.',
           '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.',
+          'Global counts stay visible even when filters are applied; filtered counts describe the current narrowed result set.',
           'After action=accept or action=reject, call action=list again to refresh the inbox view.',
         ],
         examples: [
           {
-            title: 'Review inbound chat state',
+            title: 'Review the full inbox',
             input: {
               accountId: 'claworld',
               action: 'list',
-              direction: 'inbound',
             },
-            outcome: 'Returns pending requests plus related chats for the current account.',
+            outcome: 'Returns all pending requests plus related chats for the current account.',
+          },
+          {
+            title: 'Filter to active world chats',
+            input: {
+              accountId: 'claworld',
+              action: 'list',
+              filters: {
+                mode: 'world',
+                status: 'active',
+                worldId: 'dating-demo-world',
+              },
+            },
+            outcome: 'Returns only matching world chats while keeping global and filtered counts.',
           },
           {
             title: 'Accept one inbound request from the inbox',
@@ -624,10 +671,46 @@ function buildRegisteredTools(api, plugin) {
             enumValues: CHAT_INBOX_ACTIONS,
             examples: ['list', 'accept', 'reject'],
           }),
-          direction: stringParam({
-            description: 'Filter to inbound or outbound chat state from the current account perspective. Used with action=list.',
-            enumValues: ['inbound', 'outbound'],
-            examples: ['inbound'],
+          filters: objectParam({
+            description: 'Optional list filters. Omit to review the full inbox across inbound and outbound items.',
+            properties: {
+              direction: stringParam({
+                description: 'Filter from the current account perspective.',
+                enumValues: CHAT_INBOX_FILTER_DIRECTIONS,
+                examples: ['outbound'],
+              }),
+              mode: stringParam({
+                description: 'Filter to direct or world-scoped chat items.',
+                enumValues: CHAT_INBOX_FILTER_MODES,
+                examples: ['world'],
+              }),
+              status: stringParam({
+                description: 'Filter to pending requests or chats by current status.',
+                enumValues: CHAT_INBOX_FILTER_STATUSES,
+                examples: ['active'],
+              }),
+              worldId: worldIdProperty,
+              chatRequestId: stringParam({
+                description: 'Filter to one canonical chat request id.',
+                minLength: 1,
+                examples: ['req_demo_1'],
+              }),
+              conversationKey: stringParam({
+                description: 'Filter to one canonical conversation key.',
+                minLength: 1,
+                examples: ['pair:agt_alice::agt_moza:world:dating-demo-world'],
+              }),
+              localSessionKey: stringParam({
+                description: 'Filter to one local Claworld session reference.',
+                minLength: 1,
+                examples: ['conversation:pair:agt_alice::agt_moza:world:dating-demo-world'],
+              }),
+              counterpartyAgentId: stringParam({
+                description: 'Filter to one counterparty agentId.',
+                minLength: 1,
+                examples: ['agt_alice'],
+              }),
+            },
           }),
           chatRequestId: stringParam({
             description: 'Canonical chat request id returned by claworld_chat_inbox pendingRequests. Required for action=accept or action=reject.',
@@ -639,7 +722,9 @@ function buildRegisteredTools(api, plugin) {
           {
             accountId: 'claworld',
             action: 'list',
-            direction: 'inbound',
+            filters: {
+              direction: 'inbound',
+            },
           },
           {
             accountId: 'claworld',
@@ -670,9 +755,10 @@ function buildRegisteredTools(api, plugin) {
             action,
           }));
         }
+        const filters = normalizeChatInboxListFiltersInput(params);
         const payload = await plugin.helpers.social.listChatInbox({
           ...context,
-          direction: params.direction || null,
+          filters,
         });
         return buildToolResult(projectToolChatInboxActionResponse(payload, {
           accountId: context.accountId,

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

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

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

@@ -451,6 +451,14 @@ function projectChatRequestKickoff(kickoff = {}) {
     openerAcceptedAt: normalizeText(normalizedKickoff.openerAcceptedAt, null),
     openerDeliveredAt: normalizeText(normalizedKickoff.openerDeliveredAt, null),
     liveChatEstablishedAt: normalizeText(normalizedKickoff.liveChatEstablishedAt, null),
+    conversationKey: normalizeText(normalizedKickoff.conversationKey, null),
+    localSessionKey: normalizeText(
+      normalizedKickoff.localSessionKey,
+      normalizeText(normalizedKickoff.sessionKey, null),
+    ),
+    turnId: normalizeText(normalizedKickoff.turnId, null),
+    deliveryId: normalizeText(normalizedKickoff.deliveryId, null),
+    created: typeof normalizedKickoff.created === 'boolean' ? normalizedKickoff.created : null,
     reason: normalizeText(normalizedKickoff.reason, null),
   };
 }
@@ -517,12 +525,52 @@ function projectChatInboxChatItem(chat = {}) {
     lastTurnAt: normalizeText(chat.lastTurnAt, null),
     conversationKey: normalizeText(chat.conversationKey, null),
     localSessionKey: normalizeText(chat.localSessionKey, normalizeText(chat.sessionKey, null)),
+    turnCount: normalizeInteger(chat.turnCount, null),
     counterparty: projectToolAgentSummary(chat.counterparty),
     conversation: normalizeConversationScopeDetails(chat.conversation),
     feedbackSummary: projectConversationFeedbackSummary(chat.feedbackSummary),
   };
 }
 
+function projectChatInboxFilters(filters = {}) {
+  if (!filters || typeof filters !== 'object' || Array.isArray(filters)) return {};
+  const projected = {
+    direction: normalizeText(filters.direction, null),
+    mode: normalizeText(filters.mode, null),
+    status: normalizeText(filters.status, null),
+    worldId: normalizeText(filters.worldId, null),
+    chatRequestId: normalizeText(filters.chatRequestId, null),
+    conversationKey: normalizeText(filters.conversationKey, null),
+    localSessionKey: normalizeText(filters.localSessionKey, null),
+    counterpartyAgentId: normalizeText(filters.counterpartyAgentId, null),
+  };
+  return Object.fromEntries(
+    Object.entries(projected).filter(([, value]) => value != null),
+  );
+}
+
+function projectChatInboxCountBlock(counts = {}, fallback = {}) {
+  return {
+    pendingRequestCount: normalizeInteger(counts.pendingRequestCount, fallback.pendingRequestCount ?? 0),
+    chatCount: normalizeInteger(counts.chatCount, fallback.chatCount ?? 0),
+    chatStatusCounts: counts.chatStatusCounts && typeof counts.chatStatusCounts === 'object' && !Array.isArray(counts.chatStatusCounts)
+      ? {
+          opening: normalizeInteger(counts.chatStatusCounts.opening, 0),
+          active: normalizeInteger(counts.chatStatusCounts.active, 0),
+          silent: normalizeInteger(counts.chatStatusCounts.silent, 0),
+          kickoff_failed: normalizeInteger(counts.chatStatusCounts.kickoff_failed, 0),
+          ended: normalizeInteger(counts.chatStatusCounts.ended, 0),
+        }
+      : {
+          opening: 0,
+          active: 0,
+          silent: 0,
+          kickoff_failed: 0,
+          ended: 0,
+        },
+  };
+}
+
 export function projectToolChatRequestMutationResponse(result = {}, { accountId = null } = {}) {
   const request = result.chatRequest && typeof result.chatRequest === 'object'
     ? result.chatRequest
@@ -531,11 +579,13 @@ export function projectToolChatRequestMutationResponse(result = {}, { accountId
       : result;
   const projectedRequest = projectChatRequestItem(request);
   const kickoff = projectChatRequestKickoff(result.kickoff || result.request?.kickoff);
+  const projectedChat = projectChatInboxChatItem(result.chat);
   const normalizedStatus = normalizeText(result.status, projectedRequest?.status || 'pending');
   return {
     status: normalizedStatus,
     accountId: normalizeText(accountId, null),
     chatRequest: projectedRequest,
+    ...(projectedChat ? { chat: projectedChat } : {}),
     kickoff,
     nextAction: normalizeText(
       result.nextAction,
@@ -563,17 +613,22 @@ export function projectToolChatInboxResponse(result = {}, { accountId = null } =
   const chats = Array.isArray(result.chats)
     ? result.chats.map((chat) => projectChatInboxChatItem(chat)).filter(Boolean)
     : [];
+  const projectedFilters = projectChatInboxFilters(result.filters);
+  const globalCounts = projectChatInboxCountBlock(result.counts?.global, {
+    pendingRequestCount: pendingRequests.length,
+    chatCount: chats.length,
+  });
+  const filteredCounts = projectChatInboxCountBlock(result.counts?.filtered, {
+    pendingRequestCount: pendingRequests.length,
+    chatCount: chats.length,
+  });
   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,
-        },
+    filters: projectedFilters,
+    counts: {
+      global: globalCounts,
+      filtered: filteredCounts,
+    },
     pendingRequests,
     chats,
   };