a2a-xmtp 1.0.1

package/README.md

@@ -0,0 +1,105 @@
+# a2a-xmtp
+
+Decentralized Agent-to-Agent E2EE messaging for [OpenClaw](https://openclaw.ai) via [XMTP](https://xmtp.org) protocol.
+
+## 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`
+
+## Install
+
+```bash
+openclaw plugins install a2a-xmtp
+chown -R root:root ~/.openclaw/extensions/a2a-xmtp/
+
+Configure
+
+Edit ~/.openclaw/openclaw.json:
+
+{
+"tools": {
+  "profile": "full"
+},
+"plugins": {
+  "entries": {
+    "a2a-xmtp": {
+      "enabled": true,
+      "config": {
+        "xmtp": {
+          "env": "dev",
+          "dbPath": "/root/.openclaw/xmtp-data"
+        }
+      }
+    }
+  }
+}
+}
+
+Then restart:
+
+mkdir -p /root/.openclaw/xmtp-data
+openclaw gateway restart
+
+Verify
+
+# Check plugin loaded
+openclaw plugins list | grep a2a-xmtp
+
+# Check bridge status (replace TOKEN with your gateway auth token)
+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:
+
+{
+"plugin": "a2a-xmtp",
+"bridgeCount": 1,
+"agents": [{"agentId": "main", "xmtpAddress": "0x...", "connected": true}]
+}
+
+Usage
+
+Talk to your Agent via Telegram or any OpenClaw channel:
+
+┌─────────────────┬──────────────────────────────────────────┐
+│     Command     │                 Example                  │
+├─────────────────┼──────────────────────────────────────────┤
+│ Discover agents │ "使用 xmtp_agents 列出可通信的 Agent"    │
+├─────────────────┼──────────────────────────────────────────┤
+│ Send message    │ "使用 xmtp_send 给 0xAddress 发送 Hello" │
+├─────────────────┼──────────────────────────────────────────┤
+│ Check inbox     │ "使用 xmtp_inbox 查看消息"               │
+└─────────────────┴──────────────────────────────────────────┘
+
+Cross-Server Communication
+
+Two OpenClaw agents on different servers can message each other — just exchange XMTP addresses:
+
+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
+
+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
+
+MIT

package/openclaw.plugin.json

@@ -0,0 +1,45 @@
+{
+  "id": "a2a-xmtp",
+  "name": "Agent-to-Agent IM (XMTP)",
+  "description": "Decentralized Agent-to-Agent E2EE messaging powered by XMTP protocol",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "xmtp": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "env": {
+            "type": "string",
+            "enum": ["dev", "production"],
+            "default": "dev"
+          },
+          "dbPath": {
+            "type": "string",
+            "default": "./xmtp-data"
+          }
+        }
+      },
+      "policy": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "maxTurns": { "type": "number", "default": 10 },
+          "maxDepth": { "type": "number", "default": 5 },
+          "minIntervalMs": { "type": "number", "default": 5000 },
+          "ttlMinutes": { "type": "number", "default": 60 },
+          "consentMode": {
+            "type": "string",
+            "enum": ["auto-allow-local", "explicit-only"],
+            "default": "auto-allow-local"
+          }
+        }
+      },
+      "walletKey": {
+        "type": "string",
+        "description": "Optional: pre-existing XMTP wallet private key (hex). If omitted, auto-generated."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "a2a-xmtp",
+  "version": "1.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@xmtp/agent-sdk": "^2.3.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "description": "Decentralized Agent-to-Agent E2EE messaging for OpenClaw via XMTP",
+  "keywords": [
+    "openclaw",
+    "xmtp",
+    "a2a",
+    "agent",
+    "messaging",
+    "e2ee",
+    "web3"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "openclaw.plugin.json",
+    "package.json",
+    "README.md"
+  ]
+}

package/src/identity-registry.ts

@@ -0,0 +1,134 @@
+// ============================================================
+// Module 3: Identity Registry
+// agentId ↔ XMTP wallet address 双向映射，wallet key 生成/加载
+// 使用文件系统持久化（stateDir）
+// ============================================================
+
+import { createUser, createSigner } from "@xmtp/agent-sdk";
+import { privateKeyToAccount } from "viem/accounts";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import type { XmtpWalletConfig, XmtpEnv } from "./types.js";
+
+export class IdentityRegistry {
+  private agentToConfig = new Map<string, XmtpWalletConfig>();
+  private addressToAgent = new Map<string, string>();
+  private storePath: string;
+
+  constructor(
+    stateDir: string,
+    private env: XmtpEnv = "dev",
+  ) {
+    this.storePath = join(stateDir, "identities");
+    mkdirSync(this.storePath, { recursive: true });
+    this.loadFromDisk();
+  }
+
+  /**
+   * 为 Agent 初始化 XMTP wallet。
+   * 如果已有配置则加载，否则生成新的 wallet。
+   */
+  async initAgent(agentId: string, existingKey?: string): Promise<XmtpWalletConfig> {
+    const cached = this.agentToConfig.get(agentId);
+    if (cached) return cached;
+
+    // 尝试从磁盘加载
+    const filePath = join(this.storePath, `${agentId}.json`);
+    if (existsSync(filePath)) {
+      const config: XmtpWalletConfig = JSON.parse(readFileSync(filePath, "utf-8"));
+      this.cacheMapping(agentId, config);
+      return config;
+    }
+
+    // 生成新 wallet 或使用提供的 key
+    let privateKey: string;
+    let address: string;
+
+    if (existingKey) {
+      privateKey = existingKey;
+      const account = privateKeyToAccount(existingKey as `0x${string}`);
+      address = account.address;
+    } else {
+      const user = createUser();
+      privateKey = user.key;            // createUser() returns { key, account, wallet }
+      address = user.account.address;
+    }
+
+    const config: XmtpWalletConfig = {
+      privateKey,
+      address,
+      xmtpInboxId: "",
+      env: this.env,
+    };
+
+    // 持久化到磁盘
+    writeFileSync(filePath, JSON.stringify(config, null, 2));
+    this.cacheMapping(agentId, config);
+
+    return config;
+  }
+
+  /** 更新 inboxId */
+  async updateInboxId(agentId: string, inboxId: string): Promise<void> {
+    const config = this.agentToConfig.get(agentId);
+    if (!config) return;
+    config.xmtpInboxId = inboxId;
+    const filePath = join(this.storePath, `${agentId}.json`);
+    writeFileSync(filePath, JSON.stringify(config, null, 2));
+  }
+
+  getAddress(agentId: string): string | undefined {
+    return this.agentToConfig.get(agentId)?.address;
+  }
+
+  getConfig(agentId: string): XmtpWalletConfig | undefined {
+    return this.agentToConfig.get(agentId);
+  }
+
+  getAgentId(address: string): string | undefined {
+    return this.addressToAgent.get(address.toLowerCase());
+  }
+
+  async resolveAgentId(address: string): Promise<string | null> {
+    return this.addressToAgent.get(address.toLowerCase()) ?? null;
+  }
+
+  listAgents(): Array<{ agentId: string; address: string; env: XmtpEnv }> {
+    return Array.from(this.agentToConfig.entries()).map(([id, config]) => ({
+      agentId: id,
+      address: config.address,
+      env: config.env,
+    }));
+  }
+
+  has(agentId: string): boolean {
+    return this.agentToConfig.has(agentId);
+  }
+
+  registerExternal(address: string, agentId: string): void {
+    this.addressToAgent.set(address.toLowerCase(), agentId);
+  }
+
+  private cacheMapping(agentId: string, config: XmtpWalletConfig): void {
+    this.agentToConfig.set(agentId, config);
+    this.addressToAgent.set(config.address.toLowerCase(), agentId);
+  }
+
+  /** 从磁盘加载所有已有 identity */
+  private loadFromDisk(): void {
+    if (!existsSync(this.storePath)) return;
+    const { readdirSync } = require("node:fs") as typeof import("node:fs");
+    for (const file of readdirSync(this.storePath)) {
+      if (!file.endsWith(".json")) continue;
+      const agentId = file.replace(".json", "");
+      try {
+        const config: XmtpWalletConfig = JSON.parse(
+          readFileSync(join(this.storePath, file), "utf-8"),
+        );
+        this.cacheMapping(agentId, config);
+      } catch {
+        // skip corrupt files
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,176 @@
+// ============================================================
+// Module 1: Plugin 入口
+// 使用 OpenClaw Plugin SDK 真实 API
+// ============================================================
+
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { Type } from "@sinclair/typebox";
+import { IdentityRegistry } from "./identity-registry.js";
+import { PolicyEngine } from "./policy-engine.js";
+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";
+
+const AGENT_ID = "main"; // OpenClaw 默认 agent
+
+export default definePluginEntry({
+  id: "a2a-xmtp",
+  name: "Agent-to-Agent IM (XMTP)",
+  description: "Decentralized Agent-to-Agent E2EE messaging powered by XMTP protocol",
+
+  register(api) {
+    const bridges = new Map<string, XmtpBridge>();
+    let registry: IdentityRegistry;
+    let policyEngine: PolicyEngine;
+
+    // ── 1. 注册 Tools ──
+
+    api.registerTool({
+      name: "xmtp_send",
+      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...)" }),
+        message: Type.String({ description: "Message content to send" }),
+        conversationId: Type.Optional(Type.String({ description: "Reuse existing conversation" })),
+        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" };
+        return await handleXmtpSend(bridges, registry, policyEngine, p, AGENT_ID);
+      },
+    });
+
+    api.registerTool({
+      name: "xmtp_inbox",
+      description:
+        "Check your XMTP inbox for messages from other agents. " +
+        "Messages are E2E encrypted and only you can read them.",
+      parameters: Type.Object({
+        limit: Type.Optional(Type.Number({ description: "Max messages to return (default: 10)" })),
+        from: Type.Optional(Type.String({ description: "Filter by sender agent ID or address" })),
+      }),
+      async execute(_toolCallId, params) {
+        const p = params as { limit?: number; from?: string };
+        return await handleXmtpInbox(bridges, registry, p, AGENT_ID);
+      },
+    });
+
+    api.registerTool({
+      name: "xmtp_agents",
+      description:
+        "Discover agents available for XMTP communication. " +
+        "Lists registered agents and their connection status.",
+      parameters: Type.Object({
+        includeExternal: Type.Optional(
+          Type.Boolean({ description: "Include ERC-8004 external registry (Phase 3)" }),
+        ),
+      }),
+      async execute(_toolCallId, params) {
+        const p = params as { includeExternal?: boolean };
+        return await handleDiscoverAgents(bridges, registry, p);
+      },
+    });
+
+    // ── 2. 注册 HTTP 状态路由 ──
+
+    api.registerHttpRoute({
+      path: "/a2a-xmtp/status",
+      auth: "gateway",
+      handler: async (_req, res) => {
+        const status = {
+          plugin: "a2a-xmtp",
+          bridgeCount: bridges.size,
+          agents: Array.from(bridges.entries()).map(([id, b]) => ({
+            agentId: id,
+            xmtpAddress: b.address,
+            connected: b.isConnected,
+            env: b.env,
+          })),
+          policy: policyEngine?.getPolicy(),
+        };
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify(status, null, 2));
+        return true;
+      },
+    });
+
+    // ── 3. 注册 Service（生命周期管理） ──
+
+    api.registerService({
+      id: "a2a-xmtp-bridge",
+      async start(ctx) {
+        ctx.logger.info("[a2a-xmtp] Starting XMTP Bridge Service...");
+
+        // 加载配置
+        const pluginCfg = (ctx.config as any)?.plugins?.entries?.["a2a-xmtp"]?.config;
+        const config: PluginConfig = {
+          xmtp: {
+            env: pluginCfg?.xmtp?.env ?? DEFAULT_PLUGIN_CONFIG.xmtp.env,
+            dbPath: pluginCfg?.xmtp?.dbPath ?? DEFAULT_PLUGIN_CONFIG.xmtp.dbPath,
+          },
+          policy: {
+            maxTurns: pluginCfg?.policy?.maxTurns ?? DEFAULT_PLUGIN_CONFIG.policy.maxTurns,
+            maxDepth: pluginCfg?.policy?.maxDepth ?? DEFAULT_PLUGIN_CONFIG.policy.maxDepth,
+            minIntervalMs: pluginCfg?.policy?.minIntervalMs ?? DEFAULT_PLUGIN_CONFIG.policy.minIntervalMs,
+            ttlMinutes: pluginCfg?.policy?.ttlMinutes ?? DEFAULT_PLUGIN_CONFIG.policy.ttlMinutes,
+            consentMode: pluginCfg?.policy?.consentMode ?? DEFAULT_PLUGIN_CONFIG.policy.consentMode,
+          },
+          walletKey: pluginCfg?.walletKey,
+        };
+
+        // 初始化核心组件
+        registry = new IdentityRegistry(ctx.stateDir, config.xmtp.env);
+        policyEngine = new PolicyEngine(config.policy);
+
+        // 初始化主 Agent 的 XMTP Bridge
+        try {
+          const walletConfig = await registry.initAgent(AGENT_ID, config.walletKey);
+          policyEngine.registerLocalAgent(AGENT_ID);
+
+          const bridge = new XmtpBridge(
+            AGENT_ID,
+            walletConfig,
+            policyEngine,
+            registry,
+            config.xmtp.dbPath,
+          );
+
+          // 消息回调：收到 XMTP 消息时记录日志
+          bridge.onMessage = (agentId, message) => {
+            ctx.logger.info(`[a2a-xmtp] Incoming message for ${agentId}: ${message}`);
+          };
+
+          await bridge.start();
+          bridges.set(AGENT_ID, bridge);
+
+          ctx.logger.info(
+            `[a2a-xmtp] Bridge started: ${AGENT_ID} → ${bridge.address} (env: ${config.xmtp.env})`,
+          );
+        } catch (err) {
+          ctx.logger.error(
+            `[a2a-xmtp] Failed to start bridge: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      },
+
+      async stop(ctx) {
+        ctx.logger.info("[a2a-xmtp] Stopping XMTP bridges...");
+        for (const [id, bridge] of bridges) {
+          try {
+            await bridge.stop();
+            ctx.logger.info(`[a2a-xmtp] Bridge stopped: ${id}`);
+          } catch (err) {
+            ctx.logger.error(`[a2a-xmtp] Error stopping bridge ${id}: ${err}`);
+          }
+        }
+        bridges.clear();
+      },
+    });
+  },
+});

package/src/policy-engine.ts

@@ -0,0 +1,121 @@
+// ============================================================
+// Module 5: Policy Engine
+// 四重保护：Turn Budget / Cool-down / Depth Guard / Consent
+// ============================================================
+
+import type { ConversationPolicy, ConversationState, ConsentState } from "./types.js";
+
+export interface PolicyCheckParams {
+  from: string;
+  to: string;
+  conversationId: string;
+  depth?: number;
+}
+
+export interface PolicyCheckResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+export class PolicyEngine {
+  private conversations = new Map<string, ConversationState>();
+  private consents = new Map<string, ConsentState>();
+  private localAgentIds = new Set<string>();
+
+  constructor(private policy: ConversationPolicy) {}
+
+  registerLocalAgent(agentId: string): void {
+    this.localAgentIds.add(agentId);
+  }
+
+  checkOutgoing(params: PolicyCheckParams): PolicyCheckResult {
+    return this.check(params);
+  }
+
+  checkIncoming(params: PolicyCheckParams): PolicyCheckResult {
+    const consent = this.getConsent(params.from);
+    if (consent === "deny") {
+      return { allowed: false, reason: `Sender ${params.from} is denied` };
+    }
+    if (this.policy.consentMode === "explicit-only" && consent !== "allow") {
+      return {
+        allowed: false,
+        reason: `Sender ${params.from} not explicitly allowed (consent: ${consent})`,
+      };
+    }
+    return this.check(params);
+  }
+
+  private check(params: PolicyCheckParams): PolicyCheckResult {
+    const state = this.getOrCreateState(params.conversationId);
+    const now = Date.now();
+
+    const ttlMs = this.policy.ttlMinutes * 60 * 1000;
+    if (now - state.createdAt > ttlMs) {
+      return { allowed: false, reason: `Conversation TTL expired (${this.policy.ttlMinutes} min)` };
+    }
+
+    if (state.turn >= this.policy.maxTurns) {
+      return { allowed: false, reason: `Turn budget exhausted (${state.turn}/${this.policy.maxTurns})` };
+    }
+
+    if (state.lastSendTime > 0 && now - state.lastSendTime < this.policy.minIntervalMs) {
+      return { allowed: false, reason: `Cool-down active (${this.policy.minIntervalMs}ms between sends)` };
+    }
+
+    const depth = params.depth ?? state.depth;
+    if (depth >= this.policy.maxDepth) {
+      return { allowed: false, reason: `Depth limit reached (${depth}/${this.policy.maxDepth})` };
+    }
+
+    return { allowed: true };
+  }
+
+  recordTurn(conversationId: string, depth?: number): void {
+    const state = this.getOrCreateState(conversationId);
+    state.turn += 1;
+    state.lastSendTime = Date.now();
+    if (depth !== undefined) {
+      state.depth = Math.max(state.depth, depth);
+    }
+  }
+
+  getConversationState(conversationId: string): ConversationState | null {
+    return this.conversations.get(conversationId) ?? null;
+  }
+
+  resetConversation(conversationId: string): void {
+    this.conversations.delete(conversationId);
+  }
+
+  setConsent(address: string, consent: ConsentState): void {
+    this.consents.set(address.toLowerCase(), consent);
+  }
+
+  getConsent(identifier: string): ConsentState {
+    const normalized = identifier.toLowerCase();
+    if (this.policy.consentMode === "auto-allow-local" && this.localAgentIds.has(identifier)) {
+      return "allow";
+    }
+    return this.consents.get(normalized) ?? "unknown";
+  }
+
+  loadAclRules(rules: Array<{ address: string; consent: ConsentState }>): void {
+    for (const rule of rules) {
+      this.consents.set(rule.address.toLowerCase(), rule.consent);
+    }
+  }
+
+  getPolicy(): ConversationPolicy {
+    return { ...this.policy };
+  }
+
+  private getOrCreateState(conversationId: string): ConversationState {
+    let state = this.conversations.get(conversationId);
+    if (!state) {
+      state = { turn: 0, depth: 0, lastSendTime: 0, createdAt: Date.now() };
+      this.conversations.set(conversationId, state);
+    }
+    return state;
+  }
+}

package/src/tools/xmtp-agents.ts

@@ -0,0 +1,38 @@
+// ============================================================
+// Tool: xmtp_agents — 发现可通信的 Agent
+// ============================================================
+
+import type { XmtpBridge } from "../xmtp-bridge.js";
+import type { IdentityRegistry } from "../identity-registry.js";
+
+export async function handleDiscoverAgents(
+  bridges: Map<string, XmtpBridge>,
+  registry: IdentityRegistry,
+  params: { includeExternal?: boolean },
+) {
+  const localAgents = registry.listAgents();
+
+  const lines = localAgents.map((agent) => {
+    const bridge = bridges.get(agent.agentId);
+    const status = bridge?.isConnected ? "online" : "offline";
+    return `- ${agent.agentId} (${agent.address}) [${status}]`;
+  });
+
+  let text = `Available agents (${localAgents.length}):\n${lines.join("\n")}`;
+
+  if (params.includeExternal) {
+    text += "\n\nNote: ERC-8004 external registry lookup is planned for Phase 3.";
+  }
+
+  return {
+    content: [{ type: "text" as const, text }],
+    details: {
+      count: localAgents.length,
+      agents: localAgents.map((a) => ({
+        agentId: a.agentId,
+        address: a.address,
+        connected: bridges.get(a.agentId)?.isConnected ?? false,
+      })),
+    },
+  };
+}

package/src/tools/xmtp-inbox.ts

@@ -0,0 +1,46 @@
+// ============================================================
+// Tool: xmtp_inbox — 查看 XMTP 收件箱消息
+// ============================================================
+
+import type { XmtpBridge } from "../xmtp-bridge.js";
+import type { IdentityRegistry } from "../identity-registry.js";
+
+export async function handleXmtpInbox(
+  bridges: Map<string, XmtpBridge>,
+  registry: IdentityRegistry,
+  params: { limit?: number; from?: 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." }] };
+  }
+
+  // 解析 from
+  let fromFilter = params.from;
+  if (fromFilter && !fromFilter.startsWith("0x")) {
+    const addr = registry.getAddress(fromFilter);
+    if (addr) fromFilter = addr;
+  }
+
+  try {
+    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." }] };
+    }
+
+    const lines = messages.map((m, i) => {
+      const sender = m.from.agentId ?? m.from.xmtpAddress;
+      return `${i + 1}. [${m.timestamp}] from ${sender}: ${m.content}`;
+    });
+
+    return {
+      content: [{ type: "text" as const, text: lines.join("\n") }],
+      details: { count: messages.length, myAddress: bridge.address },
+    };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text" as const, text: `Failed to fetch inbox: ${msg}` }] };
+  }
+}

package/src/tools/xmtp-send.ts

@@ -0,0 +1,67 @@
+// ============================================================
+// Tool: xmtp_send — 发送 E2EE 消息到另一个 Agent
+// ============================================================
+
+import type { XmtpBridge } from "../xmtp-bridge.js";
+import type { IdentityRegistry } from "../identity-registry.js";
+import type { PolicyEngine } from "../policy-engine.js";
+
+export async function handleXmtpSend(
+  bridges: Map<string, XmtpBridge>,
+  registry: IdentityRegistry,
+  policyEngine: PolicyEngine,
+  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." }] };
+  }
+
+  // 解析目标地址
+  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;
+  }
+
+  if (targetAddress.toLowerCase() === bridge.address.toLowerCase()) {
+    return { content: [{ type: "text" as const, text: "Cannot send message to yourself." }] };
+  }
+
+  // Policy 检查
+  const convId = params.conversationId ?? `dm:${senderAgentId}:${params.to}`;
+  const check = policyEngine.checkOutgoing({ from: senderAgentId, to: params.to, conversationId: convId });
+  if (!check.allowed) {
+    return { content: [{ type: "text" as const, text: `Blocked: ${check.reason}` }] };
+  }
+
+  try {
+    const result = await bridge.sendMessage(targetAddress, params.message, {
+      contentType: params.contentType,
+      conversationId: params.conversationId,
+    });
+
+    return {
+      content: [{ type: "text" as const, text: `Message sent to ${params.to} (${targetAddress}).` }],
+      details: {
+        status: "sent",
+        conversationId: result.conversationId,
+        messageId: result.messageId,
+        to: params.to,
+        toAddress: targetAddress,
+      },
+    };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text" as const, text: `Failed to send: ${msg}` }] };
+  }
+}

package/src/types.ts

@@ -0,0 +1,146 @@
+// ============================================================
+// Module 6: 类型定义 & 消息协议适配
+// ============================================================
+
+/** Agent 的 XMTP 钱包配置 */
+export interface XmtpWalletConfig {
+  privateKey: string;
+  address: string;
+  xmtpInboxId: string;
+  env: XmtpEnv;
+}
+
+export type XmtpEnv = "dev" | "production";
+
+/** 注入 Agent session 的消息格式 */
+export interface A2AInjectPayload {
+  type: "a2a-xmtp";
+  from: {
+    agentId: string | null;
+    xmtpAddress: string;
+    displayName?: string;
+  };
+  conversation: {
+    id: string;
+    isGroup: boolean;
+    participants: string[];
+  };
+  message: {
+    id: string;
+    content: string;
+    contentType: A2AContentType;
+    turn: number;
+    depth: number;
+    replyTo?: string;
+  };
+  timestamp: string;
+}
+
+export type A2AContentType = "text" | "markdown" | "transaction" | "action";
+
+/** 防循环策略配置 */
+export interface ConversationPolicy {
+  maxTurns: number;
+  maxDepth: number;
+  minIntervalMs: number;
+  ttlMinutes: number;
+  consentMode: ConsentMode;
+}
+
+export type ConsentMode = "auto-allow-local" | "explicit-only";
+export type ConsentState = "allow" | "deny" | "unknown";
+
+/** 插件运行时配置（从 openclaw.json entries.a2a-xmtp.config 解析） */
+export interface PluginConfig {
+  xmtp: {
+    env: XmtpEnv;
+    dbPath: string;
+  };
+  policy: ConversationPolicy;
+  walletKey?: string;
+}
+
+/** 会话状态（Policy Engine 内部使用） */
+export interface ConversationState {
+  turn: number;
+  depth: number;
+  lastSendTime: number;
+  createdAt: number;
+}
+
+/** 收件箱消息 */
+export interface InboxMessage {
+  id: string;
+  from: {
+    agentId: string | null;
+    xmtpAddress: string;
+  };
+  conversationId: string;
+  content: string;
+  contentType: A2AContentType;
+  timestamp: string;
+}
+
+/** 默认策略配置 */
+export const DEFAULT_POLICY: ConversationPolicy = {
+  maxTurns: 10,
+  maxDepth: 5,
+  minIntervalMs: 5000,
+  ttlMinutes: 60,
+  consentMode: "auto-allow-local",
+};
+
+/** 默认插件配置 */
+export const DEFAULT_PLUGIN_CONFIG: PluginConfig = {
+  xmtp: {
+    env: "dev",
+    dbPath: "./xmtp-data",
+  },
+  policy: DEFAULT_POLICY,
+};
+
+/** 格式化 A2A 消息（注入 session 时的文本表示） */
+export function formatA2AMessage(payload: A2AInjectPayload): string {
+  const sender = payload.from.agentId || payload.from.xmtpAddress;
+  const prefix = payload.conversation.isGroup ? "[A2A Group]" : "[A2A]";
+  return `${prefix} from ${sender} (turn ${payload.message.turn}): ${payload.message.content}`;
+}
+
+/** 创建 A2AInjectPayload */
+export function createA2APayload(params: {
+  fromAgentId: string | null;
+  fromAddress: string;
+  conversationId: string;
+  isGroup: boolean;
+  participants: string[];
+  messageId: string;
+  content: string;
+  contentType: A2AContentType;
+  turn: number;
+  depth: number;
+  replyTo?: string;
+  displayName?: string;
+}): A2AInjectPayload {
+  return {
+    type: "a2a-xmtp",
+    from: {
+      agentId: params.fromAgentId,
+      xmtpAddress: params.fromAddress,
+      displayName: params.displayName,
+    },
+    conversation: {
+      id: params.conversationId,
+      isGroup: params.isGroup,
+      participants: params.participants,
+    },
+    message: {
+      id: params.messageId,
+      content: params.content,
+      contentType: params.contentType,
+      turn: params.turn,
+      depth: params.depth,
+      replyTo: params.replyTo,
+    },
+    timestamp: new Date().toISOString(),
+  };
+}

package/src/xmtp-bridge.ts

@@ -0,0 +1,174 @@
+// ============================================================
+// Module 2: XMTP Bridge Service
+// 每个 Agent 对应一个 XMTP Client，消息 stream + 收件箱缓存
+// ============================================================
+
+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";
+
+export class XmtpBridge {
+  private agent: InstanceType<typeof Agent> | null = null;
+  private running = false;
+
+  /** 收件箱缓存 */
+  private inboxBuffer: InboxMessage[] = [];
+  private readonly maxInboxBuffer = 100;
+
+  /** 消息回调（由 plugin 入口设置，用于注入 session） */
+  onMessage?: (agentId: string, formattedMessage: string) => void;
+
+  constructor(
+    readonly agentId: string,
+    private walletConfig: XmtpWalletConfig,
+    private policyEngine: PolicyEngine,
+    private registry: IdentityRegistry,
+    private dbPath: string,
+  ) {}
+
+  async start(): Promise<void> {
+    if (this.running) return;
+
+    // Reconstruct full user from stored key — createUser() accepts an existing private key
+    const user = createUser(this.walletConfig.privateKey as `0x${string}`);
+    const signer = createSigner(user);
+
+    this.agent = await Agent.create(signer, {
+      env: this.walletConfig.env,
+      dbPath: `${this.dbPath}/${this.agentId}`,
+    });
+
+    await this.registry.updateInboxId(this.agentId, this.agent.address);
+
+    this.agent.on("text", async (ctx: any) => {
+      await this.handleIncoming(ctx, "text");
+    });
+
+    this.agent.on("markdown", async (ctx: any) => {
+      await this.handleIncoming(ctx, "markdown");
+    });
+
+    await this.agent.start();
+    this.running = true;
+  }
+
+  async stop(): Promise<void> {
+    if (!this.running || !this.agent) return;
+    await this.agent.stop();
+    this.running = false;
+  }
+
+  async sendMessage(
+    toAddress: string,
+    content: string,
+    opts?: { contentType?: "text" | "markdown"; conversationId?: string },
+  ): Promise<{ conversationId: string; messageId: string }> {
+    if (!this.agent) throw new Error(`Bridge for ${this.agentId} not started`);
+
+    let conversation: any;
+    if (opts?.conversationId) {
+      conversation = await this.agent.client.conversations.getConversationById(opts.conversationId);
+      if (!conversation) throw new Error(`Conversation ${opts.conversationId} not found`);
+    } else {
+      conversation = await (this.agent as any).createDmWithAddress(toAddress);
+    }
+
+    const messageId = opts?.contentType === "markdown"
+      ? await conversation.sendMarkdown(content)
+      : await conversation.sendText(content);
+
+    this.policyEngine.recordTurn(conversation.id);
+
+    return { conversationId: conversation.id, messageId: String(messageId) };
+  }
+
+  async getInbox(opts?: { limit?: number; from?: string }): Promise<InboxMessage[]> {
+    const limit = opts?.limit ?? 10;
+    let messages = [...this.inboxBuffer];
+    if (opts?.from) {
+      const f = opts.from.toLowerCase();
+      messages = messages.filter(
+        (m) => m.from.agentId === opts.from || m.from.xmtpAddress.toLowerCase() === f,
+      );
+    }
+    return messages.slice(0, limit);
+  }
+
+  async createGroup(memberAddresses: 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;
+  }
+
+  async canMessage(address: string): Promise<boolean> {
+    if (!this.agent) return false;
+    const result = await this.agent.client.canMessage([
+      { identifier: address, identifierKind: IdentifierKind.Ethereum },
+    ]);
+    return result.get(address.toLowerCase()) ?? false;
+  }
+
+  private async handleIncoming(ctx: any, contentType: A2AContentType): Promise<void> {
+    const senderAddress: string = await ctx.getSenderAddress();
+
+    if (senderAddress.toLowerCase() === this.address.toLowerCase()) return;
+
+    const senderAgentId = await this.registry.resolveAgentId(senderAddress);
+
+    const policyResult = this.policyEngine.checkIncoming({
+      from: senderAgentId || senderAddress,
+      to: this.agentId,
+      conversationId: ctx.conversation.id,
+    });
+    if (!policyResult.allowed) return;
+
+    const convState = this.policyEngine.getConversationState(ctx.conversation.id);
+    const turn = convState?.turn ?? 0;
+    const depth = convState?.depth ?? 0;
+
+    this.policyEngine.recordTurn(ctx.conversation.id, depth + 1);
+
+    const payload = createA2APayload({
+      fromAgentId: senderAgentId,
+      fromAddress: senderAddress,
+      conversationId: ctx.conversation.id,
+      isGroup: ctx.conversation.isGroup ?? false,
+      participants: [],
+      messageId: ctx.message.id ?? crypto.randomUUID(),
+      content: String(ctx.message.content),
+      contentType,
+      turn: turn + 1,
+      depth: depth + 1,
+    });
+
+    // 缓存到 inbox
+    this.inboxBuffer.unshift({
+      id: payload.message.id,
+      from: { agentId: senderAgentId, xmtpAddress: senderAddress },
+      conversationId: ctx.conversation.id,
+      content: String(ctx.message.content),
+      contentType,
+      timestamp: payload.timestamp,
+    });
+    if (this.inboxBuffer.length > this.maxInboxBuffer) this.inboxBuffer.pop();
+
+    // 通知 plugin 层
+    if (this.onMessage) {
+      this.onMessage(this.agentId, formatA2AMessage(payload));
+    }
+  }
+
+  get address(): string {
+    return this.agent?.address ?? this.walletConfig.address;
+  }
+
+  get isConnected(): boolean {
+    return this.running;
+  }
+
+  get env() {
+    return this.walletConfig.env;
+  }
+}