a2a-xmtp 1.3.1 → 1.4.1

package/README.md

@@ -7,7 +7,7 @@ Decentralized Agent-to-Agent E2EE messaging for [OpenClaw](https://openclaw.ai)
 - **E2EE Messaging** — End-to-end encrypted Agent-to-Agent communication over XMTP
 - **Group Chat** — Create and manage multi-agent group conversations with natural turn-taking
 - **Auto-Reply** — Incoming messages trigger LLM reasoning via subagent, replies sent automatically
-- **Anti-Loop** — 4-layer protection (turn budget, cool-down, depth limit, consent) prevents infinite loops
+- **Anti-Loop** — 3-layer protection (turn budget, cool-down, consent) prevents infinite loops
 - **Cross-Gateway** — Agents on different servers communicate directly, no VPN or API sharing needed
 - **4 Agent Tools** — `xmtp_send`, `xmtp_inbox`, `xmtp_agents`, `xmtp_group`
 
@@ -138,17 +138,17 @@ This works for both DMs and group chats. In group chats, the system prompt inclu
 
 ## Multi-Agent Group Chat
 
-When multiple OpenClaw agents are in the same group, the plugin ensures natural turn-taking:
+When multiple OpenClaw agents are in the same group, the plugin coordinates turn-taking automatically:
 
-- **No parallel replies** — When a human sends a message, agents use random delay + dedup check so only one responds first
-- **Sequential discussion** — After one agent replies, the other naturally follows, creating a back-and-forth discussion
-- **Natural conversation flow** — The LLM is prompted to behave like a human in group chat, only speaking when it has something to add
+- **Deterministic round-robin** — Each message has exactly one designated responder, agents take turns equally
+- **Automatic failover** — If the designated agent is offline, the next agent in line takes over after a timeout
+- **No duplicate replies** — Claim mechanism prevents multiple agents from responding to the same message
 
 ```
 Admin:   "Discuss the pros and cons of Rust vs Go"
-Agent A: "Rust offers memory safety without GC..."     (responds first)
-Agent B: "I agree on safety, but Go's simplicity..."   (follows up)
-Agent A: "Good point. For our use case though..."       (continues)
+Agent A: "Rust offers memory safety without GC..."     (designated for msg #0)
+Agent B: "I agree on safety, but Go's simplicity..."   (designated for msg #1)
+Agent C: "For our use case, Go's concurrency model..." (designated for msg #2)
 ```
 
 ## Cross-Server Communication
@@ -163,16 +163,23 @@ No VPN, no API keys, no shared infrastructure needed.
 
 ## Policy Configuration
 
-Anti-loop protection with 4 guards:
+Anti-loop protection with 3 guards:
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `policy.maxTurns` | 10 | Max turns per conversation |
-| `policy.maxDepth` | 5 | Max reply depth |
+| `policy.maxTurns` | 10 | Max messages this agent can send per conversation |
 | `policy.minIntervalMs` | 5000 | Cool-down between sends (ms) |
 | `policy.ttlMinutes` | 60 | Conversation TTL |
 | `policy.consentMode` | `auto-allow-local` | `auto-allow-local` or `explicit-only` |
 
+Group chat scheduling:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `groupScheduling.baseDelayMs` | 1000 | Delay before designated agent claims a message (ms) |
+| `groupScheduling.slotTimeoutMs` | 6000 | Wait time before next agent takes over (ms) |
+| `groupScheduling.claimExpireMs` | 30000 | Max wait after claim before failover (ms) |
+
 ## Architecture
 
 ```
@@ -184,6 +191,7 @@ Plugin Entry (index.ts)
   │     IdentityRegistry ── agentId <-> wallet mapping
   └── Coordination Layer (coordination/)
         MessageOrchestrator ── message flow, LLM subagent, security
+        GroupScheduler ── round-robin turn-taking, claim, failover
         PolicyEngine ── anti-loop guards, consent
 ```
 

package/openclaw.plugin.json

@@ -26,7 +26,6 @@
         "additionalProperties": false,
         "properties": {
           "maxTurns": { "type": "number", "default": 10 },
-          "maxDepth": { "type": "number", "default": 5 },
           "minIntervalMs": { "type": "number", "default": 5000 },
           "ttlMinutes": { "type": "number", "default": 60 },
           "consentMode": {
@@ -36,6 +35,15 @@
           }
         }
       },
+      "groupScheduling": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "baseDelayMs": { "type": "number", "default": 1000, "description": "Base delay before designated agent claims (ms)" },
+          "slotTimeoutMs": { "type": "number", "default": 6000, "description": "Time to wait for previous slot's claim before promoting (ms)" },
+          "claimExpireMs": { "type": "number", "default": 30000, "description": "Max time after claim before failover (ms)" }
+        }
+      },
       "walletKey": {
         "type": "string",
         "description": "Optional: pre-existing XMTP wallet private key (hex). If omitted, auto-generated."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2a-xmtp",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "type": "module",
   "main": "src/index.ts",
   "description": "Decentralized Agent-to-Agent E2EE messaging for OpenClaw via XMTP",

package/src/coordination/group-scheduler.ts

@@ -0,0 +1,198 @@
+// ============================================================
+// Group Scheduler
+// 固定 Round-Robin 轮询 + Claim 机制的群聊调度器
+// 每个 agent 独立计算相同的发言顺序，确定性地分配回复权
+// ============================================================
+
+import { createHash } from "node:crypto";
+import type { GroupSchedulingConfig, GroupConversationState } from "../types.js";
+import { CLAIM_PREFIX, DEFAULT_GROUP_SCHEDULING } from "../types.js";
+
+export type ScheduleDecision =
+  | { action: "respond"; delayMs: number }
+  | { action: "watch"; timeoutMs: number }
+  | { action: "skip"; reason: string };
+
+export class GroupScheduler {
+  private groups = new Map<string, GroupConversationState>();
+
+  constructor(private config: GroupSchedulingConfig = DEFAULT_GROUP_SCHEDULING) {}
+
+  // ── 发言顺序计算 ──
+
+  /**
+   * 根据 groupId 和成员列表计算固定发言顺序。
+   * 所有 agent 独立计算结果一致（相同输入 → 相同输出）。
+   */
+  computeSpeakingOrder(groupId: string, members: string[]): string[] {
+    const sorted = [...members].map((m) => m.toLowerCase()).sort();
+    const seed = sha256(`${groupId}+${sorted.join(",")}`);
+    const scored = sorted.map((addr) => ({
+      addr,
+      score: sha256(`${addr}+${seed}`),
+    }));
+    scored.sort((a, b) => (a.score < b.score ? -1 : a.score > b.score ? 1 : 0));
+    return scored.map((s) => s.addr);
+  }
+
+  // ── 群组状态管理 ──
+
+  /**
+   * 初始化或获取群组状态。成员变化时自动重算。
+   * @param agentAddresses 已知的 agent 地址集合，仅 agent 参与轮询；
+   *                       非 agent（如群主/人类）不参与 speaking order。
+   */
+  getOrInitGroup(groupId: string, members: string[], agentAddresses?: Set<string>): GroupConversationState {
+    const existing = this.groups.get(groupId);
+    // 仅保留 agent 地址参与轮询，非 agent 跳过
+    const agentMembers = agentAddresses
+      ? members.filter((m) => agentAddresses.has(m.toLowerCase()))
+      : members;
+    const order = this.computeSpeakingOrder(groupId, agentMembers);
+
+    // 成员变化 → 重算并重置计数
+    if (existing && !arraysEqual(existing.speakingOrder, order)) {
+      const reset: GroupConversationState = {
+        speakingOrder: order,
+        messageCount: 0,
+        lastClaim: null,
+      };
+      this.groups.set(groupId, reset);
+      return reset;
+    }
+
+    if (existing) return existing;
+
+    const state: GroupConversationState = {
+      speakingOrder: order,
+      messageCount: 0,
+      lastClaim: null,
+    };
+    this.groups.set(groupId, state);
+    return state;
+  }
+
+  getGroupState(groupId: string): GroupConversationState | null {
+    return this.groups.get(groupId) ?? null;
+  }
+
+  // ── Claim 消息识别 ──
+
+  static isClaimMessage(content: string): boolean {
+    return content.startsWith(CLAIM_PREFIX);
+  }
+
+  static formatClaimMessage(messageId: string): string {
+    return `${CLAIM_PREFIX}${messageId}`;
+  }
+
+  static parseClaimMessageId(content: string): string | null {
+    if (!GroupScheduler.isClaimMessage(content)) return null;
+    return content.slice(CLAIM_PREFIX.length);
+  }
+
+  // ── 消息计数 ──
+
+  /**
+   * 收到非 claim 消息时递增计数。返回该消息的 index。
+   */
+  recordMessage(groupId: string): number {
+    const state = this.groups.get(groupId);
+    if (!state) return 0;
+    const idx = state.messageCount;
+    state.messageCount += 1;
+    return idx;
+  }
+
+  /**
+   * 记录收到的 claim。
+   */
+  recordClaim(groupId: string, sender: string, messageId: string): void {
+    const state = this.groups.get(groupId);
+    if (!state) return;
+    state.lastClaim = { sender: sender.toLowerCase(), timestamp: Date.now(), messageId };
+  }
+
+  // ── 调度决策 ──
+
+  /**
+   * 为当前 agent 计算调度决策：应该回复、监听还是跳过。
+   */
+  decide(
+    groupId: string,
+    myAddress: string,
+    messageIndex: number,
+  ): ScheduleDecision {
+    const state = this.groups.get(groupId);
+    if (!state || state.speakingOrder.length === 0) {
+      return { action: "skip", reason: "Group not initialized" };
+    }
+
+    const order = state.speakingOrder;
+    const myAddr = myAddress.toLowerCase();
+    const mySlot = order.indexOf(myAddr);
+
+    if (mySlot === -1) {
+      return { action: "skip", reason: "Not a member of speaking order" };
+    }
+
+    const designatedSlot = messageIndex % order.length;
+
+    if (mySlot === designatedSlot) {
+      // 我是指定回复者
+      return { action: "respond", delayMs: this.config.baseDelayMs };
+    }
+
+    // 计算与指定回复者的距离 → failover 超时
+    const distance = (mySlot - designatedSlot + order.length) % order.length;
+    const timeoutMs = this.config.baseDelayMs + distance * this.config.slotTimeoutMs;
+
+    return { action: "watch", timeoutMs };
+  }
+
+  /**
+   * 检查是否有未过期的 claim（某 agent 已声明要回复）。
+   */
+  hasActiveClaim(groupId: string): boolean {
+    const state = this.groups.get(groupId);
+    if (!state?.lastClaim) return false;
+    const elapsed = Date.now() - state.lastClaim.timestamp;
+    return elapsed < this.config.claimExpireMs;
+  }
+
+  /**
+   * 检查 claim 是否已过期（agent 声明了但 LLM 挂起）。
+   */
+  isClaimExpired(groupId: string): boolean {
+    const state = this.groups.get(groupId);
+    if (!state?.lastClaim) return false;
+    const elapsed = Date.now() - state.lastClaim.timestamp;
+    return elapsed >= this.config.claimExpireMs;
+  }
+
+  /**
+   * 清除 claim 状态（收到实际回复后调用）。
+   */
+  clearClaim(groupId: string): void {
+    const state = this.groups.get(groupId);
+    if (state) state.lastClaim = null;
+  }
+
+  getConfig(): GroupSchedulingConfig {
+    return { ...this.config };
+  }
+}
+
+// ── Helpers ──
+
+function sha256(input: string): string {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+function arraysEqual(a: string[], b: string[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}

package/src/coordination/message-orchestrator.ts

@@ -1,11 +1,13 @@
 // ============================================================
 // Message Orchestrator
-// 从 index.ts 提取的消息回调逻辑：群聊防抢答、LLM subagent
-// 调用、安全校验、回复提取与发送
+// 群聊 round-robin 调度、LLM subagent 调用、安全校验、回复提取与发送
 // ============================================================
 
 import type { XmtpBridge } from "../transport/xmtp-bridge.js";
+import type { IdentityRegistry } from "../transport/identity-registry.js";
 import { formatA2AMessage, type A2AInjectPayload } from "../types.js";
+import { GroupScheduler } from "./group-scheduler.js";
+import type { PolicyEngine } from "./policy-engine.js";
 
 /** OpenClaw subagent runtime 接口（由 api.runtime.subagent 提供） */
 export interface SubagentAPI {
@@ -39,13 +41,35 @@ export interface Logger {
 const ALLOWED_TOOLS = new Set(["web_search"]);
 
 export class MessageOrchestrator {
+  private groupScheduler: GroupScheduler;
+  /** 每个会话的 pending watch（failover 等待），用于取消 */
+  private pendingWatches = new Map<string, AbortController>();
+
   constructor(
     private subagentApi: SubagentAPI,
     private logger: Logger,
-  ) {}
+    private policyEngine: PolicyEngine,
+    groupScheduler: GroupScheduler,
+    private registry: IdentityRegistry,
+  ) {
+    this.groupScheduler = groupScheduler;
+  }
+
+  /**
+   * 处理 claim 消息回调（由 bridge.onClaim 触发）
+   */
+  handleClaim(conversationId: string, senderAddress: string, messageId: string): void {
+    this.groupScheduler.recordClaim(conversationId, senderAddress, messageId);
+    // 取消该会话的 pending watch（指定回复者已 claim）
+    const ctrl = this.pendingWatches.get(conversationId);
+    if (ctrl) {
+      ctrl.abort();
+      this.pendingWatches.delete(conversationId);
+    }
+  }
 
   /**
-   * 处理收到的 XMTP 消息：群聊防抢答 → LLM 推理 → 安全校验 → 回复
+   * 处理收到的 XMTP 消息：群聊 round-robin 调度 → LLM 推理 → 安全校验 → 回复
    */
   async handleMessage(
     bridge: XmtpBridge,
@@ -56,26 +80,13 @@ export class MessageOrchestrator {
     const formattedMsg = formatA2AMessage(payload);
     const senderLabel = payload.from.agentId || payload.from.xmtpAddress;
 
-    // ── 群聊防抢答：随机延迟 + 发送前检查 ──
-    if (payload.conversation.isGroup) {
-      const delay = 3000 + Math.random() * 5000; // 3-8 秒随机延迟
-      this.logger.info(
-        `[a2a-xmtp] Group message from ${senderLabel}, waiting ${Math.round(delay)}ms before responding...`,
-      );
-      await new Promise((r) => setTimeout(r, delay));
-
-      // 检查延迟期间是否已有其他人回复
-      const alreadyReplied = await bridge.hasNewGroupReplies(
-        payload.conversation.id,
-        payload.timestamp,
-        [bridge.address, payload.from.xmtpAddress],
+    // ── 群聊 round-robin 调度 ──
+    if (payload.conversation.isGroup && payload.conversation.participants.length > 0) {
+      const shouldRespond = await this.scheduleGroupResponse(
+        bridge,
+        payload,
       );
-      if (alreadyReplied) {
-        this.logger.info(
-          `[a2a-xmtp] Skipping reply — another agent already responded in ${payload.conversation.id}`,
-        );
-        return;
-      }
+      if (!shouldRespond) return;
     }
 
     const extraSystemPrompt = this.buildSystemPrompt(payload, senderLabel);
@@ -113,24 +124,19 @@ export class MessageOrchestrator {
         const replyText = this.extractReplyText(messages);
         if (!replyText) return;
 
-        // 群聊：发送前再次检查竞态
-        if (payload.conversation.isGroup) {
-          const raceCheck = await bridge.hasNewGroupReplies(
-            payload.conversation.id,
-            payload.timestamp,
-            [bridge.address, payload.from.xmtpAddress],
-          );
-          if (raceCheck) {
-            this.logger.info(
-              `[a2a-xmtp] Skipping reply (post-LLM check) — another agent responded in ${payload.conversation.id}`,
-            );
-            return;
-          }
-        }
-
+        // recordTurn 由 bridge.sendMessage 内部调用，此处不重复
         await bridge.sendMessage(payload.from.xmtpAddress, replyText, {
           conversationId: payload.conversation.id,
         });
+
+        // 群聊：计入自己的消息 + 清除 claim
+        if (payload.conversation.isGroup) {
+          // 自己发的消息 handleIncoming 不会收到（跳过 self），
+          // 手动递增以保持与其他 agent 的 messageCount 同步
+          this.groupScheduler.recordMessage(payload.conversation.id);
+          this.groupScheduler.clearClaim(payload.conversation.id);
+        }
+
         this.logger.info(`[a2a-xmtp] Replied to ${senderLabel} in ${payload.conversation.id}`);
       }
     } catch (err) {
@@ -140,6 +146,113 @@ export class MessageOrchestrator {
     }
   }
 
+  /**
+   * 群聊调度：根据 round-robin 决定是否应该回复。
+   * 返回 true 表示应该回复，false 表示让其他 agent 处理。
+   */
+  private async scheduleGroupResponse(
+    bridge: XmtpBridge,
+    payload: A2AInjectPayload,
+  ): Promise<boolean> {
+    const convId = payload.conversation.id;
+    const members = payload.conversation.participants;
+    const myAddress = bridge.address;
+
+    // 筛选出 agent 地址：自己 + registry 中已知的 agent
+    const agentAddresses = new Set<string>();
+    agentAddresses.add(myAddress.toLowerCase());
+    for (const addr of members) {
+      if (this.registry.getAgentId(addr)) {
+        agentAddresses.add(addr.toLowerCase());
+      }
+    }
+
+    // 初始化群组状态（仅 agent 参与轮询，人类/admin 不参与）
+    this.groupScheduler.getOrInitGroup(convId, members, agentAddresses);
+
+    // 检查 turn budget 是否耗尽
+    if (this.policyEngine.isTurnExhausted(convId)) {
+      this.logger.info(
+        `[a2a-xmtp] Turn budget exhausted for ${convId}, skipping`,
+      );
+      return false;
+    }
+
+    // 记录消息并获取 index
+    const msgIndex = this.groupScheduler.recordMessage(convId);
+
+    // 计算调度决策
+    const decision = this.groupScheduler.decide(convId, myAddress, msgIndex);
+
+    if (decision.action === "skip") {
+      this.logger.info(
+        `[a2a-xmtp] Skipping group message: ${decision.reason}`,
+      );
+      return false;
+    }
+
+    if (decision.action === "respond") {
+      // 我是指定回复者：等待 baseDelay 后发送 claim
+      this.logger.info(
+        `[a2a-xmtp] I am designated responder for msg #${msgIndex} in ${convId}`,
+      );
+      await sleep(decision.delayMs);
+
+      // 发送 claim
+      try {
+        await bridge.sendClaim(convId, payload.message.id);
+      } catch (err) {
+        this.logger.warn(
+          `[a2a-xmtp] Failed to send claim: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+      return true;
+    }
+
+    // decision.action === "watch": 等待指定回复者的 claim 或回复
+    this.logger.info(
+      `[a2a-xmtp] Watching for claim/reply in ${convId}, timeout ${decision.timeoutMs}ms`,
+    );
+
+    const abortCtrl = new AbortController();
+    this.pendingWatches.set(convId, abortCtrl);
+
+    try {
+      const timedOut = await waitWithAbort(decision.timeoutMs, abortCtrl.signal);
+
+      if (!timedOut) {
+        // 被取消 = 收到了 claim 或回复 → 保持沉默
+        this.logger.info(
+          `[a2a-xmtp] Saw claim/reply in ${convId}, staying silent`,
+        );
+        return false;
+      }
+
+      // 超时且没有 claim → 检查是否有未过期的 claim（可能在等待期间收到）
+      if (this.groupScheduler.hasActiveClaim(convId)) {
+        this.logger.info(
+          `[a2a-xmtp] Active claim exists in ${convId}, staying silent`,
+        );
+        return false;
+      }
+
+      // 接管：发送 claim 并回复
+      this.logger.info(
+        `[a2a-xmtp] Failover: taking over msg #${msgIndex} in ${convId}`,
+      );
+      try {
+        await bridge.sendClaim(convId, payload.message.id);
+      } catch (err) {
+        this.logger.warn(
+          `[a2a-xmtp] Failed to send failover claim: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+      return true;
+    } finally {
+      this.pendingWatches.delete(convId);
+    }
+  }
+
   /**
    * 构建安全约束的系统提示词
    */
@@ -207,3 +320,31 @@ export class MessageOrchestrator {
     return replyText.trim() || null;
   }
 }
+
+// ── Helpers ──
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * 等待指定时间，可被 AbortSignal 取消。
+ * 返回 true = 超时（自然结束），false = 被取消。
+ */
+function waitWithAbort(ms: number, signal: AbortSignal): Promise<boolean> {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve(false);
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve(true);
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      resolve(false);
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/coordination/policy-engine.ts

@@ -1,6 +1,7 @@
 // ============================================================
 // Module 5: Policy Engine
-// 四重保护：Turn Budget / Cool-down / Depth Guard / Consent
+// 三重保护：Turn Budget / Cool-down / Consent
+// Depth Guard 已移除，由 GroupScheduler round-robin + turn budget 取代
 // ============================================================
 
 import type { ConversationPolicy, ConversationState, ConsentState } from "../types.js";
@@ -9,7 +10,6 @@ export interface PolicyCheckParams {
   from: string;
   to: string;
   conversationId: string;
-  depth?: number;
 }
 
 export interface PolicyCheckResult {
@@ -28,10 +28,10 @@ export class PolicyEngine {
     this.localAgentIds.add(agentId);
   }
 
-  checkOutgoing(params: PolicyCheckParams): PolicyCheckResult {
-    return this.check(params);
-  }
-
+  /**
+   * 入站检查：consent + TTL + turn budget（不检查 cool-down，
+   * 否则刚发完消息后收到的回复会被静默丢弃）
+   */
   checkIncoming(params: PolicyCheckParams): PolicyCheckResult {
     const consent = this.getConsent(params.from);
     if (consent === "deny") {
@@ -43,10 +43,23 @@ export class PolicyEngine {
         reason: `Sender ${params.from} not explicitly allowed (consent: ${consent})`,
       };
     }
-    return this.check(params);
+    // 仅检查 TTL + turn budget，不检查 cool-down
+    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})` };
+    }
+    return { allowed: true };
   }
 
-  private check(params: PolicyCheckParams): PolicyCheckResult {
+  /**
+   * 出站检查：TTL + turn budget + cool-down
+   */
+  checkOutgoing(params: PolicyCheckParams): PolicyCheckResult {
     const state = this.getOrCreateState(params.conversationId);
     const now = Date.now();
 
@@ -63,21 +76,20 @@ export class PolicyEngine {
       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 {
+  recordTurn(conversationId: string): void {
     const state = this.getOrCreateState(conversationId);
     state.turn += 1;
     state.lastSendTime = Date.now();
-    if (depth !== undefined) {
-      state.depth = Math.max(state.depth, depth);
-    }
+  }
+
+  /** 检查此 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 {
@@ -113,7 +125,7 @@ export class PolicyEngine {
   private getOrCreateState(conversationId: string): ConversationState {
     let state = this.conversations.get(conversationId);
     if (!state) {
-      state = { turn: 0, depth: 0, lastSendTime: 0, createdAt: Date.now() };
+      state = { turn: 0, lastSendTime: 0, createdAt: Date.now() };
       this.conversations.set(conversationId, state);
     }
     return state;

package/src/index.ts

@@ -7,6 +7,7 @@ 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";
@@ -139,11 +140,15 @@ export default definePluginEntry({
           },
           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,
           },
+          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,
         };
 
@@ -151,8 +156,15 @@ export default definePluginEntry({
         registry = new IdentityRegistry(ctx.stateDir, config.xmtp.env);
         policyEngine = new PolicyEngine(config.policy);
 
-        // 初始化消息编排器
-        const orchestrator = new MessageOrchestrator(api.runtime.subagent, ctx.logger);
+        // 初始化群聊调度器和消息编排器
+        const groupScheduler = new GroupScheduler(config.groupScheduling);
+        const orchestrator = new MessageOrchestrator(
+          api.runtime.subagent,
+          ctx.logger,
+          policyEngine,
+          groupScheduler,
+          registry,
+        );
 
         // 初始化主 Agent 的 XMTP Bridge
         try {
@@ -171,6 +183,10 @@ export default definePluginEntry({
           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);
 

package/src/transport/xmtp-bridge.ts

@@ -7,7 +7,8 @@ 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 } from "../types.js";
+import { createA2APayload, CLAIM_PREFIX } from "../types.js";
+import { GroupScheduler } from "../coordination/group-scheduler.js";
 
 /** IdentifierKind.Ethereum = 0 (const enum, 不能在 isolatedModules 下直接访问) */
 const IDENTIFIER_KIND_ETHEREUM = 0;
@@ -24,6 +25,9 @@ export class XmtpBridge {
   /** 消息回调（由 plugin 入口设置，用于触发 subagent 处理） */
   onMessage?: (agentId: string, payload: A2AInjectPayload) => void;
 
+  /** Claim 消息回调（由 orchestrator 设置，用于群聊调度） */
+  onClaim?: (conversationId: string, senderAddress: string, messageId: string) => void;
+
   constructor(
     readonly agentId: string,
     private walletConfig: XmtpWalletConfig,
@@ -99,6 +103,17 @@ export class XmtpBridge {
     return { conversationId: conversation.id, messageId: String(messageId) };
   }
 
+  /**
+   * 发送 claim 消息到群聊，表明本 agent 将要回复。
+   */
+  async sendClaim(conversationId: string, messageId: 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 claimText = GroupScheduler.formatClaimMessage(messageId);
+    await conv.sendText(claimText);
+  }
+
   async getInbox(opts?: { limit?: number; from?: string }): Promise<InboxMessage[]> {
     const limit = opts?.limit ?? 10;
     let messages = [...this.inboxBuffer];
@@ -220,6 +235,17 @@ export class XmtpBridge {
 
     if (senderAddress.toLowerCase() === this.address.toLowerCase()) return;
 
+    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;
+    }
+
     const senderAgentId = await this.registry.resolveAgentId(senderAddress);
 
     const policyResult = this.policyEngine.checkIncoming({
@@ -231,9 +257,6 @@ export class XmtpBridge {
 
     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);
 
     // 群聊时获取参与者列表
     let participants: string[] = [];
@@ -254,10 +277,9 @@ export class XmtpBridge {
       isGroup,
       participants,
       messageId: ctx.message.id ?? crypto.randomUUID(),
-      content: String(ctx.message.content),
+      content,
       contentType,
       turn: turn + 1,
-      depth: depth + 1,
     });
 
     // 缓存到 inbox
@@ -266,7 +288,7 @@ export class XmtpBridge {
       from: { agentId: senderAgentId, xmtpAddress: senderAddress },
       conversationId: ctx.conversation.id,
       isGroup,
-      content: String(ctx.message.content),
+      content,
       contentType,
       timestamp: payload.timestamp,
     });

package/src/types.ts

@@ -30,7 +30,6 @@ export interface A2AInjectPayload {
     content: string;
     contentType: A2AContentType;
     turn: number;
-    depth: number;
     replyTo?: string;
   };
   timestamp: string;
@@ -41,12 +40,21 @@ export type A2AContentType = "text" | "markdown" | "transaction" | "action";
 /** 防循环策略配置 */
 export interface ConversationPolicy {
   maxTurns: number;
-  maxDepth: 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";
 
@@ -57,17 +65,37 @@ export interface PluginConfig {
     dbPath: string;
   };
   policy: ConversationPolicy;
+  groupScheduling: GroupSchedulingConfig;
   walletKey?: string;
 }
 
 /** 会话状态（Policy Engine 内部使用） */
 export interface ConversationState {
   turn: number;
-  depth: 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 消息前缀（零宽空格 + [processing]:） */
+export const CLAIM_PREFIX = "\u200B[processing]:";
+
+/** 默认群聊调度配置 */
+export const DEFAULT_GROUP_SCHEDULING: GroupSchedulingConfig = {
+  baseDelayMs: 1000,
+  slotTimeoutMs: 6000,
+  claimExpireMs: 30000,
+};
+
 /** 收件箱消息 */
 export interface InboxMessage {
   id: string;
@@ -93,7 +121,6 @@ export interface GroupInfo {
 /** 默认策略配置 */
 export const DEFAULT_POLICY: ConversationPolicy = {
   maxTurns: 10,
-  maxDepth: 5,
   minIntervalMs: 5000,
   ttlMinutes: 60,
   consentMode: "auto-allow-local",
@@ -106,6 +133,7 @@ export const DEFAULT_PLUGIN_CONFIG: PluginConfig = {
     dbPath: "./xmtp-data",
   },
   policy: DEFAULT_POLICY,
+  groupScheduling: DEFAULT_GROUP_SCHEDULING,
 };
 
 /** 格式化 A2A 消息（注入 session 时的文本表示） */
@@ -126,7 +154,6 @@ export function createA2APayload(params: {
   content: string;
   contentType: A2AContentType;
   turn: number;
-  depth: number;
   replyTo?: string;
   displayName?: string;
 }): A2AInjectPayload {
@@ -147,7 +174,6 @@ export function createA2APayload(params: {
       content: params.content,
       contentType: params.contentType,
       turn: params.turn,
-      depth: params.depth,
       replyTo: params.replyTo,
     },
     timestamp: new Date().toISOString(),