@relaymessenger/openclaw-plugin 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Companion Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# Relay channel plugin for OpenClaw
+
+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`.
+
+## Install
+
+```sh
+npm install -g @relaymessenger/cli
+relaymessenger pair
+relaymessenger install-openclaw
+```
+
+The installer uses the OpenClaw archive bundled in the installed `relaymessenger`
+package, persists that archive in the paired account's private Relay runtime,
+and invokes OpenClaw's managed `npm-pack:` installer on the stable copy so
+declared runtime dependencies are installed with the plugin. It surgically
+adds Relay to `~/.openclaw/openclaw.json`, preserves unrelated configuration,
+writes the token to an owner-only file, and never prints it. It refuses to
+replace a different configured Relay identity.
+
+For integration development from this checkout only:
+
+```sh
+cd integrations/openclaw
+npm install
+npm pack
+openclaw plugins install npm-pack:./relaymessenger-openclaw-plugin-0.1.0.tgz --force
+```
+
+The installer produces the equivalent Relay-specific configuration:
+
+```json
+{
+  "plugins": {
+    "allow": ["relay"],
+    "entries": { "relay": { "enabled": true } }
+  },
+  "channels": {
+    "relay": {
+      "enabled": true,
+      "tokenFile": "~/.openclaw/secrets/relay-agent-token",
+      "baseUrl": "https://api.relayapp.im"
+    }
+  }
+}
+```
+
+`RELAY_AGENT_TOKEN` / `RELAY_BASE_URL` are honored for the default account
+when the config fields are absent. Multiple agents run as named accounts under
+`channels.relay.accounts.<id>`, one token each.
+
+## Sender security
+
+Relay agents can be discoverable, so adding an agent as a contact is not an
+authorization boundary. The plugin accepts inbound turns only from the
+authenticated agent's `owner_user_id` returned by `GET /v1/agents/me` and any
+Relay user ids the operator explicitly adds to `allowFrom`. Wildcards are
+ignored. If neither an API owner nor an explicit allowlist is available, the
+account fails closed and does not start polling.
+
+## One consumer per token
+
+Relay's `GET /v1/events` long poll allows **exactly one consumer per Agent
+Token**:
+
+- A newer poll takes the slot; the older consumer's request ends with
+  `409 terminated_by_other_consumer`. Running this plugin and another
+  long-poll consumer (for example `relaymessenger start`, or a second OpenClaw) on
+  the same token makes them steal the slot from each other forever. Give each
+  consumer its own agent/token.
+- Long polling is **XOR with webhooks**: while a webhook endpoint is enabled
+  for the agent, `/v1/events` returns `409 conflict` and the channel stops
+  with a terminal disconnect. Disable or delete the agent's webhooks to poll.
+
+The plugin also refuses to start a second configured account that resolves to
+the same agent id as a running one.
+
+## Config reference (per account)
+
+| Field | Meaning |
+| --- | --- |
+| `token` / `tokenFile` | Agent Token (or file containing it) |
+| `baseUrl` | Relay API origin (default `https://api.relayapp.im`). Remote origins must use HTTPS; HTTP is accepted only for loopback development. Paths, credentials, queries, and fragments are rejected. |
+| `allowFrom` | Additional Relay user ids (`usr_…`) allowed alongside the API-pinned owner. These identities may also run control commands. Wildcards are ignored. |
+| `pollTimeoutSeconds` | Long-poll hold time, 1–30 (default 30) |
+
+## Harness
+
+Run `npm run gateway:harness` from the repository root for the clean installed-
+runtime proof. It packs the plugin, installs it into an isolated `HOME`, starts
+a real OpenClaw gateway against `harness/mock-relay-server.mjs`, receives a
+Relay event, completes a mock model turn, and verifies the reply reaches
+Relay. The release workflow requires this proof.
+
+## Delivery and crash semantics
+
+- Every outbound platform send has a logical-send idempotency key. Durable
+  queue retries reuse the same key, while intentional identical messages and
+  identical chunks remain distinct.
+- Admission, route/session resolution, envelope building, and context
+  finalization run before an inbound event is marked attempted. Failures in
+  that replay-safe preflight release the claim and retry the event. The marker
+  is committed durably immediately before OpenClaw can dispatch the agent or
+  its tools; a failure after that boundary does not silently replay possible
+  tool side effects. The user can resend the message deliberately.
+- The long-poll cursor and inbound attempt keys are bound to the canonical
+  Relay API origin plus Relay agent id, not to a mutable local account label.
+  Renaming an account therefore retains its cursor. A missing identity starts
+  at cursor zero; corrupt, mismatched, unreadable, or unwritable state fails
+  closed instead of replaying retained history. The cursor namespace rejects
+  new identities at capacity rather than evicting an older cursor. Cursor
+  state is independent of the bounded 30-day attempt-dedupe horizon. Both
+  namespaces are private, lock-protected, atomically replaced Relay-owned
+  files under `$OPENCLAW_STATE_DIR/relay/state` (normally
+  `~/.openclaw/relay/state`); the plugin never requests trusted-only OpenClaw
+  host SQLite access.
+- Before polling, the plugin takes an atomic per-origin/per-agent filesystem
+  lock under `~/.openclaw/relay/consumer-locks`. A second OpenClaw process
+  fails closed; a lock whose recorded PID is dead is recovered on startup.
+  Shutdown aborts the active long poll and releases both process-local and
+  filesystem ownership before a replacement starts.
+- Every API operation has a deadline (15 seconds for ordinary calls; the
+  configured long-poll hold plus 15 seconds for event polling). Retrying a
+  message send reuses its logical delivery idempotency key.
+
+## v1 scope
+
+Direct conversations only. Inbound text renders as-is; inbound media and
+voice memos render as a labeled fetchable capability URL (the URL is itself
+the authorization, so no Agent Token is needed to fetch the bytes) rather
+than the agent seeing the file inline; reactions are observe-only; receipts
+(`message.delivered`/`message.read`) never start a turn. Final agent replies
+are delivered durably (chunked to Relay's 8 KiB per-part cap,
+idempotency-keyed, retry-safe).

package/dist/index.js

@@ -0,0 +1,11 @@
+// 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/dist/setup-entry.js

@@ -0,0 +1,5 @@
+// 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);

package/dist/src/account-lock.js

@@ -0,0 +1,91 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function processIsLive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error?.code === "EPERM";
+    }
+}
+function readOwner(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (Number.isSafeInteger(value.pid) &&
+            typeof value.nonce === "string" &&
+            typeof value.account_id === "string" &&
+            typeof value.created_at === "string") {
+            return value;
+        }
+    }
+    catch {
+        // Missing/malformed ownership is never deleted in place by a contender.
+    }
+    return undefined;
+}
+/** Atomic filesystem lease preventing two OpenClaw processes polling one agent. */
+export class RelayAccountLock {
+    accountId;
+    lockPath;
+    ownerPath;
+    nonce = randomUUID();
+    held = false;
+    constructor(baseUrl, agentId, accountId, baseDir = join(homedir(), ".openclaw", "relay", "consumer-locks")) {
+        this.accountId = accountId;
+        const key = createHash("sha256").update(`${baseUrl}\0${agentId}`).digest("hex");
+        this.lockPath = join(baseDir, key);
+        this.ownerPath = join(this.lockPath, "owner.json");
+    }
+    acquire() {
+        mkdirSync(join(this.lockPath, ".."), { recursive: true, mode: 0o700 });
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            try {
+                mkdirSync(this.lockPath, { mode: 0o700 });
+                const owner = {
+                    pid: process.pid,
+                    nonce: this.nonce,
+                    account_id: this.accountId,
+                    created_at: new Date().toISOString(),
+                };
+                writeFileSync(this.ownerPath, `${JSON.stringify(owner)}\n`, { mode: 0o600 });
+                this.held = true;
+                return;
+            }
+            catch (error) {
+                if (error?.code !== "EEXIST")
+                    throw error;
+                const owner = readOwner(this.ownerPath);
+                if (!owner || processIsLive(owner.pid)) {
+                    const claimant = owner
+                        ? `account "${owner.account_id}" (pid ${owner.pid})`
+                        : "an existing process with unreadable ownership";
+                    throw new Error(`relay: this agent already has an active consumer in ${claimant}`);
+                }
+                const stalePath = `${this.lockPath}.stale-${Date.now()}-${randomUUID()}`;
+                try {
+                    renameSync(this.lockPath, stalePath);
+                    rmSync(stalePath, { recursive: true, force: true });
+                }
+                catch (renameError) {
+                    if (renameError?.code !== "ENOENT")
+                        throw renameError;
+                }
+            }
+        }
+        throw new Error("relay: could not acquire the agent consumer lock");
+    }
+    release() {
+        if (!this.held)
+            return;
+        const owner = readOwner(this.ownerPath);
+        if (owner?.nonce === this.nonce && existsSync(this.lockPath)) {
+            rmSync(this.lockPath, { recursive: true, force: true });
+        }
+        this.held = false;
+    }
+}

package/dist/src/accounts.js

@@ -0,0 +1,67 @@
+// Multi-account resolution: channels.relay.accounts.<id> with a
+// default-account fallback, so one OpenClaw can back several Relay contacts
+// (one Agent Token each). Env vars cover the single-account quickstart.
+import { createAccountListHelpers, resolveMergedAccountConfig, } from "openclaw/plugin-sdk/account-helpers";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { tryReadSecretFileSync } from "openclaw/plugin-sdk/channel-core";
+import { DEFAULT_RELAY_BASE_URL, normalizeRelayBaseUrl } from "./client.js";
+export const RELAY_TOKEN_ENV_VAR = "RELAY_AGENT_TOKEN";
+export const RELAY_BASE_URL_ENV_VAR = "RELAY_BASE_URL";
+const DEFAULT_POLL_TIMEOUT_SECONDS = 30;
+const { listAccountIds, resolveDefaultAccountId } = createAccountListHelpers("relay", {
+    normalizeAccountId,
+    implicitDefaultAccount: {
+        channelKeys: ["token", "tokenFile"],
+        envVars: [RELAY_TOKEN_ENV_VAR],
+    },
+});
+export { listAccountIds as listRelayAccountIds, resolveDefaultAccountId as resolveDefaultRelayAccountId, DEFAULT_ACCOUNT_ID, };
+function resolveMergedRelayAccountConfig(cfg, accountId) {
+    return resolveMergedAccountConfig({
+        channelConfig: cfg.channels?.relay,
+        accounts: cfg.channels?.relay?.accounts,
+        accountId,
+        omitKeys: ["defaultAccount"],
+        normalizeAccountId,
+    });
+}
+function resolveToken(params) {
+    const direct = params.merged.token?.trim();
+    if (direct) {
+        return direct;
+    }
+    const fromFile = params.merged.tokenFile
+        ? tryReadSecretFileSync(params.merged.tokenFile, "relay tokenFile")?.trim()
+        : undefined;
+    if (fromFile) {
+        return fromFile;
+    }
+    // Env token applies to the default account only, so named accounts cannot
+    // silently share one token.
+    if (params.accountId === DEFAULT_ACCOUNT_ID) {
+        return params.env[RELAY_TOKEN_ENV_VAR]?.trim() ?? "";
+    }
+    return "";
+}
+export function resolveRelayAccount(params) {
+    const env = params.env ?? process.env;
+    const accountId = normalizeAccountId(params.accountId);
+    const merged = resolveMergedRelayAccountConfig(params.cfg, accountId);
+    const baseEnabled = params.cfg.channels?.relay?.enabled !== false;
+    const enabled = baseEnabled && merged.enabled !== false;
+    const token = resolveToken({ merged, accountId, env });
+    const baseUrl = normalizeRelayBaseUrl(merged.baseUrl?.trim() ||
+        (accountId === DEFAULT_ACCOUNT_ID ? env[RELAY_BASE_URL_ENV_VAR]?.trim() : undefined) ||
+        DEFAULT_RELAY_BASE_URL);
+    const pollTimeoutSeconds = Math.min(Math.max(merged.pollTimeoutSeconds ?? DEFAULT_POLL_TIMEOUT_SECONDS, 1), 30);
+    return {
+        accountId,
+        enabled,
+        configured: Boolean(token),
+        ...(merged.name?.trim() ? { name: merged.name.trim() } : {}),
+        token,
+        baseUrl,
+        pollTimeoutSeconds,
+        config: merged,
+    };
+}