a2a-xmtp 1.0.1 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2a-xmtp",
-  "version": "1.0.1",
+  "version": "1.1.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
 
@@ -33,15 +34,15 @@ export default definePluginEntry({
         "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);
       },
     });
@@ -77,6 +78,23 @@ export default definePluginEntry({
       },
     });
 
+    api.registerTool({
+      name: "xmtp_group",
+      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 +159,73 @@ 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;
+
+            const extraSystemPrompt = [
+              `你收到了一条 XMTP 消息，来自 ${senderLabel}。`,
+              payload.conversation.isGroup
+                ? `这是群聊，参与者: ${payload.conversation.participants.join(", ")}。`
+                : `这是私聊。`,
+              `请直接用文本回复，不要调用任何工具（不要调用 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; // 没有有效文本则不回复
+                  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,152 @@
+// ============================================================
+// 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." }] };
+  }
+
+  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." }] };
+        }
+        // 解析成员地址
+        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.` }] };
+            }
+            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." }] };
+        }
+        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." }] };
+        }
+        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." }] };
+        }
+        if (!params.members?.length) {
+          return { content: [{ type: "text" as const, text: "Parameter 'members' is required for add_member action." }] };
+        }
+        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.` }] };
+            }
+            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." }] };
+        }
+        if (!params.members?.length) {
+          return { content: [{ type: "text" as const, text: "Parameter 'members' is required for remove_member action." }] };
+        }
+        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.` }] };
+            }
+            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.` }],
+        };
+    }
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text" as const, text: `Group operation failed: ${msg}` }] };
+  }
+}

package/src/tools/xmtp-send.ts

@@ -10,7 +10,7 @@ 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）
@@ -19,39 +19,48 @@ export async function handleXmtpSend(
     return { content: [{ type: "text" as const, text: "No XMTP bridge available. Plugin not initialized." }] };
   }
 
-  // 解析目标地址
-  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." }] };
   }
 
-  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.` }],
+        };
+      }
+      targetAddress = addr;
+    }
+
+    if (targetAddress.toLowerCase() === bridge.address.toLowerCase()) {
+      return { content: [{ type: "text" as const, text: "Cannot send message to yourself." }] };
+    }
   }
 
   // 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}` }] };
   }
 
   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,

package/src/types.ts

@@ -81,6 +81,14 @@ export interface InboxMessage {
   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

@@ -6,19 +6,20 @@
 import { Agent, createUser, createSigner, IdentifierKind } 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";
 
 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,
@@ -52,10 +53,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,10 +108,64 @@ 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: IdentifierKind.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: IdentifierKind.Ethereum,
+    }));
+    await (conv as any).removeMembersByIdentifiers(identifiers);
   }
 
   async canMessage(address: string): Promise<boolean> {
@@ -130,12 +196,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,
@@ -154,9 +232,9 @@ export class XmtpBridge {
     });
     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);
     }
   }