@relaymessenger/openclaw-plugin 0.2.0

package/src/inbound-dedupe.ts

@@ -0,0 +1,241 @@
+// 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;
+
+type MaybePromise<T> = T | Promise<T>;
+
+/** Minimal claim/commit/release slice of the SDK's ClaimableDedupe. */
+export type RelayClaimableGuard = {
+  claim: (key: string, opts: { namespace: string }) => Promise<{ kind: string }>;
+  commit: (key: string, opts: { namespace: string }) => Promise<unknown>;
+  release: (key: string, opts: { namespace: string }) => void;
+};
+
+export type RelayAttemptStateStore = {
+  lookup(key: string): MaybePromise<{ attemptedAt: number } | undefined>;
+  register(
+    key: string,
+    value: { attemptedAt: number },
+    opts?: { ttlMs?: number },
+  ): MaybePromise<void>;
+};
+
+export type RelayInboundDeduper = {
+  /** True when the caller now owns the event; false for committed or in-flight duplicates. */
+  claimEvent: (eventId: string) => Promise<boolean>;
+  /** Records an attempted event at the agent-dispatch boundary so restart cannot run it again. */
+  commitEvent: (eventId: string) => Promise<void>;
+  /** Drops an uncommitted claim so a failed dispatch can retry the event. */
+  releaseEvent: (eventId: string) => void;
+};
+
+export function buildRelayInboundDedupeKey(params: {
+  baseUrl: string;
+  agentId: string;
+  eventId: string;
+}): string | null {
+  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: {
+  guard: RelayClaimableGuard;
+  baseUrl: string;
+  agentId: string;
+}): RelayInboundDeduper {
+  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: string, namespace: string): string {
+  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?: {
+  env?: NodeJS.ProcessEnv;
+  onDiskError?: (error: unknown) => void;
+  store?: RelayAttemptStateStore;
+  maxEntries?: number;
+  ttlMs?: number;
+  now?: () => number;
+}): RelayClaimableGuard {
+  type PersistedAttempt = { attemptedAt: number; expiresAt: number };
+  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 = (): number => {
+    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: string, value: unknown): value is PersistedAttempt => {
+    if (!/^[a-f0-9]{64}$/u.test(key) || !value || typeof value !== "object") return false;
+    const entry = value as Partial<PersistedAttempt>;
+    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<PersistedAttempt>({
+        fileName: "inbound-attempts.json",
+        ...(params?.env ? { env: params.env } : {}),
+      });
+  const store =
+    params?.store ??
+    {
+      lookup: async (key: string) => {
+        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: string,
+        value: { attemptedAt: number },
+        opts?: { ttlMs?: number },
+      ) => {
+        await state!.updateOr(emptyRelayStateDocument<PersistedAttempt>(), (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),
+          };
+        });
+      },
+    } satisfies RelayAttemptStateStore;
+  const inflight = new Set<string>();
+  const claiming = new Set<string>();
+
+  const withDiskError = async <T>(operation: () => MaybePromise<T>): Promise<T> => {
+    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/src/inbound.ts

@@ -0,0 +1,128 @@
+// 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";
+
+/** 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";
+  }
+}
+
+/**
+ * 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");
+}
+
+/** 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;
+}
+
+/** 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;
+};
+
+/**
+ * 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: RelayEvent,
+  params: { agentId: string },
+): 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);
+  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/src/lifecycle.ts

@@ -0,0 +1,42 @@
+export type RelayAccountLifecycleLease = {
+  signal: AbortSignal;
+  release: () => void;
+};
+
+/** Owns exactly one abortable long-poll lifecycle per configured account. */
+export function createRelayAccountLifecycleRegistry() {
+  const controllers = new Map<string, AbortController>();
+
+  return {
+    acquire(accountId: string, parentSignal: AbortSignal): RelayAccountLifecycleLease {
+      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: string): boolean {
+      const controller = controllers.get(accountId);
+      if (!controller) {
+        return false;
+      }
+      controller.abort();
+      return true;
+    },
+  };
+}

package/src/outbound.ts

@@ -0,0 +1,136 @@
+// 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 } from "./client.js";
+import type { RelayMessage } 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;
+
+const IDEMPOTENCY_KEY_MAX = 255;
+
+/**
+ * Idempotency key for one logical send. When core supplies a durable delivery
+ * queue id, the key is a stable function of (queueId, partIndex) 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.
+ */
+export function deriveRelayIdempotencyKey(params: {
+  deliveryQueueId?: string;
+  deliveryPartIndex?: number;
+  random?: () => string;
+}): string {
+  const queueId = params.deliveryQueueId?.trim();
+  const key = queueId
+    ? `relay-send:${queueId}:${params.deliveryPartIndex ?? 0}`
+    : `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")}`;
+}
+
+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: RelayMessage[];
+};
+
+export async function sendRelayText(params: {
+  client: RelayClient;
+  conversationId: string;
+  text: string;
+  replyToId?: string | null;
+  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 } } : {}),
+        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;
+}
+
+export type RelayUnknownSendVerdict =
+  | { status: "sent"; messageId: string; messages: RelayMessage[] }
+  | { 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;
+  idempotencyKey: string;
+}): Promise<RelayUnknownSendVerdict> {
+  try {
+    const result = await sendRelayText({
+      client: params.client,
+      conversationId: params.conversationId,
+      text: params.text,
+      replyToId: params.replyToId ?? null,
+      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 };
+  }
+}