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

package/dist/src/vendor/relay-sdk/client.js

@@ -1,163 +0,0 @@
-import { RelayApiError, classifyRelayHttpStatus, isAbortError, } from "./errors.js";
-import { normalizeRelayBaseUrl } from "./url.js";
-async function readErrorDetail(response) {
-    try {
-        const body = (await response.json());
-        return {
-            ...(body?.error?.code ? { code: body.error.code } : {}),
-            ...(body?.error?.details ? { details: body.error.details } : {}),
-            message: body?.error?.message ?? body?.message ?? "",
-        };
-    }
-    catch {
-        return { message: "" };
-    }
-}
-export function createRelayClient(options) {
-    if (!options.token.trim()) {
-        throw new Error("relay: Agent Token is required");
-    }
-    const baseUrl = normalizeRelayBaseUrl(options.baseUrl);
-    const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
-    const requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
-    const request = async (params) => {
-        const url = new URL(`${baseUrl}${params.path}`);
-        for (const [key, value] of Object.entries(params.query ?? {})) {
-            if (value !== undefined)
-                url.searchParams.set(key, String(value));
-        }
-        const timeoutSignal = AbortSignal.timeout(params.timeoutMs ?? requestTimeoutMs);
-        const signal = params.signal
-            ? AbortSignal.any([params.signal, timeoutSignal])
-            : timeoutSignal;
-        let response;
-        try {
-            response = await fetchImpl(url.toString(), {
-                method: params.method,
-                headers: {
-                    authorization: `Bearer ${options.token}`,
-                    ...(params.body === undefined ? {} : { "content-type": "application/json" }),
-                    ...params.headers,
-                },
-                ...(params.body === undefined ? {} : { body: JSON.stringify(params.body) }),
-                signal,
-            });
-        }
-        catch (error) {
-            if (timeoutSignal.aborted && !params.signal?.aborted) {
-                throw new RelayApiError(`relay: ${params.method} ${params.path} timed out after ${params.timeoutMs ?? requestTimeoutMs}ms`, { kind: "retryable" });
-            }
-            if (isAbortError(error))
-                throw error;
-            throw new RelayApiError(`relay: network error: ${String(error)}`, {
-                kind: "retryable",
-            });
-        }
-        if (!response.ok) {
-            const detail = await readErrorDetail(response);
-            throw new RelayApiError(`relay: ${params.method} ${params.path} failed with ${response.status}${detail.message ? `: ${detail.message}` : ""}`, {
-                status: response.status,
-                kind: classifyRelayHttpStatus(response.status),
-                ...(detail.code ? { code: detail.code } : {}),
-                ...(detail.details ? { details: detail.details } : {}),
-            });
-        }
-        return response;
-    };
-    const client = {
-        baseUrl,
-        getMe: async (params) => {
-            const response = await request({
-                method: "GET",
-                path: "/v1/agents/me",
-                ...(params?.signal ? { signal: params.signal } : {}),
-            });
-            const body = (await response.json());
-            return body.agent;
-        },
-        pollEvents: async (params) => {
-            const timeoutSeconds = Math.min(Math.max(params.timeoutSeconds ?? 30, 1), 30);
-            const response = await request({
-                method: "GET",
-                path: "/v1/events",
-                query: {
-                    cursor: params.cursor,
-                    timeout: timeoutSeconds,
-                    ...(params.limit === undefined ? {} : { limit: params.limit }),
-                },
-                ...(params.signal ? { signal: params.signal } : {}),
-                timeoutMs: (timeoutSeconds + 15) * 1_000,
-            });
-            const body = (await response.json());
-            const events = Array.isArray(body.events) ? body.events : [];
-            const nextCursor = typeof body.next_cursor === "number" && Number.isSafeInteger(body.next_cursor)
-                ? body.next_cursor
-                : params.cursor;
-            return { events, nextCursor };
-        },
-        sendMessage: async (params) => {
-            const response = await request({
-                method: "POST",
-                path: "/v1/messages",
-                headers: { "idempotency-key": params.idempotencyKey },
-                body: {
-                    conversation_id: params.conversationId,
-                    parts: params.parts,
-                    ...(params.invocationId ? { invocation_id: params.invocationId } : {}),
-                    ...(params.replyTo ? { reply_to: params.replyTo } : {}),
-                },
-                ...(params.signal ? { signal: params.signal } : {}),
-            });
-            const body = (await response.json());
-            return { messages: body.messages };
-        },
-        sendText: async (params) => {
-            const { text, ...rest } = params;
-            return client.sendMessage({
-                ...rest,
-                parts: [{ type: "text", text }],
-            });
-        },
-        setTyping: async (params) => {
-            await request({
-                method: "POST",
-                path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/typing`,
-                body: {
-                    started: params.started,
-                    ...(params.label ? { label: params.label } : {}),
-                    ...(params.invocationId ? { invocation_id: params.invocationId } : {}),
-                },
-                ...(params.signal ? { signal: params.signal } : {}),
-            });
-        },
-        setResponding: async (params) => {
-            await request({
-                method: "POST",
-                path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/responding`,
-                body: {
-                    message_id: params.messageId,
-                    ...(params.label ? { label: params.label } : {}),
-                    ...(params.invocationId ? { invocation_id: params.invocationId } : {}),
-                },
-                ...(params.signal ? { signal: params.signal } : {}),
-            });
-        },
-        markDelivered: async (params) => {
-            await request({
-                method: "POST",
-                path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/delivered`,
-                body: { message_id: params.messageId },
-                ...(params.signal ? { signal: params.signal } : {}),
-            });
-        },
-        markRead: async (params) => {
-            await request({
-                method: "POST",
-                path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/read`,
-                body: { message_id: params.messageId },
-                ...(params.signal ? { signal: params.signal } : {}),
-            });
-        },
-    };
-    return client;
-}

package/dist/src/vendor/relay-sdk/errors.js

@@ -1,45 +0,0 @@
-/** Classified Relay API failure. `terminal` means retrying the same request cannot succeed. */
-export class RelayApiError extends Error {
-    status;
-    kind;
-    code;
-    /** Structured `error.details` from the response body, e.g. `highest_delivered_cursor` on 422. */
-    details;
-    constructor(message, params) {
-        super(message);
-        this.name = "RelayApiError";
-        this.status = params.status;
-        this.kind = params.kind;
-        this.code = params.code;
-        this.details = params.details;
-    }
-    get terminal() {
-        return this.kind !== "retryable";
-    }
-    get retryable() {
-        return this.kind === "retryable";
-    }
-}
-export class WebhookVerificationError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "WebhookVerificationError";
-    }
-}
-export function classifyRelayHttpStatus(status) {
-    if (status === 401)
-        return "auth";
-    if (status === 409)
-        return "conflict";
-    if (status === 408 || status === 429 || status >= 500)
-        return "retryable";
-    return "rejected";
-}
-export function isAbortError(error) {
-    return error instanceof Error && error.name === "AbortError";
-}
-export function isRelayWebhookConflict(error) {
-    return (error instanceof RelayApiError &&
-        error.status === 409 &&
-        error.code !== "terminated_by_other_consumer");
-}

package/dist/src/vendor/relay-sdk/types.js

@@ -1,2 +0,0 @@
-/** Wire types for the Relay v1 developer API used by plugins and examples. */
-export {};

package/dist/src/vendor/relay-sdk/url.js

@@ -1,39 +0,0 @@
-import { isIP } from "node:net";
-export const DEFAULT_RELAY_BASE_URL = "https://api.relayapp.im";
-function isLoopbackHostname(hostname) {
-    const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
-    const ipVersion = isIP(normalized);
-    if (ipVersion === 4)
-        return normalized.split(".")[0] === "127";
-    if (ipVersion === 6)
-        return normalized === "::1";
-    return normalized === "localhost" || normalized.endsWith(".localhost");
-}
-/**
- * Validate and canonicalize the API origin before a bearer token can be sent.
- * Remote origins must use HTTPS. Plain HTTP is allowed only on loopback.
- */
-export function normalizeRelayBaseUrl(raw) {
-    const candidate = raw?.trim() || DEFAULT_RELAY_BASE_URL;
-    let url;
-    try {
-        url = new URL(candidate);
-    }
-    catch {
-        throw new Error(`relay: invalid baseUrl ${JSON.stringify(candidate)}`);
-    }
-    if (url.username || url.password) {
-        throw new Error("relay: baseUrl must not contain credentials");
-    }
-    if (url.search || url.hash) {
-        throw new Error("relay: baseUrl must not contain a query or fragment");
-    }
-    if (!/^\/+$/u.test(url.pathname)) {
-        throw new Error("relay: baseUrl must be an origin without a path");
-    }
-    if (url.protocol !== "https:" &&
-        !(url.protocol === "http:" && isLoopbackHostname(url.hostname))) {
-        throw new Error("relay: baseUrl must use HTTPS (HTTP is allowed only for loopback development)");
-    }
-    return url.origin;
-}

package/src/account-lock.ts

@@ -1,108 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-interface LockOwner {
-  pid: number;
-  nonce: string;
-  account_id: string;
-  created_at: string;
-}
-
-function processIsLive(pid: number): boolean {
-  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error: any) {
-    return error?.code === "EPERM";
-  }
-}
-
-function readOwner(path: string): LockOwner | undefined {
-  try {
-    const value = JSON.parse(readFileSync(path, "utf8")) as Partial<LockOwner>;
-    if (
-      Number.isSafeInteger(value.pid) &&
-      typeof value.nonce === "string" &&
-      typeof value.account_id === "string" &&
-      typeof value.created_at === "string"
-    ) {
-      return value as LockOwner;
-    }
-  } catch {
-    // Missing/malformed ownership is never deleted in place by a contender.
-  }
-  return undefined;
-}
-
-/** Atomic filesystem lease preventing two OpenClaw processes polling one agent. */
-export class RelayAccountLock {
-  private readonly lockPath: string;
-  private readonly ownerPath: string;
-  private readonly nonce = randomUUID();
-  private held = false;
-
-  constructor(
-    baseUrl: string,
-    agentId: string,
-    private readonly accountId: string,
-    baseDir = join(homedir(), ".openclaw", "relay", "consumer-locks"),
-  ) {
-    const key = createHash("sha256").update(`${baseUrl}\0${agentId}`).digest("hex");
-    this.lockPath = join(baseDir, key);
-    this.ownerPath = join(this.lockPath, "owner.json");
-  }
-
-  acquire(): void {
-    mkdirSync(join(this.lockPath, ".."), { recursive: true, mode: 0o700 });
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-      try {
-        mkdirSync(this.lockPath, { mode: 0o700 });
-        const owner: LockOwner = {
-          pid: process.pid,
-          nonce: this.nonce,
-          account_id: this.accountId,
-          created_at: new Date().toISOString(),
-        };
-        writeFileSync(this.ownerPath, `${JSON.stringify(owner)}\n`, { mode: 0o600 });
-        this.held = true;
-        return;
-      } catch (error: any) {
-        if (error?.code !== "EEXIST") throw error;
-        const owner = readOwner(this.ownerPath);
-        if (!owner || processIsLive(owner.pid)) {
-          const claimant = owner
-            ? `account "${owner.account_id}" (pid ${owner.pid})`
-            : "an existing process with unreadable ownership";
-          throw new Error(`relay: this agent already has an active consumer in ${claimant}`);
-        }
-        const stalePath = `${this.lockPath}.stale-${Date.now()}-${randomUUID()}`;
-        try {
-          renameSync(this.lockPath, stalePath);
-          rmSync(stalePath, { recursive: true, force: true });
-        } catch (renameError: any) {
-          if (renameError?.code !== "ENOENT") throw renameError;
-        }
-      }
-    }
-    throw new Error("relay: could not acquire the agent consumer lock");
-  }
-
-  release(): void {
-    if (!this.held) return;
-    const owner = readOwner(this.ownerPath);
-    if (owner?.nonce === this.nonce && existsSync(this.lockPath)) {
-      rmSync(this.lockPath, { recursive: true, force: true });
-    }
-    this.held = false;
-  }
-}

package/src/client.ts

@@ -1,51 +0,0 @@
-// The Relay API client the plugin uses. There is no implementation here: this
-// is `@relaymessenger/sdk`'s client, vendored under `./vendor/relay-sdk`
-// (see that directory's README for why, and for the one-file swap when the
-// package ships).
-//
-// The plugin used to hand-roll its own client beside the SDK's. They drifted,
-// and the drift was a defect: the hand-rolled one had no `invocationId` on
-// `sendMessage`, `setTyping`, or `setResponding`, so an agent's first group
-// mention wedged its entire event stream (REL-167).
-import { createRelayClient as createVendoredRelayClient } from "./vendor/relay-sdk/client.js";
-import type { RelayClient as VendoredRelayClient } from "./vendor/relay-sdk/client.js";
-import type { RelayEventsPage } from "./types.js";
-
-export { DEFAULT_RELAY_BASE_URL, normalizeRelayBaseUrl } from "./vendor/relay-sdk/url.js";
-export {
-  classifyRelayHttpStatus,
-  isAbortError,
-  isRelayWebhookConflict,
-  RelayApiError,
-} from "./vendor/relay-sdk/errors.js";
-export type { RelayApiErrorKind } from "./vendor/relay-sdk/errors.js";
-export type { RelayClientOptions } from "./vendor/relay-sdk/client.js";
-/**
- * A message as the server echoes it back from a send. Distinct from
- * `types.ts`'s `RelayMessage`, which is the inbound shape the plugin renders
- * with its typed parts: a send result is only ever read for its ids.
- */
-export type { RelayMessage as RelaySentMessage } from "./vendor/relay-sdk/types.js";
-
-/**
- * The vendored client, restated over the plugin's own event types.
- *
- * The SDK types an event's `data` as an open `Record<string, unknown>`; the
- * plugin types the parts of it that it renders (`message`, its typed parts,
- * `invocation_id`). Both describe the same JSON at different resolutions, and
- * the narrowing happens for real in `buildRelayInboundFacts`, which returns
- * null for anything that does not match. This type only names that boundary —
- * the object is the SDK's, unmodified, at runtime.
- */
-export type RelayClient = Omit<VendoredRelayClient, "pollEvents"> & {
-  pollEvents: (params: {
-    cursor: number;
-    timeoutSeconds?: number;
-    limit?: number;
-    signal?: AbortSignal;
-  }) => Promise<RelayEventsPage>;
-};
-
-export const createRelayClient = createVendoredRelayClient as (
-  options: Parameters<typeof createVendoredRelayClient>[0],
-) => RelayClient;

package/src/cursor-store.ts

@@ -1,186 +0,0 @@
-// Persisted long-poll cursor, Telegram-offset style:
-// monotonic writes only, bound to the agent identity so a token that now
-// resolves to a different agent discards the stale cursor instead of acking
-// another contact's event stream.
-import { createHash } from "node:crypto";
-import {
-  assertRelayStateDocument,
-  emptyRelayStateDocument,
-  openRelayStateDocument,
-} from "./state-files.js";
-
-export const RELAY_CURSOR_MAX_ENTRIES = 1_000;
-export const RELAY_CURSOR_OVERFLOW_POLICY = "reject-new" as const;
-
-const RECORD_VERSION = 2;
-
-export type RelayCursorRecord = {
-  version: number;
-  cursor: number;
-  baseUrl: string;
-  agentId: string;
-};
-
-/**
- * Minimal state-store slice the cursor needs. The channel runtime binds this
- * to Relay-owned files; tests can inject a memory map.
- */
-export type RelayCursorStateStore = {
-  lookup(key: string): Promise<RelayCursorRecord | undefined>;
-  register(key: string, value: RelayCursorRecord): Promise<void>;
-};
-
-export type RelayCursorStore = {
-  /** Loads the persisted cursor; only a genuinely absent stable identity starts at 0. */
-  load(): Promise<number>;
-  /** Last accepted cursor (in-memory view). */
-  current(): number;
-  /**
-   * Persist a new cursor. Only called after the batch it acknowledges has been
-   * durably handled (claim/commit); ignores non-monotonic or invalid values so
-   * a replayed batch can never move the ack backwards.
-   */
-  advance(cursor: number): Promise<void>;
-};
-
-/**
- * Open Relay's private, lock-protected state file with fail-closed capacity
- * semantics. A cursor is permanent safety state: evicting an old identity to
- * admit a new one could replay retained events when the old identity returns.
- */
-export function openRelayCursorStateStore(
-  warn: (line: string) => void,
-  options: { env?: NodeJS.ProcessEnv; maxEntries?: number } = {},
-): RelayCursorStateStore {
-  const maxEntries = options.maxEntries ?? RELAY_CURSOR_MAX_ENTRIES;
-  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
-    throw new Error("relay cursor maxEntries must be a positive safe integer");
-  }
-  const store = openRelayStateDocument<RelayCursorRecord>({
-    fileName: "cursors.json",
-    ...(options.env ? { env: options.env } : {}),
-  });
-  const storageKey = (key: string) => createHash("sha256").update(key).digest("hex");
-  const validateEntry = (key: string, value: unknown): value is RelayCursorRecord => {
-    if (!/^[a-f0-9]{64}$/u.test(key) || !value || typeof value !== "object") return false;
-    const record = value as Partial<RelayCursorRecord>;
-    return (
-      record.version === RECORD_VERSION &&
-      isValidCursor(record.cursor) &&
-      typeof record.baseUrl === "string" &&
-      (() => {
-        try {
-          return new URL(record.baseUrl).origin === record.baseUrl;
-        } catch {
-          return false;
-        }
-      })() &&
-      typeof record.agentId === "string" &&
-      record.agentId.length > 0
-    );
-  };
-  const read = async () => {
-    try {
-      const current = await store.read();
-      if (current === undefined) return emptyRelayStateDocument<RelayCursorRecord>();
-      assertRelayStateDocument(current, "cursor", validateEntry);
-      return current;
-    } catch (error) {
-      warn(`[relay] cursor state unavailable; refusing unsafe cursor reset: ${String(error)}`);
-      throw error;
-    }
-  };
-  return {
-    lookup: async (key) => (await read()).entries[storageKey(key)],
-    register: async (key, value) => {
-      try {
-        await store.updateOr(emptyRelayStateDocument<RelayCursorRecord>(), (current) => {
-          assertRelayStateDocument(current, "cursor", validateEntry);
-          const hashedKey = storageKey(key);
-          if (
-            !Object.hasOwn(current.entries, hashedKey) &&
-            Object.keys(current.entries).length >= maxEntries
-          ) {
-            throw new Error(
-              `relay cursor state reached ${maxEntries} identities (${RELAY_CURSOR_OVERFLOW_POLICY})`,
-            );
-          }
-          return {
-            version: current.version,
-            entries: { ...current.entries, [hashedKey]: value },
-          };
-        });
-      } catch (error) {
-        warn(`[relay] cursor state unavailable; refusing unsafe cursor reset: ${String(error)}`);
-        throw error;
-      }
-    },
-  };
-}
-
-function isValidCursor(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
-
-export function createRelayCursorStore(params: {
-  store: RelayCursorStateStore;
-  baseUrl: string;
-  agentId: string;
-  onPersistError?: (error: unknown) => void;
-}): RelayCursorStore {
-  const baseUrl = new URL(params.baseUrl).origin;
-  const key = `relay:${baseUrl}:${params.agentId}`;
-  let cursor = 0;
-  let loaded = false;
-
-  return {
-    load: async () => {
-      let record: RelayCursorRecord | undefined;
-      try {
-        record = await params.store.lookup(key);
-      } catch (error) {
-        params.onPersistError?.(error);
-        throw new Error(`relay cursor state could not be loaded: ${String(error)}`);
-      }
-      if (!record) {
-        cursor = 0;
-        loaded = true;
-        return cursor;
-      }
-      if (
-        record.version !== RECORD_VERSION ||
-        !isValidCursor(record.cursor) ||
-        record.agentId !== params.agentId ||
-        record.baseUrl !== baseUrl
-      ) {
-        throw new Error(`relay cursor state is corrupt for ${baseUrl} ${params.agentId}; refusing cursor-zero replay`);
-      }
-      cursor = record.cursor;
-      loaded = true;
-      return cursor;
-    },
-
-    current: () => cursor,
-
-    advance: async (next) => {
-      if (!loaded) {
-        throw new Error("relay cursor store: advance() before load()");
-      }
-      if (!isValidCursor(next) || next <= cursor) {
-        return;
-      }
-      try {
-        await params.store.register(key, {
-          version: RECORD_VERSION,
-          cursor: next,
-          baseUrl,
-          agentId: params.agentId,
-        });
-      } catch (error) {
-        params.onPersistError?.(error);
-        throw new Error(`relay cursor advance was not durable: ${String(error)}`);
-      }
-      cursor = next;
-    },
-  };
-}