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

package/src/inbound.ts

@@ -1,139 +1,88 @@
-// Pure inbound mapping: Relay events -> normalized fact bundles.
-// No SDK imports so the mapping is unit-testable without an OpenClaw runtime;
-// the runtime dispatch wiring lives in channel.ts.
-import type { RelayEvent, RelayMessage, RelayPart } from "./types.js";
+import type {
+  MessagePartResponse,
+  RelayWebhookEvent,
+} from "@relaymessenger/sdk";
+import type {
+  RelayInboundFacts,
+  RelayMessageReceivedEvent,
+} from "./types.js";
 
-/** Coarse classification deciding whether an event can start an agent turn. */
-export type RelayEventClass =
-  | "message" // message.received -> can start an agent turn
-  | "reaction" // reaction.added/removed -> observe-only at v1
-  | "lifecycle" // message.delivered/read -> bookkeeping, never dispatch
-  | "unknown"; // forward-compatible: ignore quietly
-
-export function classifyRelayEvent(event: Pick<RelayEvent, "event_type">): RelayEventClass {
-  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: MessagePartResponse): string | undefined {
+  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: readonly RelayPart[]): string {
-  const lines: string[] = [];
-  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: string;
-        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: readonly MessagePartResponse[],
+): string {
+  return parts
+    .map(renderPart)
+    .filter((value): value is string => Boolean(value?.trim()))
+    .join("\n");
 }
 
-/** Drop the agent's own sends echoed back on the event stream. */
-export function isRelayEchoMessage(
-  message: Pick<RelayMessage, "sender">,
-  agentId: string,
-): boolean {
-  return message.sender.kind === "agent" && message.sender.id === agentId;
+export function isRelayMessageReceivedEvent(
+  event: RelayWebhookEvent,
+): event is RelayMessageReceivedEvent {
+  if (event.event_type !== "message.received") return false;
+  const data = event.data as Partial<RelayMessageReceivedEvent["data"]>;
+  return (
+    typeof data.id === "string" &&
+    typeof data.chat?.id === "string" &&
+    data.direction === "inbound" &&
+    typeof data.sender_handle?.id === "string" &&
+    Array.isArray(data.parts)
+  );
 }
 
-/** Normalized facts for one dispatchable inbound message. */
-export type RelayInboundFacts = {
-  eventId: string;
-  messageId: string;
-  conversationId: string;
-  senderId: string;
-  senderKind: "user" | "agent";
-  replyToId?: string;
-  text: string;
-  timestamp?: number;
-  /**
-   * The group invocation this message belongs to, when it is group work.
-   * Every subsequent server call about this message must carry it back, and
-   * because only a group mints one, its presence is also the group signal.
-   */
-  invocationId?: string;
-};
-
 /**
- * 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: RelayEvent,
-  params: { agentId: string },
+  event: RelayWebhookEvent,
 ): RelayInboundFacts | null {
-  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);
-  const invocationId = typeof event.data.invocation_id === "string"
-    && event.data.invocation_id.trim()
-    ? event.data.invocation_id
-    : undefined;
+  if (!isRelayMessageReceivedEvent(event)) return null;
+  if (event.data.sender_handle.kind !== "user") return null;
+
+  const text = renderRelayMessageParts(event.data.parts);
+  if (!text.trim()) return null;
+
+  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 } : {}),
   };
 }

package/src/ingress.ts

@@ -0,0 +1,123 @@
+import type { RelayWebhookEvent } from "@relaymessenger/sdk";
+import { createStandardRawEventIngressMonitor } from "openclaw/plugin-sdk/channel-ingress-runtime";
+import {
+  createChannelIngressError,
+  type ChannelIngressMonitorLifecycle,
+  type ChannelIngressQueue,
+} from "openclaw/plugin-sdk/channel-outbound";
+import type { RelayIngressPayload } from "./types.js";
+
+export type RelayIngressLifecycle = Omit<
+  ChannelIngressMonitorLifecycle,
+  "admission"
+>;
+
+const RelayIngressPermanentError = createChannelIngressError<"invalid-event">(
+  "RelayIngressPermanentError",
+  { withReason: true },
+);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function inspectRelayEvent(event: RelayWebhookEvent): {
+  eventId: string;
+  laneKey: string;
+} {
+  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: string,
+  claimedId: string,
+): RelayWebhookEvent {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawEvent);
+  } catch (error) {
+    throw new RelayIngressPermanentError(
+      "invalid-event",
+      `Relay ingress row ${claimedId} contains invalid JSON.`,
+      { cause: error },
+    );
+  }
+  inspectRelayEvent(parsed as RelayWebhookEvent);
+  return parsed as RelayWebhookEvent;
+}
+
+export function createRelayIngressMonitor(options: {
+  queue: ChannelIngressQueue<RelayIngressPayload>;
+  dispatch: (
+    event: RelayWebhookEvent,
+    lifecycle: RelayIngressLifecycle,
+  ) => Promise<void>;
+  abortSignal?: AbortSignal;
+  pollIntervalMs?: number;
+  onError?: (error: unknown) => void;
+}) {
+  return createStandardRawEventIngressMonitor<
+    RelayWebhookEvent,
+    unknown,
+    { eventId: string; laneKey: string }
+  >({
+    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,
+  });
+}
+
+export type RelayIngressMonitor = ReturnType<
+  typeof createRelayIngressMonitor
+>;

package/src/outbound.ts

@@ -1,166 +1,87 @@
-// Durable outbound sends: every logical send carries an
-// Idempotency-Key; internal retries and unknown-send reconciliation replay
-// the same key, so a retry can never duplicate a visible message
-// (server contract: commitMessage.ts idempotent replay).
-import { createHash } from "node:crypto";
-import { RelayApiError } from "./client.js";
-import type { RelayClient, RelaySentMessage } from "./client.js";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  Relay,
+  RelayAPIError,
+  type MessageSendResponse,
+} from "@relaymessenger/sdk";
+import type { ResolvedRelayAccount } from "./types.js";
 
-/**
- * Per-part text ceiling declared to core's renderer so long agent replies are
- * split into multiple messages instead of truncated. Server caps a text part at 8 KiB UTF-8
- * (server/src/domain/commitMessage.ts MAX_TEXT_BYTES); 2000 chars is safe for
- * any UTF-8 content (4 bytes/char worst case).
- */
-export const RELAY_TEXT_CHUNK_LIMIT = 2_000;
+export const RELAY_TEXT_CHUNK_LIMIT = 10_000;
+const IDEMPOTENCY_KEY_MAX_LENGTH = 255;
 
-const IDEMPOTENCY_KEY_MAX = 255;
+export function createRelaySdkClient(
+  account: Pick<ResolvedRelayAccount, "baseUrl" | "token">,
+): Relay {
+  return new Relay({
+    apiKey: account.token,
+    baseURL: account.baseUrl,
+  });
+}
 
-/**
- * Idempotency key for one logical send. When core supplies a durable delivery
- * queue id, the key is a stable function of (queueId, part) so internal
- * retries and reconciliation replay the exact same key. Without a queue id a
- * fresh key is minted: identical intentional sends must remain distinct.
- *
- * The part term names WHICH piece of one delivery this is. Core supplies
- * `deliveryPartIndex` from 2026.7.2-beta.5 onward and that is authoritative.
- * Older cores do not: they call `enqueueDelivery` once, mint ONE queue id, and
- * then hand the channel each chunk of a long reply under it. Defaulting the
- * missing index to 0 would key every chunk to `...:0`, so the server would
- * replay the first chunk for each of the rest and the person would receive a
- * long answer truncated to its opening chunk with no error anywhere.
- *
- * So when core cannot say which part this is, the part term is a digest of the
- * part's own text. Sibling chunks differ, so each commits; a retry reproduces
- * the same text, so it replays. This is not the content-in-the-key mistake
- * that defeats conflict detection: the digest stands in FOR the position core
- * did not give us, it does not replace it. Two byte-identical chunks in one
- * delivery do collapse to one message, which is the residual cost of an
- * unindexed core and is bounded to a repeat the reader would see twice.
- */
 export function deriveRelayIdempotencyKey(params: {
-  deliveryQueueId?: string;
-  deliveryPartIndex?: number;
-  /** Part text, used only when core supplies no `deliveryPartIndex`. */
-  partText?: string;
+  deliveryQueueId?: string | undefined;
+  deliveryPartIndex?: number | undefined;
   random?: () => string;
 }): string {
   const queueId = params.deliveryQueueId?.trim();
-  const part = params.deliveryPartIndex ?? (
-    params.partText === undefined
-      ? 0
-      : `t${createHash("sha256").update(params.partText).digest("hex").slice(0, 16)}`
-  );
-  const key = queueId
-    ? `relay-send:${queueId}:${part}`
-    : `relay-send:${(params.random ?? (() => crypto.randomUUID()))()}`;
-  // Server accepts 8-255 chars; the prefix guarantees the minimum.
-  if (key.length <= IDEMPOTENCY_KEY_MAX) {
-    return key;
-  }
-  // Preserve uniqueness when an opaque core queue id is unusually long; a
-  // simple prefix slice could erase the part index and collapse two chunks.
-  return `relay-send:h:${createHash("sha256").update(key).digest("hex")}`;
+  const raw = queueId
+    ? `relay-openclaw:${queueId}:${params.deliveryPartIndex ?? 0}`
+    : `relay-openclaw:${(params.random ?? randomUUID)()}`;
+  return raw.length <= IDEMPOTENCY_KEY_MAX_LENGTH
+    ? raw
+    : `relay-openclaw:sha256:${createHash("sha256").update(raw).digest("hex")}`;
 }
 
-export type RelayOutboundSendResult = {
-  /** Id of the first committed message; core's receipt APIs name one id. */
-  messageId: string;
-  /**
-   * Every message the send committed, in display order. A single text part
-   * commits exactly one, but the 202 is always an array and the receipt
-   * should name everything the server stored.
-   */
-  messages: RelaySentMessage[];
-};
-
 export async function sendRelayText(params: {
-  client: RelayClient;
-  conversationId: string;
+  relay: Pick<Relay, "chats">;
+  chatId: string;
   text: string;
-  replyToId?: string | null;
-  /**
-   * Required when replying into a group: the server refuses an agent's group
-   * message that does not name the invocation it is answering.
-   */
-  invocationId?: string;
+  replyToId?: string | null | undefined;
   idempotencyKey: string;
   signal?: AbortSignal;
-}): Promise<RelayOutboundSendResult> {
-  let lastError: unknown;
-  for (let attempt = 0; attempt < 3; attempt += 1) {
-    try {
-      const result = await params.client.sendMessage({
-        conversationId: params.conversationId,
-        parts: [{ type: "text", text: params.text }],
-        ...(params.replyToId ? { replyTo: { message_id: params.replyToId } } : {}),
-        ...(params.invocationId ? { invocationId: params.invocationId } : {}),
-        idempotencyKey: params.idempotencyKey,
-        ...(params.signal ? { signal: params.signal } : {}),
-      });
-      const first = result.messages[0];
-      if (!first) {
-        throw new RelayApiError("relay: 202 carried no messages", { kind: "retryable" });
-      }
-      return { messageId: first.id, messages: result.messages };
-    } catch (error) {
-      lastError = error;
-      if (!(error instanceof RelayApiError) || !error.retryable || params.signal?.aborted) {
-        throw error;
-      }
-    }
-  }
-  throw lastError;
+  onPlatformSendDispatch?: () => Promise<void>;
+}): Promise<MessageSendResponse> {
+  await params.onPlatformSendDispatch?.();
+  return await params.relay.chats.messages.send(
+    params.chatId,
+    {
+      message: {
+        parts: [{ type: "text", value: params.text }],
+        idempotency_key: params.idempotencyKey,
+        ...(params.replyToId
+          ? { reply_to: { message_id: params.replyToId } }
+          : {}),
+      },
+    },
+    params.signal ? { signal: params.signal } : undefined,
+  );
 }
 
-export type RelayUnknownSendVerdict =
-  | { status: "sent"; messageId: string; messages: RelaySentMessage[] }
-  | { status: "not_sent" }
-  | { status: "unresolved"; error?: string; retryable?: boolean };
-
-/**
- * Reconcile a send whose platform outcome is unknown: replay the POST with the
- * same idempotency key and body. By server contract the replay either performs
- * the send exactly once or returns the originally committed messages — either
- * way the visible outcome is the one set of messages the key names, never a
- * duplicate.
- */
-export async function reconcileRelayUnknownSend(params: {
-  client: RelayClient;
-  conversationId: string;
-  text: string;
-  replyToId?: string | null;
-  invocationId?: string;
-  idempotencyKey: string;
-}): Promise<RelayUnknownSendVerdict> {
-  try {
-    const result = await sendRelayText({
-      client: params.client,
-      conversationId: params.conversationId,
-      text: params.text,
-      replyToId: params.replyToId ?? null,
-      ...(params.invocationId ? { invocationId: params.invocationId } : {}),
-      idempotencyKey: params.idempotencyKey,
-    });
-    return { status: "sent", messageId: result.messageId, messages: result.messages };
-  } catch (error) {
-    if (error instanceof RelayApiError) {
-      if (error.kind === "conflict") {
-        // Key already used with a different request body: the original send
-        // reached the server but we cannot recover its receipt. Do not retry —
-        // a retry with a fresh key would duplicate the visible message.
-        return { status: "unresolved", error: error.message, retryable: false };
-      }
-      if (error.retryable) {
-        return { status: "unresolved", error: error.message, retryable: true };
-      }
-      if (error.kind === "auth") {
-        return { status: "unresolved", error: error.message, retryable: false };
-      }
-      // Deterministic rejection (403/404/422): the original request would have
-      // been rejected identically, so nothing reached the conversation.
-      return { status: "not_sent" };
-    }
-    return { status: "unresolved", error: String(error), retryable: true };
+export function classifyUnknownRelaySend(error: unknown): {
+  status: "not_sent" | "unresolved";
+  error?: string;
+  retryable?: boolean;
+} {
+  if (!(error instanceof RelayAPIError)) {
+    return {
+      status: "unresolved",
+      error: error instanceof Error ? error.message : String(error),
+      retryable: true,
+    };
+  }
+  if (error.retryable) {
+    return {
+      status: "unresolved",
+      error: error.message,
+      retryable: true,
+    };
+  }
+  if (error.status === 409) {
+    return {
+      status: "unresolved",
+      error: error.message,
+      retryable: false,
+    };
   }
+  return { status: "not_sent" };
 }

package/src/runtime.ts

@@ -1,7 +1,7 @@
-// Injected plugin runtime store (qa-channel pattern): defineChannelPluginEntry
-// calls setRelayRuntime, and gateway/inbound code reads it lazily.
-import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
-import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
+import {
+  createPluginRuntimeStore,
+  type PluginRuntime,
+} from "openclaw/plugin-sdk/runtime-store";
 
 const { setRuntime: setRelayRuntime, getRuntime: getRelayRuntime } =
   createPluginRuntimeStore<PluginRuntime>({