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

package/src/inbound-dedupe.ts

@@ -1,241 +0,0 @@
-// 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/invocations.ts

@@ -1,58 +0,0 @@
-/**
- * Which group invocation an in-flight turn belongs to.
- *
- * Relay mints an invocation when a human invokes an agent in a group, and
- * every call the agent then makes about that message has to carry the id back:
- * `/typing` and `/responding` refuse without it, and so does the reply itself.
- *
- * The reply does not leave through this plugin's own code. It leaves through
- * core's durable message adapter, whose send context carries `to`, `text`, and
- * delivery bookkeeping and nothing about the message being answered
- * (`ChannelMessageSendTextContext`). There is no field to thread the id
- * through, so the turn parks it here for the adapter to find.
- *
- * Keyed by (accountId, conversationId) because `to` and `accountId` are all
- * the adapter knows. Two agents in one group get separate slots. Two
- * overlapping turns for ONE agent in ONE group share a slot and the later one
- * wins — bounded by the server, which spends an invocation exactly once and
- * refuses the loser rather than misattributing it.
- */
-const pendingInvocations = new Map<string, string>();
-
-function slotKey(accountId: string, conversationId: string): string {
-  return `${accountId}\0${conversationId}`;
-}
-
-/**
- * Hold `invocationId` for the life of one turn. Returns the release function;
- * call it in a `finally` so a thrown turn cannot strand the slot.
- *
- * Releasing only clears the slot if this turn still owns it, so a turn that
- * finishes after being superseded cannot delete its successor's id.
- */
-export function rememberRelayInvocation(params: {
-  accountId: string;
-  conversationId: string;
-  invocationId: string;
-}): () => void {
-  const key = slotKey(params.accountId, params.conversationId);
-  pendingInvocations.set(key, params.invocationId);
-  return () => {
-    if (pendingInvocations.get(key) === params.invocationId) {
-      pendingInvocations.delete(key);
-    }
-  };
-}
-
-/** The invocation an outbound send in this conversation belongs to, if any. */
-export function relayInvocationFor(params: {
-  accountId: string;
-  conversationId: string;
-}): string | undefined {
-  return pendingInvocations.get(slotKey(params.accountId, params.conversationId));
-}
-
-/** Test seam: drop every slot. */
-export function resetRelayInvocationsForTest(): void {
-  pendingInvocations.clear();
-}

package/src/lifecycle.ts

@@ -1,42 +0,0 @@
-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/poll-loop.ts

@@ -1,173 +0,0 @@
-// 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);
-            // A rejection is the server's final answer: replaying the identical
-            // request produces the identical refusal. Holding the cursor for it
-            // is a livelock, and the cursor is ONE watermark for the whole
-            // channel — so a single permanently-refused event would starve every
-            // later message, direct ones included (REL-167). Losing one event is
-            // strictly better than losing the channel, so log it loudly and let
-            // the page cursor move past it.
-            if (error instanceof RelayApiError && error.kind === "rejected") {
-              log(`[relay] event ${event.event_id} was permanently rejected by the server, ` +
-                `skipping it so later messages are not starved: ${String(error)}`);
-              continue;
-            }
-            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/responding.ts

@@ -1,52 +0,0 @@
-import { RelayApiError } from "./client.js";
-import type { RelayClient } from "./client.js";
-import type { RelayInboundFacts } from "./inbound.js";
-
-/**
- * Record the read/responding receipt, then commit the durable attempt marker.
- *
- * The receipt is a courtesy to the person waiting: it turns their message Read
- * and shows that something is composing. It is NOT permission to answer, and
- * it used to be treated as such — a rejected receipt threw here, before
- * `markAttempt`, which sent the poll loop down its replay branch and froze the
- * channel's single delivery cursor. One group mention whose receipt the server
- * refused therefore starved every later message, direct ones included
- * (REL-167).
- *
- * So a failed receipt is reported and the turn continues. The ordering that
- * mattered is kept: the receipt is still attempted BEFORE the attempt marker,
- * so a receipt that succeeds still precedes any agent or tool work.
- */
-export async function markRespondingBeforeAttempt(params: {
-  client: RelayClient;
-  /**
-   * The whole fact bundle, not its fields one at a time. The receipt needs the
-   * conversation, the message, AND the invocation when there is one, and a
-   * caller that copies two of those three out by hand can silently forget the
-   * third — which is how the group receipt shipped without its invocation id.
-   */
-  facts: Pick<RelayInboundFacts, "conversationId" | "messageId" | "invocationId">;
-  label: string;
-  markAttempt: () => Promise<void>;
-  onReceiptFailure?: (line: string) => void;
-}): Promise<void> {
-  const { facts } = params;
-  try {
-    await params.client.setResponding({
-      conversationId: facts.conversationId,
-      messageId: facts.messageId,
-      label: params.label,
-      ...(facts.invocationId ? { invocationId: facts.invocationId } : {}),
-    });
-  } catch (error) {
-    // An aborted shutdown is not a receipt failure; let it settle the loop.
-    if (error instanceof Error && error.name === "AbortError") {
-      throw error;
-    }
-    const detail = error instanceof RelayApiError ? error.message : String(error);
-    params.onReceiptFailure?.(
-      `responding receipt for message ${facts.messageId} failed, answering anyway: ${detail}`,
-    );
-  }
-  await params.markAttempt();
-}

package/src/security.ts

@@ -1,36 +0,0 @@
-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);
-}