r2-relay-channel 0.3.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wei Wu
+
+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,309 @@
+# r2-relay-channel
+
+- [English](#english)
+- [简体中文](#simplified-chinese)
+
+---
+
+<a id="english"></a>
+
+## English
+
+`r2-relay-channel` is an OpenClaw channel plugin that uses Cloudflare R2 as a lightweight relay layer for chat delivery.
+
+AgentDeck is the companion iOS app. The complete app and plugin source is fully
+open source under the MIT License. Build AgentDeck for free from the
+[repository](https://github.com/dodid/AgentDeck), or install the signed public
+app from the App Store as a paid app by searching for **AgentDeck**.
+
+It is designed for setups where an OpenClaw server publishes session metadata and exchanges messages through an object-store-backed protocol instead of a conventional always-on websocket or direct mobile push transport.
+
+### Why this exists
+
+- **No ports open** — your server stays behind its firewall instead of being exposed directly to the internet.
+- **Instant setup** — connect once without juggling bots, webhooks, or extra chat platform plumbing.
+- **You own your data** — conversations live in your own Cloudflare R2 bucket, not on someone else's hosted chat service.
+- **Chat your way** — the same OpenClaw backend can power a friendly mobile chat UI or a more terminal-style interface for power users.
+
+### Security note
+
+OpenClaw's plugin code-safety audit may warn that this plugin reads local files and sends data over the network. That warning is expected here: outbound media delivery intentionally reads agent-produced local files (for example images referenced by reply payloads) and uploads them to the configured Cloudflare R2 relay bucket so they can be delivered as attachments. Review this behavior in `src/channel.ts` (`buildRelayAttachments`) and use the plugin only in workspaces and relay buckets you trust.
+
+### Requirements
+
+- OpenClaw `2026.7.1` or later
+- a Cloudflare R2 bucket
+- an R2 endpoint URL
+- an access key id and secret access key with bucket access
+
+### Install the plugin in OpenClaw
+
+Install directly from ClawHub by plugin id:
+
+```bash
+openclaw plugins install clawhub:r2-relay-channel
+openclaw gateway restart
+```
+
+### Configure OpenClaw
+
+After installing the plugin, run:
+
+```bash
+openclaw configure
+```
+
+OpenClaw should expose `R2 Relay` as a channel setup flow and prompt for:
+
+- R2 endpoint URL
+- bucket name
+- access key ID
+- secret access key
+- gateway server ID
+
+The wizard suggests a short random server ID candidate automatically, and you can keep it or edit it. Keep it unique if you have multiple gateways sharing the same R2 bucket.
+
+### Install AgentDeck on iOS
+
+To use this relay from iPhone or iPad, install AgentDeck from the App Store by
+searching for **AgentDeck**. For a free self-built version, follow the
+[iOS build instructions](../../apps/ios/README.md).
+
+Open AgentDeck and enter the same R2 connection details you configured for this plugin.
+
+### `/session-target` command
+
+The plugin registers a command that shows the current conversation's relay targets, which can be used for cron job delivery or direct webhook POSTing.
+
+After at least one inbound relay message has established conversation state, run:
+
+```text
+/session-target
+```
+
+It returns two copy-pasteable code blocks:
+
+- the cron target string
+- the webhook URL
+
+#### Cron target string
+
+The plugin supports native OpenClaw delivery targeting through `--channel r2-relay-channel` and a provider-specific `--to` format.
+
+The target format:
+
+```text
+peer=<peer>,session=<sessionKey>
+```
+
+Example:
+
+```bash
+openclaw cron add \
+  --name "Morning brief" \
+  --cron "0 7 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Summarize overnight updates." \
+  --announce \
+  --channel r2-relay-channel \
+  --to 'peer=phone-abc123,session=agent:main:main'
+```
+
+Notes:
+
+- `peer` is the relay recipient id.
+- `session` is the exact OpenClaw session key to route into.
+- `,` and `=` are reserved inside values in this minimal format.
+
+#### Webhook URL
+
+The plugin exposes a minimal webhook endpoint for cron jobs.
+
+Authentication uses OpenClaw's existing `cron.webhookToken`; there is no separate plugin token.
+
+Set a cron webhook token in your OpenClaw config:
+
+```json5
+{
+  cron: {
+    webhookToken: "replace-with-a-random-secret"
+  }
+}
+```
+
+The endpoint expects a JSON POST body. It accepts:
+
+- cron finished-event payloads with a `summary` field
+- simple manual payloads with a `text` field
+- error payloads with an `error` field
+
+It forwards the first non-empty value from `text`, `summary`, or `error` into the specified relay session.
+
+Curl example:
+
+```bash
+curl -X POST 'http://127.0.0.1:18789/r2-relay-channel/webhook/moss-river-w5/agent%3Amain%3Amain' \
+  -H 'Authorization: Bearer <cron.webhookToken>' \
+  -H 'Content-Type: application/json' \
+  --data '{"text":"hello from curl"}'
+```
+
+### Uninstall the plugin from OpenClaw
+
+To remove the plugin:
+
+```bash
+openclaw plugins uninstall r2-relay-channel
+openclaw gateway restart
+```
+
+---
+
+<a id="simplified-chinese"></a>
+
+## 简体中文
+
+`r2-relay-channel` 是一个 OpenClaw 通道插件，使用 Cloudflare R2 作为轻量中继层来传递聊天消息。
+
+它适用于这样的部署方式：OpenClaw 服务器负责发布会话元数据与消息交换，但底层通过对象存储协议完成中继，而不是依赖常驻 WebSocket 或直接移动推送。
+
+### 这个插件为什么存在
+
+- **无需开放端口**：你的服务器可以继续留在防火墙后，不必直接暴露到公网。
+- **部署快速**：一次接入即可工作，无需再拼装 bot、webhook 或额外聊天平台链路。
+- **数据归你所有**：会话数据存放在你自己的 Cloudflare R2 bucket，而不是第三方托管聊天服务。
+- **聊天形态自由**：同一个 OpenClaw 后端既可驱动移动端友好 UI，也可支持偏终端风格的高阶交互。
+
+### 依赖要求
+
+- OpenClaw `2026.7.1` 或更高版本
+- 一个 Cloudflare R2 bucket
+- 一个 R2 endpoint URL
+- 对该 bucket 有访问权限的 access key id 与 secret access key
+
+### 在 OpenClaw 中安装插件
+
+通过 ClawHub 使用插件 ID 直接安装：
+
+```bash
+openclaw plugins install clawhub:r2-relay-channel
+openclaw gateway restart
+```
+
+### 配置 OpenClaw
+
+安装后执行：
+
+```bash
+openclaw configure
+```
+
+OpenClaw 应显示 `R2 Relay` 的通道配置流程，并提示你输入：
+
+- R2 endpoint URL
+- bucket name
+- access key ID
+- secret access key
+- gateway server ID
+
+向导会自动给出一个简短的随机 server ID 候选值。你可以直接使用，也可以修改。若多个 gateway 共享同一个 R2 bucket，请确保每个 server ID 唯一。
+
+### 在 iOS 上安装 AgentDeck
+
+若要在 iPhone 或 iPad 上使用这个 relay，请在 App Store 中搜索
+**AgentDeck** 并安装。你也可以按照
+[iOS 构建说明](../../apps/ios/README.md) 免费自行构建。
+
+打开 AgentDeck，并填写与本插件一致的 R2 连接信息。
+
+### `/session-target` 命令
+
+插件会注册一个命令，用于显示当前会话可用的中继目标，可用于 cron 投递或直接 webhook POST。
+
+至少先让一条入站中继消息建立会话状态，然后运行：
+
+```text
+/session-target
+```
+
+命令会返回两个可复制的代码块：
+
+- cron target string
+- webhook URL
+
+#### Cron target string
+
+插件支持 OpenClaw 原生投递目标：`--channel r2-relay-channel` 搭配 provider 专用 `--to` 格式。
+
+目标格式：
+
+```text
+peer=<peer>,session=<sessionKey>
+```
+
+示例：
+
+```bash
+openclaw cron add \
+  --name "Morning brief" \
+  --cron "0 7 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Summarize overnight updates." \
+  --announce \
+  --channel r2-relay-channel \
+  --to 'peer=phone-abc123,session=agent:main:main'
+```
+
+说明：
+
+- `peer` 是中继接收端 id。
+- `session` 是需要路由到的 OpenClaw 精确 session key。
+- 该最小格式中，值内部保留字符为 `,` 与 `=`。
+
+#### Webhook URL
+
+插件提供一个简化 webhook 端点供 cron 调用。
+
+认证沿用 OpenClaw 已有的 `cron.webhookToken`，无需单独插件 token。
+
+请先在 OpenClaw 配置中设置 cron webhook token：
+
+```json5
+{
+  cron: {
+    webhookToken: "replace-with-a-random-secret"
+  }
+}
+```
+
+端点接收 JSON POST 请求，支持：
+
+- 包含 `summary` 字段的 cron finished event 负载
+- 包含 `text` 字段的手工请求负载
+- 包含 `error` 字段的错误负载
+
+插件会按 `text`、`summary`、`error` 的优先顺序选择第一个非空值，并转发到指定 relay session。
+
+Curl 示例：
+
+```bash
+curl -X POST 'http://127.0.0.1:18789/r2-relay-channel/webhook/moss-river-w5/agent%3Amain%3Amain' \
+  -H 'Authorization: Bearer <cron.webhookToken>' \
+  -H 'Content-Type: application/json' \
+  --data '{"text":"hello from curl"}'
+```
+
+### 从 OpenClaw 卸载插件
+
+执行以下命令：
+
+```bash
+openclaw plugins uninstall r2-relay-channel
+openclaw gateway restart
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

package/dist/channel.d.ts

@@ -0,0 +1,16 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+import { resolveR2RelayAccount, type ResolvedR2RelayAccount } from "./config.js";
+type RelayApprovalCapability = {
+    getExecInitiatingSurfaceState: (params: {
+        cfg: Parameters<typeof resolveR2RelayAccount>[0]["cfg"];
+        accountId?: string | null;
+        action: "approve";
+    }) => {
+        kind: "enabled" | "disabled";
+    };
+};
+type RelayChannelPlugin = ChannelPlugin<ResolvedR2RelayAccount> & {
+    approvalCapability: RelayApprovalCapability;
+};
+export declare const r2RelayPlugin: RelayChannelPlugin;
+export {};

package/dist/channel.js

@@ -0,0 +1,271 @@
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
+import { buildBaseChannelStatusSummary, collectStatusIssuesFromLastError, } from "openclaw/plugin-sdk/status-helpers";
+import { runPassiveAccountLifecycle } from "openclaw/plugin-sdk/channel-lifecycle";
+import { r2RelayChannelConfigSchema, resolveR2RelayAccount, listR2RelayAccountIds, } from "./config.js";
+import { r2RelaySetupAdapter, r2RelaySetupWizard } from "./setup.js";
+import { loadCheckpointState } from "./checkpoint-store.js";
+import { formatInboundRelayBody, classifyInboundRelayMessageFailure, dispatchInboundMessage } from "./inbound.js";
+import { clearService, createDefaultRuntimeState, getOrCreateService, pollRelayInbox, redactEndpoint, runSweeperLoop, setRuntimeSnapshot, touchRuntime, } from "./lifecycle.js";
+import { r2RelayMessageAdapter } from "./message-adapter.js";
+import { syncPublishedIdentity } from "./session-publication.js";
+import { formatRelayTargetHint, parseRelayTarget } from "./target.js";
+function jsonResult(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload, null, 2),
+            },
+        ],
+        details: payload,
+        channelData: payload,
+    };
+}
+function readStringParam(params, key, options) {
+    const value = params[key];
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.length > 0 || !options?.required) {
+            return trimmed;
+        }
+    }
+    if (options?.required) {
+        throw new Error(`Missing required parameter: ${key}`);
+    }
+    return "";
+}
+function readBooleanParam(params, key) {
+    const value = params[key];
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return value !== 0;
+    }
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (["1", "true", "yes", "y", "on"].includes(normalized)) {
+            return true;
+        }
+        if (["0", "false", "no", "n", "off", ""].includes(normalized)) {
+            return false;
+        }
+    }
+    return false;
+}
+function readReactionParams(params, options) {
+    const emoji = readStringParam(params, "emoji") || readStringParam(params, "reaction");
+    const remove = readBooleanParam(params, "remove");
+    const isEmpty = emoji.length === 0;
+    if (remove && isEmpty) {
+        throw new Error(options?.removeErrorMessage ?? "remove=true requires a specific emoji.");
+    }
+    if (!remove && isEmpty) {
+        throw new Error("Missing required parameter: emoji");
+    }
+    return { emoji, remove, isEmpty };
+}
+function agentIdFromConversationId(conversationId) {
+    const normalized = conversationId?.trim();
+    if (!normalized) {
+        return null;
+    }
+    const parts = normalized.split(":");
+    if (parts.length >= 2 && parts[0] === "agent" && parts[1]?.trim()) {
+        return parts[1].trim();
+    }
+    return null;
+}
+export const r2RelayPlugin = {
+    id: "r2-relay-channel",
+    meta: {
+        id: "r2-relay-channel",
+        label: "R2 Relay",
+        selectionLabel: "R2 Relay",
+        docsPath: "/channels/r2-relay-channel",
+        docsLabel: "r2-relay-channel",
+        blurb: "Cloudflare R2-backed relay channel for direct text messaging.",
+        order: 120,
+    },
+    capabilities: {
+        chatTypes: ["direct"],
+        reactions: true,
+        media: true,
+    },
+    approvalCapability: {
+        getExecInitiatingSurfaceState: ({ cfg, accountId, }) => {
+            const account = resolveR2RelayAccount({ cfg, accountId });
+            if (!account.enabled || !account.configured) {
+                return { kind: "disabled" };
+            }
+            return { kind: "enabled" };
+        },
+    },
+    reload: { configPrefixes: ["channels.r2-relay-channel"] },
+    configSchema: r2RelayChannelConfigSchema,
+    setupWizard: r2RelaySetupWizard,
+    setup: r2RelaySetupAdapter,
+    config: {
+        listAccountIds: (cfg) => listR2RelayAccountIds(cfg),
+        resolveAccount: (cfg, accountId) => resolveR2RelayAccount({ cfg, accountId }),
+        defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+        isConfigured: (account) => account.configured,
+        describeAccount: (account) => ({
+            accountId: account.accountId,
+            enabled: account.enabled,
+            configured: account.configured,
+            serverId: account.serverId,
+            bucket: account.bucket,
+            endpoint: redactEndpoint(account.endpoint),
+        }),
+    },
+    actions: {
+        describeMessageTool: () => ({
+            actions: ["react"],
+        }),
+        supportsAction: ({ action }) => action === "react",
+        handleAction: async ({ action, params, cfg, accountId }) => {
+            const account = resolveR2RelayAccount({ cfg, accountId });
+            const service = getOrCreateService(account);
+            if (action === "react") {
+                const to = readStringParam(params, "to", { required: true });
+                const messageId = readStringParam(params, "messageId", { required: true });
+                const reaction = readReactionParams(params, {
+                    removeErrorMessage: "R2 Relay reactions support remove=true only with a specific emoji.",
+                });
+                const target = parseRelayTarget(to);
+                const result = await service.sendMessage(target.peer, {
+                    route: {
+                        agent_id: target.conversationId ? agentIdFromConversationId(target.conversationId) ?? "main" : "main",
+                        conversation_id: target.conversationId ?? null,
+                        instance_id: null,
+                    },
+                    content: {
+                        type: "reaction",
+                        target_msg_id: messageId,
+                        emoji: reaction.emoji || "✅",
+                        remove: reaction.remove || reaction.isEmpty,
+                    },
+                });
+                touchRuntime(account.accountId, {
+                    lastOutboundAt: Date.now(),
+                    lastError: null,
+                });
+                return jsonResult({
+                    ok: true,
+                    channel: "r2-relay-channel",
+                    action: "react",
+                    to: to.trim(),
+                    messageId: result.messageId,
+                    targetMessageId: messageId,
+                    emoji: reaction.emoji,
+                    remove: reaction.remove || reaction.isEmpty,
+                });
+            }
+            throw new Error(`Unsupported r2-relay-channel action: ${action}`);
+        },
+    },
+    messaging: {
+        normalizeTarget: (target) => target.trim(),
+        targetResolver: {
+            looksLikeId: (input) => Boolean(input.trim()),
+            hint: `${formatRelayTargetHint()} or <peer>`,
+        },
+    },
+    message: r2RelayMessageAdapter,
+    status: {
+        defaultRuntime: createDefaultRuntimeState(DEFAULT_ACCOUNT_ID),
+        collectStatusIssues: (accounts) => collectStatusIssuesFromLastError("r2-relay-channel", accounts),
+        buildChannelSummary: ({ snapshot }) => {
+            const extended = snapshot;
+            return {
+                ...buildBaseChannelStatusSummary(snapshot),
+                serverId: extended.serverId ?? null,
+                bucket: extended.bucket ?? null,
+                endpoint: extended.endpoint ?? null,
+                lastPollAt: extended.lastPollAt ?? null,
+                checkpointHeadKey: extended.checkpointHeadKey ?? null,
+                lastInboundAt: extended.lastInboundAt ?? null,
+                lastOutboundAt: extended.lastOutboundAt ?? null,
+            };
+        },
+        buildAccountSnapshot: ({ account, runtime }) => {
+            const extendedRuntime = (runtime ?? null);
+            return {
+                accountId: account.accountId,
+                enabled: account.enabled,
+                configured: account.configured,
+                running: runtime?.running ?? false,
+                lastStartAt: runtime?.lastStartAt ?? null,
+                lastStopAt: runtime?.lastStopAt ?? null,
+                lastError: runtime?.lastError ?? null,
+                lastPollAt: extendedRuntime?.lastPollAt ?? null,
+                lastInboundAt: extendedRuntime?.lastInboundAt ?? null,
+                lastOutboundAt: extendedRuntime?.lastOutboundAt ?? null,
+                serverId: account.serverId,
+                bucket: account.bucket,
+                endpoint: redactEndpoint(account.endpoint),
+                checkpointHeadKey: extendedRuntime?.checkpointHeadKey ?? null,
+            };
+        },
+    },
+    gateway: {
+        startAccount: async (ctx) => {
+            const account = ctx.account;
+            const runtime = createDefaultRuntimeState(account.accountId);
+            runtime.serverId = account.serverId;
+            runtime.bucket = account.bucket;
+            runtime.endpoint = redactEndpoint(account.endpoint);
+            setRuntimeSnapshot(account.accountId, runtime);
+            ctx.setStatus({
+                accountId: account.accountId,
+            });
+            return runPassiveAccountLifecycle({
+                abortSignal: ctx.abortSignal,
+                start: async () => {
+                    const service = getOrCreateService(account);
+                    await syncPublishedIdentity(service, account, true);
+                    void runSweeperLoop({
+                        account,
+                        service,
+                        abortSignal: ctx.abortSignal,
+                        log: ctx.log,
+                    });
+                    touchRuntime(account.accountId, {
+                        running: true,
+                        lastStartAt: Date.now(),
+                        lastError: null,
+                        serverId: account.serverId,
+                        bucket: account.bucket,
+                        endpoint: redactEndpoint(account.endpoint),
+                    });
+                    ctx.setStatus({
+                        accountId: account.accountId,
+                    });
+                    const state = await loadCheckpointState(account.accountId);
+                    await pollRelayInbox({
+                        cfg: ctx.cfg,
+                        account,
+                        service,
+                        abortSignal: ctx.abortSignal,
+                        log: ctx.log,
+                        setStatus: ctx.setStatus,
+                        state,
+                        syncPublishedIdentity,
+                        dispatchInboundMessage,
+                        formatInboundRelayBody,
+                        classifyInboundRelayMessageFailure,
+                    });
+                    return { service };
+                },
+                stop: async () => {
+                    clearService(account.accountId);
+                    touchRuntime(account.accountId, {
+                        running: false,
+                        lastStopAt: Date.now(),
+                    });
+                },
+            });
+        },
+    },
+};

package/dist/checkpoint-store.d.ts

@@ -0,0 +1,4 @@
+import { defaultCheckpointState, hasSeenMessage, rememberMessage, type RelayCheckpointState } from "./relay-core/index.js";
+export declare function loadCheckpointState(accountId?: string): Promise<RelayCheckpointState>;
+export declare function saveCheckpointState(state: RelayCheckpointState, accountId?: string): Promise<void>;
+export { defaultCheckpointState, hasSeenMessage, rememberMessage, type RelayCheckpointState, };

package/dist/checkpoint-store.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
+import { defaultCheckpointState, hasSeenMessage, loadCheckpointStateFromFile, rememberMessage, saveCheckpointStateToFile, } from "./relay-core/index.js";
+import { getRelayRuntime } from "./runtime.js";
+import { PLUGIN_ID } from "./config.js";
+function stateFilePath(accountId = DEFAULT_ACCOUNT_ID) {
+    const baseDir = getRelayRuntime().state.resolveStateDir();
+    return path.join(baseDir, "plugins", PLUGIN_ID, `${accountId}.json`);
+}
+export async function loadCheckpointState(accountId = DEFAULT_ACCOUNT_ID) {
+    return await loadCheckpointStateFromFile(stateFilePath(accountId));
+}
+export async function saveCheckpointState(state, accountId = DEFAULT_ACCOUNT_ID) {
+    await saveCheckpointStateToFile(stateFilePath(accountId), state);
+}
+export { defaultCheckpointState, hasSeenMessage, rememberMessage, };

package/dist/commands.d.ts

@@ -0,0 +1,2 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+export declare function registerRelayCommands(api: OpenClawPluginApi): void;