@relaymessenger/openclaw-plugin 0.2.0

package/src/poll-loop.ts

@@ -0,0 +1,161 @@
+// startAccount receive engine: abort-aware long poll over GET /v1/events with
+// claim -> durable attempt commit -> dispatch per event and the cursor advanced
+// only after the batch's commits. The supervisor owns restart/backoff: this loop settles
+// (throws) on terminal auth failure and consumer conflicts, and only sleeps
+// in-loop for transient errors.
+import { RelayApiError, isAbortError } from "./client.js";
+import type { RelayClient } from "./client.js";
+import type { RelayCursorStore } from "./cursor-store.js";
+import type { RelayInboundDeduper } from "./inbound-dedupe.js";
+import type { RelayEvent } from "./types.js";
+
+const TRANSIENT_BASE_DELAY_MS = 500;
+const TRANSIENT_MAX_DELAY_MS = 30_000;
+
+export type RelayPollLoopParams = {
+  client: RelayClient;
+  cursorStore: RelayCursorStore;
+  deduper: RelayInboundDeduper;
+  abortSignal: AbortSignal;
+  /**
+   * Perform safe preflight, then call markAttempt exactly before the first
+   * non-replayable agent/tool side effect. Errors before that callback replay;
+   * errors after it are acknowledged because tools may already have run.
+   */
+  handleEvent: (event: RelayEvent, markAttempt: () => Promise<void>) => Promise<void>;
+  /**
+   * Cheap pre-dedupe classification: events returning false (receipts,
+   * reactions, echoes) are acked by the batch cursor without burning a
+   * dedupe claim/commit or a dispatch.
+   */
+  shouldProcess?: (event: RelayEvent) => boolean;
+  timeoutSeconds?: number;
+  limit?: number;
+  onBatch?: (events: readonly RelayEvent[]) => void;
+  log?: (line: string) => void;
+  /** Injectable for tests. */
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+  random?: () => number;
+};
+
+function defaultSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export async function runRelayPollLoop(params: RelayPollLoopParams): Promise<void> {
+  const sleep = params.sleep ?? defaultSleep;
+  const random = params.random ?? Math.random;
+  const log = params.log ?? (() => {});
+  let transientAttempts = 0;
+
+  const transientDelayMs = () => {
+    const backoff = Math.min(
+      TRANSIENT_MAX_DELAY_MS,
+      TRANSIENT_BASE_DELAY_MS * 2 ** Math.min(transientAttempts, 6),
+    );
+    return backoff + Math.floor(random() * 250);
+  };
+
+  while (!params.abortSignal.aborted) {
+    let page;
+    try {
+      page = await params.client.pollEvents({
+        cursor: params.cursorStore.current(),
+        timeoutSeconds: params.timeoutSeconds ?? 30,
+        ...(params.limit === undefined ? {} : { limit: params.limit }),
+        signal: params.abortSignal,
+      });
+    } catch (error) {
+      if (params.abortSignal.aborted || isAbortError(error)) {
+        return;
+      }
+      if (error instanceof RelayApiError && error.kind === "auth") {
+        // Token revoked: settle so the supervisor applies terminalDisconnect
+        // (server-channels.ts:718) — an operator has to fix the token.
+        throw error;
+      }
+      if (error instanceof RelayApiError && error.kind === "conflict") {
+        // Another consumer took the long poll. Settle and let the
+        // supervisor's backoff arbitrate.
+        log(`[relay] long poll terminated by another consumer: ${error.message}`);
+        throw error;
+      }
+      transientAttempts += 1;
+      log(`[relay] transient poll error (attempt ${transientAttempts}): ${String(error)}`);
+      await sleep(transientDelayMs(), params.abortSignal);
+      continue;
+    }
+    transientAttempts = 0;
+
+    if (page.events.length > 0) {
+      params.onBatch?.(page.events);
+    }
+
+    let batchFailed = false;
+    for (const event of page.events) {
+      if (params.abortSignal.aborted) {
+        batchFailed = true;
+        break;
+      }
+      if (params.shouldProcess && !params.shouldProcess(event)) {
+        // Bookkeeping events (receipts, reactions, echoes) never dispatch, so
+        // they are acked by the batch cursor without a dedupe row.
+        continue;
+      }
+      const claimed = await params.deduper.claimEvent(event.event_id);
+      if (claimed) {
+        let attempted = false;
+        const markAttempt = async () => {
+          if (attempted) return;
+          await params.deduper.commitEvent(event.event_id);
+          attempted = true;
+          if (params.abortSignal.aborted) throw new Error("aborted after durable attempt");
+        };
+        try {
+          await params.handleEvent(event, markAttempt);
+        } catch (error) {
+          if (!attempted) {
+            params.deduper.releaseEvent(event.event_id);
+            log(`[relay] event ${event.event_id} safe preflight failed, will replay: ${String(error)}`);
+            batchFailed = true;
+            break;
+          }
+          log(`[relay] event ${event.event_id} dispatch failed after its attempt was committed; ` +
+            `will not replay possible tool side effects: ${String(error)}`);
+        }
+        if (!attempted) {
+          // Admission/preflight intentionally consumed no side effect; release
+          // the claim and allow the page cursor to acknowledge it.
+          params.deduper.releaseEvent(event.event_id);
+        }
+        if (params.abortSignal.aborted) {
+          batchFailed = true;
+          break;
+        }
+      }
+    }
+
+    // The server's next_cursor covers the whole page (cursor N acks <= N), so
+    // only a batch with durable attempt markers may ack it. A marker-write
+    // failure acks nothing and committed predecessors absorb the replay.
+    if (!batchFailed) {
+      await params.cursorStore.advance(page.nextCursor);
+    } else {
+      await sleep(transientDelayMs(), params.abortSignal);
+    }
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,13 @@
+// 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";
+
+const { setRuntime: setRelayRuntime, getRuntime: getRelayRuntime } =
+  createPluginRuntimeStore<PluginRuntime>({
+    pluginId: "relay",
+    errorMessage: "Relay runtime not initialized",
+  });
+
+export { getRelayRuntime, setRelayRuntime };
+export type { PluginRuntime };

package/src/security.ts

@@ -0,0 +1,36 @@
+import type { RelayAgentProfile } from "./types.js";
+
+function normalizeSenderId(value: string | number): string | null {
+  const normalized = String(value).trim();
+  return normalized ? normalized : null;
+}
+
+/**
+ * Build the only identities allowed to start an OpenClaw turn. The Relay
+ * account owner is pinned from the authenticated agent profile; operators can
+ * deliberately extend that set with `allowFrom`. No wildcard is accepted.
+ */
+export function resolveRelayAllowedSenderIds(params: {
+  profile: Pick<RelayAgentProfile, "owner_user_id">;
+  allowFrom?: Array<string | number>;
+}): string[] {
+  const allowed = new Set<string>();
+  const owner = params.profile.owner_user_id?.trim();
+  if (owner) {
+    allowed.add(owner);
+  }
+  for (const entry of params.allowFrom ?? []) {
+    const normalized = normalizeSenderId(entry);
+    if (normalized && normalized !== "*") {
+      allowed.add(normalized);
+    }
+  }
+  return [...allowed];
+}
+
+export function relaySenderIsAllowed(
+  allowedSenderIds: readonly string[],
+  senderId: string,
+): boolean {
+  return allowedSenderIds.includes(senderId);
+}

package/src/state-files.ts

@@ -0,0 +1,212 @@
+import { jsonStore } from "@openclaw/fs-safe/store";
+import type { JsonStore } from "@openclaw/fs-safe/store";
+import { withFileLock } from "@openclaw/fs-safe/file-lock";
+import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
+import { chmodSync, lstatSync, mkdirSync } from "node:fs";
+import { hostname } from "node:os";
+import { basename, join } from "node:path";
+
+const RELAY_STATE_DOCUMENT_VERSION = 1;
+const RELAY_STATE_LOCK_VERSION = 1;
+const RELAY_STATE_LOCK_TIMEOUT_MS = 30_000;
+
+type RelayStateLockOwner = {
+  version: typeof RELAY_STATE_LOCK_VERSION;
+  kind: "relay-state";
+  pid: number;
+  host: string;
+  createdAt: string;
+};
+
+export type RelayStateDocument<T> = {
+  version: typeof RELAY_STATE_DOCUMENT_VERSION;
+  entries: Record<string, T>;
+};
+
+export function emptyRelayStateDocument<T>(): RelayStateDocument<T> {
+  return { version: RELAY_STATE_DOCUMENT_VERSION, entries: {} };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export function assertRelayStateDocument<T>(
+  value: unknown,
+  label: string,
+  validateEntry: (key: string, value: unknown) => value is T,
+): asserts value is RelayStateDocument<T> {
+  if (
+    !isRecord(value) ||
+    value.version !== RELAY_STATE_DOCUMENT_VERSION ||
+    !isRecord(value.entries)
+  ) {
+    throw new Error(`relay ${label} state is corrupt`);
+  }
+  for (const [key, entry] of Object.entries(value.entries)) {
+    if (!validateEntry(key, entry)) {
+      throw new Error(`relay ${label} state is corrupt`);
+    }
+  }
+}
+
+function isRelayStateLockOwner(value: unknown): value is RelayStateLockOwner {
+  if (!isRecord(value)) return false;
+  return (
+    value.version === RELAY_STATE_LOCK_VERSION &&
+    value.kind === "relay-state" &&
+    Number.isSafeInteger(value.pid) &&
+    (value.pid as number) > 0 &&
+    typeof value.host === "string" &&
+    value.host.length > 0 &&
+    typeof value.createdAt === "string" &&
+    Number.isFinite(Date.parse(value.createdAt))
+  );
+}
+
+function localProcessIsLive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM proves the process exists but is owned by another user. Unknown
+    // failures also fail closed; only ESRCH proves this host no longer has it.
+    return !(error instanceof Error && "code" in error && error.code === "ESRCH");
+  }
+}
+
+/**
+ * Windows opens the sidecar lock with an openat-style
+ * `O_CREAT | O_EXCL` beneath a parent handle. While a just-released lock file
+ * is still delete-pending, that create returns `ACCESS_DENIED` instead of the
+ * `already exists` fs-safe retries on, so contention escapes the acquire loop
+ * as a hard `EACCES`. Retry those on Windows only, bounded by the caller's lock
+ * timeout: a genuine permission failure simply reproduces until the deadline
+ * and then surfaces unchanged.
+ */
+function isWindowsLockAcquisitionContention(error: unknown): boolean {
+  if (process.platform !== "win32") return false;
+  const code = (error as NodeJS.ErrnoException | null)?.code;
+  return code === "EACCES" || code === "EPERM";
+}
+
+function lockRetryDelayMs(attempt: number, remainingMs: number): number {
+  const backoff = Math.min(25 * 2 ** attempt, 250);
+  return Math.max(1, Math.min(backoff * (0.5 + Math.random() / 2), remainingMs));
+}
+
+function canRecoverRelayStateLock(value: unknown): boolean {
+  return (
+    isRelayStateLockOwner(value) &&
+    value.host === hostname() &&
+    !localProcessIsLive(value.pid)
+  );
+}
+
+function ensurePrivateStateDirectory(path: string): void {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`relay state path is not a private directory: ${path}`);
+  }
+  try {
+    chmodSync(path, 0o700);
+  } catch {
+    // POSIX modes are not fully implemented on Windows. fs-safe's private
+    // write path still owns the platform-specific file guarantees.
+  }
+}
+
+/**
+ * Relay owns these files rather than requesting OpenClaw's privileged host
+ * SQLite. jsonStore gives every mutation a private atomic replacement. An
+ * fs-safe sidecar lock serializes cross-process mutations and is recovered
+ * only when its valid Relay owner names this host and its PID is provably dead.
+ */
+export function openRelayStateDocument<T>(params: {
+  fileName: string;
+  env?: NodeJS.ProcessEnv;
+  lockTimeoutMs?: number;
+}): JsonStore<RelayStateDocument<T>> {
+  if (!params.fileName || basename(params.fileName) !== params.fileName) {
+    throw new Error("relay state fileName must be one file name");
+  }
+  const lockTimeoutMs = params.lockTimeoutMs ?? RELAY_STATE_LOCK_TIMEOUT_MS;
+  if (!Number.isSafeInteger(lockTimeoutMs) || lockTimeoutMs < 1) {
+    throw new Error("relay state lockTimeoutMs must be a positive safe integer");
+  }
+  const stateRoot = resolveStateDir(params.env ?? process.env);
+  const relayRoot = join(stateRoot, "relay");
+  const relayStateRoot = join(relayRoot, "state");
+  ensurePrivateStateDirectory(relayRoot);
+  ensurePrivateStateDirectory(relayStateRoot);
+  const store = jsonStore<RelayStateDocument<T>>({
+    filePath: join(relayStateRoot, params.fileName),
+    dirMode: 0o700,
+    mode: 0o600,
+  });
+  const withMutationLock = async <R>(run: () => Promise<R>): Promise<R> => {
+    const deadline = Date.now() + lockTimeoutMs;
+    for (let attempt = 0; ; attempt += 1) {
+      // Only acquisition is retried. Once the mutation itself has started it has
+      // observed state under the lock, so replaying it could double-apply.
+      let mutationStarted = false;
+      try {
+        return await withFileLock(
+          store.filePath,
+          {
+            managerKey: `relay-state:${store.filePath}`,
+            staleMs: RELAY_STATE_LOCK_TIMEOUT_MS,
+            timeoutMs: Math.max(1, deadline - Date.now()),
+            staleRecovery: "remove-if-unchanged",
+            retry: {
+              retries: 300,
+              minTimeout: 25,
+              maxTimeout: 250,
+              randomize: true,
+            },
+            payload: (): RelayStateLockOwner => ({
+              version: RELAY_STATE_LOCK_VERSION,
+              kind: "relay-state",
+              pid: process.pid,
+              host: hostname(),
+              createdAt: new Date().toISOString(),
+            }),
+            shouldReclaim: ({ payload }) => canRecoverRelayStateLock(payload),
+            shouldRemoveStaleLock: ({ payload }) => canRecoverRelayStateLock(payload),
+          },
+          async () => {
+            mutationStarted = true;
+            return await run();
+          },
+        );
+      } catch (error) {
+        const remaining = deadline - Date.now();
+        if (
+          mutationStarted ||
+          remaining <= 0 ||
+          !isWindowsLockAcquisitionContention(error)
+        ) {
+          throw error;
+        }
+        await new Promise((resolve) =>
+          setTimeout(resolve, lockRetryDelayMs(attempt, remaining)),
+        );
+      }
+    }
+  };
+
+  return {
+    filePath: store.filePath,
+    read: store.read,
+    readOr: store.readOr,
+    readRequired: store.readRequired,
+    write: async (value) => {
+      await withMutationLock(async () => await store.write(value));
+    },
+    update: async (run) =>
+      await withMutationLock(async () => await store.update(run)),
+    updateOr: async (fallback, run) =>
+      await withMutationLock(async () => await store.updateOr(fallback, run)),
+  };
+}

package/src/types.ts

@@ -0,0 +1,173 @@
+// 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 = {
+  kind: "user" | "agent";
+  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;
+    [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.
+// ---------------------------------------------------------------------------
+
+export type RelayAccountConfig = {
+  name?: string;
+  enabled?: boolean;
+  token?: string;
+  tokenFile?: string;
+  baseUrl?: string;
+  allowFrom?: Array<string | number>;
+  pollTimeoutSeconds?: number;
+};
+
+export type RelayChannelConfig = RelayAccountConfig & {
+  accounts?: Record<string, Partial<RelayAccountConfig>>;
+  defaultAccount?: string;
+};
+
+export type RelayCoreConfig = {
+  channels?: {
+    relay?: RelayChannelConfig;
+  };
+  session?: {
+    store?: string;
+  };
+};
+
+export type ResolvedRelayAccount = {
+  accountId: string;
+  enabled: boolean;
+  configured: boolean;
+  name?: string;
+  token: string;
+  baseUrl: string;
+  pollTimeoutSeconds: number;
+  config: RelayAccountConfig;
+};