@relaymessenger/openclaw-plugin 0.4.7-staging.3 → 0.4.7-staging.31

package/README.md

@@ -12,6 +12,28 @@ 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.
+
+## 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

package/contracts/relay-v1.lock.json

@@ -1,16 +1,16 @@
 {
   "relayServer": {
     "repository": "RelayMessenger/Relay-Server",
-    "commit": "78d7991c7b8a615302ab30d727503779755df3ab",
+    "commit": "486fb8b70680bafd52532d478e4067e714901774",
     "openapiPath": "contracts/developer/openapi.yaml",
-    "sha256": "1d790da998a8dfc26cffc098def76d85b8275af7a343148df8e78c486cd02849"
+    "sha256": "eac6c797d7f4a63ed2bdcd3d9bc0b0a0f5b4b889c6c0b2f731ac0738f7c0eb69"
   },
   "relaySdk": {
     "package": "@relaymessenger/sdk",
-    "version": "0.3.6-staging.3",
-    "integrity": "sha512-yT5/q4alxyFPPmrOh3MqVk9i+55ZPyiLFPX4K4QGeqQsI8/qNt5GCaNVBGewD/rq6Zlw7sfeDqR9P/9leMfPwg==",
-    "operationsSha256": "a7c3367841e1f7803ff4a040586e30a6347d80548999015503f18d8e32f47b40",
-    "workspaceOpenapiSha256": "1d790da998a8dfc26cffc098def76d85b8275af7a343148df8e78c486cd02849",
+    "version": "0.3.6-staging.33",
+    "integrity": "sha512-sYj/2OEqse7EkVvy9pPRlgocNuN46LVHVtB1kg4ro+56QNMML132kn6to8B3lUoO2SBRwG/u1gN45nTjaetWlw==",
+    "operationsSha256": "dc65744bdac51c47863b72536ae7ac7914a72d882f58f8ccc7d1cd3e5a54bec6",
+    "workspaceOpenapiSha256": "eac6c797d7f4a63ed2bdcd3d9bc0b0a0f5b4b889c6c0b2f731ac0738f7c0eb69",
     "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, 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";
@@ -177,7 +178,9 @@ export async function dispatchRelayEvent(params) {
         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,
         },

package/dist/src/inbound.js

@@ -1,3 +1,4 @@
+import { selectionReply, selectionReplyContext } from "@relaymessenger/sdk";
 function renderPart(part) {
     switch (part.type) {
         case "text":
@@ -8,12 +9,11 @@ function renderPart(part) {
             return `[Attachment: ${part.filename} (${part.mime_type})] ${part.url}`;
         case "system":
             return part.value;
-        // A tap reads as the label the person chose: the same text the server
-        // derives for a button_reply. The agent's own buttons part reads as
-        // nothing, again as the server does; its question is the text beside it.
-        case "button_reply":
-            return part.label;
+        // 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;
     }
 }
@@ -44,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" &&
@@ -53,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,
@@ -70,9 +75,11 @@ export function buildRelayInboundFacts(event) {
         ...(event.data.reply_to?.message_id
             ? {
                 replyToId: event.data.reply_to.message_id,
-                replyAnchorId: event.data.parts.some((part) => part.type === "button_reply")
-                    ? event.data.id
-                    : 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, 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) {
@@ -17,17 +17,49 @@ 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, payment, error } = answerMessages(params.text);
+    if (error)
+        params.onButtonsError?.(error);
+    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, {
+            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.3",
+  "version": "0.4.7-staging.31",
   "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.3"
+    "@relaymessenger/sdk": "0.3.6-staging.33"
   },
   "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, PAYMENT_BLOCK_INSTRUCTION, PAYMENT_GUIDANCE, LINK_LINE_INSTRUCTION, SELECTION_GUIDANCE, SELECTION_BLOCK_INSTRUCTION, selectionReplyContext } from "@relaymessenger/sdk";
 import type {
   Message,
   Relay,
@@ -243,7 +244,9 @@ export async function dispatchRelayEvent(params: {
     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,
     },

package/src/inbound.ts

@@ -1,3 +1,4 @@
+import { selectionReply, selectionReplyContext } from "@relaymessenger/sdk";
 import type {
   MessagePartResponse,
   RelayWebhookEvent,
@@ -17,12 +18,11 @@ function renderPart(part: MessagePartResponse): string | undefined {
       return `[Attachment: ${part.filename} (${part.mime_type})] ${part.url}`;
     case "system":
       return part.value;
-    // A tap reads as the label the person chose: the same text the server
-    // derives for a button_reply. The agent's own buttons part reads as
-    // nothing, again as the server does; its question is the text beside it.
-    case "button_reply":
-      return part.label;
+    // 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;
   }
 }
@@ -64,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" &&
@@ -75,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,
@@ -93,9 +98,11 @@ export function buildRelayInboundFacts(
     ...(event.data.reply_to?.message_id
       ? {
         replyToId: event.data.reply_to.message_id,
-        replyAnchorId: event.data.parts.some((part) => part.type === "button_reply")
-          ? event.data.id
-          : 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,8 @@
 import { createHash, randomUUID } from "node:crypto";
 import {
+  answerMessages,
+  createPaymentPart,
+  indexedIdempotencyKey,
   Relay,
   RelayAPIError,
   type MessageSendResponse,
@@ -32,29 +35,58 @@ 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">;
+  relay: Pick<Relay, "chats" | "paymentRequests">;
   chatId: string;
   text: string;
   replyToId?: string | null | undefined;
   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, payment, error } = answerMessages(params.text);
+  if (error) params.onButtonsError?.(error);
+  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(
+      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;
@@ -73,10 +78,9 @@ export type RelayInboundFacts = {
   ownerHandle?: ChatHandle;
   replyToId?: string;
   /**
-   * The Message an outbound reply should quote. A tap's reply_to names the
-   * agent's buttons part, which only a button_reply may target, so the
-   * agent's answer quotes the tap itself; every other Message quotes what
-   * the person quoted.
+   * 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;