@relaymessenger/openclaw-plugin 0.4.7-staging.9 → 0.4.7

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)
@@ -12,12 +12,45 @@ delivers events over its v1 WebSocket, and the plugin sends replies through
 the Relay v1 REST Message API. The plugin imports `@relaymessenger/sdk`; it
 does not contain a copied Relay client or protocol implementation.
 
+## Selection
+
+End the final answer with a `selection` JSON fence holding the question as
+`title` (1 to 60 characters) and the `options`; any words outside the fence go
+as a normal message above the card.
+`BodyForAgent` carries structured response and rich-message JSON; `RawBody` and
+`CommandBody` retain readable text. Stable values are not executable commands.
+
+New human reply text is literal `• ` + each selected source label joined with
+`\n`, followed by `selection_response` metadata in source-option order. Dispatch
+with `selected_values` and the explicit source target, never label parsing.
+Exact legacy comma-joined text remains a server compatibility input. The person
+checks any number of options and submits them once; checking sends nothing, and
+a person answers a given selection once. iOS may draw a checkmark in place of
+each bullet and repeat the prompt's title, as presentation only.
+
+## Payment
+
+The agent ends the final answer with a `payment` JSON fence holding the
+payment request's fields (`description`, `category`, and `amount` with
+`currency`, or `mode: "subscription"` with `price_id`). The plugin creates the
+request with its own Relay token, on the card's own idempotency key; the words
+go first and the payment card follows as its own Message.
+
 ## Install
 
 ```bash
 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
@@ -106,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:
@@ -153,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": "17ad8d0c1d1d420e88a008eeaa3f3e910cb01972",
+    "commit": "9448e92fb7465bdf30bad37475e5f3017460799b",
     "openapiPath": "contracts/developer/openapi.yaml",
-    "sha256": "c97bee2a79fac1866326a7df4398bb8b9750b824cf501dfe226130c18275c171"
+    "sha256": "61bd07d26328a493fa3aca1ceef9bf1c43321d31fb3ba3c6e10f7d353b48218b"
   },
   "relaySdk": {
     "package": "@relaymessenger/sdk",
-    "version": "0.3.6-staging.8",
-    "integrity": "sha512-Jj96lQtPRgn3y7BWBgAoestpSrA5JLoo91LUFPdUVj5jfbFwhOUzS3+GSp+1yd85c+r1pYjCAxh5mb5tiujmlw==",
-    "operationsSha256": "04e5e1f1f626a2b0607fb0d091f12a4205a9e298fdb6f56e5bfcc446c9fe5ee3",
-    "workspaceOpenapiSha256": "c97bee2a79fac1866326a7df4398bb8b9750b824cf501dfe226130c18275c171",
+    "version": "0.3.6",
+    "integrity": "sha512-npGKYHveASvFDQ5DEq3ZYEjqwJDrDJhXfxELHEWPUYY2mylwJiXX4J/5RjQ76c5oS+bG2jOy8YXKhgr0TIgMTQ==",
+    "operationsSha256": "b118ea1dcd729270b1453afad2b69f5d12e85fc24682b59305f9e691e9a6eae6",
+    "workspaceOpenapiSha256": "61bd07d26328a493fa3aca1ceef9bf1c43321d31fb3ba3c6e10f7d353b48218b",
     "usedOperations": [
       {
         "method": "GET",

package/dist/src/channel.js

@@ -249,7 +249,7 @@ export const relayChannelPlugin = createChatChannelPlugin({
                         deliveryQueueId: ctx.deliveryQueueId,
                         deliveryPartIndex: ctx.deliveryPartIndex,
                     }),
-                    onButtonsError: (error) => ctx.log?.warn?.(`relay: buttons block left as text: ${error}`),
+                    onButtonsError: (error) => ctx.log?.warn?.(`relay: component block left as text: ${error}`),
                     ...(ctx.onPlatformSendDispatch
                         ? { onPlatformSendDispatch: ctx.onPlatformSendDispatch }
                         : {}),

package/dist/src/dispatch.js

@@ -1,7 +1,9 @@
+import { BUTTONS_GUIDANCE, BUTTONS_BLOCK_INSTRUCTION, PAYMENT_BLOCK_INSTRUCTION, PAYMENT_GUIDANCE, LINK_LINE_INSTRUCTION, SELECTION_GUIDANCE, SELECTION_BLOCK_INSTRUCTION, selectionReplyContext } from "@relaymessenger/sdk";
 import { buildChannelInboundEventContext, resolveChannelInboundRouteEnvelope, } from "openclaw/plugin-sdk/channel-inbound";
 import { resolveStableChannelMessageIngress } from "openclaw/plugin-sdk/channel-ingress-runtime";
 import { bindIngressLifecycleToReplyOptions } from "openclaw/plugin-sdk/channel-outbound";
-import { buildRelayInboundFacts } from "./inbound.js";
+import { buildRelayInboundFacts, renderRelayMessageParts } from "./inbound.js";
+import { waitForIdleChat } from "./turns.js";
 function isReplyToAgentMessage(message, chatId) {
     return message.chat_id === chatId && message.is_from_me === true;
 }
@@ -28,7 +30,8 @@ export async function resolveRelayTurnActivation(params) {
     }
     if (!params.facts.replyToId)
         return null;
-    const replyTarget = await params.relay.messages.retrieve(params.facts.replyToId);
+    const replyTarget = params.replyTarget
+        ?? await params.relay.messages.retrieve(params.facts.replyToId);
     if (!isReplyToAgentMessage(replyTarget, params.facts.chatId))
         return null;
     return {
@@ -37,15 +40,90 @@ export async function resolveRelayTurnActivation(params) {
         implicitMentionKinds: ["reply_to_bot"],
     };
 }
+/**
+ * The Message a swipe-reply answers, read once for the quote and for group
+ * activation. A failed read is logged and the turn runs without the quote;
+ * group activation then reads it itself and fails the delivery as before.
+ */
+async function readReplyTarget(params) {
+    if (!params.facts.replyToId)
+        return undefined;
+    try {
+        return await params.relay.messages.retrieve(params.facts.replyToId);
+    }
+    catch (error) {
+        params.warn?.(`relay: could not read the Message ${params.facts.replyToId} that ${params.facts.messageId} replies to: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+/**
+ * OpenClaw's own reply context, `supplemental.quote`, which it renders to the
+ * model as "Reply target of current user message" (id, sender, body), as its
+ * Telegram channel fills it from Telegram's `reply_to_message`. A reply names
+ * one bubble: a multipart target is narrowed to the swiped part, the rule
+ * Relay's iOS app uses to draw the quote (the SDK's `replyTargetParts`); a
+ * tap or a selection answer names a part with no words, so it keeps the
+ * whole Message.
+ */
+export function relayReplyQuote(facts, target) {
+    if (!target || target.chat_id !== facts.chatId)
+        return undefined;
+    const parts = target.parts ?? [];
+    const swiped = parts.length > 1 && facts.replyToPartIndex !== undefined
+        ? parts[facts.replyToPartIndex]
+        : undefined;
+    const body = renderRelayMessageParts(swiped && swiped.type !== "buttons" && swiped.type !== "selection" ? [swiped] : parts);
+    const sender = target.from_handle?.display_name?.trim()
+        || target.from_handle?.handle
+        || target.from
+        || undefined;
+    return {
+        id: target.id,
+        ...(body ? { body } : {}),
+        ...(sender ? { sender } : {}),
+        senderAllowed: true,
+    };
+}
+/**
+ * Whether the part a reply names may itself be replied to. A tap names the
+ * agent's buttons part and a selection answer its selection part; no reply may
+ * point at those (Relay v1 ReplyTo.part_index), so a person's tap keeps its
+ * own Message as the reply target.
+ */
+function repliable(target, partIndex) {
+    const part = target?.parts?.[partIndex ?? 0];
+    return part !== undefined && part.type !== "buttons" && part.type !== "selection";
+}
+/**
+ * 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) {
         params.warn?.(`relay: durably accepted ${params.event.event_type} event ${params.event.event_id} without an agent turn`);
         return;
     }
+    const repliedTo = await readReplyTarget({
+        facts,
+        relay: params.relay,
+        warn: params.warn,
+    });
     const activation = await resolveRelayTurnActivation({
         facts,
         relay: params.relay,
+        ...(repliedTo ? { replyTarget: repliedTo } : {}),
     });
     if (!activation) {
         params.warn?.(`relay: durably accepted unmentioned group Message ${facts.messageId} without an agent turn`);
@@ -136,6 +214,17 @@ 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 to, OpenClaw's ReplyToId, as its
+    // Telegram channel sets `reply.replyToId` to Telegram's reply_to_message:
+    // the prompt names it beside the quote. A tap or a selection answer names a
+    // part no reply may target, so it keeps the person's own Message.
+    const quote = relayReplyQuote(facts, repliedTo);
+    const replyTarget = facts.fromAgent
+        ? facts.agentReplyLink
+        : quote && repliable(repliedTo, facts.replyToPartIndex)
+            ? quote.id
+            : facts.replyAnchorId ?? facts.replyToId;
     const body = buildEnvelope({
         channel: "Relay",
         from: `${facts.displayName} (@${facts.handle})`,
@@ -170,17 +259,18 @@ 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",
             body,
-            bodyForAgent: facts.text,
+            bodyForAgent: [facts.text, selectionReplyContext(facts.selection, facts.richMessage),
+                `${BUTTONS_BLOCK_INSTRUCTION} ${LINK_LINE_INSTRUCTION} ${BUTTONS_GUIDANCE} ${SELECTION_BLOCK_INSTRUCTION} ${SELECTION_GUIDANCE} ${PAYMENT_BLOCK_INSTRUCTION} ${PAYMENT_GUIDANCE}`,
+            ].filter(Boolean).join("\n\n"),
             rawBody: facts.text,
             commandBody: facts.text,
         },
+        ...(quote ? { supplemental: { quote } } : {}),
         channelIngress: access,
         access: {
             commands: {
@@ -197,6 +287,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),
@@ -209,7 +308,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,
@@ -222,9 +321,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");
@@ -247,7 +354,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

@@ -1,3 +1,4 @@
+import { selectionReply, selectionReplyContext } from "@relaymessenger/sdk";
 function renderPart(part) {
     switch (part.type) {
         case "text":
@@ -11,6 +12,8 @@ function renderPart(part) {
         // The agent's own buttons part reads as nothing, as on the server; its
         // question is the text beside it. A tap arrives as ordinary text.
         case "buttons":
+        case "selection":
+        case "selection_response":
             return undefined;
     }
 }
@@ -41,7 +44,9 @@ export function buildRelayInboundFacts(event) {
         event.data.sender_handle.kind !== "agent")
         return null;
     const text = renderRelayMessageParts(event.data.parts);
-    if (!text.trim())
+    const message = { parts: event.data.parts, ...(event.data.reply_to ? { reply_to: event.data.reply_to } : {}) };
+    const richMessage = selectionReplyContext(undefined, message) ? message : undefined;
+    if (!text.trim() && !richMessage)
         return null;
     const mentionHandles = event.data.parts.flatMap((part) => part.type === "text" &&
         typeof part.mention === "string" &&
@@ -50,7 +55,23 @@ 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,
@@ -67,11 +88,15 @@ export function buildRelayInboundFacts(event) {
         ...(event.data.reply_to?.message_id
             ? {
                 replyToId: event.data.reply_to.message_id,
+                ...(event.data.reply_to.part_index === undefined
+                    ? {}
+                    : { replyToPartIndex: event.data.reply_to.part_index }),
                 // 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/outbound.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { answerMessages, indexedIdempotencyKey, Relay, RelayAPIError, } from "@relaymessenger/sdk";
+import { answerMessages, createPaymentPart, indexedIdempotencyKey, Relay, RelayAPIError, } from "@relaymessenger/sdk";
 export const RELAY_TEXT_CHUNK_LIMIT = 10_000;
 const IDEMPOTENCY_KEY_MAX_LENGTH = 255;
 export function createRelaySdkClient(account) {
@@ -27,11 +27,25 @@ export function deriveRelayIdempotencyKey(params) {
  */
 export async function sendRelayText(params) {
     await params.onPlatformSendDispatch?.();
-    const { messages, error } = answerMessages(params.text);
+    const { messages, payment, error } = answerMessages(params.text);
     if (error)
         params.onButtonsError?.(error);
-    if (messages.length === 0)
+    if (messages.length === 0 && !payment)
         messages.push([{ type: "text", value: params.text }]);
+    if (payment) {
+        // Created with the card's own key, so a retry of this delivery returns
+        // the same request. A refusal after words went out is reported and the
+        // words stand; with nothing sent yet, it is the delivery's own error.
+        const key = indexedIdempotencyKey(params.idempotencyKey, messages.length);
+        try {
+            messages.push([await createPaymentPart(params.relay, payment, key, params.signal ? { signal: params.signal } : undefined)]);
+        }
+        catch (refusal) {
+            if (!(refusal instanceof RelayAPIError) || refusal.retryable || messages.length === 0)
+                throw refusal;
+            params.onButtonsError?.(`the payment was not sent: ${refusal.message}`);
+        }
+    }
     let first;
     for (const [index, parts] of messages.entries()) {
         const response = await params.relay.chats.messages.send(params.chatId, {

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.9",
+  "version": "0.4.7",
   "description": "Native Relay channel plugin for OpenClaw",
   "license": "MIT",
   "type": "module",
@@ -33,15 +33,15 @@
     "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.8"
+    "@relaymessenger/sdk": "0.3.6"
   },
   "devDependencies": {
-    "@types/node": "^26.0.0",
-    "openclaw": "2026.8.1",
+    "@types/node": "^26.6.2",
+    "openclaw": "2026.9.5",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   },
@@ -164,7 +164,7 @@
       "pluginApi": ">=2026.8.1 <2026.10.0"
     },
     "build": {
-      "openclawVersion": "2026.8.1"
+      "openclawVersion": "2026.9.5"
     }
   }
 }

package/src/channel.ts

@@ -331,7 +331,7 @@ export const relayChannelPlugin: ChannelPlugin<ResolvedRelayAccount> =
             }),
             onButtonsError: (error) =>
               (ctx as { log?: { warn?: (message: string) => void } }).log?.warn?.(
-                `relay: buttons block left as text: ${error}`,
+                `relay: component block left as text: ${error}`,
               ),
             ...(ctx.onPlatformSendDispatch
               ? { onPlatformSendDispatch: ctx.onPlatformSendDispatch }

package/src/dispatch.ts

@@ -1,3 +1,4 @@
+import { BUTTONS_GUIDANCE, BUTTONS_BLOCK_INSTRUCTION, PAYMENT_BLOCK_INSTRUCTION, PAYMENT_GUIDANCE, LINK_LINE_INSTRUCTION, SELECTION_GUIDANCE, SELECTION_BLOCK_INSTRUCTION, selectionReplyContext } from "@relaymessenger/sdk";
 import type {
   Message,
   Relay,
@@ -10,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 { buildRelayInboundFacts } from "./inbound.js";
+import type { ReplyPayload } from "openclaw/plugin-sdk/reply-payload";
+import { buildRelayInboundFacts, renderRelayMessageParts } 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,
@@ -52,6 +55,8 @@ function isReplyToAgentMessage(
 export async function resolveRelayTurnActivation(params: {
   facts: RelayInboundFacts;
   relay: RelayReplyLookup;
+  /** The replied-to Message when the caller already read it. */
+  replyTarget?: Message;
 }): Promise<RelayTurnActivation | null> {
   if (params.facts.chatType === "direct") {
     return {
@@ -74,9 +79,8 @@ export async function resolveRelayTurnActivation(params: {
   }
 
   if (!params.facts.replyToId) return null;
-  const replyTarget = await params.relay.messages.retrieve(
-    params.facts.replyToId,
-  );
+  const replyTarget = params.replyTarget
+    ?? await params.relay.messages.retrieve(params.facts.replyToId);
   if (!isReplyToAgentMessage(replyTarget, params.facts.chatId)) return null;
   return {
     kind: "reply",
@@ -85,6 +89,89 @@ export async function resolveRelayTurnActivation(params: {
   };
 }
 
+/**
+ * The Message a swipe-reply answers, read once for the quote and for group
+ * activation. A failed read is logged and the turn runs without the quote;
+ * group activation then reads it itself and fails the delivery as before.
+ */
+async function readReplyTarget(params: {
+  facts: RelayInboundFacts;
+  relay: RelayReplyLookup;
+  warn: ((message: string) => void) | undefined;
+}): Promise<Message | undefined> {
+  if (!params.facts.replyToId) return undefined;
+  try {
+    return await params.relay.messages.retrieve(params.facts.replyToId);
+  } catch (error) {
+    params.warn?.(
+      `relay: could not read the Message ${params.facts.replyToId} that ${params.facts.messageId} replies to: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return undefined;
+  }
+}
+
+/**
+ * OpenClaw's own reply context, `supplemental.quote`, which it renders to the
+ * model as "Reply target of current user message" (id, sender, body), as its
+ * Telegram channel fills it from Telegram's `reply_to_message`. A reply names
+ * one bubble: a multipart target is narrowed to the swiped part, the rule
+ * Relay's iOS app uses to draw the quote (the SDK's `replyTargetParts`); a
+ * tap or a selection answer names a part with no words, so it keeps the
+ * whole Message.
+ */
+export function relayReplyQuote(
+  facts: Pick<RelayInboundFacts, "chatId" | "replyToPartIndex">,
+  target: Message | undefined,
+) {
+  if (!target || target.chat_id !== facts.chatId) return undefined;
+  const parts = target.parts ?? [];
+  const swiped = parts.length > 1 && facts.replyToPartIndex !== undefined
+    ? parts[facts.replyToPartIndex]
+    : undefined;
+  const body = renderRelayMessageParts(
+    swiped && swiped.type !== "buttons" && swiped.type !== "selection" ? [swiped] : parts,
+  );
+  const sender = target.from_handle?.display_name?.trim()
+    || target.from_handle?.handle
+    || target.from
+    || undefined;
+  return {
+    id: target.id,
+    ...(body ? { body } : {}),
+    ...(sender ? { sender } : {}),
+    senderAllowed: true,
+  };
+}
+
+/**
+ * Whether the part a reply names may itself be replied to. A tap names the
+ * agent's buttons part and a selection answer its selection part; no reply may
+ * point at those (Relay v1 ReplyTo.part_index), so a person's tap keeps its
+ * own Message as the reply target.
+ */
+function repliable(target: Message | undefined, partIndex: number | undefined): boolean {
+  const part = target?.parts?.[partIndex ?? 0];
+  return part !== undefined && part.type !== "buttons" && part.type !== "selection";
+}
+
+/**
+ * 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;
@@ -92,6 +179,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);
@@ -102,9 +190,15 @@ export async function dispatchRelayEvent(params: {
     return;
   }
 
+  const repliedTo = await readReplyTarget({
+    facts,
+    relay: params.relay,
+    warn: params.warn,
+  });
   const activation = await resolveRelayTurnActivation({
     facts,
     relay: params.relay,
+    ...(repliedTo ? { replyTarget: repliedTo } : {}),
   });
   if (!activation) {
     params.warn?.(
@@ -202,6 +296,17 @@ 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 to, OpenClaw's ReplyToId, as its
+  // Telegram channel sets `reply.replyToId` to Telegram's reply_to_message:
+  // the prompt names it beside the quote. A tap or a selection answer names a
+  // part no reply may target, so it keeps the person's own Message.
+  const quote = relayReplyQuote(facts, repliedTo);
+  const replyTarget = facts.fromAgent
+    ? facts.agentReplyLink
+    : quote && repliable(repliedTo, facts.replyToPartIndex)
+      ? quote.id
+      : facts.replyAnchorId ?? facts.replyToId;
   const body = buildEnvelope({
     channel: "Relay",
     from: `${facts.displayName} (@${facts.handle})`,
@@ -236,17 +341,18 @@ 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",
       body,
-      bodyForAgent: facts.text,
+      bodyForAgent: [facts.text, selectionReplyContext(facts.selection, facts.richMessage),
+        `${BUTTONS_BLOCK_INSTRUCTION} ${LINK_LINE_INSTRUCTION} ${BUTTONS_GUIDANCE} ${SELECTION_BLOCK_INSTRUCTION} ${SELECTION_GUIDANCE} ${PAYMENT_BLOCK_INSTRUCTION} ${PAYMENT_GUIDANCE}`,
+      ].filter(Boolean).join("\n\n"),
       rawBody: facts.text,
       commandBody: facts.text,
     },
+    ...(quote ? { supplemental: { quote } } : {}),
     channelIngress: access,
     access: {
       commands: {
@@ -264,6 +370,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),
@@ -277,7 +393,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,
@@ -290,9 +406,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(
@@ -317,7 +442,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

@@ -1,3 +1,4 @@
+import { selectionReply, selectionReplyContext } from "@relaymessenger/sdk";
 import type {
   MessagePartResponse,
   RelayWebhookEvent,
@@ -20,6 +21,8 @@ function renderPart(part: MessagePartResponse): string | undefined {
     // The agent's own buttons part reads as nothing, as on the server; its
     // question is the text beside it. A tap arrives as ordinary text.
     case "buttons":
+    case "selection":
+    case "selection_response":
       return undefined;
   }
 }
@@ -61,7 +64,9 @@ export function buildRelayInboundFacts(
   ) return null;
 
   const text = renderRelayMessageParts(event.data.parts);
-  if (!text.trim()) return null;
+  const message = { parts: event.data.parts, ...(event.data.reply_to ? { reply_to: event.data.reply_to } : {}) };
+  const richMessage = selectionReplyContext(undefined, message) ? message : undefined;
+  if (!text.trim() && !richMessage) return null;
 
   const mentionHandles = event.data.parts.flatMap((part) =>
     part.type === "text" &&
@@ -72,7 +77,23 @@ 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,
@@ -90,11 +111,15 @@ export function buildRelayInboundFacts(
     ...(event.data.reply_to?.message_id
       ? {
         replyToId: event.data.reply_to.message_id,
+        ...(event.data.reply_to.part_index === undefined
+          ? {}
+          : { replyToPartIndex: event.data.reply_to.part_index }),
         // 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/outbound.ts

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import {
   answerMessages,
+  createPaymentPart,
   indexedIdempotencyKey,
   Relay,
   RelayAPIError,
@@ -43,7 +44,7 @@ export function deriveRelayIdempotencyKey(params: {
  * Message; the response is the first Message's, the one the reply anchors to.
  */
 export async function sendRelayText(params: {
-  relay: Pick<Relay, "chats">;
+  relay: Pick<Relay, "chats" | "paymentRequests">;
   chatId: string;
   text: string;
   replyToId?: string | null | undefined;
@@ -53,9 +54,21 @@ export async function sendRelayText(params: {
   onButtonsError?: (error: string) => void;
 }): Promise<MessageSendResponse> {
   await params.onPlatformSendDispatch?.();
-  const { messages, error } = answerMessages(params.text);
+  const { messages, payment, error } = answerMessages(params.text);
   if (error) params.onButtonsError?.(error);
-  if (messages.length === 0) messages.push([{ type: "text", value: params.text }]);
+  if (messages.length === 0 && !payment) messages.push([{ type: "text", value: params.text }]);
+  if (payment) {
+    // Created with the card's own key, so a retry of this delivery returns
+    // the same request. A refusal after words went out is reported and the
+    // words stand; with nothing sent yet, it is the delivery's own error.
+    const key = indexedIdempotencyKey(params.idempotencyKey, messages.length);
+    try {
+      messages.push([await createPaymentPart(params.relay, payment, key, params.signal ? { signal: params.signal } : undefined)]);
+    } catch (refusal) {
+      if (!(refusal instanceof RelayAPIError) || refusal.retryable || messages.length === 0) throw refusal;
+      params.onButtonsError?.(`the payment was not sent: ${refusal.message}`);
+    }
+  }
   let first: MessageSendResponse | undefined;
   for (const [index, parts] of messages.entries()) {
     const response = await params.relay.chats.messages.send(

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

@@ -1,5 +1,8 @@
 import type {
   Chat,
+  SelectionReply,
+  MessagePartResponse,
+  ReplyTo,
   ChatHandle,
   MessageWebhookData,
   Message,
@@ -61,6 +64,8 @@ export type RelayMessageReceivedEvent = RelayWebhookEnvelope<
 >;
 
 export type RelayInboundFacts = {
+  selection?: SelectionReply;
+  richMessage?: { parts: MessagePartResponse[]; reply_to?: ReplyTo | null };
   eventId: string;
   messageId: string;
   chatId: string;
@@ -72,11 +77,20 @@ export type RelayInboundFacts = {
   mentionHandles: string[];
   ownerHandle?: ChatHandle;
   replyToId?: string;
+  /** The part of the replied-to Message the person swiped (`reply_to.part_index`). */
+  replyToPartIndex?: number;
   /**
    * The Message an outbound reply should quote when the person's Message
    * was itself a reply: the person's Message. A tap's reply_to names the
    * 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;
 };