a2a-xmtp 1.3.0 → 1.4.0

package/src/coordination/policy-engine.ts

@@ -0,0 +1,120 @@
+// ============================================================
+// Module 5: Policy Engine
+// 三重保护：Turn Budget / Cool-down / Consent
+// Depth Guard 已移除，由 GroupScheduler round-robin + turn budget 取代
+// ============================================================
+
+import type { ConversationPolicy, ConversationState, ConsentState } from "../types.js";
+
+export interface PolicyCheckParams {
+  from: string;
+  to: string;
+  conversationId: string;
+}
+
+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)` };
+    }
+
+    return { allowed: true };
+  }
+
+  recordTurn(conversationId: string): void {
+    const state = this.getOrCreateState(conversationId);
+    state.turn += 1;
+    state.lastSendTime = Date.now();
+  }
+
+  /** 检查此 agent 在该会话中的 turn 是否已用完 */
+  isTurnExhausted(conversationId: string): boolean {
+    const state = this.conversations.get(conversationId);
+    if (!state) return false;
+    return state.turn >= this.policy.maxTurns;
+  }
+
+  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, lastSendTime: 0, createdAt: Date.now() };
+      this.conversations.set(conversationId, state);
+    }
+    return state;
+  }
+}

package/src/index.ts

@@ -0,0 +1,216 @@
+// ============================================================
+// Module 1: Plugin 入口
+// 使用 OpenClaw Plugin SDK 真实 API
+// ============================================================
+
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { Type } from "@sinclair/typebox";
+import { IdentityRegistry } from "./transport/identity-registry.js";
+import { PolicyEngine } from "./coordination/policy-engine.js";
+import { GroupScheduler } from "./coordination/group-scheduler.js";
+import { MessageOrchestrator } from "./coordination/message-orchestrator.js";
+import { XmtpBridge } from "./transport/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 { handleXmtpGroup } from "./tools/xmtp-group.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",
+      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.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. 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" };
+        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.",
+      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",
+      label: "Discover 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);
+      },
+    });
+
+    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({
+      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,
+            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,
+          },
+          groupScheduling: {
+            baseDelayMs: pluginCfg?.groupScheduling?.baseDelayMs ?? DEFAULT_PLUGIN_CONFIG.groupScheduling.baseDelayMs,
+            slotTimeoutMs: pluginCfg?.groupScheduling?.slotTimeoutMs ?? DEFAULT_PLUGIN_CONFIG.groupScheduling.slotTimeoutMs,
+            claimExpireMs: pluginCfg?.groupScheduling?.claimExpireMs ?? DEFAULT_PLUGIN_CONFIG.groupScheduling.claimExpireMs,
+          },
+          walletKey: pluginCfg?.walletKey,
+        };
+
+        // 初始化核心组件
+        registry = new IdentityRegistry(ctx.stateDir, config.xmtp.env);
+        policyEngine = new PolicyEngine(config.policy);
+
+        // 初始化群聊调度器和消息编排器
+        const groupScheduler = new GroupScheduler(config.groupScheduling);
+        const orchestrator = new MessageOrchestrator(
+          api.runtime.subagent,
+          ctx.logger,
+          policyEngine,
+          groupScheduler,
+        );
+
+        // 初始化主 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,
+          );
+
+          // 消息回调：委托给 orchestrator 处理
+          bridge.onMessage = (agentId, payload) =>
+            orchestrator.handleMessage(bridge, agentId, payload);
+
+          // Claim 回调：通知 orchestrator 取消 failover 等待
+          bridge.onClaim = (conversationId, senderAddress, messageId) =>
+            orchestrator.handleClaim(conversationId, senderAddress, messageId);
+
+          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/tools/xmtp-agents.ts

@@ -0,0 +1,38 @@
+// ============================================================
+// Tool: xmtp_agents — 发现可通信的 Agent
+// ============================================================
+
+import type { XmtpBridge } from "../transport/xmtp-bridge.js";
+import type { IdentityRegistry } from "../transport/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-group.ts

@@ -0,0 +1,153 @@
+// ============================================================
+// Tool: xmtp_group — 群聊管理（创建、列表、成员查看/添加/移除）
+// ============================================================
+
+import type { XmtpBridge } from "../transport/xmtp-bridge.js";
+import type { IdentityRegistry } from "../transport/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

@@ -0,0 +1,47 @@
+// ============================================================
+// Tool: xmtp_inbox — 查看 XMTP 收件箱消息
+// ============================================================
+
+import type { XmtpBridge } from "../transport/xmtp-bridge.js";
+import type { IdentityRegistry } from "../transport/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." }], details: null };
+  }
+
+  // 解析 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." }], details: null };
+    }
+
+    const lines = messages.map((m, i) => {
+      const sender = m.from.agentId ?? m.from.xmtpAddress;
+      const groupTag = m.isGroup ? " [group]" : "";
+      return `${i + 1}. [${m.timestamp}]${groupTag} 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}` }], details: null };
+  }
+}

package/src/tools/xmtp-send.ts

@@ -0,0 +1,77 @@
+// ============================================================
+// Tool: xmtp_send — 发送 E2EE 消息到另一个 Agent
+// ============================================================
+
+import type { XmtpBridge } from "../transport/xmtp-bridge.js";
+import type { IdentityRegistry } from "../transport/identity-registry.js";
+import type { PolicyEngine } from "../coordination/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." }], details: null };
+  }
+
+  // 当提供 conversationId 时，to 可省略（直接向已有会话发送）
+  if (!params.to && !params.conversationId) {
+    return { content: [{ type: "text" as const, text: "Either 'to' or 'conversationId' must be provided." }], details: null };
+  }
+
+  // 解析目标地址（仅在提供 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: toLabel, conversationId: convId });
+  if (!check.allowed) {
+    return { content: [{ type: "text" as const, text: `Blocked: ${check.reason}` }], details: null };
+  }
+
+  try {
+    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 ${recipientLabel}.` }],
+      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}` }], details: null };
+  }
+}