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

package/src/dispatch.ts

@@ -0,0 +1,324 @@
+import type {
+  Message,
+  Relay,
+  RelayWebhookEvent,
+} from "@relaymessenger/sdk";
+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 type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import { buildRelayInboundFacts } from "./inbound.js";
+import type { RelayIngressLifecycle } from "./ingress.js";
+import type { PluginRuntime } from "./runtime.js";
+import type {
+  RelayCoreConfig,
+  RelayInboundFacts,
+  ResolvedRelayAccount,
+} from "./types.js";
+
+export type RelayTurnActivation =
+  | {
+      kind: "direct";
+      wasMentioned: false;
+      implicitMentionKinds: [];
+    }
+  | {
+      kind: "mention";
+      wasMentioned: true;
+      implicitMentionKinds: [];
+    }
+  | {
+      kind: "reply";
+      wasMentioned: false;
+      implicitMentionKinds: ["reply_to_bot"];
+    };
+
+type RelayReplyLookup = Pick<Relay, "messages">;
+
+function isReplyToAgentMessage(
+  message: Message,
+  chatId: string,
+): boolean {
+  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: {
+  facts: RelayInboundFacts;
+  relay: RelayReplyLookup;
+}): Promise<RelayTurnActivation | null> {
+  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: {
+  event: RelayWebhookEvent;
+  lifecycle: RelayIngressLifecycle;
+  account: ResolvedRelayAccount;
+  cfg: RelayCoreConfig;
+  relay: Pick<Relay, "chats" | "messages">;
+  runtime: PluginRuntime;
+  warn?: (message: string) => void;
+}): Promise<void> {
+  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 as OpenClawConfig,
+    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: unknown;
+  try {
+    await params.runtime.channel.inbound.dispatch({
+      cfg: params.cfg as OpenClawConfig,
+      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: unknown) => {
+      params.warn?.(`relay: stop typing failed: ${String(error)}`);
+    });
+  }
+}

package/src/full-sync.ts

@@ -0,0 +1,47 @@
+import type {
+  Chat,
+  Message,
+  Relay,
+  WebSocketFullSyncContext,
+} from "@relaymessenger/sdk";
+import type {
+  RelaySnapshot,
+} from "./types.js";
+import type { RelayStateStore } from "./state.js";
+
+type RelaySnapshotClient = Pick<Relay, "chats">;
+
+export async function readCompleteRelaySnapshot(params: {
+  relay: RelaySnapshotClient;
+  context: WebSocketFullSyncContext;
+}): Promise<RelaySnapshot> {
+  const chats: Array<{ chat: Chat; messages: Message[] }> = [];
+  const firstChatPage = await params.relay.chats.listChats({ limit: 100 });
+  for await (const chat of firstChatPage) {
+    const messages: Message[] = [];
+    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: {
+  relay: RelaySnapshotClient;
+  state: RelayStateStore;
+  context: WebSocketFullSyncContext;
+}): Promise<void> {
+  const snapshot = await readCompleteRelaySnapshot(params);
+  await params.state.replaceSnapshot(snapshot);
+}

package/src/gateway.ts

@@ -0,0 +1,216 @@
+import {
+  type Relay,
+  RelayWebhookConfiguredError,
+  type RelayWebhookEvent,
+} from "@relaymessenger/sdk";
+import { createHash } from "node:crypto";
+import type { ChannelGatewayContext } from "openclaw/plugin-sdk/channel-contract";
+import type { ChannelIngressQueue } from "openclaw/plugin-sdk/channel-outbound";
+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,
+  type RelayStateStore,
+} from "./state.js";
+import type {
+  RelayCoreConfig,
+  RelayIngressPayload,
+  ResolvedRelayAccount,
+} from "./types.js";
+
+const runningCredentials = new Map<string, string>();
+const accountControllers = new Map<string, AbortController>();
+
+function credentialKey(account: ResolvedRelayAccount): string {
+  return createHash("sha256")
+    .update(`${account.baseUrl}\0${account.token}`)
+    .digest("hex");
+}
+
+function openIngressQueue(params: {
+  transportId: string;
+  state: RelayStateStore;
+  warn: (message: string) => void;
+}): ChannelIngressQueue<RelayIngressPayload> {
+  try {
+    return getRelayRuntime().state.openChannelIngressQueue<RelayIngressPayload>({
+      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: {
+  relay: Pick<Relay, "webhookSubscriptions">;
+  accountId: string;
+  signal?: AbortSignal;
+}): Promise<void> {
+  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: ChannelGatewayContext<ResolvedRelayAccount>,
+): Promise<void> {
+  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: string) => 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 as RelayCoreConfig,
+        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: RelayWebhookEvent,
+      ) => {
+        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: ChannelGatewayContext<ResolvedRelayAccount>,
+): Promise<void> {
+  accountControllers.get(ctx.accountId)?.abort(
+    new Error(`relay: account "${ctx.accountId}" stopped`),
+  );
+  ctx.setStatus({
+    accountId: ctx.accountId,
+    running: false,
+    connected: false,
+    lifecycle: "stopped",
+  });
+}