@relaymessenger/openclaw-plugin 0.4.7-staging.35 → 0.4.7-staging.37

package/README.md

@@ -1,7 +1,7 @@
 # Relay for OpenClaw
 
 `@relaymessenger/openclaw-plugin` is the native Relay channel for OpenClaw
-`2026.8.1`.
+`2026.8.1` through `2026.9.6`, the versions its gateway harness runs against.
 
 Source is maintained in
 [`RelayMessenger/Relay-SDK`](https://github.com/RelayMessenger/Relay-SDK/tree/main/packages/openclaw)
@@ -42,6 +42,15 @@ go first and the payment card follows as its own Message.
 openclaw plugins install @relaymessenger/openclaw-plugin
 ```
 
+OpenClaw asks two questions for a plugin from npm: whether you trust a source
+outside ClawHub, and whether to accept the capabilities the plugin declares.
+This plugin declares one capability, the `relay` channel. Where no terminal
+can answer, pass both answers:
+
+```bash
+openclaw plugins install @relaymessenger/openclaw-plugin --force --accept-capabilities
+```
+
 Configure the default account:
 
 ```json
@@ -130,6 +139,16 @@ Without `allowFrom`, any user or agent Contact whose Message Relay delivers
 to this agent can start a direct turn, while the group activation rules above
 still apply.
 
+## Messages from another agent
+
+Another agent's call reaches this agent as a Message, and Relay gives the
+caller the answer whose `reply_to` names its Message. So every answer to
+another agent names the Message it answers. When the same agent sends a second
+Message while a turn is still running in that Chat, the plugin holds it until
+the turn ends, then gives it a turn of its own. OpenClaw would otherwise steer
+it into the running turn, and the second caller would get no answer. A
+person's Messages keep OpenClaw's own queue and reply behavior.
+
 ## Durable delivery
 
 For every WebSocket event, the plugin:
@@ -177,10 +196,12 @@ exact SHA selected from the `staging` branch, the matching
 validated tarball and publishes that same digest with npm provenance; its
 publish job is also bound to the `staging` GitHub environment.
 
-`gateway:harness` packs the plugin, installs the tarball with OpenClaw
-`2026.8.1`, inspects the managed installation, starts a real OpenClaw gateway,
-connects to a loopback Relay WebSocket, receives one Message, and proves the
-durable ACK and idempotent REST reply.
+`gateway:harness` packs the plugin, installs the tarball with the OpenClaw
+version in `devDependencies`, inspects the managed installation, starts a real
+OpenClaw gateway, connects to a loopback Relay WebSocket, receives one Message,
+and proves the durable ACK and idempotent REST reply. Its `--overlap` run sends
+two Messages from one agent, the second while the model still answers the
+first, and requires two answers, each naming its own Message.
 
 ## Contract lock
 

package/contracts/relay-v1.lock.json

@@ -1,16 +1,16 @@
 {
   "relayServer": {
     "repository": "RelayMessenger/Relay-Server",
-    "commit": "e53138b79536f2fb8bbd339e6d344819c0afe8ff",
+    "commit": "d511deefd9e07953f910759e37d662cafa3e6c14",
     "openapiPath": "contracts/developer/openapi.yaml",
-    "sha256": "3ac33f08a16f83be44585a34df34d7067f9157a8971e63686ab41f44374ce5f8"
+    "sha256": "02e42cd6efdac39c4f3a894ec9251bc8560bbfbabe539e4eb06d9e0c6c55d0a6"
   },
   "relaySdk": {
     "package": "@relaymessenger/sdk",
-    "version": "0.3.6-staging.38",
-    "integrity": "sha512-Lcx/o0DXrgHmfC+9iE0PTwaodpCMhYpdL8bBKtndFE93ABkpLoevi5g9pVsZC1NY5ccQGACNhYd6oQb1QB9jHw==",
+    "version": "0.3.6-staging.43",
+    "integrity": "sha512-I3QTO65wJlEWolmdazHoFEDwYBl22xq326j0iWJsjgGv+NnS1DT8DmKYYydi1KzyRnJlCGPSur/FiRC9A7RJaQ==",
     "operationsSha256": "bb36ba7380042a0d7ceb5064fd15e883e1e6fe11a28fc0d5157bb0df501111e3",
-    "workspaceOpenapiSha256": "3ac33f08a16f83be44585a34df34d7067f9157a8971e63686ab41f44374ce5f8",
+    "workspaceOpenapiSha256": "02e42cd6efdac39c4f3a894ec9251bc8560bbfbabe539e4eb06d9e0c6c55d0a6",
     "usedOperations": [
       {
         "method": "GET",

package/dist/src/dispatch.js

@@ -3,6 +3,7 @@ import { buildChannelInboundEventContext, resolveChannelInboundRouteEnvelope, }
 import { resolveStableChannelMessageIngress } from "openclaw/plugin-sdk/channel-ingress-runtime";
 import { bindIngressLifecycleToReplyOptions } from "openclaw/plugin-sdk/channel-outbound";
 import { buildRelayInboundFacts } from "./inbound.js";
+import { waitForIdleChat } from "./turns.js";
 function isReplyToAgentMessage(message, chatId) {
     return message.chat_id === chatId && message.is_from_me === true;
 }
@@ -38,6 +39,21 @@ export async function resolveRelayTurnActivation(params) {
         implicitMentionKinds: ["reply_to_bot"],
     };
 }
+/**
+ * The answer to another agent names the Message it answers: the model's own
+ * reply target when it chose one, else the agent's Message. Where no reply may
+ * point (a Message opening with buttons or a selection), OpenClaw's implicit
+ * current-message reply is removed.
+ */
+export function agentReplyPayload(payload, facts) {
+    if (facts.agentReplyLink) {
+        return { ...payload, replyToId: payload.replyToId ?? facts.agentReplyLink };
+    }
+    if (payload.replyToId !== facts.messageId)
+        return payload;
+    const { replyToId: _unlinked, ...rest } = payload;
+    return rest;
+}
 export async function dispatchRelayEvent(params) {
     const facts = buildRelayInboundFacts(params.event);
     if (!facts) {
@@ -137,6 +153,11 @@ export async function dispatchRelayEvent(params) {
         params.warn?.(`relay: Contact @${facts.handle} did not pass OpenClaw ingress (${access.ingress.decision}:${access.ingress.reasonCode})`);
         return;
     }
+    // An agent's reply target is only its own Message (agentReplyLink); a
+    // person's is the Message they replied from, as before.
+    const replyTarget = facts.fromAgent
+        ? facts.agentReplyLink
+        : facts.replyAnchorId ?? facts.replyToId;
     const body = buildEnvelope({
         channel: "Relay",
         from: `${facts.displayName} (@${facts.handle})`,
@@ -171,9 +192,7 @@ export async function dispatchRelayEvent(params) {
         reply: {
             to: facts.chatId,
             originatingTo: facts.chatId,
-            ...((facts.replyAnchorId ?? facts.replyToId)
-                ? { replyToId: facts.replyAnchorId ?? facts.replyToId }
-                : {}),
+            ...(replyTarget ? { replyToId: replyTarget } : {}),
         },
         message: {
             inboundEventKind: "user_request",
@@ -200,6 +219,15 @@ export async function dispatchRelayEvent(params) {
             },
         },
     });
+    // Another agent's Message waits for the turn running in its Chat, so it
+    // gets a turn and an answer of its own (turns.ts).
+    if (facts.fromAgent) {
+        await waitForIdleChat({
+            turns: params.turns,
+            chatId: facts.chatId,
+            lifecycle: params.lifecycle,
+        });
+    }
     await Promise.allSettled([
         params.relay.chats.markAsRead(facts.chatId),
         params.relay.chats.startTyping(facts.chatId),
@@ -212,7 +240,7 @@ export async function dispatchRelayEvent(params) {
     });
     let deliveryError;
     try {
-        await params.runtime.channel.inbound.dispatch({
+        await params.turns.track(facts.chatId, () => params.runtime.channel.inbound.dispatch({
             cfg: params.cfg,
             channel: "relay",
             accountId: params.account.accountId,
@@ -225,9 +253,17 @@ export async function dispatchRelayEvent(params) {
             delivery: {
                 durable: {
                     to: facts.chatId,
-                    replyToId: null,
+                    replyToId: facts.fromAgent ? facts.agentReplyLink ?? null : null,
                     requiredCapabilities: { reconcileUnknownSend: true },
                 },
+                // Every answer to another agent names its Message, whatever
+                // `replyToMode` the operator chose; OpenClaw's own implicit
+                // current-message reply is dropped where no reply may point.
+                ...(facts.fromAgent
+                    ? {
+                        preparePayload: (payload) => agentReplyPayload(payload, facts),
+                    }
+                    : {}),
                 deliver: async (_payload, info) => {
                     if (info.kind === "final") {
                         throw new Error("relay: durable final Message delivery was unavailable");
@@ -250,7 +286,7 @@ export async function dispatchRelayEvent(params) {
                         : new Error(`relay: session record failed: ${String(error)}`);
                 },
             },
-        });
+        }));
         if (deliveryError) {
             throw deliveryError instanceof Error
                 ? deliveryError

package/dist/src/gateway.js

@@ -4,6 +4,7 @@ import { dispatchRelayEvent } from "./dispatch.js";
 import { commitRelayFullSync } from "./full-sync.js";
 import { createRelayIngressMonitor } from "./ingress.js";
 import { createRelaySdkClient } from "./outbound.js";
+import { createRelayChatTurns } from "./turns.js";
 import { getRelayRuntime } from "./runtime.js";
 import { openRelayStateStore, } from "./state.js";
 const runningCredentials = new Map();
@@ -58,6 +59,7 @@ export async function startRelayAccount(ctx) {
         accountId: transportId,
     });
     const relay = createRelaySdkClient(account);
+    const turns = createRelayChatTurns();
     const ingress = createRelayIngressMonitor({
         queue: openIngressQueue({
             transportId,
@@ -80,6 +82,7 @@ export async function startRelayAccount(ctx) {
                 cfg: ctx.cfg,
                 relay,
                 runtime,
+                turns,
                 warn,
             });
         },

package/dist/src/inbound.js

@@ -56,9 +56,22 @@ export function buildRelayInboundFacts(event) {
     const timestampValue = event.data.sent_at ?? event.created_at;
     const timestamp = Date.parse(timestampValue);
     const selection = selectionReply(event.data.parts, event.data.reply_to);
+    const fromAgent = event.data.sender_handle.kind === "agent";
+    // Another agent's Message is named by the answer, as Relay's CLI bridges
+    // do (packages/cli/src/bridge-turn.ts, PR 366): Relay's A2A door gives a
+    // calling agent only the answer whose reply_to names its Message
+    // (Relay-Server a2a.ts replyTo). A Message that opens with buttons or a
+    // selection is not named: an agent may not reply to those parts, and a
+    // reply names part 0.
+    const opening = event.data.parts[0]?.type;
+    const agentReplyLink = fromAgent && opening !== "buttons" && opening !== "selection"
+        ? event.data.id
+        : undefined;
     return {
         ...(selection ? { selection } : {}),
         ...(richMessage ? { richMessage } : {}),
+        fromAgent,
+        ...(agentReplyLink ? { agentReplyLink } : {}),
         eventId: event.event_id,
         messageId: event.data.id,
         chatId: event.data.chat.id,
@@ -78,8 +91,9 @@ export function buildRelayInboundFacts(event) {
                 // The answer quotes the person's message, the one it answers (a bot's
                 // reply_to in Telegram and Discord names the person's message). A
                 // tap's reply_to names the agent's buttons part, which no reply may
-                // target, so this is also what keeps a tap answerable.
-                replyAnchorId: event.data.id,
+                // target, so this is also what keeps a tap answerable. An agent's
+                // Message is quoted only through agentReplyLink.
+                ...(fromAgent ? {} : { replyAnchorId: event.data.id }),
             }
             : {}),
         ...(Number.isFinite(timestamp) ? { timestamp } : {}),

package/dist/src/turns.js

@@ -0,0 +1,69 @@
+export function createRelayChatTurns() {
+    const running = new Map();
+    return {
+        track(chatId, work) {
+            const turns = running.get(chatId) ?? new Set();
+            running.set(chatId, turns);
+            const turn = work();
+            turns.add(turn);
+            const settle = () => {
+                turns.delete(turn);
+                if (turns.size === 0 && running.get(chatId) === turns)
+                    running.delete(chatId);
+            };
+            turn.then(settle, settle);
+            return turn;
+        },
+        busy: (chatId) => Boolean(running.get(chatId)?.size),
+        async idle(chatId, signal) {
+            for (;;) {
+                signal?.throwIfAborted();
+                const turns = running.get(chatId);
+                if (!turns?.size)
+                    return;
+                const settled = Promise.allSettled([...turns]);
+                if (!signal) {
+                    await settled;
+                    continue;
+                }
+                await new Promise((resolve, reject) => {
+                    const abort = () => reject(signal.reason);
+                    signal.addEventListener("abort", abort, { once: true });
+                    void settled.then(() => {
+                        signal.removeEventListener("abort", abort);
+                        resolve();
+                    });
+                });
+            }
+        },
+    };
+}
+/**
+ * Hold a claimed Relay event until its Chat is idle. The claim is handed off
+ * as deferred and kept alive with the drain's own heartbeat
+ * (`ChannelIngressDispatchLifecycle.onDeferred` / `onDeferredHeartbeat`,
+ * docs/plugins/sdk-channel-outbound.md "Deferred claim heartbeats"), so the
+ * adoption watchdog does not retry a Message that is only waiting its turn. On
+ * shutdown the wait rejects before adoption, and the drain keeps the event for
+ * the next start.
+ */
+export async function waitForIdleChat(params) {
+    const { lifecycle } = params;
+    if (!params.turns.busy(params.chatId))
+        return;
+    const signal = lifecycle.abortSignal;
+    lifecycle.onDeferred?.();
+    const interval = lifecycle.deferredHeartbeatIntervalMs;
+    const heartbeat = lifecycle.onDeferredHeartbeat && interval && interval > 0
+        ? setInterval(() => lifecycle.onDeferredHeartbeat?.(), interval)
+        : undefined;
+    heartbeat?.unref?.();
+    try {
+        await params.turns.idle(params.chatId, signal);
+    }
+    finally {
+        if (heartbeat)
+            clearInterval(heartbeat);
+    }
+}
+//# sourceMappingURL=turns.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relaymessenger/openclaw-plugin",
-  "version": "0.4.7-staging.35",
+  "version": "0.4.7-staging.37",
   "description": "Native Relay channel plugin for OpenClaw",
   "license": "MIT",
   "type": "module",
@@ -33,11 +33,11 @@
     "contract:verify": "node scripts/verify-contract-provenance.mjs",
     "contract:test": "node --test test/*.test.mjs",
     "pack:smoke": "node scripts/pack-smoke.mjs",
-    "gateway:harness": "node scripts/gateway-harness.mjs",
+    "gateway:harness": "node scripts/gateway-harness.mjs && node scripts/gateway-harness.mjs --overlap",
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@relaymessenger/sdk": "0.3.6-staging.38"
+    "@relaymessenger/sdk": "0.3.6-staging.43"
   },
   "devDependencies": {
     "@types/node": "^26.6.2",

package/src/dispatch.ts

@@ -11,9 +11,11 @@ import {
 import { resolveStableChannelMessageIngress } from "openclaw/plugin-sdk/channel-ingress-runtime";
 import { bindIngressLifecycleToReplyOptions } from "openclaw/plugin-sdk/channel-outbound";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import type { ReplyPayload } from "openclaw/plugin-sdk/reply-payload";
 import { buildRelayInboundFacts } from "./inbound.js";
 import type { RelayIngressLifecycle } from "./ingress.js";
 import type { PluginRuntime } from "./runtime.js";
+import { type RelayChatTurns, waitForIdleChat } from "./turns.js";
 import type {
   RelayCoreConfig,
   RelayInboundFacts,
@@ -86,6 +88,24 @@ export async function resolveRelayTurnActivation(params: {
   };
 }
 
+/**
+ * The answer to another agent names the Message it answers: the model's own
+ * reply target when it chose one, else the agent's Message. Where no reply may
+ * point (a Message opening with buttons or a selection), OpenClaw's implicit
+ * current-message reply is removed.
+ */
+export function agentReplyPayload(
+  payload: ReplyPayload,
+  facts: Pick<RelayInboundFacts, "messageId" | "agentReplyLink">,
+): ReplyPayload {
+  if (facts.agentReplyLink) {
+    return { ...payload, replyToId: payload.replyToId ?? facts.agentReplyLink };
+  }
+  if (payload.replyToId !== facts.messageId) return payload;
+  const { replyToId: _unlinked, ...rest } = payload;
+  return rest;
+}
+
 export async function dispatchRelayEvent(params: {
   event: RelayWebhookEvent;
   lifecycle: RelayIngressLifecycle;
@@ -93,6 +113,7 @@ export async function dispatchRelayEvent(params: {
   cfg: RelayCoreConfig;
   relay: Pick<Relay, "chats" | "messages">;
   runtime: PluginRuntime;
+  turns: RelayChatTurns;
   warn?: (message: string) => void;
 }): Promise<void> {
   const facts = buildRelayInboundFacts(params.event);
@@ -203,6 +224,11 @@ export async function dispatchRelayEvent(params: {
     return;
   }
 
+  // An agent's reply target is only its own Message (agentReplyLink); a
+  // person's is the Message they replied from, as before.
+  const replyTarget = facts.fromAgent
+    ? facts.agentReplyLink
+    : facts.replyAnchorId ?? facts.replyToId;
   const body = buildEnvelope({
     channel: "Relay",
     from: `${facts.displayName} (@${facts.handle})`,
@@ -237,9 +263,7 @@ export async function dispatchRelayEvent(params: {
     reply: {
       to: facts.chatId,
       originatingTo: facts.chatId,
-      ...((facts.replyAnchorId ?? facts.replyToId)
-        ? { replyToId: facts.replyAnchorId ?? facts.replyToId }
-        : {}),
+      ...(replyTarget ? { replyToId: replyTarget } : {}),
     },
     message: {
       inboundEventKind: "user_request",
@@ -267,6 +291,16 @@ export async function dispatchRelayEvent(params: {
     },
   });
 
+  // Another agent's Message waits for the turn running in its Chat, so it
+  // gets a turn and an answer of its own (turns.ts).
+  if (facts.fromAgent) {
+    await waitForIdleChat({
+      turns: params.turns,
+      chatId: facts.chatId,
+      lifecycle: params.lifecycle,
+    });
+  }
+
   await Promise.allSettled([
     params.relay.chats.markAsRead(facts.chatId),
     params.relay.chats.startTyping(facts.chatId),
@@ -280,7 +314,7 @@ export async function dispatchRelayEvent(params: {
 
   let deliveryError: unknown;
   try {
-    await params.runtime.channel.inbound.dispatch({
+    await params.turns.track(facts.chatId, () => params.runtime.channel.inbound.dispatch({
       cfg: params.cfg as OpenClawConfig,
       channel: "relay",
       accountId: params.account.accountId,
@@ -293,9 +327,18 @@ export async function dispatchRelayEvent(params: {
       delivery: {
         durable: {
           to: facts.chatId,
-          replyToId: null,
+          replyToId: facts.fromAgent ? facts.agentReplyLink ?? null : null,
           requiredCapabilities: { reconcileUnknownSend: true },
         },
+        // Every answer to another agent names its Message, whatever
+        // `replyToMode` the operator chose; OpenClaw's own implicit
+        // current-message reply is dropped where no reply may point.
+        ...(facts.fromAgent
+          ? {
+              preparePayload: (payload: ReplyPayload) =>
+                agentReplyPayload(payload, facts),
+            }
+          : {}),
         deliver: async (_payload, info) => {
           if (info.kind === "final") {
             throw new Error(
@@ -320,7 +363,7 @@ export async function dispatchRelayEvent(params: {
             : new Error(`relay: session record failed: ${String(error)}`);
         },
       },
-    });
+    }));
     if (deliveryError) {
       throw deliveryError instanceof Error
         ? deliveryError

package/src/gateway.ts

@@ -10,6 +10,7 @@ import { dispatchRelayEvent } from "./dispatch.js";
 import { commitRelayFullSync } from "./full-sync.js";
 import { createRelayIngressMonitor } from "./ingress.js";
 import { createRelaySdkClient } from "./outbound.js";
+import { createRelayChatTurns } from "./turns.js";
 import { getRelayRuntime } from "./runtime.js";
 import {
   openRelayStateStore,
@@ -96,6 +97,7 @@ export async function startRelayAccount(
     accountId: transportId,
   });
   const relay = createRelaySdkClient(account);
+  const turns = createRelayChatTurns();
   const ingress = createRelayIngressMonitor({
     queue: openIngressQueue({
       transportId,
@@ -119,6 +121,7 @@ export async function startRelayAccount(
         cfg: ctx.cfg as RelayCoreConfig,
         relay,
         runtime,
+        turns,
         warn,
       });
     },

package/src/inbound.ts

@@ -78,9 +78,22 @@ export function buildRelayInboundFacts(
   const timestampValue = event.data.sent_at ?? event.created_at;
   const timestamp = Date.parse(timestampValue);
   const selection = selectionReply(event.data.parts, event.data.reply_to);
+  const fromAgent = event.data.sender_handle.kind === "agent";
+  // Another agent's Message is named by the answer, as Relay's CLI bridges
+  // do (packages/cli/src/bridge-turn.ts, PR 366): Relay's A2A door gives a
+  // calling agent only the answer whose reply_to names its Message
+  // (Relay-Server a2a.ts replyTo). A Message that opens with buttons or a
+  // selection is not named: an agent may not reply to those parts, and a
+  // reply names part 0.
+  const opening = event.data.parts[0]?.type;
+  const agentReplyLink = fromAgent && opening !== "buttons" && opening !== "selection"
+    ? event.data.id
+    : undefined;
   return {
     ...(selection ? { selection } : {}),
     ...(richMessage ? { richMessage } : {}),
+    fromAgent,
+    ...(agentReplyLink ? { agentReplyLink } : {}),
     eventId: event.event_id,
     messageId: event.data.id,
     chatId: event.data.chat.id,
@@ -101,8 +114,9 @@ export function buildRelayInboundFacts(
         // The answer quotes the person's message, the one it answers (a bot's
         // reply_to in Telegram and Discord names the person's message). A
         // tap's reply_to names the agent's buttons part, which no reply may
-        // target, so this is also what keeps a tap answerable.
-        replyAnchorId: event.data.id,
+        // target, so this is also what keeps a tap answerable. An agent's
+        // Message is quoted only through agentReplyLink.
+        ...(fromAgent ? {} : { replyAnchorId: event.data.id }),
       }
       : {}),
     ...(Number.isFinite(timestamp) ? { timestamp } : {}),

package/src/turns.ts

@@ -0,0 +1,94 @@
+import type { RelayIngressLifecycle } from "./ingress.js";
+
+/**
+ * The OpenClaw turns running in each Chat of one Relay account, so another
+ * agent's Message can wait for them instead of steering into them.
+ *
+ * OpenClaw steers a Message that arrives mid-turn into the running turn by
+ * default (`messages.queue.mode` "steer", docs/concepts/queue.md), and that
+ * turn's answer names the first Message. With `followup` the queued turn's
+ * answer names none. Relay's A2A door gives each calling agent only the answer
+ * whose `reply_to` names its Message (Relay-Server `a2a.ts` `replyTo`), so the
+ * second of two overlapping calls got no answer. A channel plugin "may
+ * preserve ordering ... before a message enters the session queue"
+ * (docs/concepts/messages.md, Queueing and followups); this is that ordering,
+ * the same rule Relay's CLI bridges follow (`replacesLiveTurn`, PR 366): an
+ * agent's Message waits its turn, a person's Message is left to OpenClaw.
+ */
+export type RelayChatTurns = {
+  /** Run one dispatch into OpenClaw, recorded as running in its Chat until it settles. */
+  track<T>(chatId: string, work: () => Promise<T>): Promise<T>;
+  /** Whether a turn runs in the Chat now. */
+  busy(chatId: string): boolean;
+  /** Resolve once no turn runs in the Chat; reject with the signal's reason. */
+  idle(chatId: string, signal?: AbortSignal): Promise<void>;
+};
+
+export function createRelayChatTurns(): RelayChatTurns {
+  const running = new Map<string, Set<Promise<unknown>>>();
+  return {
+    track(chatId, work) {
+      const turns = running.get(chatId) ?? new Set<Promise<unknown>>();
+      running.set(chatId, turns);
+      const turn = work();
+      turns.add(turn);
+      const settle = () => {
+        turns.delete(turn);
+        if (turns.size === 0 && running.get(chatId) === turns) running.delete(chatId);
+      };
+      turn.then(settle, settle);
+      return turn;
+    },
+    busy: (chatId) => Boolean(running.get(chatId)?.size),
+    async idle(chatId, signal) {
+      for (;;) {
+        signal?.throwIfAborted();
+        const turns = running.get(chatId);
+        if (!turns?.size) return;
+        const settled = Promise.allSettled([...turns]);
+        if (!signal) {
+          await settled;
+          continue;
+        }
+        await new Promise<void>((resolve, reject) => {
+          const abort = () => reject(signal.reason);
+          signal.addEventListener("abort", abort, { once: true });
+          void settled.then(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+          });
+        });
+      }
+    },
+  };
+}
+
+/**
+ * Hold a claimed Relay event until its Chat is idle. The claim is handed off
+ * as deferred and kept alive with the drain's own heartbeat
+ * (`ChannelIngressDispatchLifecycle.onDeferred` / `onDeferredHeartbeat`,
+ * docs/plugins/sdk-channel-outbound.md "Deferred claim heartbeats"), so the
+ * adoption watchdog does not retry a Message that is only waiting its turn. On
+ * shutdown the wait rejects before adoption, and the drain keeps the event for
+ * the next start.
+ */
+export async function waitForIdleChat(params: {
+  turns: RelayChatTurns;
+  chatId: string;
+  lifecycle: Partial<RelayIngressLifecycle>;
+}): Promise<void> {
+  const { lifecycle } = params;
+  if (!params.turns.busy(params.chatId)) return;
+  const signal = lifecycle.abortSignal;
+  lifecycle.onDeferred?.();
+  const interval = lifecycle.deferredHeartbeatIntervalMs;
+  const heartbeat = lifecycle.onDeferredHeartbeat && interval && interval > 0
+    ? setInterval(() => lifecycle.onDeferredHeartbeat?.(), interval)
+    : undefined;
+  heartbeat?.unref?.();
+  try {
+    await params.turns.idle(params.chatId, signal);
+  } finally {
+    if (heartbeat) clearInterval(heartbeat);
+  }
+}

package/src/types.ts

@@ -83,5 +83,12 @@ export type RelayInboundFacts = {
    * agent's buttons part, which no reply may target.
    */
   replyAnchorId?: string;
+  /** Whether another agent sent the Message. */
+  fromAgent: boolean;
+  /**
+   * The Message every answer names when another agent sent it: this one,
+   * unless it opens with buttons or a selection, which no reply may target.
+   */
+  agentReplyLink?: string;
   timestamp?: number;
 };