@relaymessenger/openclaw-plugin 0.2.0 → 0.3.3

package/README.md

@@ -4,10 +4,14 @@ Backs a Relay contact with an OpenClaw agent: install the plugin, point it at
 an owner-only Agent Token file, and your OpenClaw appears in Relay as a contact
 you text like a friend.
 
-Requires `openclaw >= 2026.7.2-beta.5`, which today means the OpenClaw beta
-channel: stable `2026.7.1-2` is too old, because the plugin derives its
-idempotency keys from the per-part delivery context that only the beta line
-provides. Install it with `npm install -g openclaw@beta`.
+Requires `openclaw >= 2026.7.1-2`, which the stable channel satisfies today.
+
+Cores from `2026.7.2-beta.5` onward tell the channel which part of a delivery
+each chunk is, and the plugin keys its idempotent sends on that. Older cores do
+not, so on those the plugin keys each chunk by a digest of the chunk's own
+text. Both keep a retry replaying the same message instead of posting a second
+one. The one thing an older core cannot do is separate two byte-identical
+chunks of a single reply, which arrive as one message.
 
 ## Install
 

package/dist/src/channel.js

@@ -3,6 +3,17 @@
 // wiring. Transport logic lives in client/poll-loop/inbound/outbound modules;
 // this file owns the OpenClaw adapter surfaces.
 import { createChatChannelPlugin } from "openclaw/plugin-sdk/channel-core";
+/**
+ * Read core's part index without requiring it to exist. Cores before
+ * 2026.7.2-beta.5 have no `deliveryPartIndex` in their outbound context at all,
+ * so naming the field directly would not typecheck against them. Reading it
+ * through a widened shape keeps one source compiling on every supported core;
+ * `deriveRelayIdempotencyKey` handles the undefined case.
+ */
+function deliveryPartIndexOf(ctx) {
+    const index = ctx.deliveryPartIndex;
+    return typeof index === "number" ? index : undefined;
+}
 import { resolveStableChannelMessageIngress } from "openclaw/plugin-sdk/channel-ingress-runtime";
 import { createMessageReceiptFromOutboundResults, defineChannelMessageAdapter, } from "openclaw/plugin-sdk/channel-outbound";
 import { resolveInboundRouteEnvelopeBuilderWithRuntime } from "openclaw/plugin-sdk/inbound-envelope";
@@ -16,6 +27,7 @@ import { buildRelayInboundFacts } from "./inbound.js";
 import { createRelayAccountLifecycleRegistry } from "./lifecycle.js";
 import { deriveRelayIdempotencyKey, RELAY_TEXT_CHUNK_LIMIT, reconcileRelayUnknownSend, sendRelayText, } from "./outbound.js";
 import { runRelayPollLoop } from "./poll-loop.js";
+import { markRespondingBeforeAttempt } from "./responding.js";
 import { getRelayRuntime } from "./runtime.js";
 import { relaySenderIsAllowed, resolveRelayAllowedSenderIds } from "./security.js";
 export const RELAY_CHANNEL_ID = "relay";
@@ -131,12 +143,13 @@ const relayMessageAdapter = defineChannelMessageAdapter({
                 conversationId: ctx.to,
                 text: ctx.text,
                 replyToId: ctx.replyToId ?? null,
-                // Stable per (queueId, partIndex): internal retries replay the same
-                // key, so the server-side idempotent commit makes duplicates
-                // impossible by contract.
+                // Stable per (queueId, part): internal retries replay the same key,
+                // so the server-side idempotent commit makes duplicates impossible by
+                // contract. On a core with no part index the text names the part.
                 idempotencyKey: deriveRelayIdempotencyKey({
                     deliveryQueueId: ctx.deliveryQueueId,
-                    deliveryPartIndex: ctx.deliveryPartIndex,
+                    deliveryPartIndex: deliveryPartIndexOf(ctx),
+                    partText: ctx.text,
                 }),
                 ...(ctx.signal ? { signal: ctx.signal } : {}),
             });
@@ -232,7 +245,13 @@ async function dispatchRelayInbound(params) {
     // Admission, runtime resolution, route/session lookup, envelope building,
     // and context finalization above are replay-safe. The durable attempt starts
     // immediately before OpenClaw can invoke the agent or its tools.
-    await params.markAttempt();
+    await markRespondingBeforeAttempt({
+        client: params.client,
+        conversationId: facts.conversationId,
+        messageId: facts.messageId,
+        label: "OpenClaw",
+        markAttempt: params.markAttempt,
+    });
     await runtime.channel.inbound.dispatchReply({
         cfg: params.cfg,
         channel: RELAY_CHANNEL_ID,
@@ -422,11 +441,6 @@ async function startRelayAccount(ctx) {
                     allowedSenderIds,
                     markAttempt,
                 });
-                // Read watermark after the turn is handled: read implies delivered;
-                // best effort — a failed receipt must not replay the event.
-                await client
-                    .markRead({ conversationId: facts.conversationId, messageId: facts.messageId })
-                    .catch((error) => log(`[relay] markRead failed: ${String(error)}`));
             },
         });
     }
@@ -596,7 +610,8 @@ export const relayChannelPlugin = createChatChannelPlugin({
                     // this invocation so two intentional identical sends remain two.
                     idempotencyKey: deriveRelayIdempotencyKey({
                         deliveryQueueId: ctx.deliveryQueueId,
-                        deliveryPartIndex: ctx.deliveryPartIndex,
+                        deliveryPartIndex: deliveryPartIndexOf(ctx),
+                        partText: text,
                     }),
                 });
                 return { messageId: result.messageId };

package/dist/src/client.js

@@ -1,7 +1,6 @@
-// Thin Relay REST client for the OpenClaw channel plugin. Bespoke fetch until
-// the Relay SDK ships. Owns the abort-aware long poll, idempotent
-// sends, typing, and read watermarks. No SDK imports so unit tests run
-// without an OpenClaw runtime.
+// Thin Relay REST client boundary for the standalone OpenClaw channel plugin.
+// Owns the abort-aware long poll, idempotent sends, typing, responding, and
+// read watermarks without loading an OpenClaw runtime in unit tests.
 import { isIP } from "node:net";
 export const DEFAULT_RELAY_BASE_URL = "https://api.relayapp.im";
 function isLoopbackHostname(hostname) {
@@ -207,6 +206,17 @@ export function createRelayClient(options) {
                 signal: params.signal,
             });
         },
+        setResponding: async (params) => {
+            await request({
+                method: "POST",
+                path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/responding`,
+                body: {
+                    message_id: params.messageId,
+                    ...(params.label ? { label: params.label } : {}),
+                },
+                signal: params.signal,
+            });
+        },
         markRead: async (params) => {
             await request({
                 method: "POST",

package/dist/src/outbound.js

@@ -14,14 +14,33 @@ export const RELAY_TEXT_CHUNK_LIMIT = 2_000;
 const IDEMPOTENCY_KEY_MAX = 255;
 /**
  * Idempotency key for one logical send. When core supplies a durable delivery
- * queue id, the key is a stable function of (queueId, partIndex) so internal
+ * queue id, the key is a stable function of (queueId, part) so internal
  * retries and reconciliation replay the exact same key. Without a queue id a
  * fresh key is minted: identical intentional sends must remain distinct.
+ *
+ * The part term names WHICH piece of one delivery this is. Core supplies
+ * `deliveryPartIndex` from 2026.7.2-beta.5 onward and that is authoritative.
+ * Older cores do not: they call `enqueueDelivery` once, mint ONE queue id, and
+ * then hand the channel each chunk of a long reply under it. Defaulting the
+ * missing index to 0 would key every chunk to `...:0`, so the server would
+ * replay the first chunk for each of the rest and the person would receive a
+ * long answer truncated to its opening chunk with no error anywhere.
+ *
+ * So when core cannot say which part this is, the part term is a digest of the
+ * part's own text. Sibling chunks differ, so each commits; a retry reproduces
+ * the same text, so it replays. This is not the content-in-the-key mistake
+ * that defeats conflict detection: the digest stands in FOR the position core
+ * did not give us, it does not replace it. Two byte-identical chunks in one
+ * delivery do collapse to one message, which is the residual cost of an
+ * unindexed core and is bounded to a repeat the reader would see twice.
  */
 export function deriveRelayIdempotencyKey(params) {
     const queueId = params.deliveryQueueId?.trim();
+    const part = params.deliveryPartIndex ?? (params.partText === undefined
+        ? 0
+        : `t${createHash("sha256").update(params.partText).digest("hex").slice(0, 16)}`);
     const key = queueId
-        ? `relay-send:${queueId}:${params.deliveryPartIndex ?? 0}`
+        ? `relay-send:${queueId}:${part}`
         : `relay-send:${(params.random ?? (() => crypto.randomUUID()))()}`;
     // Server accepts 8-255 chars; the prefix guarantees the minimum.
     if (key.length <= IDEMPOTENCY_KEY_MAX) {

package/dist/src/responding.js

@@ -0,0 +1,13 @@
+/**
+ * The receipt must commit before OpenClaw can run an agent or tool. A rejected
+ * receipt leaves the durable attempt marker untouched, so the poll loop can
+ * replay the event safely instead of hiding the failure after execution.
+ */
+export async function markRespondingBeforeAttempt(params) {
+    await params.client.setResponding({
+        conversationId: params.conversationId,
+        messageId: params.messageId,
+        label: params.label,
+    });
+    await params.markAttempt();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relaymessenger/openclaw-plugin",
-  "version": "0.2.0",
+  "version": "0.3.3",
   "description": "Relay channel plugin for OpenClaw. Text your OpenClaw like a friend.",
   "license": "MIT",
   "publishConfig": {
@@ -39,7 +39,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@openclaw/fs-safe": "0.5.5"
+    "@openclaw/fs-safe": "0.5.6"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
@@ -48,7 +48,7 @@
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.7.2-beta.5"
+    "openclaw": ">=2026.7.1-2"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -57,12 +57,12 @@
   },
   "openclaw": {
     "compat": {
-      "pluginApi": ">=2026.7.2-beta.5"
+      "pluginApi": ">=2026.7.1-2"
     },
     "install": {
       "localPath": ".",
       "defaultChoice": "local",
-      "minHostVersion": ">=2026.7.2-beta.5"
+      "minHostVersion": ">=2026.7.1-2"
     },
     "build": {
       "openclawVersion": "2026.7.2-beta.7"

package/src/channel.ts

@@ -5,6 +5,18 @@
 import { createChatChannelPlugin } from "openclaw/plugin-sdk/channel-core";
 import type { ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
 import type { ChannelGatewayContext } from "openclaw/plugin-sdk/channel-contract";
+
+/**
+ * Read core's part index without requiring it to exist. Cores before
+ * 2026.7.2-beta.5 have no `deliveryPartIndex` in their outbound context at all,
+ * so naming the field directly would not typecheck against them. Reading it
+ * through a widened shape keeps one source compiling on every supported core;
+ * `deriveRelayIdempotencyKey` handles the undefined case.
+ */
+function deliveryPartIndexOf(ctx: unknown): number | undefined {
+  const index = (ctx as { deliveryPartIndex?: unknown }).deliveryPartIndex;
+  return typeof index === "number" ? index : undefined;
+}
 import { resolveStableChannelMessageIngress } from "openclaw/plugin-sdk/channel-ingress-runtime";
 import {
   createMessageReceiptFromOutboundResults,
@@ -38,6 +50,7 @@ import {
   sendRelayText,
 } from "./outbound.js";
 import { runRelayPollLoop } from "./poll-loop.js";
+import { markRespondingBeforeAttempt } from "./responding.js";
 import { getRelayRuntime } from "./runtime.js";
 import { relaySenderIsAllowed, resolveRelayAllowedSenderIds } from "./security.js";
 import type { RelayCoreConfig, ResolvedRelayAccount } from "./types.js";
@@ -163,12 +176,13 @@ const relayMessageAdapter = defineChannelMessageAdapter({
         conversationId: ctx.to,
         text: ctx.text,
         replyToId: ctx.replyToId ?? null,
-        // Stable per (queueId, partIndex): internal retries replay the same
-        // key, so the server-side idempotent commit makes duplicates
-        // impossible by contract.
+        // Stable per (queueId, part): internal retries replay the same key,
+        // so the server-side idempotent commit makes duplicates impossible by
+        // contract. On a core with no part index the text names the part.
         idempotencyKey: deriveRelayIdempotencyKey({
           deliveryQueueId: ctx.deliveryQueueId,
-          deliveryPartIndex: ctx.deliveryPartIndex,
+          deliveryPartIndex: deliveryPartIndexOf(ctx),
+          partText: ctx.text,
         }),
         ...(ctx.signal ? { signal: ctx.signal } : {}),
       });
@@ -273,7 +287,13 @@ async function dispatchRelayInbound(params: {
   // Admission, runtime resolution, route/session lookup, envelope building,
   // and context finalization above are replay-safe. The durable attempt starts
   // immediately before OpenClaw can invoke the agent or its tools.
-  await params.markAttempt();
+  await markRespondingBeforeAttempt({
+    client: params.client,
+    conversationId: facts.conversationId,
+    messageId: facts.messageId,
+    label: "OpenClaw",
+    markAttempt: params.markAttempt,
+  });
   await runtime.channel.inbound.dispatchReply({
     cfg: params.cfg,
     channel: RELAY_CHANNEL_ID,
@@ -479,11 +499,6 @@ async function startRelayAccount(ctx: ChannelGatewayContext<ResolvedRelayAccount
           allowedSenderIds,
           markAttempt,
         });
-        // Read watermark after the turn is handled: read implies delivered;
-        // best effort — a failed receipt must not replay the event.
-        await client
-          .markRead({ conversationId: facts.conversationId, messageId: facts.messageId })
-          .catch((error) => log(`[relay] markRead failed: ${String(error)}`));
       },
     });
   } catch (error) {
@@ -659,7 +674,8 @@ export const relayChannelPlugin: ChannelPlugin<ResolvedRelayAccount> = createCha
           // this invocation so two intentional identical sends remain two.
           idempotencyKey: deriveRelayIdempotencyKey({
             deliveryQueueId: ctx.deliveryQueueId,
-            deliveryPartIndex: ctx.deliveryPartIndex,
+            deliveryPartIndex: deliveryPartIndexOf(ctx),
+            partText: text,
           }),
         });
         return { messageId: result.messageId };

package/src/client.ts

@@ -1,7 +1,6 @@
-// Thin Relay REST client for the OpenClaw channel plugin. Bespoke fetch until
-// the Relay SDK ships. Owns the abort-aware long poll, idempotent
-// sends, typing, and read watermarks. No SDK imports so unit tests run
-// without an OpenClaw runtime.
+// Thin Relay REST client boundary for the standalone OpenClaw channel plugin.
+// Owns the abort-aware long poll, idempotent sends, typing, responding, and
+// read watermarks without loading an OpenClaw runtime in unit tests.
 import { isIP } from "node:net";
 import type {
   RelayAgentProfile,
@@ -146,6 +145,12 @@ export type RelayClient = {
     label?: string;
     signal?: AbortSignal;
   }) => Promise<void>;
+  setResponding: (params: {
+    conversationId: string;
+    messageId: string;
+    label?: string;
+    signal?: AbortSignal;
+  }) => Promise<void>;
   markRead: (params: {
     conversationId: string;
     messageId: string;
@@ -301,6 +306,18 @@ export function createRelayClient(options: RelayClientOptions): RelayClient {
       });
     },
 
+    setResponding: async (params) => {
+      await request({
+        method: "POST",
+        path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/responding`,
+        body: {
+          message_id: params.messageId,
+          ...(params.label ? { label: params.label } : {}),
+        },
+        signal: params.signal,
+      });
+    },
+
     markRead: async (params) => {
       await request({
         method: "POST",

package/src/outbound.ts

@@ -19,18 +19,41 @@ const IDEMPOTENCY_KEY_MAX = 255;
 
 /**
  * Idempotency key for one logical send. When core supplies a durable delivery
- * queue id, the key is a stable function of (queueId, partIndex) so internal
+ * queue id, the key is a stable function of (queueId, part) so internal
  * retries and reconciliation replay the exact same key. Without a queue id a
  * fresh key is minted: identical intentional sends must remain distinct.
+ *
+ * The part term names WHICH piece of one delivery this is. Core supplies
+ * `deliveryPartIndex` from 2026.7.2-beta.5 onward and that is authoritative.
+ * Older cores do not: they call `enqueueDelivery` once, mint ONE queue id, and
+ * then hand the channel each chunk of a long reply under it. Defaulting the
+ * missing index to 0 would key every chunk to `...:0`, so the server would
+ * replay the first chunk for each of the rest and the person would receive a
+ * long answer truncated to its opening chunk with no error anywhere.
+ *
+ * So when core cannot say which part this is, the part term is a digest of the
+ * part's own text. Sibling chunks differ, so each commits; a retry reproduces
+ * the same text, so it replays. This is not the content-in-the-key mistake
+ * that defeats conflict detection: the digest stands in FOR the position core
+ * did not give us, it does not replace it. Two byte-identical chunks in one
+ * delivery do collapse to one message, which is the residual cost of an
+ * unindexed core and is bounded to a repeat the reader would see twice.
  */
 export function deriveRelayIdempotencyKey(params: {
   deliveryQueueId?: string;
   deliveryPartIndex?: number;
+  /** Part text, used only when core supplies no `deliveryPartIndex`. */
+  partText?: string;
   random?: () => string;
 }): string {
   const queueId = params.deliveryQueueId?.trim();
+  const part = params.deliveryPartIndex ?? (
+    params.partText === undefined
+      ? 0
+      : `t${createHash("sha256").update(params.partText).digest("hex").slice(0, 16)}`
+  );
   const key = queueId
-    ? `relay-send:${queueId}:${params.deliveryPartIndex ?? 0}`
+    ? `relay-send:${queueId}:${part}`
     : `relay-send:${(params.random ?? (() => crypto.randomUUID()))()}`;
   // Server accepts 8-255 chars; the prefix guarantees the minimum.
   if (key.length <= IDEMPOTENCY_KEY_MAX) {

package/src/responding.ts

@@ -0,0 +1,21 @@
+import type { RelayClient } from "./client.js";
+
+/**
+ * The receipt must commit before OpenClaw can run an agent or tool. A rejected
+ * receipt leaves the durable attempt marker untouched, so the poll loop can
+ * replay the event safely instead of hiding the failure after execution.
+ */
+export async function markRespondingBeforeAttempt(params: {
+  client: RelayClient;
+  conversationId: string;
+  messageId: string;
+  label: string;
+  markAttempt: () => Promise<void>;
+}): Promise<void> {
+  await params.client.setResponding({
+    conversationId: params.conversationId,
+    messageId: params.messageId,
+    label: params.label,
+  });
+  await params.markAttempt();
+}