@relaymessenger/openclaw-plugin 0.2.0 → 0.3.0

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";
@@ -131,12 +142,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 } : {}),
             });
@@ -596,7 +608,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relaymessenger/openclaw-plugin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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,
@@ -163,12 +175,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 } : {}),
       });
@@ -659,7 +672,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/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) {