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

package/dist/src/dispatch.js

@@ -0,0 +1,257 @@
+import { buildChannelInboundEventContext, resolveChannelInboundRouteEnvelope, } from "openclaw/plugin-sdk/channel-inbound";
+import { resolveStableChannelMessageIngress } from "openclaw/plugin-sdk/channel-ingress-runtime";
+import { bindIngressLifecycleToReplyOptions } from "openclaw/plugin-sdk/channel-outbound";
+import { buildRelayInboundFacts } from "./inbound.js";
+function isReplyToAgentMessage(message, chatId) {
+    return message.chat_id === chatId && message.is_from_me === true;
+}
+/**
+ * Relay's structured mention and reply facts are authoritative. In
+ * particular, this does not infer an activation from visible `@handle` text.
+ */
+export async function resolveRelayTurnActivation(params) {
+    if (params.facts.chatType === "direct") {
+        return {
+            kind: "direct",
+            wasMentioned: false,
+            implicitMentionKinds: [],
+        };
+    }
+    const ownerHandle = params.facts.ownerHandle;
+    if (ownerHandle?.kind === "agent" &&
+        params.facts.mentionHandles.includes(ownerHandle.handle)) {
+        return {
+            kind: "mention",
+            wasMentioned: true,
+            implicitMentionKinds: [],
+        };
+    }
+    if (!params.facts.replyToId)
+        return null;
+    const replyTarget = await params.relay.messages.retrieve(params.facts.replyToId);
+    if (!isReplyToAgentMessage(replyTarget, params.facts.chatId))
+        return null;
+    return {
+        kind: "reply",
+        wasMentioned: false,
+        implicitMentionKinds: ["reply_to_bot"],
+    };
+}
+export async function dispatchRelayEvent(params) {
+    const facts = buildRelayInboundFacts(params.event);
+    if (!facts) {
+        params.warn?.(`relay: durably accepted ${params.event.event_type} event ${params.event.event_id} without an agent turn`);
+        return;
+    }
+    const activation = await resolveRelayTurnActivation({
+        facts,
+        relay: params.relay,
+    });
+    if (!activation) {
+        params.warn?.(`relay: durably accepted unmentioned group Message ${facts.messageId} without an agent turn`);
+        return;
+    }
+    const { route, buildEnvelope } = resolveChannelInboundRouteEnvelope({
+        cfg: params.cfg,
+        channel: "relay",
+        accountId: params.account.accountId,
+        peer: {
+            kind: facts.chatType,
+            id: facts.chatId,
+        },
+    });
+    const restricted = params.account.allowFrom.length > 0;
+    const effectiveAllowFrom = restricted
+        ? params.account.allowFrom
+        : ["*"];
+    const access = await resolveStableChannelMessageIngress({
+        channelId: "relay",
+        accountId: params.account.accountId,
+        identity: {
+            key: "contactId",
+            kind: "stable-id",
+            entryIdPrefix: "relay-contact",
+            aliases: [
+                {
+                    key: "handle",
+                    kind: "username",
+                    normalize: (value) => value.trim().replace(/^@/u, "").toLowerCase(),
+                    dangerous: true,
+                },
+            ],
+        },
+        subject: {
+            stableId: facts.contactId,
+            aliases: { handle: facts.handle },
+        },
+        conversation: {
+            kind: facts.chatType,
+            id: facts.chatId,
+            title: facts.chatType === "direct" ? facts.displayName : facts.chatId,
+        },
+        contextBinding: {
+            agentId: route.agentId,
+            sessionKey: route.sessionKey,
+            messageId: facts.messageId,
+            nativeChannelId: facts.chatId,
+            inboundEventKind: "user_request",
+        },
+        dmPolicy: restricted ? "allowlist" : "open",
+        groupPolicy: restricted ? "allowlist" : "open",
+        policy: {
+            groupAllowFromFallbackToAllowFrom: true,
+            ...(facts.chatType === "group"
+                ? {
+                    activation: {
+                        requireMention: true,
+                        allowTextCommands: false,
+                        implicitMentions: {
+                            replyToBot: true,
+                            quotedBot: false,
+                            threadParticipation: false,
+                        },
+                        allowedImplicitMentionKinds: ["reply_to_bot"],
+                    },
+                }
+                : {}),
+        },
+        ...(facts.chatType === "group"
+            ? {
+                mentionFacts: {
+                    canDetectMention: true,
+                    wasMentioned: activation.wasMentioned,
+                    hasAnyMention: facts.mentionHandles.length > 0,
+                    implicitMentionKinds: activation.implicitMentionKinds,
+                },
+            }
+            : {}),
+        allowFrom: effectiveAllowFrom,
+        groupAllowFrom: effectiveAllowFrom,
+    });
+    if (access.ingress.admission !== "dispatch") {
+        params.warn?.(`relay: Contact @${facts.handle} did not pass OpenClaw ingress (${access.ingress.decision}:${access.ingress.reasonCode})`);
+        return;
+    }
+    const body = buildEnvelope({
+        channel: "Relay",
+        from: `${facts.displayName} (@${facts.handle})`,
+        ...(facts.timestamp ? { timestamp: facts.timestamp } : {}),
+        body: facts.text,
+    });
+    const ctxPayload = buildChannelInboundEventContext({
+        channel: "relay",
+        accountId: route.accountId ?? params.account.accountId,
+        messageId: facts.messageId,
+        messageIdFull: facts.messageId,
+        ...(facts.timestamp ? { timestamp: facts.timestamp } : {}),
+        from: facts.chatId,
+        sender: {
+            id: facts.contactId,
+            name: facts.displayName,
+            username: facts.handle,
+        },
+        conversation: {
+            kind: facts.chatType,
+            id: facts.chatId,
+            label: facts.chatType === "group" ? facts.chatId : facts.displayName,
+            nativeChannelId: facts.chatId,
+        },
+        route: {
+            agentId: route.agentId,
+            accountId: route.accountId,
+            routeSessionKey: route.sessionKey,
+            dispatchSessionKey: route.sessionKey,
+            ...(route.dmScope ? { dmScope: route.dmScope } : {}),
+        },
+        reply: {
+            to: facts.chatId,
+            originatingTo: facts.chatId,
+            ...(facts.replyToId ? { replyToId: facts.replyToId } : {}),
+        },
+        message: {
+            inboundEventKind: "user_request",
+            body,
+            bodyForAgent: facts.text,
+            rawBody: facts.text,
+            commandBody: facts.text,
+        },
+        channelIngress: access,
+        access: {
+            commands: {
+                authorized: access.senderAccess.allowed,
+            },
+            mentions: {
+                canDetectMention: facts.chatType === "group",
+                wasMentioned: activation.wasMentioned,
+                hasAnyMention: facts.mentionHandles.length > 0,
+                explicitlyMentionedBot: activation.kind === "mention",
+                implicitMentionKinds: activation.implicitMentionKinds,
+                requireMention: facts.chatType === "group",
+                effectiveWasMentioned: facts.chatType === "group",
+            },
+        },
+    });
+    await Promise.allSettled([
+        params.relay.chats.markAsRead(facts.chatId),
+        params.relay.chats.startTyping(facts.chatId),
+    ]).then((results) => {
+        for (const result of results) {
+            if (result.status === "rejected") {
+                params.warn?.(`relay: pre-dispatch Chat state failed: ${String(result.reason)}`);
+            }
+        }
+    });
+    let deliveryError;
+    try {
+        await params.runtime.channel.inbound.dispatch({
+            cfg: params.cfg,
+            channel: "relay",
+            accountId: params.account.accountId,
+            route: {
+                agentId: route.agentId,
+                sessionKey: route.sessionKey,
+                ...(route.dmScope ? { dmScope: route.dmScope } : {}),
+            },
+            ctxPayload,
+            delivery: {
+                durable: {
+                    to: facts.chatId,
+                    replyToId: null,
+                    requiredCapabilities: { reconcileUnknownSend: true },
+                },
+                deliver: async (_payload, info) => {
+                    if (info.kind === "final") {
+                        throw new Error("relay: durable final Message delivery was unavailable");
+                    }
+                    return { visibleReplySent: false };
+                },
+                onError: (error) => {
+                    deliveryError ??= error;
+                },
+            },
+            replyPipeline: {},
+            replyOptions: {
+                ...bindIngressLifecycleToReplyOptions(params.lifecycle),
+                disableBlockStreaming: true,
+            },
+            record: {
+                onRecordError: (error) => {
+                    throw error instanceof Error
+                        ? error
+                        : new Error(`relay: session record failed: ${String(error)}`);
+                },
+            },
+        });
+        if (deliveryError) {
+            throw deliveryError instanceof Error
+                ? deliveryError
+                : new Error(`relay: reply delivery failed: ${String(deliveryError)}`);
+        }
+    }
+    finally {
+        await params.relay.chats.stopTyping(facts.chatId).catch((error) => {
+            params.warn?.(`relay: stop typing failed: ${String(error)}`);
+        });
+    }
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/src/full-sync.js

@@ -0,0 +1,24 @@
+export async function readCompleteRelaySnapshot(params) {
+    const chats = [];
+    const firstChatPage = await params.relay.chats.listChats({ limit: 100 });
+    for await (const chat of firstChatPage) {
+        const messages = [];
+        const firstMessagePage = await params.relay.chats.messages.list(chat.id, { limit: 100 });
+        for await (const message of firstMessagePage) {
+            messages.push(message);
+        }
+        chats.push({ chat, messages });
+    }
+    return {
+        version: 1,
+        throughSequence: params.context.throughSequence,
+        reason: params.context.reason,
+        completedAt: new Date().toISOString(),
+        chats,
+    };
+}
+export async function commitRelayFullSync(params) {
+    const snapshot = await readCompleteRelaySnapshot(params);
+    await params.state.replaceSnapshot(snapshot);
+}
+//# sourceMappingURL=full-sync.js.map

package/dist/src/gateway.js

@@ -0,0 +1,171 @@
+import { RelayWebhookConfiguredError, } from "@relaymessenger/sdk";
+import { createHash } from "node:crypto";
+import { dispatchRelayEvent } from "./dispatch.js";
+import { commitRelayFullSync } from "./full-sync.js";
+import { createRelayIngressMonitor } from "./ingress.js";
+import { createRelaySdkClient } from "./outbound.js";
+import { getRelayRuntime } from "./runtime.js";
+import { openRelayStateStore, } from "./state.js";
+const runningCredentials = new Map();
+const accountControllers = new Map();
+function credentialKey(account) {
+    return createHash("sha256")
+        .update(`${account.baseUrl}\0${account.token}`)
+        .digest("hex");
+}
+function openIngressQueue(params) {
+    try {
+        return getRelayRuntime().state.openChannelIngressQueue({
+            accountId: params.transportId,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!message.includes("only available for trusted plugins"))
+            throw error;
+        params.warn("relay: OpenClaw trusted ingress state is unavailable for this install; using the plugin's private SQLite queue");
+        return params.state.ingressQueue;
+    }
+}
+export async function assertRelayWebSocketAvailable(params) {
+    const { subscriptions } = await params.relay.webhookSubscriptions.list(params.signal ? { signal: params.signal } : undefined);
+    if (subscriptions.length > 0) {
+        throw new RelayWebhookConfiguredError(`relay: account "${params.accountId}" has saved Webhook subscriptions; delete them before using OpenClaw WebSocket delivery`);
+    }
+}
+export async function startRelayAccount(ctx) {
+    const account = ctx.account;
+    if (!account.configured) {
+        throw new Error(`relay: account "${account.accountId}" is missing a Relay Agent Token`);
+    }
+    const runtime = getRelayRuntime();
+    const controller = new AbortController();
+    const abortSignal = AbortSignal.any([ctx.abortSignal, controller.signal]);
+    const key = credentialKey(account);
+    const transportId = `transport-${key}`;
+    const existing = runningCredentials.get(key);
+    if (existing) {
+        throw new Error(`relay: account "${account.accountId}" reuses the Agent Token already active in account "${existing}"`);
+    }
+    runningCredentials.set(key, account.accountId);
+    accountControllers.set(account.accountId, controller);
+    const warn = (message) => ctx.log?.warn?.(message);
+    const state = openRelayStateStore({
+        stateDir: runtime.state.resolveStateDir(),
+        // Bind pending events and FULL-sync state to the authenticated transport,
+        // not a mutable OpenClaw account label. Token rotation cannot dispatch old
+        // rows through a different Relay Contact, and account renames keep state.
+        accountId: transportId,
+    });
+    const relay = createRelaySdkClient(account);
+    const ingress = createRelayIngressMonitor({
+        queue: openIngressQueue({
+            transportId,
+            state,
+            warn,
+        }),
+        abortSignal,
+        onError: (error) => ctx.log?.error?.(`relay: ingress drain failed: ${String(error)}`),
+        dispatch: async (event, lifecycle) => {
+            ctx.setStatus({
+                accountId: account.accountId,
+                running: true,
+                connected: true,
+                lastInboundAt: Date.now(),
+            });
+            await dispatchRelayEvent({
+                event,
+                lifecycle,
+                account,
+                cfg: ctx.cfg,
+                relay,
+                runtime,
+                warn,
+            });
+        },
+    });
+    ctx.setStatus({
+        accountId: account.accountId,
+        running: true,
+        connected: false,
+        lifecycle: "starting",
+        configured: true,
+        enabled: account.enabled,
+    });
+    try {
+        await assertRelayWebSocketAvailable({
+            relay,
+            accountId: account.accountId,
+            signal: abortSignal,
+        });
+        ingress.start();
+        ctx.setStatus({
+            accountId: account.accountId,
+            running: true,
+            connected: true,
+            lifecycle: "ready",
+            lastError: null,
+        });
+        await relay.websocket.run({
+            signal: abortSignal,
+            onEvent: async (event) => {
+                const admission = await ingress.receive(event);
+                if (admission.kind === "invalid") {
+                    throw new Error(admission.message);
+                }
+            },
+            onFullSync: async (context) => {
+                await commitRelayFullSync({ relay, state, context });
+            },
+            onError: (error) => {
+                ctx.log?.warn?.(`relay: WebSocket reconnecting after ${String(error)}`);
+                ctx.setStatus({
+                    accountId: account.accountId,
+                    running: true,
+                    connected: false,
+                    lifecycle: "recovering",
+                    lastError: error instanceof Error ? error.message : String(error),
+                });
+            },
+        });
+    }
+    catch (error) {
+        if (abortSignal.aborted)
+            return;
+        if (error instanceof RelayWebhookConfiguredError) {
+            ctx.setStatus({
+                accountId: account.accountId,
+                running: false,
+                connected: false,
+                terminalDisconnect: true,
+                lastError: error.message,
+            });
+        }
+        throw error;
+    }
+    finally {
+        await ingress.stop();
+        if (runningCredentials.get(key) === account.accountId) {
+            runningCredentials.delete(key);
+        }
+        if (accountControllers.get(account.accountId) === controller) {
+            accountControllers.delete(account.accountId);
+        }
+        ctx.setStatus({
+            accountId: account.accountId,
+            running: false,
+            connected: false,
+            lifecycle: "stopped",
+        });
+    }
+}
+export async function stopRelayAccount(ctx) {
+    accountControllers.get(ctx.accountId)?.abort(new Error(`relay: account "${ctx.accountId}" stopped`));
+    ctx.setStatus({
+        accountId: ctx.accountId,
+        running: false,
+        connected: false,
+        lifecycle: "stopped",
+    });
+}
+//# sourceMappingURL=gateway.js.map

package/dist/src/inbound.js

@@ -1,99 +1,68 @@
-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";
+function renderPart(part) {
+    switch (part.type) {
+        case "text":
+            return part.value;
+        case "link":
+            return part.value;
+        case "media":
+            return `[Attachment: ${part.filename} (${part.mime_type})] ${part.url}`;
+        case "system":
+            return part.value;
     }
 }
-/**
- * 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");
+export function renderRelayMessageParts(parts) {
+    return parts
+        .map(renderPart)
+        .filter((value) => Boolean(value?.trim()))
+        .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;
+export function isRelayMessageReceivedEvent(event) {
+    if (event.event_type !== "message.received")
+        return false;
+    const data = event.data;
+    return (typeof data.id === "string" &&
+        typeof data.chat?.id === "string" &&
+        data.direction === "inbound" &&
+        typeof data.sender_handle?.id === "string" &&
+        Array.isArray(data.parts));
 }
 /**
- * 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.
+ * Map the current Relay v1 Message event to OpenClaw facts. Agent-authored
+ * Messages are accepted at the transport boundary but do not start turns.
  */
-export function buildRelayInboundFacts(event, params) {
-    if (classifyRelayEvent(event) !== "message") {
-        return null;
-    }
-    const message = event.data.message;
-    if (!message || !message.id || !message.conversation_id) {
+export function buildRelayInboundFacts(event) {
+    if (!isRelayMessageReceivedEvent(event))
         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)) {
+    if (event.data.sender_handle.kind !== "user")
         return null;
-    }
-    const text = renderRelayPartsText(message.parts) || message.fallback_text || "";
-    if (!text.trim()) {
+    const text = renderRelayMessageParts(event.data.parts);
+    if (!text.trim())
         return null;
-    }
-    const createdAtMs = Date.parse(message.created_at);
-    const invocationId = typeof event.data.invocation_id === "string"
-        && event.data.invocation_id.trim()
-        ? event.data.invocation_id
-        : undefined;
+    const mentionHandles = event.data.parts.flatMap((part) => part.type === "text" &&
+        typeof part.mention === "string" &&
+        part.mention.length > 0
+        ? [part.mention]
+        : []);
+    const timestampValue = event.data.sent_at ?? event.created_at;
+    const timestamp = Date.parse(timestampValue);
     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 } : {}),
+        messageId: event.data.id,
+        chatId: event.data.chat.id,
+        chatType: event.data.chat.is_group === true ? "group" : "direct",
+        contactId: event.data.sender_handle.id,
+        handle: event.data.sender_handle.handle,
+        displayName: event.data.sender_handle.display_name?.trim() ||
+            event.data.sender_handle.handle,
         text,
-        ...(Number.isFinite(createdAtMs) ? { timestamp: createdAtMs } : {}),
-        ...(invocationId ? { invocationId } : {}),
+        mentionHandles,
+        ...(event.data.chat.owner_handle
+            ? { ownerHandle: event.data.chat.owner_handle }
+            : {}),
+        ...(event.data.reply_to?.message_id
+            ? { replyToId: event.data.reply_to.message_id }
+            : {}),
+        ...(Number.isFinite(timestamp) ? { timestamp } : {}),
     };
 }
+//# sourceMappingURL=inbound.js.map

package/dist/src/ingress.js

@@ -0,0 +1,64 @@
+import { createStandardRawEventIngressMonitor } from "openclaw/plugin-sdk/channel-ingress-runtime";
+import { createChannelIngressError, } from "openclaw/plugin-sdk/channel-outbound";
+const RelayIngressPermanentError = createChannelIngressError("RelayIngressPermanentError", { withReason: true });
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function inspectRelayEvent(event) {
+    if (!isRecord(event)) {
+        throw new RelayIngressPermanentError("invalid-event", "Relay WebSocket event must be an object.");
+    }
+    const eventId = typeof event.event_id === "string" ? event.event_id.trim() : "";
+    const eventType = typeof event.event_type === "string" ? event.event_type.trim() : "";
+    if (!eventId || !eventType) {
+        throw new RelayIngressPermanentError("invalid-event", "Relay WebSocket event is missing event_id or event_type.");
+    }
+    const data = isRecord(event.data) ? event.data : undefined;
+    const chat = data && isRecord(data.chat) ? data.chat : undefined;
+    const chatId = typeof chat?.id === "string"
+        ? chat.id.trim()
+        : typeof data?.chat_id === "string"
+            ? data.chat_id.trim()
+            : "";
+    return {
+        eventId,
+        laneKey: chatId ? `chat:${chatId}` : `event:${eventType}`,
+    };
+}
+function decodeRelayEvent(rawEvent, claimedId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawEvent);
+    }
+    catch (error) {
+        throw new RelayIngressPermanentError("invalid-event", `Relay ingress row ${claimedId} contains invalid JSON.`, { cause: error });
+    }
+    inspectRelayEvent(parsed);
+    return parsed;
+}
+export function createRelayIngressMonitor(options) {
+    return createStandardRawEventIngressMonitor({
+        queue: options.queue,
+        inspect: inspectRelayEvent,
+        payload: {
+            serialize: (event) => JSON.stringify(event),
+            deserialize: (rawEvent, { claim }) => decodeRelayEvent(rawEvent, claim.id),
+            createClaimError: (kind, claim) => new RelayIngressPermanentError("invalid-event", kind === "invalid-version"
+                ? `Relay ingress row ${claim.id} has an invalid payload version.`
+                : `Relay ingress row ${claim.id} changed identity after admission.`),
+        },
+        deliver: async (event, lifecycle) => {
+            await options.dispatch(event, lifecycle);
+        },
+        ...(options.pollIntervalMs === undefined
+            ? {}
+            : { pollIntervalMs: options.pollIntervalMs }),
+        ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+        createStoppedError: () => new Error("Relay ingress monitor is stopped."),
+        onError: (error) => options.onError?.(error),
+        classifyAdmissionError: (error) => error instanceof RelayIngressPermanentError
+            ? error.message
+            : undefined,
+    });
+}
+//# sourceMappingURL=ingress.js.map