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

package/src/types.ts

@@ -1,155 +1,12 @@
-// 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 type RelaySender = {
-  // `system` is real on the wire: a group's own notices are authored by it
-  // (creating a group commits "<name> created <title>"). Only `user` messages
-  // start a turn, and `buildRelayInboundFacts` drops everything else.
-  kind: "user" | "agent" | "system";
-  id: string;
-};
-
-// Inline mention of a conversation participant. Offsets are UTF-16 code
-// units into the part's text, which holds the inserted display name with
-// no "@". Ranges are sorted by start and never overlap.
-export type RelayMentionRange = {
-  start: number;
-  length: number;
-  participant_id: string;
-};
-
-export type RelayTextStyle = "bold" | "italic" | "underline" | "strikethrough" | "monospace" | "spoiler";
-
-// One formatting run over a text part, offsets in UTF-16 code units like
-// mentions. An EMPTY styles array on the part is meaningful: it marks
-// structured plain text as opposed to a legacy Markdown body.
-export type RelayStyleRange = {
-  start: number;
-  length: number;
-  styles: RelayTextStyle[];
-};
-
-export type RelayTextPart = {
-  part_index?: number;
-  type: "text";
-  text: string;
-  mentions?: RelayMentionRange[];
-  styles?: RelayStyleRange[];
-};
-
-export type RelayMediaPart = {
-  part_index?: number;
-  type: "media";
-  url: string;
-  attachment_id?: string;
-  // Pixel dimensions (always paired) and a blurhash placeholder (base83)
-  // to draw before the bytes download.
-  width?: number;
-  height?: number;
-  blur_hash?: string;
-};
-
-export type RelayVoiceMemoPart = {
-  part_index?: number;
-  type: "voice_memo";
-  url: string;
-  attachment_id?: string;
-  duration_ms?: number;
-};
-
-export type RelayLinkPreviewPart = {
-  part_index?: number;
-  type: "link_preview";
-  url: string;
-};
-
-export type RelayDataPart = {
-  part_index?: number;
-  type: "data";
-  data: unknown;
-};
-
-export type RelayPart =
-  | RelayTextPart
-  | RelayMediaPart
-  | RelayVoiceMemoPart
-  | RelayLinkPreviewPart
-  | RelayDataPart;
-
-export type RelayReplyRef = {
-  message_id?: string;
-} | null;
-
-export type RelayMessage = {
-  id: string;
-  conversation_id: string;
-  sequence: number;
-  sender: RelaySender;
-  parts: RelayPart[];
-  reply_to?: RelayReplyRef;
-  fallback_text: string;
-  status: string;
-  created_at: string;
-};
-
-export type RelayEventType =
-  | "message.received"
-  | "reaction.added"
-  | "reaction.removed"
-  | "message.delivered"
-  | "message.read"
-  | (string & {});
-
-export type RelayEvent = {
-  event_id: string;
-  event_type: RelayEventType;
-  agent_id: string;
-  created_at: string;
-  data: {
-    message?: RelayMessage;
-    /**
-     * Present only when this event belongs to a group invocation: a human
-     * mentioned the agent, replied to it, or picked it. In a group the server
-     * delivers nothing to an agent that was not invoked, and every call the
-     * agent then makes about the message must carry this id back
-     * (`/typing`, `/responding`, and the reply itself all refuse without it).
-     * A direct message never carries one — the server rejects
-     * `invoked_agent_ids` outside a group — so its presence is also how the
-     * plugin knows it is in a group.
-     */
-    invocation_id?: string;
-    [key: string]: unknown;
-  };
-};
-
-export type RelayAgentProfile = {
-  id: string;
-  owner_user_id?: string;
-  handle: string;
-  display_name: string;
-  tagline?: string;
-  avatar_url?: string | null;
-  visibility?: "private" | "unlisted" | "public";
-  created_at?: string;
-};
-
-export type RelayEventsPage = {
-  events: RelayEvent[];
-  nextCursor: number;
-};
-
-// The 202 from POST /v1/messages. The server splits the accepted parts at
-// ingest: each visible non-media part becomes its own message, contiguous
-// media parts stay one media message, and a voice memo always commits alone,
-// so one send commits one or more messages, in display order.
-export type RelaySendResult = {
-  messages: RelayMessage[];
-};
-
-// ---------------------------------------------------------------------------
-// Plugin config (channels.relay) and resolved account.
-// ---------------------------------------------------------------------------
+import type {
+  Chat,
+  ChatHandle,
+  MessageWebhookData,
+  Message,
+  RelayWebhookEnvelope,
+  RelayWebhookEvent,
+} from "@relaymessenger/sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
 
 export type RelayAccountConfig = {
   name?: string;
@@ -157,31 +14,63 @@ export type RelayAccountConfig = {
   token?: string;
   tokenFile?: string;
   baseUrl?: string;
-  allowFrom?: Array<string | number>;
-  pollTimeoutSeconds?: number;
+  allowFrom?: string[];
 };
 
 export type RelayChannelConfig = RelayAccountConfig & {
-  accounts?: Record<string, Partial<RelayAccountConfig>>;
   defaultAccount?: string;
+  accounts?: Record<string, RelayAccountConfig>;
 };
 
-export type RelayCoreConfig = {
-  channels?: {
+export type RelayCoreConfig = OpenClawConfig & {
+  channels?: OpenClawConfig["channels"] & {
     relay?: RelayChannelConfig;
   };
-  session?: {
-    store?: string;
-  };
 };
 
 export type ResolvedRelayAccount = {
   accountId: string;
+  name?: string;
   enabled: boolean;
   configured: boolean;
-  name?: string;
   token: string;
   baseUrl: string;
-  pollTimeoutSeconds: number;
+  allowFrom: string[];
   config: RelayAccountConfig;
 };
+
+export type RelayIngressPayload = {
+  version: 1;
+  rawEvent: string;
+};
+
+export type RelaySnapshot = {
+  version: 1;
+  throughSequence: string;
+  reason: "checkpoint_outside_retention";
+  completedAt: string;
+  chats: Array<{
+    chat: Chat;
+    messages: Message[];
+  }>;
+};
+
+export type RelayMessageReceivedEvent = RelayWebhookEnvelope<
+  MessageWebhookData,
+  "message.received"
+>;
+
+export type RelayInboundFacts = {
+  eventId: string;
+  messageId: string;
+  chatId: string;
+  chatType: "direct" | "group";
+  contactId: string;
+  handle: string;
+  displayName: string;
+  text: string;
+  mentionHandles: string[];
+  ownerHandle?: ChatHandle;
+  replyToId?: string;
+  timestamp?: number;
+};

package/dist/src/account-lock.js

@@ -1,91 +0,0 @@
-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/client.js

@@ -1,13 +0,0 @@
-// The Relay API client the plugin uses. There is no implementation here: this
-// is `@relaymessenger/sdk`'s client, vendored under `./vendor/relay-sdk`
-// (see that directory's README for why, and for the one-file swap when the
-// package ships).
-//
-// The plugin used to hand-roll its own client beside the SDK's. They drifted,
-// and the drift was a defect: the hand-rolled one had no `invocationId` on
-// `sendMessage`, `setTyping`, or `setResponding`, so an agent's first group
-// mention wedged its entire event stream (REL-167).
-import { createRelayClient as createVendoredRelayClient } from "./vendor/relay-sdk/client.js";
-export { DEFAULT_RELAY_BASE_URL, normalizeRelayBaseUrl } from "./vendor/relay-sdk/url.js";
-export { classifyRelayHttpStatus, isAbortError, isRelayWebhookConflict, RelayApiError, } from "./vendor/relay-sdk/errors.js";
-export const createRelayClient = createVendoredRelayClient;

package/dist/src/cursor-store.js

@@ -1,136 +0,0 @@
-// 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

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