@relaymessenger/openclaw-plugin 0.2.0

package/dist/src/outbound.js

@@ -0,0 +1,98 @@
+// Durable outbound sends: every logical send carries an
+// Idempotency-Key; internal retries and unknown-send reconciliation replay
+// the same key, so a retry can never duplicate a visible message
+// (server contract: commitMessage.ts idempotent replay).
+import { createHash } from "node:crypto";
+import { RelayApiError } from "./client.js";
+/**
+ * Per-part text ceiling declared to core's renderer so long agent replies are
+ * split into multiple messages instead of truncated. Server caps a text part at 8 KiB UTF-8
+ * (server/src/domain/commitMessage.ts MAX_TEXT_BYTES); 2000 chars is safe for
+ * any UTF-8 content (4 bytes/char worst case).
+ */
+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
+ * retries and reconciliation replay the exact same key. Without a queue id a
+ * fresh key is minted: identical intentional sends must remain distinct.
+ */
+export function deriveRelayIdempotencyKey(params) {
+    const queueId = params.deliveryQueueId?.trim();
+    const key = queueId
+        ? `relay-send:${queueId}:${params.deliveryPartIndex ?? 0}`
+        : `relay-send:${(params.random ?? (() => crypto.randomUUID()))()}`;
+    // Server accepts 8-255 chars; the prefix guarantees the minimum.
+    if (key.length <= IDEMPOTENCY_KEY_MAX) {
+        return key;
+    }
+    // Preserve uniqueness when an opaque core queue id is unusually long; a
+    // simple prefix slice could erase the part index and collapse two chunks.
+    return `relay-send:h:${createHash("sha256").update(key).digest("hex")}`;
+}
+export async function sendRelayText(params) {
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            const result = await params.client.sendMessage({
+                conversationId: params.conversationId,
+                parts: [{ type: "text", text: params.text }],
+                ...(params.replyToId ? { replyTo: { message_id: params.replyToId } } : {}),
+                idempotencyKey: params.idempotencyKey,
+                ...(params.signal ? { signal: params.signal } : {}),
+            });
+            const first = result.messages[0];
+            if (!first) {
+                throw new RelayApiError("relay: 202 carried no messages", { kind: "retryable" });
+            }
+            return { messageId: first.id, messages: result.messages };
+        }
+        catch (error) {
+            lastError = error;
+            if (!(error instanceof RelayApiError) || !error.retryable || params.signal?.aborted) {
+                throw error;
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * Reconcile a send whose platform outcome is unknown: replay the POST with the
+ * same idempotency key and body. By server contract the replay either performs
+ * the send exactly once or returns the originally committed messages — either
+ * way the visible outcome is the one set of messages the key names, never a
+ * duplicate.
+ */
+export async function reconcileRelayUnknownSend(params) {
+    try {
+        const result = await sendRelayText({
+            client: params.client,
+            conversationId: params.conversationId,
+            text: params.text,
+            replyToId: params.replyToId ?? null,
+            idempotencyKey: params.idempotencyKey,
+        });
+        return { status: "sent", messageId: result.messageId, messages: result.messages };
+    }
+    catch (error) {
+        if (error instanceof RelayApiError) {
+            if (error.kind === "conflict") {
+                // Key already used with a different request body: the original send
+                // reached the server but we cannot recover its receipt. Do not retry —
+                // a retry with a fresh key would duplicate the visible message.
+                return { status: "unresolved", error: error.message, retryable: false };
+            }
+            if (error.retryable) {
+                return { status: "unresolved", error: error.message, retryable: true };
+            }
+            if (error.kind === "auth") {
+                return { status: "unresolved", error: error.message, retryable: false };
+            }
+            // Deterministic rejection (403/404/422): the original request would have
+            // been rejected identically, so nothing reached the conversation.
+            return { status: "not_sent" };
+        }
+        return { status: "unresolved", error: String(error), retryable: true };
+    }
+}

package/dist/src/poll-loop.js

@@ -0,0 +1,125 @@
+// startAccount receive engine: abort-aware long poll over GET /v1/events with
+// claim -> durable attempt commit -> dispatch per event and the cursor advanced
+// only after the batch's commits. The supervisor owns restart/backoff: this loop settles
+// (throws) on terminal auth failure and consumer conflicts, and only sleeps
+// in-loop for transient errors.
+import { RelayApiError, isAbortError } from "./client.js";
+const TRANSIENT_BASE_DELAY_MS = 500;
+const TRANSIENT_MAX_DELAY_MS = 30_000;
+function defaultSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export async function runRelayPollLoop(params) {
+    const sleep = params.sleep ?? defaultSleep;
+    const random = params.random ?? Math.random;
+    const log = params.log ?? (() => { });
+    let transientAttempts = 0;
+    const transientDelayMs = () => {
+        const backoff = Math.min(TRANSIENT_MAX_DELAY_MS, TRANSIENT_BASE_DELAY_MS * 2 ** Math.min(transientAttempts, 6));
+        return backoff + Math.floor(random() * 250);
+    };
+    while (!params.abortSignal.aborted) {
+        let page;
+        try {
+            page = await params.client.pollEvents({
+                cursor: params.cursorStore.current(),
+                timeoutSeconds: params.timeoutSeconds ?? 30,
+                ...(params.limit === undefined ? {} : { limit: params.limit }),
+                signal: params.abortSignal,
+            });
+        }
+        catch (error) {
+            if (params.abortSignal.aborted || isAbortError(error)) {
+                return;
+            }
+            if (error instanceof RelayApiError && error.kind === "auth") {
+                // Token revoked: settle so the supervisor applies terminalDisconnect
+                // (server-channels.ts:718) — an operator has to fix the token.
+                throw error;
+            }
+            if (error instanceof RelayApiError && error.kind === "conflict") {
+                // Another consumer took the long poll. Settle and let the
+                // supervisor's backoff arbitrate.
+                log(`[relay] long poll terminated by another consumer: ${error.message}`);
+                throw error;
+            }
+            transientAttempts += 1;
+            log(`[relay] transient poll error (attempt ${transientAttempts}): ${String(error)}`);
+            await sleep(transientDelayMs(), params.abortSignal);
+            continue;
+        }
+        transientAttempts = 0;
+        if (page.events.length > 0) {
+            params.onBatch?.(page.events);
+        }
+        let batchFailed = false;
+        for (const event of page.events) {
+            if (params.abortSignal.aborted) {
+                batchFailed = true;
+                break;
+            }
+            if (params.shouldProcess && !params.shouldProcess(event)) {
+                // Bookkeeping events (receipts, reactions, echoes) never dispatch, so
+                // they are acked by the batch cursor without a dedupe row.
+                continue;
+            }
+            const claimed = await params.deduper.claimEvent(event.event_id);
+            if (claimed) {
+                let attempted = false;
+                const markAttempt = async () => {
+                    if (attempted)
+                        return;
+                    await params.deduper.commitEvent(event.event_id);
+                    attempted = true;
+                    if (params.abortSignal.aborted)
+                        throw new Error("aborted after durable attempt");
+                };
+                try {
+                    await params.handleEvent(event, markAttempt);
+                }
+                catch (error) {
+                    if (!attempted) {
+                        params.deduper.releaseEvent(event.event_id);
+                        log(`[relay] event ${event.event_id} safe preflight failed, will replay: ${String(error)}`);
+                        batchFailed = true;
+                        break;
+                    }
+                    log(`[relay] event ${event.event_id} dispatch failed after its attempt was committed; ` +
+                        `will not replay possible tool side effects: ${String(error)}`);
+                }
+                if (!attempted) {
+                    // Admission/preflight intentionally consumed no side effect; release
+                    // the claim and allow the page cursor to acknowledge it.
+                    params.deduper.releaseEvent(event.event_id);
+                }
+                if (params.abortSignal.aborted) {
+                    batchFailed = true;
+                    break;
+                }
+            }
+        }
+        // The server's next_cursor covers the whole page (cursor N acks <= N), so
+        // only a batch with durable attempt markers may ack it. A marker-write
+        // failure acks nothing and committed predecessors absorb the replay.
+        if (!batchFailed) {
+            await params.cursorStore.advance(page.nextCursor);
+        }
+        else {
+            await sleep(transientDelayMs(), params.abortSignal);
+        }
+    }
+}

package/dist/src/runtime.js

@@ -0,0 +1,8 @@
+// Injected plugin runtime store (qa-channel pattern): defineChannelPluginEntry
+// calls setRelayRuntime, and gateway/inbound code reads it lazily.
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
+const { setRuntime: setRelayRuntime, getRuntime: getRelayRuntime } = createPluginRuntimeStore({
+    pluginId: "relay",
+    errorMessage: "Relay runtime not initialized",
+});
+export { getRelayRuntime, setRelayRuntime };

package/dist/src/security.js

@@ -0,0 +1,26 @@
+function normalizeSenderId(value) {
+    const normalized = String(value).trim();
+    return normalized ? normalized : null;
+}
+/**
+ * Build the only identities allowed to start an OpenClaw turn. The Relay
+ * account owner is pinned from the authenticated agent profile; operators can
+ * deliberately extend that set with `allowFrom`. No wildcard is accepted.
+ */
+export function resolveRelayAllowedSenderIds(params) {
+    const allowed = new Set();
+    const owner = params.profile.owner_user_id?.trim();
+    if (owner) {
+        allowed.add(owner);
+    }
+    for (const entry of params.allowFrom ?? []) {
+        const normalized = normalizeSenderId(entry);
+        if (normalized && normalized !== "*") {
+            allowed.add(normalized);
+        }
+    }
+    return [...allowed];
+}
+export function relaySenderIsAllowed(allowedSenderIds, senderId) {
+    return allowedSenderIds.includes(senderId);
+}

package/dist/src/state-files.js

@@ -0,0 +1,167 @@
+import { jsonStore } from "@openclaw/fs-safe/store";
+import { withFileLock } from "@openclaw/fs-safe/file-lock";
+import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
+import { chmodSync, lstatSync, mkdirSync } from "node:fs";
+import { hostname } from "node:os";
+import { basename, join } from "node:path";
+const RELAY_STATE_DOCUMENT_VERSION = 1;
+const RELAY_STATE_LOCK_VERSION = 1;
+const RELAY_STATE_LOCK_TIMEOUT_MS = 30_000;
+export function emptyRelayStateDocument() {
+    return { version: RELAY_STATE_DOCUMENT_VERSION, entries: {} };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function assertRelayStateDocument(value, label, validateEntry) {
+    if (!isRecord(value) ||
+        value.version !== RELAY_STATE_DOCUMENT_VERSION ||
+        !isRecord(value.entries)) {
+        throw new Error(`relay ${label} state is corrupt`);
+    }
+    for (const [key, entry] of Object.entries(value.entries)) {
+        if (!validateEntry(key, entry)) {
+            throw new Error(`relay ${label} state is corrupt`);
+        }
+    }
+}
+function isRelayStateLockOwner(value) {
+    if (!isRecord(value))
+        return false;
+    return (value.version === RELAY_STATE_LOCK_VERSION &&
+        value.kind === "relay-state" &&
+        Number.isSafeInteger(value.pid) &&
+        value.pid > 0 &&
+        typeof value.host === "string" &&
+        value.host.length > 0 &&
+        typeof value.createdAt === "string" &&
+        Number.isFinite(Date.parse(value.createdAt)));
+}
+function localProcessIsLive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM proves the process exists but is owned by another user. Unknown
+        // failures also fail closed; only ESRCH proves this host no longer has it.
+        return !(error instanceof Error && "code" in error && error.code === "ESRCH");
+    }
+}
+/**
+ * Windows opens the sidecar lock with an openat-style
+ * `O_CREAT | O_EXCL` beneath a parent handle. While a just-released lock file
+ * is still delete-pending, that create returns `ACCESS_DENIED` instead of the
+ * `already exists` fs-safe retries on, so contention escapes the acquire loop
+ * as a hard `EACCES`. Retry those on Windows only, bounded by the caller's lock
+ * timeout: a genuine permission failure simply reproduces until the deadline
+ * and then surfaces unchanged.
+ */
+function isWindowsLockAcquisitionContention(error) {
+    if (process.platform !== "win32")
+        return false;
+    const code = error?.code;
+    return code === "EACCES" || code === "EPERM";
+}
+function lockRetryDelayMs(attempt, remainingMs) {
+    const backoff = Math.min(25 * 2 ** attempt, 250);
+    return Math.max(1, Math.min(backoff * (0.5 + Math.random() / 2), remainingMs));
+}
+function canRecoverRelayStateLock(value) {
+    return (isRelayStateLockOwner(value) &&
+        value.host === hostname() &&
+        !localProcessIsLive(value.pid));
+}
+function ensurePrivateStateDirectory(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`relay state path is not a private directory: ${path}`);
+    }
+    try {
+        chmodSync(path, 0o700);
+    }
+    catch {
+        // POSIX modes are not fully implemented on Windows. fs-safe's private
+        // write path still owns the platform-specific file guarantees.
+    }
+}
+/**
+ * Relay owns these files rather than requesting OpenClaw's privileged host
+ * SQLite. jsonStore gives every mutation a private atomic replacement. An
+ * fs-safe sidecar lock serializes cross-process mutations and is recovered
+ * only when its valid Relay owner names this host and its PID is provably dead.
+ */
+export function openRelayStateDocument(params) {
+    if (!params.fileName || basename(params.fileName) !== params.fileName) {
+        throw new Error("relay state fileName must be one file name");
+    }
+    const lockTimeoutMs = params.lockTimeoutMs ?? RELAY_STATE_LOCK_TIMEOUT_MS;
+    if (!Number.isSafeInteger(lockTimeoutMs) || lockTimeoutMs < 1) {
+        throw new Error("relay state lockTimeoutMs must be a positive safe integer");
+    }
+    const stateRoot = resolveStateDir(params.env ?? process.env);
+    const relayRoot = join(stateRoot, "relay");
+    const relayStateRoot = join(relayRoot, "state");
+    ensurePrivateStateDirectory(relayRoot);
+    ensurePrivateStateDirectory(relayStateRoot);
+    const store = jsonStore({
+        filePath: join(relayStateRoot, params.fileName),
+        dirMode: 0o700,
+        mode: 0o600,
+    });
+    const withMutationLock = async (run) => {
+        const deadline = Date.now() + lockTimeoutMs;
+        for (let attempt = 0;; attempt += 1) {
+            // Only acquisition is retried. Once the mutation itself has started it has
+            // observed state under the lock, so replaying it could double-apply.
+            let mutationStarted = false;
+            try {
+                return await withFileLock(store.filePath, {
+                    managerKey: `relay-state:${store.filePath}`,
+                    staleMs: RELAY_STATE_LOCK_TIMEOUT_MS,
+                    timeoutMs: Math.max(1, deadline - Date.now()),
+                    staleRecovery: "remove-if-unchanged",
+                    retry: {
+                        retries: 300,
+                        minTimeout: 25,
+                        maxTimeout: 250,
+                        randomize: true,
+                    },
+                    payload: () => ({
+                        version: RELAY_STATE_LOCK_VERSION,
+                        kind: "relay-state",
+                        pid: process.pid,
+                        host: hostname(),
+                        createdAt: new Date().toISOString(),
+                    }),
+                    shouldReclaim: ({ payload }) => canRecoverRelayStateLock(payload),
+                    shouldRemoveStaleLock: ({ payload }) => canRecoverRelayStateLock(payload),
+                }, async () => {
+                    mutationStarted = true;
+                    return await run();
+                });
+            }
+            catch (error) {
+                const remaining = deadline - Date.now();
+                if (mutationStarted ||
+                    remaining <= 0 ||
+                    !isWindowsLockAcquisitionContention(error)) {
+                    throw error;
+                }
+                await new Promise((resolve) => setTimeout(resolve, lockRetryDelayMs(attempt, remaining)));
+            }
+        }
+    };
+    return {
+        filePath: store.filePath,
+        read: store.read,
+        readOr: store.readOr,
+        readRequired: store.readRequired,
+        write: async (value) => {
+            await withMutationLock(async () => await store.write(value));
+        },
+        update: async (run) => await withMutationLock(async () => await store.update(run)),
+        updateOr: async (fallback, run) => await withMutationLock(async () => await store.updateOr(fallback, run)),
+    };
+}

package/dist/src/types.js

@@ -0,0 +1,4 @@
+// Relay wire types plus the plugin's config and resolved-account shapes. The
+// long-poll receive contract is GET /v1/events?cursor&timeout&limit ->
+// { events, next_cursor }, cursor N acknowledges everything <= N.
+export {};

package/index.ts

@@ -0,0 +1,12 @@
+// Relay channel plugin entrypoint registers the OpenClaw integration.
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { relayChannelPlugin } from "./src/channel.js";
+import { setRelayRuntime } from "./src/runtime.js";
+
+export default defineChannelPluginEntry({
+  id: "relay",
+  name: "Relay",
+  description: "Relay channel plugin. Text your OpenClaw like a friend.",
+  plugin: relayChannelPlugin,
+  setRuntime: setRelayRuntime,
+});

package/openclaw.plugin.json

@@ -0,0 +1,101 @@
+{
+  "id": "relay",
+  "name": "Relay",
+  "description": "Relay channel plugin. Connects an OpenClaw agent to a Relay contact.",
+  "activation": {
+    "onStartup": false
+  },
+  "channels": [
+    "relay"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  },
+  "channelConfigs": {
+    "relay": {
+      "label": "Relay",
+      "description": "Back a Relay contact with this OpenClaw agent.",
+      "schema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "token": {
+            "type": "string"
+          },
+          "tokenFile": {
+            "type": "string"
+          },
+          "baseUrl": {
+            "type": "string"
+          },
+          "allowFrom": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "pollTimeoutSeconds": {
+            "type": "number",
+            "minimum": 1,
+            "maximum": 30
+          },
+          "defaultAccount": {
+            "type": "string"
+          },
+          "accounts": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "enabled": {
+                  "type": "boolean"
+                },
+                "token": {
+                  "type": "string"
+                },
+                "tokenFile": {
+                  "type": "string"
+                },
+                "baseUrl": {
+                  "type": "string"
+                },
+                "allowFrom": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "pollTimeoutSeconds": {
+                  "type": "number",
+                  "minimum": 1,
+                  "maximum": 30
+                }
+              }
+            }
+          }
+        }
+      },
+      "uiHints": {
+        "token": {
+          "label": "Agent Token",
+          "sensitive": true
+        },
+        "baseUrl": {
+          "label": "Relay API base URL"
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@relaymessenger/openclaw-plugin",
+  "version": "0.2.0",
+  "description": "Relay channel plugin for OpenClaw. Text your OpenClaw like a friend.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "openclaw",
+    "relay",
+    "messaging",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=22.22.3 <23 || >=24.15.0 <25 || >=25.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/relaymessenger/Relay-SDK.git",
+    "directory": "integrations/openclaw"
+  },
+  "type": "module",
+  "files": [
+    "README.md",
+    "index.ts",
+    "setup-entry.ts",
+    "openclaw.plugin.json",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "dist/**/*.js"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "pack:smoke": "node scripts/pack-smoke.mjs",
+    "gateway:harness": "node scripts/gateway-harness.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@openclaw/fs-safe": "0.5.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "openclaw": "2026.7.2-beta.7",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.7.2-beta.5"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "compat": {
+      "pluginApi": ">=2026.7.2-beta.5"
+    },
+    "install": {
+      "localPath": ".",
+      "defaultChoice": "local",
+      "minHostVersion": ">=2026.7.2-beta.5"
+    },
+    "build": {
+      "openclawVersion": "2026.7.2-beta.7"
+    },
+    "extensions": [
+      "./index.ts"
+    ],
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "runtimeSetupEntry": "./dist/setup-entry.js",
+    "channel": {
+      "id": "relay",
+      "configuredState": {
+        "env": {
+          "anyOf": [
+            "RELAY_AGENT_TOKEN"
+          ]
+        }
+      },
+      "label": "Relay",
+      "selectionLabel": "Relay",
+      "detailLabel": "Relay",
+      "docsPath": "https://docs.relayapp.im/integrations/openclaw",
+      "docsLabel": "documentation",
+      "blurb": "Text your OpenClaw like a friend.",
+      "systemImage": "message",
+      "markdownCapable": false
+    }
+  }
+}

package/setup-entry.ts

@@ -0,0 +1,6 @@
+// Lightweight setup entry: loaded instead of the full entry while the channel
+// is disabled/unconfigured, so status/config surfaces avoid runtime imports.
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { relayChannelPlugin } from "./src/channel.js";
+
+export default defineSetupPluginEntry(relayChannelPlugin);