a2a-xmtp 1.4.5 → 2.0.0

package/src/transport/xmtp-bridge.ts

@@ -1,330 +0,0 @@
-// ============================================================
-// Module 2: XMTP Bridge Service
-// 每个 Agent 对应一个 XMTP Client，消息 stream + 收件箱缓存
-// ============================================================
-
-import { Agent, createUser, createSigner } from "@xmtp/agent-sdk";
-import type { IdentityRegistry } from "./identity-registry.js";
-import { PolicyEngine } from "../coordination/policy-engine.js";
-import type { XmtpWalletConfig, InboxMessage, A2AContentType, A2AInjectPayload, GroupInfo } from "../types.js";
-import { createA2APayload, CLAIM_PREFIX, type GroupParticipant } from "../types.js";
-import { GroupScheduler } from "../coordination/group-scheduler.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 入口设置，用于触发 subagent 处理） */
-  onMessage?: (agentId: string, payload: A2AInjectPayload) => void;
-
-  /** Claim 消息回调（由 orchestrator 设置，用于群聊调度） */
-  onClaim?: (conversationId: string, senderAddress: string, messageId: string) => void;
-
-  /** 群聊 self 消息计数回调（由 orchestrator 设置，用于 round-robin 同步） */
-  onSelfGroupMessage?: (conversationId: 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;
-
-    // 定期同步会话列表，发现被外部添加到的新群聊（每 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;
-  }
-
-  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) };
-  }
-
-  /**
-   * 发送 claim 消息到群聊，表明本 agent 将要回复。
-   */
-  async sendClaim(conversationId: string, messageId: string): Promise<string> {
-    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 claimText = GroupScheduler.formatClaimMessage(messageId);
-    const claimMsgId = await conv.sendText(claimText);
-    return String(claimMsgId);
-  }
-
-  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);
-  }
-
-  /**
-   * 获取指定会话的最近消息（供 coordination 层查询）
-   */
-  getRecentMessages(conversationId: string, limit: number): InboxMessage[] {
-    return this.inboxBuffer
-      .filter((m) => m.conversationId === conversationId)
-      .slice(0, limit);
-  }
-
-  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 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: IDENTIFIER_KIND_ETHEREUM },
-    ]);
-    return result.get(address.toLowerCase()) ?? false;
-  }
-
-  private async handleIncoming(ctx: any, contentType: A2AContentType): Promise<void> {
-    const senderAddress: string = await ctx.getSenderAddress();
-    const isSelf = senderAddress.toLowerCase() === this.address.toLowerCase();
-    const content = String(ctx.message.content);
-
-    // 识别 claim 消息：不计数、不缓存、通知调度器
-    if (GroupScheduler.isClaimMessage(content)) {
-      const claimedMsgId = GroupScheduler.parseClaimMessageId(content);
-      if (this.onClaim && claimedMsgId) {
-        this.onClaim(ctx.conversation.id, senderAddress, claimedMsgId);
-      }
-      return;
-    }
-
-    // 群聊 self 消息：仅计数（保持 messageCount 同步），不触发响应
-    const isGroup = ctx.conversation.isGroup ?? false;
-    if (isSelf) {
-      if (isGroup && this.onSelfGroupMessage) {
-        this.onSelfGroupMessage(ctx.conversation.id);
-      }
-      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;
-
-    // 群聊时获取参与者列表（含角色信息）
-    let participants: string[] = [];
-    let participantDetails: GroupParticipant[] | undefined;
-    if (isGroup) {
-      try {
-        const members = await ctx.conversation.members();
-        participants = members.map((m: any) =>
-          m.accountAddresses?.[0]?.toLowerCase() ?? m.inboxId,
-        );
-        participantDetails = members.map((m: any) => ({
-          address: (m.accountAddresses?.[0]?.toLowerCase() ?? m.inboxId) as string,
-          permissionLevel: (m.permissionLevel ?? 0) as number,
-        }));
-      } catch { /* 获取成员失败时保持空数组 */ }
-    }
-
-    const payload = createA2APayload({
-      fromAgentId: senderAgentId,
-      fromAddress: senderAddress,
-      conversationId: ctx.conversation.id,
-      isGroup,
-      participants,
-      participantDetails,
-      messageId: ctx.message.id ?? crypto.randomUUID(),
-      content,
-      contentType,
-      turn: turn + 1,
-    });
-
-    // 缓存到 inbox
-    this.inboxBuffer.unshift({
-      id: payload.message.id,
-      from: { agentId: senderAgentId, xmtpAddress: senderAddress },
-      conversationId: ctx.conversation.id,
-      isGroup,
-      content,
-      contentType,
-      timestamp: payload.timestamp,
-    });
-    if (this.inboxBuffer.length > this.maxInboxBuffer) this.inboxBuffer.pop();
-
-    // 通知 plugin 层（传递结构化 payload，由调用方决定如何处理）
-    if (this.onMessage) {
-      this.onMessage(this.agentId, payload);
-    }
-  }
-
-  get address(): string {
-    return this.agent?.address ?? this.walletConfig.address;
-  }
-
-  get isConnected(): boolean {
-    return this.running;
-  }
-
-  get env() {
-    return this.walletConfig.env;
-  }
-}

package/src/types.ts

@@ -1,192 +0,0 @@
-// ============================================================
-// Module 6: 类型定义 & 消息协议适配
-// ============================================================
-
-/** Agent 的 XMTP 钱包配置 */
-export interface XmtpWalletConfig {
-  privateKey: string;
-  address: string;
-  xmtpInboxId: string;
-  env: XmtpEnv;
-}
-
-export type XmtpEnv = "dev" | "production";
-
-/** 群成员信息（含角色） */
-export interface GroupParticipant {
-  address: string;
-  /** XMTP PermissionLevel: 0=Member, 1=Admin, 2=SuperAdmin */
-  permissionLevel: number;
-}
-
-/** 注入 Agent session 的消息格式 */
-export interface A2AInjectPayload {
-  type: "a2a-xmtp";
-  from: {
-    agentId: string | null;
-    xmtpAddress: string;
-    displayName?: string;
-  };
-  conversation: {
-    id: string;
-    isGroup: boolean;
-    participants: string[];
-    /** 群成员详细信息（含角色），仅群聊时有值 */
-    participantDetails?: GroupParticipant[];
-  };
-  message: {
-    id: string;
-    content: string;
-    contentType: A2AContentType;
-    turn: number;
-    replyTo?: string;
-  };
-  timestamp: string;
-}
-
-export type A2AContentType = "text" | "markdown" | "transaction" | "action";
-
-/** 防循环策略配置 */
-export interface ConversationPolicy {
-  maxTurns: number;
-  minIntervalMs: number;
-  ttlMinutes: number;
-  consentMode: ConsentMode;
-}
-
-/** 群聊调度配置 */
-export interface GroupSchedulingConfig {
-  /** 指定回复者发送 claim 前的基础延迟。Default: 1000ms */
-  baseDelayMs: number;
-  /** 等待前一个 slot 发送 claim 的超时时间。Default: 6000ms */
-  slotTimeoutMs: number;
-  /** 看到 claim 后等待实际回复的最大时间。Default: 30000ms */
-  claimExpireMs: number;
-}
-
-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;
-  groupScheduling: GroupSchedulingConfig;
-  walletKey?: string;
-}
-
-/** 会话状态（Policy Engine 内部使用） */
-export interface ConversationState {
-  turn: number;
-  lastSendTime: number;
-  createdAt: number;
-}
-
-/** 群聊调度状态（per-conversation） */
-export interface GroupConversationState {
-  /** 固定发言顺序（首次计算后缓存） */
-  speakingOrder: string[];
-  /** 已收到的非 claim 消息计数 */
-  messageCount: number;
-  /** 最近一次 claim 信息 */
-  lastClaim: { sender: string; timestamp: number; messageId: string } | null;
-}
-
-/** Claim 消息前缀（可见标记，避免 XMTP 传输时被 strip） */
-export const CLAIM_PREFIX = "__CLAIM__:";
-
-/** 默认群聊调度配置 */
-export const DEFAULT_GROUP_SCHEDULING: GroupSchedulingConfig = {
-  baseDelayMs: 1000,
-  slotTimeoutMs: 6000,
-  claimExpireMs: 30000,
-};
-
-/** 收件箱消息 */
-export interface InboxMessage {
-  id: string;
-  from: {
-    agentId: string | null;
-    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,
-  minIntervalMs: 5000,
-  ttlMinutes: 60,
-  consentMode: "auto-allow-local",
-};
-
-/** 默认插件配置 */
-export const DEFAULT_PLUGIN_CONFIG: PluginConfig = {
-  xmtp: {
-    env: "dev",
-    dbPath: "./xmtp-data",
-  },
-  policy: DEFAULT_POLICY,
-  groupScheduling: DEFAULT_GROUP_SCHEDULING,
-};
-
-/** 格式化 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[];
-  participantDetails?: GroupParticipant[];
-  messageId: string;
-  content: string;
-  contentType: A2AContentType;
-  turn: 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,
-      participantDetails: params.participantDetails,
-    },
-    message: {
-      id: params.messageId,
-      content: params.content,
-      contentType: params.contentType,
-      turn: params.turn,
-      replyTo: params.replyTo,
-    },
-    timestamp: new Date().toISOString(),
-  };
-}