@relaymessenger/openclaw-plugin 0.3.4 → 0.4.0-staging.0

package/index.ts

@@ -1,4 +1,3 @@
-// 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";
@@ -6,7 +5,7 @@ import { setRelayRuntime } from "./src/runtime.js";
 export default defineChannelPluginEntry({
   id: "relay",
   name: "Relay",
-  description: "Relay channel plugin. Text your OpenClaw like a friend.",
+  description: "Native Relay channel plugin for OpenClaw.",
   plugin: relayChannelPlugin,
   setRuntime: setRelayRuntime,
 });

package/openclaw.plugin.json

@@ -1,22 +1,17 @@
 {
   "id": "relay",
   "name": "Relay",
-  "description": "Relay channel plugin. Connects an OpenClaw agent to a Relay contact.",
+  "description": "Native Relay channel plugin for OpenClaw.",
   "activation": {
     "onStartup": false
   },
   "channels": [
     "relay"
   ],
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": false,
-    "properties": {}
-  },
   "channelConfigs": {
     "relay": {
       "label": "Relay",
-      "description": "Back a Relay contact with this OpenClaw agent.",
+      "description": "Connect one or more Relay Contacts to OpenClaw.",
       "schema": {
         "type": "object",
         "additionalProperties": false,
@@ -42,11 +37,6 @@
               "type": "string"
             }
           },
-          "pollTimeoutSeconds": {
-            "type": "number",
-            "minimum": 1,
-            "maximum": 30
-          },
           "defaultAccount": {
             "type": "string"
           },
@@ -76,11 +66,6 @@
                   "items": {
                     "type": "string"
                   }
-                },
-                "pollTimeoutSeconds": {
-                  "type": "number",
-                  "minimum": 1,
-                  "maximum": 30
                 }
               }
             }
@@ -92,10 +77,22 @@
           "label": "Agent Token",
           "sensitive": true
         },
+        "tokenFile": {
+          "label": "Agent Token file",
+          "sensitive": true
+        },
         "baseUrl": {
-          "label": "Relay API base URL"
+          "label": "Relay API origin"
+        },
+        "allowFrom": {
+          "label": "Allowed Contact IDs or Handles"
         }
       }
     }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
   }
 }

package/package.json

@@ -1,72 +1,79 @@
 {
   "name": "@relaymessenger/openclaw-plugin",
-  "version": "0.3.4",
-  "description": "Relay channel plugin for OpenClaw. Text your OpenClaw like a friend.",
+  "version": "0.4.0-staging.0",
+  "description": "Native Relay channel plugin for OpenClaw",
   "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "openclaw",
-    "relay",
-    "messaging",
-    "agent"
-  ],
+  "type": "module",
   "engines": {
-    "node": ">=22.22.3 <23 || >=24.15.0 <25 || >=25.9.0"
+    "node": ">=22.22.3"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/relaymessenger/Relay-SDK.git",
-    "directory": "integrations/openclaw"
+  "exports": {
+    ".": "./dist/index.js",
+    "./setup": "./dist/setup-entry.js"
   },
-  "type": "module",
   "files": [
+    "LICENSE",
     "README.md",
+    "contracts/relay-v1.lock.json",
+    "contracts/relay-sdk-0.3.0-staging.4.registry.json",
+    "openclaw.plugin.json",
     "index.ts",
     "setup-entry.ts",
-    "openclaw.plugin.json",
     "src/**/*.ts",
     "!src/**/*.test.ts",
-    "dist/**/*.js"
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "check": "tsc --noEmit",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
+    "validate": "npm run check && npm run build && npm test && npm run contract:verify && npm run contract:test",
+    "release:validate": "node scripts/release-validate.mjs",
+    "contract:verify": "node scripts/verify-contract-provenance.mjs",
+    "contract:test": "node --test test/*.test.mjs",
     "pack:smoke": "node scripts/pack-smoke.mjs",
     "gateway:harness": "node scripts/gateway-harness.mjs",
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@openclaw/fs-safe": "0.5.6"
+    "@relaymessenger/sdk": "0.3.0-staging.4"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
-    "openclaw": "2026.7.2-beta.7",
+    "@types/node": "^26.0.0",
+    "openclaw": "2026.8.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.7.1-2"
+    "openclaw": ">=2026.8.1 <2026.9.0"
   },
   "peerDependenciesMeta": {
     "openclaw": {
       "optional": true
     }
   },
+  "publishConfig": {
+    "access": "public",
+    "tag": "staging",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RelayMessenger/Relay-OpenClaw.git"
+  },
+  "homepage": "https://docs.relayapp.im/integrations/openclaw",
+  "bugs": {
+    "url": "https://github.com/RelayMessenger/Relay-OpenClaw/issues"
+  },
+  "keywords": [
+    "openclaw",
+    "relay",
+    "messaging",
+    "channel"
+  ],
   "openclaw": {
-    "compat": {
-      "pluginApi": ">=2026.7.1-2"
-    },
-    "install": {
-      "localPath": ".",
-      "defaultChoice": "local",
-      "minHostVersion": ">=2026.7.1-2"
-    },
-    "build": {
-      "openclawVersion": "2026.7.2-beta.7"
-    },
     "extensions": [
       "./index.ts"
     ],
@@ -86,12 +93,78 @@
       },
       "label": "Relay",
       "selectionLabel": "Relay",
-      "detailLabel": "Relay",
+      "detailLabel": "Relay Messenger",
       "docsPath": "https://docs.relayapp.im/integrations/openclaw",
-      "docsLabel": "documentation",
-      "blurb": "Text your OpenClaw like a friend.",
+      "docsLabel": "Relay OpenClaw",
+      "blurb": "Message your OpenClaw through Relay.",
       "systemImage": "message",
-      "markdownCapable": false
+      "markdownCapable": false,
+      "order": 70,
+      "commands": {
+        "nativeCommandsAutoEnabled": false,
+        "nativeSkillsAutoEnabled": false
+      },
+      "setup": {
+        "fields": [
+          {
+            "key": "token",
+            "kind": "string",
+            "sensitive": true,
+            "cli": {
+              "flags": "--token <token>",
+              "description": "Relay Agent Token"
+            }
+          },
+          {
+            "key": "tokenFile",
+            "kind": "string",
+            "sensitive": true,
+            "cli": {
+              "flags": "--token-file <path>",
+              "description": "File containing a Relay Agent Token"
+            }
+          },
+          {
+            "key": "baseUrl",
+            "kind": "string",
+            "cli": {
+              "flags": "--base-url <url>",
+              "description": "Relay API origin"
+            }
+          },
+          {
+            "key": "allowFrom",
+            "kind": "string-list",
+            "cli": {
+              "flags": "--allow-from <contacts>",
+              "description": "Allowed Relay Contact IDs or Handles"
+            }
+          },
+          {
+            "key": "useEnv",
+            "kind": "boolean",
+            "cli": {
+              "flags": "--use-env",
+              "description": "Use RELAY_AGENT_TOKEN"
+            },
+            "envVars": [
+              "RELAY_AGENT_TOKEN"
+            ]
+          }
+        ]
+      }
+    },
+    "install": {
+      "npmSpec": "@relaymessenger/openclaw-plugin",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.8.1",
+      "allowInvalidConfigRecovery": true
+    },
+    "compat": {
+      "pluginApi": ">=2026.8.1 <2026.9.0"
+    },
+    "build": {
+      "openclawVersion": "2026.8.1"
     }
   }
 }

package/setup-entry.ts

@@ -1,5 +1,3 @@
-// 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";
 

package/src/accounts.ts

@@ -1,98 +1,142 @@
-// 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 {
+  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";
-import type { RelayAccountConfig, RelayCoreConfig, ResolvedRelayAccount } from "./types.js";
+import type {
+  RelayAccountConfig,
+  RelayCoreConfig,
+  ResolvedRelayAccount,
+} from "./types.js";
 
 export const RELAY_TOKEN_ENV_VAR = "RELAY_AGENT_TOKEN";
 export const RELAY_BASE_URL_ENV_VAR = "RELAY_BASE_URL";
+export const DEFAULT_RELAY_BASE_URL = "https://api.relayapp.im";
 
-const DEFAULT_POLL_TIMEOUT_SECONDS = 30;
-
-const { listAccountIds, resolveDefaultAccountId } = createAccountListHelpers("relay", {
-  normalizeAccountId,
-  implicitDefaultAccount: {
-    channelKeys: ["token", "tokenFile"],
-    envVars: [RELAY_TOKEN_ENV_VAR],
+const { listAccountIds, resolveDefaultAccountId } = createAccountListHelpers(
+  "relay",
+  {
+    normalizeAccountId,
+    implicitDefaultAccount: {
+      channelKeys: ["token", "tokenFile"],
+      envVars: [RELAY_TOKEN_ENV_VAR],
+    },
   },
-});
+);
 
 export {
+  DEFAULT_ACCOUNT_ID,
   listAccountIds as listRelayAccountIds,
   resolveDefaultAccountId as resolveDefaultRelayAccountId,
-  DEFAULT_ACCOUNT_ID,
 };
 
-function resolveMergedRelayAccountConfig(
+function mergedAccountConfig(
   cfg: RelayCoreConfig,
   accountId: string,
 ): RelayAccountConfig {
   return resolveMergedAccountConfig<RelayAccountConfig>({
-    channelConfig: cfg.channels?.relay as RelayAccountConfig | undefined,
+    channelConfig: cfg.channels?.relay,
     accounts: cfg.channels?.relay?.accounts,
     accountId,
-    omitKeys: ["defaultAccount"],
+    // A channel-level token or tokenFile belongs only to the implicit/default
+    // account. Named accounts may inherit non-credential defaults, but must
+    // opt into their own credential source.
+    omitKeys:
+      accountId === DEFAULT_ACCOUNT_ID
+        ? ["defaultAccount"]
+        : ["defaultAccount", "token", "tokenFile"],
     normalizeAccountId,
   });
 }
 
 function resolveToken(params: {
-  merged: RelayAccountConfig;
+  config: RelayAccountConfig;
   accountId: string;
   env: NodeJS.ProcessEnv;
 }): string {
-  const direct = params.merged.token?.trim();
-  if (direct) {
-    return direct;
-  }
-  const fromFile = params.merged.tokenFile
-    ? tryReadSecretFileSync(params.merged.tokenFile, "relay tokenFile")?.trim()
+  const inline = params.config.token?.trim();
+  if (inline) return inline;
+
+  const fromFile = params.config.tokenFile
+    ? tryReadSecretFileSync(params.config.tokenFile, "relay tokenFile")?.trim()
     : undefined;
-  if (fromFile) {
-    return fromFile;
+  if (fromFile) return fromFile;
+
+  return params.accountId === DEFAULT_ACCOUNT_ID
+    ? (params.env[RELAY_TOKEN_ENV_VAR]?.trim() ?? "")
+    : "";
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  return (
+    hostname === "localhost" ||
+    hostname === "127.0.0.1" ||
+    hostname === "::1" ||
+    hostname.endsWith(".localhost")
+  );
+}
+
+export function normalizeRelayBaseUrl(
+  value: string | undefined,
+): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(value?.trim() || DEFAULT_RELAY_BASE_URL);
+  } catch {
+    throw new Error("relay: baseUrl must be an absolute Relay API origin");
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new Error("relay: baseUrl must not contain credentials, query, or fragment");
   }
-  // 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() ?? "";
+  if (parsed.pathname !== "/" && parsed.pathname !== "") {
+    throw new Error("relay: baseUrl must be an origin without a path");
   }
-  return "";
+  if (
+    parsed.protocol !== "https:" &&
+    !(parsed.protocol === "http:" && isLoopbackHostname(parsed.hostname))
+  ) {
+    throw new Error("relay: baseUrl must use HTTPS (HTTP is allowed only for loopback tests)");
+  }
+  return parsed.origin;
+}
+
+function normalizeAllowFrom(values: string[] | undefined): string[] {
+  return [
+    ...new Set(
+      (values ?? [])
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0),
+    ),
+  ];
 }
 
 export function resolveRelayAccount(params: {
   cfg: RelayCoreConfig;
-  accountId?: string | null;
+  accountId?: string | null | undefined;
   env?: NodeJS.ProcessEnv;
 }): ResolvedRelayAccount {
   const env = params.env ?? process.env;
   const accountId = normalizeAccountId(params.accountId);
-  const merged = resolveMergedRelayAccountConfig(params.cfg, accountId);
+  const config = mergedAccountConfig(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,
-  );
+  const token = resolveToken({ config, accountId, env });
+  const configuredBaseUrl =
+    config.baseUrl?.trim() ||
+    (accountId === DEFAULT_ACCOUNT_ID
+      ? env[RELAY_BASE_URL_ENV_VAR]?.trim()
+      : undefined);
   return {
     accountId,
-    enabled,
-    configured: Boolean(token),
-    ...(merged.name?.trim() ? { name: merged.name.trim() } : {}),
+    ...(config.name?.trim() ? { name: config.name.trim() } : {}),
+    enabled: baseEnabled && config.enabled !== false,
+    configured: token.length > 0,
     token,
-    baseUrl,
-    pollTimeoutSeconds,
-    config: merged,
+    baseUrl: normalizeRelayBaseUrl(configuredBaseUrl),
+    allowFrom: normalizeAllowFrom(config.allowFrom),
+    config,
   };
 }