a2a-xmtp 1.0.1 → 1.2.0

package/README.md

@@ -4,102 +4,189 @@ Decentralized Agent-to-Agent E2EE messaging for [OpenClaw](https://openclaw.ai)
 
 ## Features
 
-- **E2EE Messaging** — End-to-end encrypted Agent-to-Agent communication
-- **Cross-Gateway** — Agents on different servers can communicate directly
-- **XMTP Network** — Decentralized, no VPN or API sharing needed
-- **3 Agent Tools** — `xmtp_send`, `xmtp_inbox`, `xmtp_agents`
+- **E2EE Messaging** — End-to-end encrypted Agent-to-Agent communication over XMTP
+- **Group Chat** — Create and manage multi-agent group conversations with natural turn-taking
+- **Auto-Reply** — Incoming messages trigger LLM reasoning via subagent, replies sent automatically
+- **Anti-Loop** — 4-layer protection (turn budget, cool-down, depth limit, consent) prevents infinite loops
+- **Cross-Gateway** — Agents on different servers communicate directly, no VPN or API sharing needed
+- **4 Agent Tools** — `xmtp_send`, `xmtp_inbox`, `xmtp_agents`, `xmtp_group`
 
 ## Install
 
 ```bash
 openclaw plugins install a2a-xmtp
 chown -R root:root ~/.openclaw/extensions/a2a-xmtp/
+```
 
-Configure
+## Configure
 
-Edit ~/.openclaw/openclaw.json:
+Edit `~/.openclaw/openclaw.json`:
 
+```json
 {
-"tools": {
-  "profile": "full"
-},
-"plugins": {
-  "entries": {
-    "a2a-xmtp": {
-      "enabled": true,
-      "config": {
-        "xmtp": {
-          "env": "dev",
-          "dbPath": "/root/.openclaw/xmtp-data"
+  "tools": {
+    "profile": "full"
+  },
+  "plugins": {
+    "entries": {
+      "a2a-xmtp": {
+        "enabled": true,
+        "config": {
+          "xmtp": {
+            "env": "dev",
+            "dbPath": "/root/.openclaw/xmtp-data"
+          }
         }
       }
     }
   }
 }
-}
+```
 
 Then restart:
 
+```bash
 mkdir -p /root/.openclaw/xmtp-data
 openclaw gateway restart
+```
 
-Verify
+## Verify
 
+```bash
 # Check plugin loaded
 openclaw plugins list | grep a2a-xmtp
 
-# Check bridge status (replace TOKEN with your gateway auth token)
+# Check bridge status
 TOKEN=$(python3 -c "import json; print(json.load(open('/root/.openclaw/openclaw.json'))['gateway']['auth']['token'])")
 curl -s -H "Authorization: Bearer $TOKEN" http://localhost:18789/a2a-xmtp/status
+```
 
 Expected output:
 
+```json
 {
-"plugin": "a2a-xmtp",
-"bridgeCount": 1,
-"agents": [{"agentId": "main", "xmtpAddress": "0x...", "connected": true}]
+  "plugin": "a2a-xmtp",
+  "bridgeCount": 1,
+  "agents": [{"agentId": "main", "xmtpAddress": "0x...", "connected": true}]
 }
+```
+
+## Tools
+
+### xmtp_send
+
+Send an E2E encrypted message to another agent.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `to` | When no `conversationId` | Target agent ID or `0x` address |
+| `message` | Yes | Message content |
+| `conversationId` | No | Reuse existing conversation (DM or group) |
+| `contentType` | No | `text` (default) or `markdown` |
+
+### xmtp_inbox
+
+Check your inbox for messages from other agents.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `limit` | No | Max messages to return (default: 10) |
+| `from` | No | Filter by sender agent ID or address |
+
+Messages are tagged with `[group]` when from a group conversation.
+
+### xmtp_agents
+
+Discover agents available for XMTP communication.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `includeExternal` | No | Include ERC-8004 external registry (Phase 3) |
+
+### xmtp_group
+
+Manage group conversations.
 
-Usage
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `action` | Yes | `create`, `list`, `members`, `add_member`, `remove_member` |
+| `members` | For create/add/remove | Agent IDs or `0x` addresses |
+| `conversationId` | For members/add/remove | Group conversation ID |
+| `name` | No | Group name (for create) |
 
-Talk to your Agent via Telegram or any OpenClaw channel:
+**Examples:**
 
-┌─────────────────┬──────────────────────────────────────────┐
-│     Command     │                 Example                  │
-├─────────────────┼──────────────────────────────────────────┤
-│ Discover agents │ "使用 xmtp_agents 列出可通信的 Agent"    │
-├─────────────────┼──────────────────────────────────────────┤
-│ Send message    │ "使用 xmtp_send 给 0xAddress 发送 Hello" │
-├─────────────────┼──────────────────────────────────────────┤
-│ Check inbox     │ "使用 xmtp_inbox 查看消息"               │
-└─────────────────┴──────────────────────────────────────────┘
+```
+# Create a group with two agents
+"Use xmtp_group to create a group named 'Research Team' with members agent-a and 0xBob..."
 
-Cross-Server Communication
+# List all groups
+"Use xmtp_group to list all groups"
 
-Two OpenClaw agents on different servers can message each other — just exchange XMTP addresses:
+# Send message to group
+"Use xmtp_send to send 'Hello everyone' to conversationId xxx"
+```
 
-1. Get your agent's address from /a2a-xmtp/status
+## Auto-Reply
+
+When your agent receives an XMTP message, the plugin automatically:
+
+1. Buffers the message in the inbox
+2. Triggers a subagent with the message context
+3. Sends the LLM's reply back via XMTP
+
+This works for both DMs and group chats. In group chats, the system prompt includes participant info so the LLM can respond naturally.
+
+## Multi-Agent Group Chat
+
+When multiple OpenClaw agents are in the same group, the plugin ensures natural turn-taking:
+
+- **No parallel replies** — When a human sends a message, agents use random delay + dedup check so only one responds first
+- **Sequential discussion** — After one agent replies, the other naturally follows, creating a back-and-forth discussion
+- **Natural conversation flow** — The LLM is prompted to behave like a human in group chat, only speaking when it has something to add
+
+```
+Admin:   "Discuss the pros and cons of Rust vs Go"
+Agent A: "Rust offers memory safety without GC..."     (responds first)
+Agent B: "I agree on safety, but Go's simplicity..."   (follows up)
+Agent A: "Good point. For our use case though..."       (continues)
+```
+
+## Cross-Server Communication
+
+Two OpenClaw agents on different servers can message each other:
+
+1. Get your agent's address from `/a2a-xmtp/status`
 2. Share it with the other party
-3. Send messages using xmtp_send with the other agent's 0x address
+3. Send messages using `xmtp_send` with the other agent's `0x` address
 
 No VPN, no API keys, no shared infrastructure needed.
 
-Policy Configuration
-
-┌──────────────────────┬──────────────────┬────────────────────────────┐
-│       Setting        │     Default      │        Description         │
-├──────────────────────┼──────────────────┼────────────────────────────┤
-│ policy.maxTurns      │ 10               │ Max turns per conversation │
-├──────────────────────┼──────────────────┼────────────────────────────┤
-│ policy.maxDepth      │ 5                │ Max reply depth            │
-├──────────────────────┼──────────────────┼────────────────────────────┤
-│ policy.minIntervalMs │ 5000             │ Cool-down between sends    │
-├──────────────────────┼──────────────────┼────────────────────────────┤
-│ policy.ttlMinutes    │ 60               │ Conversation TTL           │
-├──────────────────────┼──────────────────┼────────────────────────────┤
-│ policy.consentMode   │ auto-allow-local │ Consent for local agents   │
-└──────────────────────┴──────────────────┴────────────────────────────┘
-
-License
+## Policy Configuration
+
+Anti-loop protection with 4 guards:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `policy.maxTurns` | 10 | Max turns per conversation |
+| `policy.maxDepth` | 5 | Max reply depth |
+| `policy.minIntervalMs` | 5000 | Cool-down between sends (ms) |
+| `policy.ttlMinutes` | 60 | Conversation TTL |
+| `policy.consentMode` | `auto-allow-local` | `auto-allow-local` or `explicit-only` |
+
+## Architecture
+
+```
+Plugin Entry (index.ts)
+  ├── xmtp_send    ─┐
+  ├── xmtp_inbox    │── Tool Handlers (src/tools/)
+  ├── xmtp_agents   │
+  ├── xmtp_group   ─┘
+  ├── XmtpBridge (xmtp-bridge.ts)     ── XMTP Agent SDK wrapper
+  ├── IdentityRegistry (identity-registry.ts) ── agentId <-> wallet mapping
+  └── PolicyEngine (policy-engine.ts)  ── anti-loop guards
+```
+
+## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2a-xmtp",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,4 +33,4 @@
     "package.json",
     "README.md"
   ]
-}
+}

package/src/index.ts

@@ -11,7 +11,8 @@ import { XmtpBridge } from "./xmtp-bridge.js";
 import { handleXmtpSend } from "./tools/xmtp-send.js";
 import { handleXmtpInbox } from "./tools/xmtp-inbox.js";
 import { handleDiscoverAgents } from "./tools/xmtp-agents.js";
-import { DEFAULT_PLUGIN_CONFIG, type PluginConfig } from "./types.js";
+import { handleXmtpGroup } from "./tools/xmtp-group.js";
+import { DEFAULT_PLUGIN_CONFIG, formatA2AMessage, type PluginConfig, type A2AInjectPayload } from "./types.js";
 
 const AGENT_ID = "main"; // OpenClaw 默认 agent
 
@@ -29,25 +30,27 @@ export default definePluginEntry({
 
     api.registerTool({
       name: "xmtp_send",
+      label: "Send XMTP Message",
       description:
         "Send an E2EE message to another agent via XMTP. " +
         "Supports cross-gateway and cross-organization communication.",
       parameters: Type.Object({
-        to: Type.String({ description: "Target agent ID or XMTP address (0x...)" }),
+        to: Type.Optional(Type.String({ description: "Target agent ID or XMTP address (0x...). Optional when conversationId is provided." })),
         message: Type.String({ description: "Message content to send" }),
-        conversationId: Type.Optional(Type.String({ description: "Reuse existing conversation" })),
+        conversationId: Type.Optional(Type.String({ description: "Reuse existing conversation. When set, 'to' is optional." })),
         contentType: Type.Optional(
           Type.String({ description: "Message type: text or markdown", default: "text" }),
         ),
       }),
       async execute(_toolCallId, params) {
-        const p = params as { to: string; message: string; conversationId?: string; contentType?: "text" | "markdown" };
+        const p = params as { to?: string; message: string; conversationId?: string; contentType?: "text" | "markdown" };
         return await handleXmtpSend(bridges, registry, policyEngine, p, AGENT_ID);
       },
     });
 
     api.registerTool({
       name: "xmtp_inbox",
+      label: "XMTP Inbox",
       description:
         "Check your XMTP inbox for messages from other agents. " +
         "Messages are E2E encrypted and only you can read them.",
@@ -63,6 +66,7 @@ export default definePluginEntry({
 
     api.registerTool({
       name: "xmtp_agents",
+      label: "Discover XMTP Agents",
       description:
         "Discover agents available for XMTP communication. " +
         "Lists registered agents and their connection status.",
@@ -77,6 +81,24 @@ export default definePluginEntry({
       },
     });
 
+    api.registerTool({
+      name: "xmtp_group",
+      label: "XMTP Group Management",
+      description:
+        "Manage XMTP group conversations. Actions: create (new group), list (all groups), " +
+        "members (view members), add_member, remove_member.",
+      parameters: Type.Object({
+        action: Type.String({ description: "Action: create | list | members | add_member | remove_member" }),
+        members: Type.Optional(Type.Array(Type.String(), { description: "Agent IDs or 0x addresses (for create/add_member/remove_member)" })),
+        conversationId: Type.Optional(Type.String({ description: "Group conversation ID (for members/add_member/remove_member)" })),
+        name: Type.Optional(Type.String({ description: "Group name (for create)" })),
+      }),
+      async execute(_toolCallId, params) {
+        const p = params as { action: string; members?: string[]; conversationId?: string; name?: string };
+        return await handleXmtpGroup(bridges, registry, p, AGENT_ID);
+      },
+    });
+
     // ── 2. 注册 HTTP 状态路由 ──
 
     api.registerHttpRoute({
@@ -141,9 +163,120 @@ export default definePluginEntry({
             config.xmtp.dbPath,
           );
 
-          // 消息回调：收到 XMTP 消息时记录日志
-          bridge.onMessage = (agentId, message) => {
-            ctx.logger.info(`[a2a-xmtp] Incoming message for ${agentId}: ${message}`);
+          // 消息回调：收到 XMTP 消息时触发 subagent 进行 LLM 推理并自动回复
+          bridge.onMessage = async (agentId, payload: A2AInjectPayload) => {
+            const sessionKey = `xmtp:${payload.conversation.id}`;
+            const formattedMsg = formatA2AMessage(payload);
+            const senderLabel = payload.from.agentId || payload.from.xmtpAddress;
+
+            // ── 群聊防抢答：随机延迟 + 发送前检查 ──
+            // 多个 agent 收到同一条消息时，随机延迟打破对称性，
+            // 延迟结束后检查是否已有其他 agent 回复，有则跳过
+            if (payload.conversation.isGroup) {
+              const delay = 3000 + Math.random() * 5000; // 3-8 秒随机延迟
+              ctx.logger.info(
+                `[a2a-xmtp] Group message from ${senderLabel}, waiting ${Math.round(delay)}ms before responding...`,
+              );
+              await new Promise((r) => setTimeout(r, delay));
+
+              // 检查延迟期间是否已有其他人回复
+              const alreadyReplied = await bridge.hasNewGroupReplies(
+                payload.conversation.id,
+                payload.timestamp,
+                [bridge.address, payload.from.xmtpAddress], // 排除自己和原始发送者
+              );
+              if (alreadyReplied) {
+                ctx.logger.info(
+                  `[a2a-xmtp] Skipping reply — another agent already responded in ${payload.conversation.id}`,
+                );
+                return;
+              }
+            }
+
+            const participantInfo = payload.conversation.isGroup
+              ? [
+                  `这是群聊，参与者: ${payload.conversation.participants.join(", ")}。`,
+                  `群内有多个 AI agent，请像人类群聊一样自然讨论。`,
+                  `不需要每条消息都回复，如果话题不需要你的输入可以保持沉默（回复空文本）。`,
+                  `回复应该是对话的自然延续，而不是重复别人的观点。`,
+                ].join("\n")
+              : `这是私聊。`;
+
+            const extraSystemPrompt = [
+              `你收到了一条 XMTP 消息，来自 ${senderLabel}。`,
+              participantInfo,
+              `请直接用文本回复，不要调用任何工具（不要调用 xmtp_send、xmtp_inbox 等）。`,
+              `系统会自动将你的文本回复发送给对方。`,
+            ].join("\n");
+
+            try {
+              const { runId } = await api.runtime.subagent.run({
+                sessionKey,
+                message: formattedMsg,
+                extraSystemPrompt,
+                deliver: false,
+                idempotencyKey: `xmtp:${payload.message.id}`,
+              });
+              const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 60000 });
+              if (result.status === "error") {
+                ctx.logger.error(`[a2a-xmtp] Subagent error: ${result.error}`);
+              } else if (result.status === "timeout") {
+                ctx.logger.warn(`[a2a-xmtp] Subagent timeout for ${sessionKey}`);
+              }
+
+              // 取回 LLM 的文本回复，手动通过 XMTP 发送
+              if (result.status === "ok") {
+                const { messages } = await api.runtime.subagent.getSessionMessages({
+                  sessionKey,
+                  limit: 5,
+                });
+                // 找到最后一条 assistant 回复
+                const lastReply = [...messages].reverse().find(
+                  (m: any) => m.role === "assistant" && m.content,
+                );
+                if (lastReply) {
+                  const rawContent = (lastReply as any).content;
+                  // content 可能是 string 或 content blocks 数组（含 thinking/text）
+                  let replyText: string;
+                  if (typeof rawContent === "string") {
+                    replyText = rawContent;
+                  } else if (Array.isArray(rawContent)) {
+                    // 只提取 type=text 的部分，跳过 thinking
+                    replyText = rawContent
+                      .filter((block: any) => block.type === "text" && block.text)
+                      .map((block: any) => block.text)
+                      .join("\n");
+                  } else {
+                    replyText = String(rawContent);
+                  }
+                  if (!replyText.trim()) return; // 没有有效文本则不回复
+
+                  // 群聊：发送前再次检查，防止 LLM 推理期间其他 agent 已经回复
+                  if (payload.conversation.isGroup) {
+                    const raceCheck = await bridge.hasNewGroupReplies(
+                      payload.conversation.id,
+                      payload.timestamp,
+                      [bridge.address, payload.from.xmtpAddress],
+                    );
+                    if (raceCheck) {
+                      ctx.logger.info(
+                        `[a2a-xmtp] Skipping reply (post-LLM check) — another agent responded in ${payload.conversation.id}`,
+                      );
+                      return;
+                    }
+                  }
+
+                  await bridge.sendMessage(payload.from.xmtpAddress, replyText, {
+                    conversationId: payload.conversation.id,
+                  });
+                  ctx.logger.info(`[a2a-xmtp] Replied to ${senderLabel} in ${payload.conversation.id}`);
+                }
+              }
+            } catch (err) {
+              ctx.logger.error(
+                `[a2a-xmtp] Failed to trigger subagent: ${err instanceof Error ? err.message : String(err)}`,
+              );
+            }
           };
 
           await bridge.start();

package/src/tools/xmtp-group.ts

@@ -0,0 +1,153 @@
+// ============================================================
+// Tool: xmtp_group — 群聊管理（创建、列表、成员查看/添加/移除）
+// ============================================================
+
+import type { XmtpBridge } from "../xmtp-bridge.js";
+import type { IdentityRegistry } from "../identity-registry.js";
+
+type GroupAction = "create" | "list" | "members" | "add_member" | "remove_member";
+
+export async function handleXmtpGroup(
+  bridges: Map<string, XmtpBridge>,
+  registry: IdentityRegistry,
+  params: {
+    action: string;
+    members?: string[];
+    conversationId?: string;
+    name?: string;
+  },
+  agentId: string,
+) {
+  const bridge = bridges.get(agentId) ?? bridges.values().next().value;
+  if (!bridge) {
+    return { content: [{ type: "text" as const, text: "No XMTP bridge available. Plugin not initialized." }], details: null };
+  }
+
+  const action = params.action as GroupAction;
+
+  try {
+    switch (action) {
+      case "create": {
+        if (!params.members?.length) {
+          return { content: [{ type: "text" as const, text: "Parameter 'members' is required for create action. Provide agent IDs or 0x addresses." }], details: null };
+        }
+        // 解析成员地址
+        const addresses: string[] = [];
+        for (const member of params.members) {
+          if (member.startsWith("0x")) {
+            addresses.push(member);
+          } else {
+            const addr = registry.getAddress(member);
+            if (!addr) {
+              return { content: [{ type: "text" as const, text: `Agent "${member}" not found. Use xmtp_agents to discover available agents.` }], details: null };
+            }
+            addresses.push(addr);
+          }
+        }
+
+        const result = await bridge.createGroup(addresses, params.name);
+        return {
+          content: [{ type: "text" as const, text: `Group created${result.name ? ` "${result.name}"` : ""} with ${addresses.length} members.` }],
+          details: {
+            action: "create",
+            conversationId: result.conversationId,
+            name: result.name,
+            memberCount: addresses.length,
+          },
+        };
+      }
+
+      case "list": {
+        const groups = await bridge.listGroups();
+        if (groups.length === 0) {
+          return { content: [{ type: "text" as const, text: "No group conversations found." }], details: null };
+        }
+        const lines = groups.map((g) => {
+          const nameLabel = g.name ? ` "${g.name}"` : "";
+          return `- ${g.conversationId}${nameLabel} (${g.memberAddresses.length} members, created ${g.createdAt})`;
+        });
+        return {
+          content: [{ type: "text" as const, text: `Groups:\n${lines.join("\n")}` }],
+          details: { action: "list", count: groups.length, groups },
+        };
+      }
+
+      case "members": {
+        if (!params.conversationId) {
+          return { content: [{ type: "text" as const, text: "Parameter 'conversationId' is required for members action." }], details: null };
+        }
+        const members = await bridge.getGroupMembers(params.conversationId);
+        // 尝试解析 agentId
+        const resolved = members.map((addr) => {
+          const aid = registry.getAgentId(addr);
+          return aid ? `${aid} (${addr})` : addr;
+        });
+        return {
+          content: [{ type: "text" as const, text: `Members (${members.length}):\n${resolved.map((m) => `- ${m}`).join("\n")}` }],
+          details: { action: "members", conversationId: params.conversationId, count: members.length, members },
+        };
+      }
+
+      case "add_member": {
+        if (!params.conversationId) {
+          return { content: [{ type: "text" as const, text: "Parameter 'conversationId' is required for add_member action." }], details: null };
+        }
+        if (!params.members?.length) {
+          return { content: [{ type: "text" as const, text: "Parameter 'members' is required for add_member action." }], details: null };
+        }
+        const addresses: string[] = [];
+        for (const member of params.members) {
+          if (member.startsWith("0x")) {
+            addresses.push(member);
+          } else {
+            const addr = registry.getAddress(member);
+            if (!addr) {
+              return { content: [{ type: "text" as const, text: `Agent "${member}" not found.` }], details: null };
+            }
+            addresses.push(addr);
+          }
+        }
+        await bridge.addGroupMembers(params.conversationId, addresses);
+        return {
+          content: [{ type: "text" as const, text: `Added ${addresses.length} member(s) to group.` }],
+          details: { action: "add_member", conversationId: params.conversationId, added: addresses },
+        };
+      }
+
+      case "remove_member": {
+        if (!params.conversationId) {
+          return { content: [{ type: "text" as const, text: "Parameter 'conversationId' is required for remove_member action." }], details: null };
+        }
+        if (!params.members?.length) {
+          return { content: [{ type: "text" as const, text: "Parameter 'members' is required for remove_member action." }], details: null };
+        }
+        const addresses: string[] = [];
+        for (const member of params.members) {
+          if (member.startsWith("0x")) {
+            addresses.push(member);
+          } else {
+            const addr = registry.getAddress(member);
+            if (!addr) {
+              return { content: [{ type: "text" as const, text: `Agent "${member}" not found.` }], details: null };
+            }
+            addresses.push(addr);
+          }
+        }
+        await bridge.removeGroupMembers(params.conversationId, addresses);
+        return {
+          content: [{ type: "text" as const, text: `Removed ${addresses.length} member(s) from group.` }],
+          details: { action: "remove_member", conversationId: params.conversationId, removed: addresses },
+        };
+      }
+
+      default:
+        return {
+          content: [{ type: "text" as const, text: `Unknown action "${action}". Supported: create, list, members, add_member, remove_member.` }],
+          details: null,
+        };
+    }
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text" as const, text: `Group operation failed: ${msg}` }], details: null };
+  }
+}

package/src/tools/xmtp-inbox.ts

@@ -13,7 +13,7 @@ export async function handleXmtpInbox(
 ) {
   const bridge = bridges.get(agentId) ?? bridges.values().next().value;
   if (!bridge) {
-    return { content: [{ type: "text" as const, text: "No XMTP bridge available." }] };
+    return { content: [{ type: "text" as const, text: "No XMTP bridge available." }], details: null };
   }
 
   // 解析 from
@@ -27,12 +27,13 @@ export async function handleXmtpInbox(
     const messages = await bridge.getInbox({ limit: params.limit ?? 10, from: fromFilter });
 
     if (messages.length === 0) {
-      return { content: [{ type: "text" as const, text: "No messages in inbox." }] };
+      return { content: [{ type: "text" as const, text: "No messages in inbox." }], details: null };
     }
 
     const lines = messages.map((m, i) => {
       const sender = m.from.agentId ?? m.from.xmtpAddress;
-      return `${i + 1}. [${m.timestamp}] from ${sender}: ${m.content}`;
+      const groupTag = m.isGroup ? " [group]" : "";
+      return `${i + 1}. [${m.timestamp}]${groupTag} from ${sender}: ${m.content}`;
     });
 
     return {
@@ -41,6 +42,6 @@ export async function handleXmtpInbox(
     };
   } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err);
-    return { content: [{ type: "text" as const, text: `Failed to fetch inbox: ${msg}` }] };
+    return { content: [{ type: "text" as const, text: `Failed to fetch inbox: ${msg}` }], details: null };
   }
 }

package/src/tools/xmtp-send.ts

@@ -10,48 +10,58 @@ export async function handleXmtpSend(
   bridges: Map<string, XmtpBridge>,
   registry: IdentityRegistry,
   policyEngine: PolicyEngine,
-  params: { to: string; message: string; conversationId?: string; contentType?: "text" | "markdown" },
+  params: { to?: string; message: string; conversationId?: string; contentType?: "text" | "markdown" },
   senderAgentId: string,
 ) {
   // 找到发送者 bridge（使用第一个可用的 bridge）
   const bridge = bridges.get(senderAgentId) ?? bridges.values().next().value;
   if (!bridge) {
-    return { content: [{ type: "text" as const, text: "No XMTP bridge available. Plugin not initialized." }] };
+    return { content: [{ type: "text" as const, text: "No XMTP bridge available. Plugin not initialized." }], details: null };
   }
 
-  // 解析目标地址
-  let targetAddress: string;
-  if (params.to.startsWith("0x")) {
-    targetAddress = params.to;
-  } else {
-    const addr = registry.getAddress(params.to);
-    if (!addr) {
-      return {
-        content: [{ type: "text" as const, text: `Agent "${params.to}" not found. Use xmtp_agents to discover available agents.` }],
-      };
-    }
-    targetAddress = addr;
+  // 当提供 conversationId 时，to 可省略（直接向已有会话发送）
+  if (!params.to && !params.conversationId) {
+    return { content: [{ type: "text" as const, text: "Either 'to' or 'conversationId' must be provided." }], details: null };
   }
 
-  if (targetAddress.toLowerCase() === bridge.address.toLowerCase()) {
-    return { content: [{ type: "text" as const, text: "Cannot send message to yourself." }] };
+  // 解析目标地址（仅在提供 to 时需要）
+  let targetAddress: string | undefined;
+  if (params.to) {
+    if (params.to.startsWith("0x")) {
+      targetAddress = params.to;
+    } else {
+      const addr = registry.getAddress(params.to);
+      if (!addr) {
+        return {
+          content: [{ type: "text" as const, text: `Agent "${params.to}" not found. Use xmtp_agents to discover available agents.` }],
+          details: null,
+        };
+      }
+      targetAddress = addr;
+    }
+
+    if (targetAddress.toLowerCase() === bridge.address.toLowerCase()) {
+      return { content: [{ type: "text" as const, text: "Cannot send message to yourself." }], details: null };
+    }
   }
 
   // Policy 检查
+  const toLabel = params.to ?? params.conversationId!;
   const convId = params.conversationId ?? `dm:${senderAgentId}:${params.to}`;
-  const check = policyEngine.checkOutgoing({ from: senderAgentId, to: params.to, conversationId: convId });
+  const check = policyEngine.checkOutgoing({ from: senderAgentId, to: toLabel, conversationId: convId });
   if (!check.allowed) {
-    return { content: [{ type: "text" as const, text: `Blocked: ${check.reason}` }] };
+    return { content: [{ type: "text" as const, text: `Blocked: ${check.reason}` }], details: null };
   }
 
   try {
-    const result = await bridge.sendMessage(targetAddress, params.message, {
+    const result = await bridge.sendMessage(targetAddress ?? "", params.message, {
       contentType: params.contentType,
       conversationId: params.conversationId,
     });
 
+    const recipientLabel = params.to ?? `conversation ${result.conversationId}`;
     return {
-      content: [{ type: "text" as const, text: `Message sent to ${params.to} (${targetAddress}).` }],
+      content: [{ type: "text" as const, text: `Message sent to ${recipientLabel}.` }],
       details: {
         status: "sent",
         conversationId: result.conversationId,
@@ -62,6 +72,6 @@ export async function handleXmtpSend(
     };
   } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err);
-    return { content: [{ type: "text" as const, text: `Failed to send: ${msg}` }] };
+    return { content: [{ type: "text" as const, text: `Failed to send: ${msg}` }], details: null };
   }
 }

package/src/types.ts

@@ -76,11 +76,20 @@ export interface InboxMessage {
     xmtpAddress: string;
   };
   conversationId: string;
+  isGroup: boolean;
   content: string;
   contentType: A2AContentType;
   timestamp: string;
 }
 
+/** 群聊信息 */
+export interface GroupInfo {
+  conversationId: string;
+  name: string;
+  memberAddresses: string[];
+  createdAt: string;
+}
+
 /** 默认策略配置 */
 export const DEFAULT_POLICY: ConversationPolicy = {
   maxTurns: 10,

package/src/xmtp-bridge.ts

@@ -3,22 +3,26 @@
 // 每个 Agent 对应一个 XMTP Client，消息 stream + 收件箱缓存
 // ============================================================
 
-import { Agent, createUser, createSigner, IdentifierKind } from "@xmtp/agent-sdk";
+import { Agent, createUser, createSigner } from "@xmtp/agent-sdk";
 import type { IdentityRegistry } from "./identity-registry.js";
 import { PolicyEngine } from "./policy-engine.js";
-import type { XmtpWalletConfig, InboxMessage, A2AContentType } from "./types.js";
-import { createA2APayload, formatA2AMessage } from "./types.js";
+import type { XmtpWalletConfig, InboxMessage, A2AContentType, A2AInjectPayload, GroupInfo } from "./types.js";
+import { createA2APayload } from "./types.js";
+
+/** IdentifierKind.Ethereum = 0 (const enum, 不能在 isolatedModules 下直接访问) */
+const IDENTIFIER_KIND_ETHEREUM = 0;
 
 export class XmtpBridge {
   private agent: InstanceType<typeof Agent> | null = null;
   private running = false;
+  private syncTimer: ReturnType<typeof setInterval> | null = null;
 
   /** 收件箱缓存 */
   private inboxBuffer: InboxMessage[] = [];
   private readonly maxInboxBuffer = 100;
 
-  /** 消息回调（由 plugin 入口设置，用于注入 session） */
-  onMessage?: (agentId: string, formattedMessage: string) => void;
+  /** 消息回调（由 plugin 入口设置，用于触发 subagent 处理） */
+  onMessage?: (agentId: string, payload: A2AInjectPayload) => void;
 
   constructor(
     readonly agentId: string,
@@ -40,7 +44,7 @@ export class XmtpBridge {
       dbPath: `${this.dbPath}/${this.agentId}`,
     });
 
-    await this.registry.updateInboxId(this.agentId, this.agent.address);
+    await this.registry.updateInboxId(this.agentId, this.agent.address!);
 
     this.agent.on("text", async (ctx: any) => {
       await this.handleIncoming(ctx, "text");
@@ -52,10 +56,21 @@ export class XmtpBridge {
 
     await this.agent.start();
     this.running = true;
+
+    // 定期同步会话列表，发现被外部添加到的新群聊（每 30 秒）
+    this.syncTimer = setInterval(async () => {
+      try {
+        await this.agent?.client.conversations.sync();
+      } catch { /* 同步失败不影响正常运行 */ }
+    }, 30_000);
   }
 
   async stop(): Promise<void> {
     if (!this.running || !this.agent) return;
+    if (this.syncTimer) {
+      clearInterval(this.syncTimer);
+      this.syncTimer = null;
+    }
     await this.agent.stop();
     this.running = false;
   }
@@ -96,16 +111,97 @@ export class XmtpBridge {
     return messages.slice(0, limit);
   }
 
-  async createGroup(memberAddresses: string[]): Promise<string> {
+  async createGroup(memberAddresses: string[], name?: string): Promise<{ conversationId: string; name: string }> {
+    if (!this.agent) throw new Error(`Bridge for ${this.agentId} not started`);
+    const opts = name ? { groupName: name } : undefined;
+    const group = await (this.agent as any).createGroupWithAddresses(memberAddresses, opts);
+    if (name) {
+      try { await group.updateName(name); } catch { /* 部分 SDK 版本 createGroupWithAddresses 不支持 opts */ }
+    }
+    return { conversationId: group.id, name: group.name ?? name ?? "" };
+  }
+
+  async listGroups(): Promise<GroupInfo[]> {
+    if (!this.agent) throw new Error(`Bridge for ${this.agentId} not started`);
+    const conversations = await this.agent.client.conversations.list();
+    const groups: GroupInfo[] = [];
+    for (const conv of conversations) {
+      const meta = await conv.metadata();
+      if (meta.conversationType !== 1) continue; // 1 = Group, 0 = Dm
+      const members = await conv.members();
+      groups.push({
+        conversationId: conv.id,
+        name: (conv as any).name ?? "",
+        memberAddresses: members.map((m: any) =>
+          m.accountAddresses?.[0]?.toLowerCase() ?? m.inboxId,
+        ),
+        createdAt: conv.createdAt.toISOString(),
+      });
+    }
+    return groups;
+  }
+
+  async getGroupMembers(conversationId: string): Promise<string[]> {
     if (!this.agent) throw new Error(`Bridge for ${this.agentId} not started`);
-    const group = await (this.agent as any).createGroupWithAddresses(memberAddresses);
-    return group.id;
+    const conv = await this.agent.client.conversations.getConversationById(conversationId);
+    if (!conv) throw new Error(`Conversation ${conversationId} not found`);
+    const members = await conv.members();
+    return members.map((m: any) => m.accountAddresses?.[0]?.toLowerCase() ?? m.inboxId);
+  }
+
+  async addGroupMembers(conversationId: string, addresses: string[]): Promise<void> {
+    if (!this.agent) throw new Error(`Bridge for ${this.agentId} not started`);
+    const conv = await this.agent.client.conversations.getConversationById(conversationId);
+    if (!conv) throw new Error(`Conversation ${conversationId} not found`);
+    const identifiers = addresses.map((addr) => ({
+      identifier: addr,
+      identifierKind: IDENTIFIER_KIND_ETHEREUM,
+    }));
+    await (conv as any).addMembersByIdentifiers(identifiers);
+  }
+
+  async removeGroupMembers(conversationId: string, addresses: string[]): Promise<void> {
+    if (!this.agent) throw new Error(`Bridge for ${this.agentId} not started`);
+    const conv = await this.agent.client.conversations.getConversationById(conversationId);
+    if (!conv) throw new Error(`Conversation ${conversationId} not found`);
+    const identifiers = addresses.map((addr) => ({
+      identifier: addr,
+      identifierKind: IDENTIFIER_KIND_ETHEREUM,
+    }));
+    await (conv as any).removeMembersByIdentifiers(identifiers);
+  }
+
+  /**
+   * 检查群聊中在 afterTimestamp 之后是否有新消息（排除自身和指定 sender）
+   * 用于防止多 agent 同时回复同一条消息
+   */
+  async hasNewGroupReplies(
+    conversationId: string,
+    afterTimestamp: string,
+    excludeAddresses: string[],
+  ): Promise<boolean> {
+    if (!this.agent) return false;
+    try {
+      const conv = await this.agent.client.conversations.getConversationById(conversationId);
+      if (!conv) return false;
+      await conv.sync();
+      const messages = await conv.messages({ limit: BigInt(10) as any });
+      const cutoffMs = new Date(afterTimestamp).getTime();
+      const excluded = new Set(excludeAddresses.map((a) => a.toLowerCase()));
+      return messages.some((m: any) => {
+        const sentMs = Number(BigInt(m.sentAtNs) / 1_000_000n);
+        const sender = (m.senderInboxId ?? m.senderAddress ?? "").toLowerCase();
+        return sentMs > cutoffMs && !excluded.has(sender);
+      });
+    } catch {
+      return false;
+    }
   }
 
   async canMessage(address: string): Promise<boolean> {
     if (!this.agent) return false;
     const result = await this.agent.client.canMessage([
-      { identifier: address, identifierKind: IdentifierKind.Ethereum },
+      { identifier: address, identifierKind: IDENTIFIER_KIND_ETHEREUM },
     ]);
     return result.get(address.toLowerCase()) ?? false;
   }
@@ -130,12 +226,24 @@ export class XmtpBridge {
 
     this.policyEngine.recordTurn(ctx.conversation.id, depth + 1);
 
+    // 群聊时获取参与者列表
+    let participants: string[] = [];
+    const isGroup = ctx.conversation.isGroup ?? false;
+    if (isGroup) {
+      try {
+        const members = await ctx.conversation.members();
+        participants = members.map((m: any) =>
+          m.accountAddresses?.[0]?.toLowerCase() ?? m.inboxId,
+        );
+      } catch { /* 获取成员失败时保持空数组 */ }
+    }
+
     const payload = createA2APayload({
       fromAgentId: senderAgentId,
       fromAddress: senderAddress,
       conversationId: ctx.conversation.id,
-      isGroup: ctx.conversation.isGroup ?? false,
-      participants: [],
+      isGroup,
+      participants,
       messageId: ctx.message.id ?? crypto.randomUUID(),
       content: String(ctx.message.content),
       contentType,
@@ -148,15 +256,16 @@ export class XmtpBridge {
       id: payload.message.id,
       from: { agentId: senderAgentId, xmtpAddress: senderAddress },
       conversationId: ctx.conversation.id,
+      isGroup,
       content: String(ctx.message.content),
       contentType,
       timestamp: payload.timestamp,
     });
     if (this.inboxBuffer.length > this.maxInboxBuffer) this.inboxBuffer.pop();
 
-    // 通知 plugin 层
+    // 通知 plugin 层（传递结构化 payload，由调用方决定如何处理）
     if (this.onMessage) {
-      this.onMessage(this.agentId, formatA2AMessage(payload));
+      this.onMessage(this.agentId, payload);
     }
   }