@relaymessenger/openclaw-plugin 0.2.0

package/dist/src/client.js

@@ -0,0 +1,219 @@
+// Thin Relay REST client for the OpenClaw channel plugin. Bespoke fetch until
+// the Relay SDK ships. Owns the abort-aware long poll, idempotent
+// sends, typing, and read watermarks. No SDK imports so unit tests run
+// without an OpenClaw runtime.
+import { isIP } from "node:net";
+export const DEFAULT_RELAY_BASE_URL = "https://api.relayapp.im";
+function isLoopbackHostname(hostname) {
+    const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    const ipVersion = isIP(normalized);
+    if (ipVersion === 4) {
+        return normalized.split(".")[0] === "127";
+    }
+    if (ipVersion === 6) {
+        return normalized === "::1";
+    }
+    return (normalized === "localhost" ||
+        normalized.endsWith(".localhost"));
+}
+/**
+ * Validate and canonicalize the API origin before a bearer token can be sent
+ * to it. Production/custom remote origins must use HTTPS. Plain HTTP remains
+ * available only for an explicit loopback development server.
+ */
+export function normalizeRelayBaseUrl(raw) {
+    const candidate = raw?.trim() || DEFAULT_RELAY_BASE_URL;
+    let url;
+    try {
+        url = new URL(candidate);
+    }
+    catch {
+        throw new Error(`relay: invalid baseUrl ${JSON.stringify(candidate)}`);
+    }
+    if (url.username || url.password) {
+        throw new Error("relay: baseUrl must not contain credentials");
+    }
+    if (url.search || url.hash) {
+        throw new Error("relay: baseUrl must not contain a query or fragment");
+    }
+    if (!/^\/+$/u.test(url.pathname)) {
+        throw new Error("relay: baseUrl must be an origin without a path");
+    }
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHostname(url.hostname))) {
+        throw new Error("relay: baseUrl must use HTTPS (HTTP is allowed only for loopback development)");
+    }
+    return url.origin;
+}
+/** Classified Relay API failure. `terminal` means operator action (bad token). */
+export class RelayApiError extends Error {
+    status;
+    kind;
+    /** Server error code from the response body (`error.code`), when present. */
+    code;
+    constructor(message, params) {
+        super(message);
+        this.name = "RelayApiError";
+        this.status = params.status;
+        this.kind = params.kind;
+        this.code = params.code;
+    }
+    get terminal() {
+        return this.kind === "auth";
+    }
+    get retryable() {
+        return this.kind === "retryable";
+    }
+}
+/**
+ * 409 from the webhook XOR rule: an enabled webhook endpoint makes long
+ * polling unavailable until the operator disables it (server code
+ * `conflict`, distinct from `terminated_by_other_consumer`).
+ */
+export function isRelayWebhookConflict(error) {
+    return (error instanceof RelayApiError &&
+        error.status === 409 &&
+        error.code !== "terminated_by_other_consumer");
+}
+export function classifyRelayHttpStatus(status) {
+    if (status === 401) {
+        return "auth";
+    }
+    if (status === 409) {
+        return "conflict";
+    }
+    if (status === 408 || status === 429 || status >= 500) {
+        return "retryable";
+    }
+    return "rejected";
+}
+export function isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+async function readErrorDetail(response) {
+    try {
+        const body = (await response.json());
+        return {
+            ...(body?.error?.code ? { code: body.error.code } : {}),
+            message: body?.error?.message ?? body?.message ?? "",
+        };
+    }
+    catch {
+        return { message: "" };
+    }
+}
+export function createRelayClient(options) {
+    const baseUrl = normalizeRelayBaseUrl(options.baseUrl);
+    const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
+    const requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
+    const request = async (params) => {
+        const url = new URL(`${baseUrl}${params.path}`);
+        for (const [key, value] of Object.entries(params.query ?? {})) {
+            if (value !== undefined) {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        let response;
+        const timeoutSignal = AbortSignal.timeout(params.timeoutMs ?? requestTimeoutMs);
+        const signal = params.signal
+            ? AbortSignal.any([params.signal, timeoutSignal])
+            : timeoutSignal;
+        try {
+            response = await fetchImpl(url.toString(), {
+                method: params.method,
+                headers: {
+                    authorization: `Bearer ${options.token}`,
+                    ...(params.body === undefined ? {} : { "content-type": "application/json" }),
+                    ...params.headers,
+                },
+                ...(params.body === undefined ? {} : { body: JSON.stringify(params.body) }),
+                signal,
+            });
+        }
+        catch (error) {
+            if (timeoutSignal.aborted && !params.signal?.aborted) {
+                throw new RelayApiError(`relay: ${params.method} ${params.path} timed out after ${params.timeoutMs ?? requestTimeoutMs}ms`, { kind: "retryable" });
+            }
+            if (isAbortError(error)) {
+                throw error;
+            }
+            // Network-level failure (DNS, reset, offline): always retryable.
+            throw new RelayApiError(`relay: network error: ${String(error)}`, { kind: "retryable" });
+        }
+        if (!response.ok) {
+            const detail = await readErrorDetail(response);
+            throw new RelayApiError(`relay: ${params.method} ${params.path} failed with ${response.status}${detail.message ? `: ${detail.message}` : ""}`, {
+                status: response.status,
+                kind: classifyRelayHttpStatus(response.status),
+                ...(detail.code ? { code: detail.code } : {}),
+            });
+        }
+        return response;
+    };
+    return {
+        getMe: async (params) => {
+            const response = await request({
+                method: "GET",
+                path: "/v1/agents/me",
+                signal: params?.signal,
+            });
+            const body = (await response.json());
+            return body.agent;
+        },
+        pollEvents: async (params) => {
+            const timeoutSeconds = Math.min(Math.max(params.timeoutSeconds ?? 30, 1), 30);
+            // Guard against a wedged connection: the server holds <= timeout seconds,
+            // so anything past timeout + slack is a dead socket, not a slow poll.
+            const response = await request({
+                method: "GET",
+                path: "/v1/events",
+                query: {
+                    cursor: params.cursor,
+                    timeout: timeoutSeconds,
+                    ...(params.limit === undefined ? {} : { limit: params.limit }),
+                },
+                signal: params.signal,
+                timeoutMs: (timeoutSeconds + 15) * 1_000,
+            });
+            const body = (await response.json());
+            const events = Array.isArray(body.events) ? body.events : [];
+            const nextCursor = typeof body.next_cursor === "number" && Number.isSafeInteger(body.next_cursor)
+                ? body.next_cursor
+                : params.cursor;
+            return { events, nextCursor };
+        },
+        sendMessage: async (params) => {
+            const response = await request({
+                method: "POST",
+                path: "/v1/messages",
+                headers: { "idempotency-key": params.idempotencyKey },
+                body: {
+                    conversation_id: params.conversationId,
+                    parts: params.parts,
+                    ...(params.replyTo ? { reply_to: params.replyTo } : {}),
+                },
+                signal: params.signal,
+            });
+            const body = (await response.json());
+            return { messages: body.messages };
+        },
+        setTyping: async (params) => {
+            await request({
+                method: "POST",
+                path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/typing`,
+                body: {
+                    started: params.started,
+                    ...(params.label ? { label: params.label } : {}),
+                },
+                signal: params.signal,
+            });
+        },
+        markRead: async (params) => {
+            await request({
+                method: "POST",
+                path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/read`,
+                body: { message_id: params.messageId },
+                signal: params.signal,
+            });
+        },
+    };
+}

package/dist/src/cursor-store.js

@@ -0,0 +1,136 @@
+// Persisted long-poll cursor, Telegram-offset style:
+// monotonic writes only, bound to the agent identity so a token that now
+// resolves to a different agent discards the stale cursor instead of acking
+// another contact's event stream.
+import { createHash } from "node:crypto";
+import { assertRelayStateDocument, emptyRelayStateDocument, openRelayStateDocument, } from "./state-files.js";
+export const RELAY_CURSOR_MAX_ENTRIES = 1_000;
+export const RELAY_CURSOR_OVERFLOW_POLICY = "reject-new";
+const RECORD_VERSION = 2;
+/**
+ * Open Relay's private, lock-protected state file with fail-closed capacity
+ * semantics. A cursor is permanent safety state: evicting an old identity to
+ * admit a new one could replay retained events when the old identity returns.
+ */
+export function openRelayCursorStateStore(warn, options = {}) {
+    const maxEntries = options.maxEntries ?? RELAY_CURSOR_MAX_ENTRIES;
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+        throw new Error("relay cursor maxEntries must be a positive safe integer");
+    }
+    const store = openRelayStateDocument({
+        fileName: "cursors.json",
+        ...(options.env ? { env: options.env } : {}),
+    });
+    const storageKey = (key) => createHash("sha256").update(key).digest("hex");
+    const validateEntry = (key, value) => {
+        if (!/^[a-f0-9]{64}$/u.test(key) || !value || typeof value !== "object")
+            return false;
+        const record = value;
+        return (record.version === RECORD_VERSION &&
+            isValidCursor(record.cursor) &&
+            typeof record.baseUrl === "string" &&
+            (() => {
+                try {
+                    return new URL(record.baseUrl).origin === record.baseUrl;
+                }
+                catch {
+                    return false;
+                }
+            })() &&
+            typeof record.agentId === "string" &&
+            record.agentId.length > 0);
+    };
+    const read = async () => {
+        try {
+            const current = await store.read();
+            if (current === undefined)
+                return emptyRelayStateDocument();
+            assertRelayStateDocument(current, "cursor", validateEntry);
+            return current;
+        }
+        catch (error) {
+            warn(`[relay] cursor state unavailable; refusing unsafe cursor reset: ${String(error)}`);
+            throw error;
+        }
+    };
+    return {
+        lookup: async (key) => (await read()).entries[storageKey(key)],
+        register: async (key, value) => {
+            try {
+                await store.updateOr(emptyRelayStateDocument(), (current) => {
+                    assertRelayStateDocument(current, "cursor", validateEntry);
+                    const hashedKey = storageKey(key);
+                    if (!Object.hasOwn(current.entries, hashedKey) &&
+                        Object.keys(current.entries).length >= maxEntries) {
+                        throw new Error(`relay cursor state reached ${maxEntries} identities (${RELAY_CURSOR_OVERFLOW_POLICY})`);
+                    }
+                    return {
+                        version: current.version,
+                        entries: { ...current.entries, [hashedKey]: value },
+                    };
+                });
+            }
+            catch (error) {
+                warn(`[relay] cursor state unavailable; refusing unsafe cursor reset: ${String(error)}`);
+                throw error;
+            }
+        },
+    };
+}
+function isValidCursor(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+export function createRelayCursorStore(params) {
+    const baseUrl = new URL(params.baseUrl).origin;
+    const key = `relay:${baseUrl}:${params.agentId}`;
+    let cursor = 0;
+    let loaded = false;
+    return {
+        load: async () => {
+            let record;
+            try {
+                record = await params.store.lookup(key);
+            }
+            catch (error) {
+                params.onPersistError?.(error);
+                throw new Error(`relay cursor state could not be loaded: ${String(error)}`);
+            }
+            if (!record) {
+                cursor = 0;
+                loaded = true;
+                return cursor;
+            }
+            if (record.version !== RECORD_VERSION ||
+                !isValidCursor(record.cursor) ||
+                record.agentId !== params.agentId ||
+                record.baseUrl !== baseUrl) {
+                throw new Error(`relay cursor state is corrupt for ${baseUrl} ${params.agentId}; refusing cursor-zero replay`);
+            }
+            cursor = record.cursor;
+            loaded = true;
+            return cursor;
+        },
+        current: () => cursor,
+        advance: async (next) => {
+            if (!loaded) {
+                throw new Error("relay cursor store: advance() before load()");
+            }
+            if (!isValidCursor(next) || next <= cursor) {
+                return;
+            }
+            try {
+                await params.store.register(key, {
+                    version: RECORD_VERSION,
+                    cursor: next,
+                    baseUrl,
+                    agentId: params.agentId,
+                });
+            }
+            catch (error) {
+                params.onPersistError?.(error);
+                throw new Error(`relay cursor advance was not durable: ${String(error)}`);
+            }
+            cursor = next;
+        },
+    };
+}

package/dist/src/inbound-dedupe.js

@@ -0,0 +1,175 @@
+// Relay inbound replay protection. The long-poll cursor acknowledges batches,
+// so a crash between dispatch and cursor advance
+// replays events. Each (canonical origin, agent, event) is claimed, safely
+// preflighted, and durably committed immediately before agent dispatch. That
+// gives engine/tool side effects at-most-once semantics:
+// an interrupted turn may need the user to resend, but it is never silently
+// executed twice.
+import { createHash } from "node:crypto";
+import { assertRelayStateDocument, emptyRelayStateDocument, openRelayStateDocument, } from "./state-files.js";
+// One shared namespace with stable Relay identity baked into each key so local
+// account renames cannot reset safety state or partition the row budget.
+const RELAY_INBOUND_DEDUPE_SCOPE = "global";
+// 30d window: a long outage can replay a deep cursor backlog.
+export const RELAY_INBOUND_DEDUPE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export const RELAY_INBOUND_DEDUPE_STATE_MAX_ENTRIES = 20_000;
+export function buildRelayInboundDedupeKey(params) {
+    const eventId = params.eventId.trim();
+    if (!eventId) {
+        return null;
+    }
+    // NUL separator: event ids are opaque strings, so a printable separator
+    // could collide two distinct (account, event) pairs.
+    return `${new URL(params.baseUrl).origin}\0${params.agentId}\0${eventId}`;
+}
+export function createRelayInboundDeduper(params) {
+    const namespace = RELAY_INBOUND_DEDUPE_SCOPE;
+    return {
+        claimEvent: async (eventId) => {
+            const key = buildRelayInboundDedupeKey({ baseUrl: params.baseUrl, agentId: params.agentId, eventId });
+            if (!key) {
+                // Fail closed: an event without a durable identity cannot safely
+                // cross the at-most-once agent/tool side-effect boundary.
+                return false;
+            }
+            return (await params.guard.claim(key, { namespace })).kind === "claimed";
+        },
+        commitEvent: async (eventId) => {
+            const key = buildRelayInboundDedupeKey({ baseUrl: params.baseUrl, agentId: params.agentId, eventId });
+            if (!key) {
+                return;
+            }
+            await params.guard.commit(key, { namespace });
+        },
+        releaseEvent: (eventId) => {
+            const key = buildRelayInboundDedupeKey({ baseUrl: params.baseUrl, agentId: params.agentId, eventId });
+            if (key) {
+                params.guard.release(key, { namespace });
+            }
+        },
+    };
+}
+function durableAttemptKey(key, namespace) {
+    return createHash("sha256").update(`${namespace}\0${key}`).digest("hex");
+}
+/**
+ * Strict Relay-owned guard used by the channel runtime. Unlike a normal
+ * message dedupe cache, persistence is not best effort: a failed attempt write
+ * must stop before agent dispatch or a crash could execute local tools twice.
+ */
+export function createRelayInboundDedupeGuard(params) {
+    const now = params?.now ?? Date.now;
+    const ttlMs = params?.ttlMs ?? RELAY_INBOUND_DEDUPE_TTL_MS;
+    const maxEntries = params?.maxEntries ?? RELAY_INBOUND_DEDUPE_STATE_MAX_ENTRIES;
+    if (!Number.isSafeInteger(ttlMs) || ttlMs < 1) {
+        throw new Error("relay inbound dedupe ttlMs must be a positive safe integer");
+    }
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+        throw new Error("relay inbound dedupe maxEntries must be a positive safe integer");
+    }
+    const readNow = () => {
+        const timestamp = now();
+        if (!Number.isSafeInteger(timestamp) || timestamp < 0) {
+            throw new Error("relay inbound dedupe clock returned an invalid timestamp");
+        }
+        return timestamp;
+    };
+    const isPersistedAttempt = (key, value) => {
+        if (!/^[a-f0-9]{64}$/u.test(key) || !value || typeof value !== "object")
+            return false;
+        const entry = value;
+        return (typeof entry.attemptedAt === "number" &&
+            Number.isSafeInteger(entry.attemptedAt) &&
+            entry.attemptedAt >= 0 &&
+            typeof entry.expiresAt === "number" &&
+            Number.isSafeInteger(entry.expiresAt) &&
+            entry.expiresAt > entry.attemptedAt);
+    };
+    const state = params?.store
+        ? undefined
+        : openRelayStateDocument({
+            fileName: "inbound-attempts.json",
+            ...(params?.env ? { env: params.env } : {}),
+        });
+    const store = params?.store ??
+        {
+            lookup: async (key) => {
+                const current = await state.read();
+                if (current === undefined)
+                    return undefined;
+                assertRelayStateDocument(current, "inbound attempt", isPersistedAttempt);
+                const entry = current.entries[key];
+                if (!entry || entry.expiresAt <= readNow())
+                    return undefined;
+                return { attemptedAt: entry.attemptedAt };
+            },
+            register: async (key, value, opts) => {
+                await state.updateOr(emptyRelayStateDocument(), (current) => {
+                    assertRelayStateDocument(current, "inbound attempt", isPersistedAttempt);
+                    const timestamp = readNow();
+                    const entryTtlMs = opts?.ttlMs ?? ttlMs;
+                    if (!Number.isSafeInteger(entryTtlMs) || entryTtlMs < 1) {
+                        throw new Error("relay inbound dedupe ttlMs must be a positive safe integer");
+                    }
+                    const expiresAt = value.attemptedAt + entryTtlMs;
+                    if (!Number.isSafeInteger(expiresAt)) {
+                        throw new Error("relay inbound dedupe expiration exceeds safe integer range");
+                    }
+                    const liveEntries = Object.fromEntries(Object.entries(current.entries).filter(([, entry]) => entry.expiresAt > timestamp));
+                    liveEntries[key] = {
+                        attemptedAt: value.attemptedAt,
+                        expiresAt,
+                    };
+                    const ordered = Object.entries(liveEntries).sort(([leftKey, left], [rightKey, right]) => left.attemptedAt - right.attemptedAt || leftKey.localeCompare(rightKey));
+                    const retained = ordered.slice(Math.max(ordered.length - maxEntries, 0));
+                    return {
+                        version: current.version,
+                        entries: Object.fromEntries(retained),
+                    };
+                });
+            },
+        };
+    const inflight = new Set();
+    const claiming = new Set();
+    const withDiskError = async (operation) => {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            params?.onDiskError?.(error);
+            throw error;
+        }
+    };
+    return {
+        claim: async (key, opts) => {
+            const storageKey = durableAttemptKey(key, opts.namespace);
+            if (inflight.has(storageKey) || claiming.has(storageKey)) {
+                return { kind: "inflight" };
+            }
+            claiming.add(storageKey);
+            try {
+                if ((await withDiskError(() => store.lookup(storageKey))) !== undefined) {
+                    return { kind: "duplicate" };
+                }
+                inflight.add(storageKey);
+                return { kind: "claimed" };
+            }
+            finally {
+                claiming.delete(storageKey);
+            }
+        },
+        commit: async (key, opts) => {
+            const storageKey = durableAttemptKey(key, opts.namespace);
+            try {
+                await withDiskError(() => store.register(storageKey, { attemptedAt: readNow() }, { ttlMs }));
+                return true;
+            }
+            finally {
+                inflight.delete(storageKey);
+            }
+        },
+        release: (key, opts) => {
+            inflight.delete(durableAttemptKey(key, opts.namespace));
+        },
+    };
+}

package/dist/src/inbound.js

@@ -0,0 +1,94 @@
+export function classifyRelayEvent(event) {
+    switch (event.event_type) {
+        case "message.received":
+            return "message";
+        case "reaction.added":
+        case "reaction.removed":
+            return "reaction";
+        case "message.delivered":
+        case "message.read":
+            return "lifecycle";
+        default:
+            return "unknown";
+    }
+}
+/**
+ * Render typed parts into agent-facing text: text parts joined, link URLs
+ * inlined, `data` parts as a compact JSON fence, media/voice as a labeled
+ * fetchable URL. The URL is a capability link: it is the authorization, so
+ * any HTTP client can fetch the bytes without an Agent Token.
+ */
+export function renderRelayPartsText(parts) {
+    const lines = [];
+    for (const part of parts) {
+        switch (part.type) {
+            case "text":
+                if (part.text) {
+                    lines.push(part.text);
+                }
+                break;
+            case "link_preview":
+                lines.push(part.url);
+                break;
+            case "data": {
+                let rendered;
+                try {
+                    rendered = JSON.stringify(part.data);
+                }
+                catch {
+                    rendered = String(part.data);
+                }
+                lines.push("```json\n" + rendered + "\n```");
+                break;
+            }
+            case "media":
+                lines.push(`[attachment] ${part.url}`);
+                break;
+            case "voice_memo":
+                lines.push(part.duration_ms
+                    ? `[voice memo, ${Math.round(part.duration_ms / 1000)}s] ${part.url}`
+                    : `[voice memo] ${part.url}`);
+                break;
+        }
+    }
+    return lines.join("\n");
+}
+/** Drop the agent's own sends echoed back on the event stream. */
+export function isRelayEchoMessage(message, agentId) {
+    return message.sender.kind === "agent" && message.sender.id === agentId;
+}
+/**
+ * Build the dispatchable fact bundle for a message.received event. Returns
+ * null when the event should not start a turn: echoes of our own agent,
+ * non-message events, or messages with no renderable content.
+ */
+export function buildRelayInboundFacts(event, params) {
+    if (classifyRelayEvent(event) !== "message") {
+        return null;
+    }
+    const message = event.data.message;
+    if (!message || !message.id || !message.conversation_id) {
+        return null;
+    }
+    // Agent-authored messages never start a local agent turn. This drops our
+    // own event echo and prevents agent-to-agent loops even if an id is
+    // mistakenly added to the user allowlist.
+    if (message.sender.kind !== "user" || isRelayEchoMessage(message, params.agentId)) {
+        return null;
+    }
+    const text = renderRelayPartsText(message.parts) || message.fallback_text || "";
+    if (!text.trim()) {
+        return null;
+    }
+    const createdAtMs = Date.parse(message.created_at);
+    return {
+        eventId: event.event_id,
+        messageId: message.id,
+        conversationId: message.conversation_id,
+        senderId: message.sender.id,
+        senderKind: message.sender.kind,
+        ...(message.reply_to?.message_id ? { replyToId: message.reply_to.message_id } : {}),
+        text,
+        ...(Number.isFinite(createdAtMs) ? { timestamp: createdAtMs } : {}),
+    };
+}

package/dist/src/lifecycle.js

@@ -0,0 +1,35 @@
+/** Owns exactly one abortable long-poll lifecycle per configured account. */
+export function createRelayAccountLifecycleRegistry() {
+    const controllers = new Map();
+    return {
+        acquire(accountId, parentSignal) {
+            if (controllers.has(accountId)) {
+                throw new Error(`relay: account "${accountId}" already has an active consumer`);
+            }
+            const controller = new AbortController();
+            controllers.set(accountId, controller);
+            const signal = AbortSignal.any([parentSignal, controller.signal]);
+            let released = false;
+            return {
+                signal,
+                release: () => {
+                    if (released) {
+                        return;
+                    }
+                    released = true;
+                    if (controllers.get(accountId) === controller) {
+                        controllers.delete(accountId);
+                    }
+                },
+            };
+        },
+        stop(accountId) {
+            const controller = controllers.get(accountId);
+            if (!controller) {
+                return false;
+            }
+            controller.abort();
+            return true;
+        },
+    };
+}