@relaymessenger/openclaw-plugin 0.4.7-staging.2 → 0.4.7-staging.21

package/README.md

@@ -12,6 +12,26 @@ 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 after the question.
+`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.
+
+## Invoice
+
+A verified agent ends the final answer with an `invoice` JSON fence holding a
+Stripe checkout link; the words go first and the invoice follows as its own
+Message.
+
 ## Install
 
 ```bash

package/contracts/relay-v1.lock.json

@@ -1,16 +1,16 @@
 {
   "relayServer": {
     "repository": "RelayMessenger/Relay-Server",
-    "commit": "74b7603fff3025b6d591a35f9b6f8ed9e2383173",
+    "commit": "3b7425e5bafcf25cdc8ceff009715e4f06877d18",
     "openapiPath": "contracts/developer/openapi.yaml",
-    "sha256": "9e92c51df654d6896e13a56e95b6a32ce0fbb4c77ed9c754603482890e84dfde"
+    "sha256": "3fb4873a3c09b7dade09012ecfc57acfef8cfb983b6b35fff9d320cf62bb3b00"
   },
   "relaySdk": {
     "package": "@relaymessenger/sdk",
-    "version": "0.3.6-staging.2",
-    "integrity": "sha512-v430wR76ud6ZyUCVqVW7RK0be2iT83NS1lQQAGKpbA4XINs0kC0zPI7SBEVFrQgq1HVmZF+zcqbjgAdeF+z9Ig==",
-    "operationsSha256": "a7c3367841e1f7803ff4a040586e30a6347d80548999015503f18d8e32f47b40",
-    "workspaceOpenapiSha256": "9e92c51df654d6896e13a56e95b6a32ce0fbb4c77ed9c754603482890e84dfde",
+    "version": "0.3.6-staging.22",
+    "integrity": "sha512-PnMaOgFgLcYD8xTspki0mGpySfVnkxC/EjnyTiNYioWuy+hJjtYzE3xwjJEnDYyJ6HlucDzZqmFCE07PgILCGw==",
+    "operationsSha256": "5d9cc3d0eed738d85deb3842b6efc0db5fe720299aa53e959f87e83c8585be36",
+    "workspaceOpenapiSha256": "3fb4873a3c09b7dade09012ecfc57acfef8cfb983b6b35fff9d320cf62bb3b00",
     "usedOperations": [
       {
         "method": "GET",

package/dist/src/channel.js

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

package/dist/src/dispatch.js

@@ -1,3 +1,4 @@
+import { BUTTONS_GUIDANCE, BUTTONS_BLOCK_INSTRUCTION, INVOICE_BLOCK_INSTRUCTION, INVOICE_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";
@@ -170,12 +171,16 @@ export async function dispatchRelayEvent(params) {
         reply: {
             to: facts.chatId,
             originatingTo: facts.chatId,
-            ...(facts.replyToId ? { replyToId: facts.replyToId } : {}),
+            ...((facts.replyAnchorId ?? facts.replyToId)
+                ? { replyToId: facts.replyAnchorId ?? facts.replyToId }
+                : {}),
         },
         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} ${INVOICE_BLOCK_INSTRUCTION} ${INVOICE_GUIDANCE}`,
+            ].filter(Boolean).join("\n\n"),
             rawBody: facts.text,
             commandBody: facts.text,
         },

package/dist/src/inbound.js

@@ -1,3 +1,4 @@
+import { selectionReply, selectionReplyContext } from "@relaymessenger/sdk";
 function renderPart(part) {
     switch (part.type) {
         case "text":
@@ -8,6 +9,12 @@ function renderPart(part) {
             return `[Attachment: ${part.filename} (${part.mime_type})] ${part.url}`;
         case "system":
             return part.value;
+        // 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;
     }
 }
 export function renderRelayMessageParts(parts) {
@@ -37,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" &&
@@ -46,7 +55,10 @@ 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);
     return {
+        ...(selection ? { selection } : {}),
+        ...(richMessage ? { richMessage } : {}),
         eventId: event.event_id,
         messageId: event.data.id,
         chatId: event.data.chat.id,
@@ -61,7 +73,14 @@ export function buildRelayInboundFacts(event) {
             ? { ownerHandle: event.data.chat.owner_handle }
             : {}),
         ...(event.data.reply_to?.message_id
-            ? { replyToId: event.data.reply_to.message_id }
+            ? {
+                replyToId: event.data.reply_to.message_id,
+                // 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,
+            }
             : {}),
         ...(Number.isFinite(timestamp) ? { timestamp } : {}),
     };

package/dist/src/outbound.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { Relay, RelayAPIError, } from "@relaymessenger/sdk";
+import { answerMessages, indexedIdempotencyKey, Relay, RelayAPIError, } from "@relaymessenger/sdk";
 export const RELAY_TEXT_CHUNK_LIMIT = 10_000;
 const IDEMPOTENCY_KEY_MAX_LENGTH = 255;
 export function createRelaySdkClient(account) {
@@ -17,17 +17,35 @@ export function deriveRelayIdempotencyKey(params) {
         ? raw
         : `relay-openclaw:sha256:${createHash("sha256").update(raw).digest("hex")}`;
 }
+/**
+ * OpenClaw hands the agent's words as text, so buttons ride in them as the
+ * SDK's fenced block, lifted here into the buttons part, and a link written
+ * alone on a line goes out as its own link Message. A block that cannot be
+ * read stays in the words and is reported through `onButtonsError`. Without
+ * a block or a link line the words go exactly as OpenClaw handed them, in one
+ * Message; the response is the first Message's, the one the reply anchors to.
+ */
 export async function sendRelayText(params) {
     await params.onPlatformSendDispatch?.();
-    return await params.relay.chats.messages.send(params.chatId, {
-        message: {
-            parts: [{ type: "text", value: params.text }],
-            idempotency_key: params.idempotencyKey,
-            ...(params.replyToId
-                ? { reply_to: { message_id: params.replyToId } }
-                : {}),
-        },
-    }, params.signal ? { signal: params.signal } : undefined);
+    const { messages, error } = answerMessages(params.text);
+    if (error)
+        params.onButtonsError?.(error);
+    if (messages.length === 0)
+        messages.push([{ type: "text", value: params.text }]);
+    let first;
+    for (const [index, parts] of messages.entries()) {
+        const response = await params.relay.chats.messages.send(params.chatId, {
+            message: {
+                parts,
+                idempotency_key: indexedIdempotencyKey(params.idempotencyKey, index),
+                ...(index === 0 && params.replyToId
+                    ? { reply_to: { message_id: params.replyToId } }
+                    : {}),
+            },
+        }, params.signal ? { signal: params.signal } : undefined);
+        first ??= response;
+    }
+    return first;
 }
 export function classifyUnknownRelaySend(error) {
     if (!(error instanceof RelayAPIError)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relaymessenger/openclaw-plugin",
-  "version": "0.4.7-staging.2",
+  "version": "0.4.7-staging.21",
   "description": "Native Relay channel plugin for OpenClaw",
   "license": "MIT",
   "type": "module",
@@ -37,11 +37,11 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@relaymessenger/sdk": "0.3.6-staging.2"
+    "@relaymessenger/sdk": "0.3.6-staging.22"
   },
   "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

@@ -329,6 +329,10 @@ export const relayChannelPlugin: ChannelPlugin<ResolvedRelayAccount> =
               deliveryQueueId: ctx.deliveryQueueId,
               deliveryPartIndex: ctx.deliveryPartIndex,
             }),
+            onButtonsError: (error) =>
+              (ctx as { log?: { warn?: (message: string) => void } }).log?.warn?.(
+                `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, INVOICE_BLOCK_INSTRUCTION, INVOICE_GUIDANCE, LINK_LINE_INSTRUCTION, SELECTION_GUIDANCE, SELECTION_BLOCK_INSTRUCTION, selectionReplyContext } from "@relaymessenger/sdk";
 import type {
   Message,
   Relay,
@@ -236,12 +237,16 @@ export async function dispatchRelayEvent(params: {
     reply: {
       to: facts.chatId,
       originatingTo: facts.chatId,
-      ...(facts.replyToId ? { replyToId: facts.replyToId } : {}),
+      ...((facts.replyAnchorId ?? facts.replyToId)
+        ? { replyToId: facts.replyAnchorId ?? facts.replyToId }
+        : {}),
     },
     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} ${INVOICE_BLOCK_INSTRUCTION} ${INVOICE_GUIDANCE}`,
+      ].filter(Boolean).join("\n\n"),
       rawBody: facts.text,
       commandBody: facts.text,
     },

package/src/inbound.ts

@@ -1,3 +1,4 @@
+import { selectionReply, selectionReplyContext } from "@relaymessenger/sdk";
 import type {
   MessagePartResponse,
   RelayWebhookEvent,
@@ -17,6 +18,12 @@ function renderPart(part: MessagePartResponse): string | undefined {
       return `[Attachment: ${part.filename} (${part.mime_type})] ${part.url}`;
     case "system":
       return part.value;
+    // 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;
   }
 }
 
@@ -57,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" &&
@@ -68,7 +77,10 @@ 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);
   return {
+    ...(selection ? { selection } : {}),
+    ...(richMessage ? { richMessage } : {}),
     eventId: event.event_id,
     messageId: event.data.id,
     chatId: event.data.chat.id,
@@ -84,7 +96,14 @@ export function buildRelayInboundFacts(
       ? { ownerHandle: event.data.chat.owner_handle }
       : {}),
     ...(event.data.reply_to?.message_id
-      ? { replyToId: event.data.reply_to.message_id }
+      ? {
+        replyToId: event.data.reply_to.message_id,
+        // 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,
+      }
       : {}),
     ...(Number.isFinite(timestamp) ? { timestamp } : {}),
   };

package/src/outbound.ts

@@ -1,5 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import {
+  answerMessages,
+  indexedIdempotencyKey,
   Relay,
   RelayAPIError,
   type MessageSendResponse,
@@ -32,6 +34,14 @@ export function deriveRelayIdempotencyKey(params: {
     : `relay-openclaw:sha256:${createHash("sha256").update(raw).digest("hex")}`;
 }
 
+/**
+ * OpenClaw hands the agent's words as text, so buttons ride in them as the
+ * SDK's fenced block, lifted here into the buttons part, and a link written
+ * alone on a line goes out as its own link Message. A block that cannot be
+ * read stays in the words and is reported through `onButtonsError`. Without
+ * a block or a link line the words go exactly as OpenClaw handed them, in one
+ * Message; the response is the first Message's, the one the reply anchors to.
+ */
 export async function sendRelayText(params: {
   relay: Pick<Relay, "chats">;
   chatId: string;
@@ -40,21 +50,30 @@ export async function sendRelayText(params: {
   idempotencyKey: string;
   signal?: AbortSignal;
   onPlatformSendDispatch?: () => Promise<void>;
+  onButtonsError?: (error: string) => void;
 }): Promise<MessageSendResponse> {
   await params.onPlatformSendDispatch?.();
-  return await params.relay.chats.messages.send(
-    params.chatId,
-    {
-      message: {
-        parts: [{ type: "text", value: params.text }],
-        idempotency_key: params.idempotencyKey,
-        ...(params.replyToId
-          ? { reply_to: { message_id: params.replyToId } }
-          : {}),
+  const { messages, error } = answerMessages(params.text);
+  if (error) params.onButtonsError?.(error);
+  if (messages.length === 0) messages.push([{ type: "text", value: params.text }]);
+  let first: MessageSendResponse | undefined;
+  for (const [index, parts] of messages.entries()) {
+    const response = await params.relay.chats.messages.send(
+      params.chatId,
+      {
+        message: {
+          parts,
+          idempotency_key: indexedIdempotencyKey(params.idempotencyKey, index),
+          ...(index === 0 && params.replyToId
+            ? { reply_to: { message_id: params.replyToId } }
+            : {}),
+        },
       },
-    },
-    params.signal ? { signal: params.signal } : undefined,
-  );
+      params.signal ? { signal: params.signal } : undefined,
+    );
+    first ??= response;
+  }
+  return first!;
 }
 
 export function classifyUnknownRelaySend(error: unknown): {

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,5 +77,11 @@ export type RelayInboundFacts = {
   mentionHandles: string[];
   ownerHandle?: ChatHandle;
   replyToId?: string;
+  /**
+   * 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;
   timestamp?: number;
 };