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

package/src/state-files.ts

@@ -1,298 +0,0 @@
-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));
-}
-
-/**
- * The sidecar lock has no in-process fast path: every waiter polls the lock
- * file, and losing an attempt costs an exclusive create plus a snapshot read.
- * Relay mutates one document from several tasks at once — a poll batch
- * registers one dedupe entry per inbound message — so N in-process writers
- * become N pollers competing with the holder for the same file. Funnelling
- * them through one in-memory queue leaves a single poller per process, which
- * matters most on Windows: same-process losers no longer race the holder's
- * unlink, so contention stops manifesting as delete-pending denials.
- *
- * Keyed by the store's file path. Two paths spelled differently for one file
- * would each get a queue and simply fall back to the sidecar lock for
- * correctness, so a miss costs throughput rather than serialization.
- */
-const RELAY_STATE_MUTEX_KEY = Symbol.for("relay.stateFileMutexes");
-
-function stateFileMutexes(): Map<string, Promise<void>> {
-  const container = globalThis as typeof globalThis & {
-    [RELAY_STATE_MUTEX_KEY]?: Map<string, Promise<void>>;
-  };
-  container[RELAY_STATE_MUTEX_KEY] ??= new Map<string, Promise<void>>();
-  return container[RELAY_STATE_MUTEX_KEY];
-}
-
-function fileLockTimeout(filePath: string): Error {
-  return Object.assign(new Error(`file lock timeout for ${filePath}`), {
-    code: "file_lock_timeout",
-  });
-}
-
-/** Waits for our turn, but never past the caller's lock deadline. */
-async function awaitTurn(
-  turn: Promise<void>,
-  deadline: number,
-  filePath: string,
-): Promise<void> {
-  const remaining = deadline - Date.now();
-  if (remaining <= 0) throw fileLockTimeout(filePath);
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  try {
-    await Promise.race([
-      turn,
-      new Promise<never>((_resolve, reject) => {
-        timer = setTimeout(() => reject(fileLockTimeout(filePath)), remaining);
-      }),
-    ]);
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
-}
-
-async function withStateFileMutex<R>(
-  filePath: string,
-  deadline: number,
-  run: () => Promise<R>,
-): Promise<R> {
-  const mutexes = stateFileMutexes();
-  const previous = mutexes.get(filePath);
-  let release!: () => void;
-  const ours = new Promise<void>((resolve) => {
-    release = resolve;
-  });
-  // Chain even when we abandon our turn on timeout: later waiters still queue
-  // behind the holder we were waiting on, so ordering survives a giving-up
-  // waiter.
-  const tail = previous ? previous.then(() => ours) : ours;
-  mutexes.set(filePath, tail);
-  let tookTurn = false;
-  try {
-    if (previous) await awaitTurn(previous, deadline, filePath);
-    tookTurn = true;
-    return await run();
-  } finally {
-    release();
-    // Forgetting the queue is only safe once it has drained. A waiter that gave
-    // up is still queued behind a holder that is running, so dropping the entry
-    // there would let the next caller past the holder and back onto the lock
-    // file the queue exists to keep it off. Leaving it costs one settled promise
-    // until the next caller drains it.
-    if (tookTurn && mutexes.get(filePath) === tail) mutexes.delete(filePath);
-  }
-}
-
-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;
-    return await withStateFileMutex(store.filePath, deadline, async () => {
-      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/vendor/relay-sdk/README.md

@@ -1,28 +0,0 @@
-# Vendored `@relaymessenger/sdk` client
-
-`client.ts`, `errors.ts`, `types.ts`, and `url.ts` are **verbatim copies** of
-`packages/sdk/src/` in this same repository. Do not edit them here. Fix the SDK
-and re-copy.
-
-## Why a copy
-
-The plugin used to carry its own hand-rolled Relay client. The two drifted, and
-the drift shipped a defect: the plugin's client had no `invocationId` on
-`sendMessage`, `setTyping`, or `setResponding`, so the first group mention an
-agent received wedged its whole event stream (REL-167). The SDK client has
-always had those parameters.
-
-The SDK is not published to npm yet (`packages/cli/CLAUDE.md`), so the plugin
-cannot depend on it. Vendoring adopts the correct client now instead of growing
-a second one.
-
-## Removing this directory
-
-When `@relaymessenger/sdk` ships:
-
-1. Add it to `dependencies` in `integrations/openclaw/package.json`.
-2. Point `src/client.ts` at `@relaymessenger/sdk` instead of `./vendor/relay-sdk/*`.
-3. Delete this directory.
-
-`src/client.ts` is the only file that imports from here, so that is the whole
-swap.

package/src/vendor/relay-sdk/client.ts

@@ -1,293 +0,0 @@
-import {
-  RelayApiError,
-  classifyRelayHttpStatus,
-  isAbortError,
-} from "./errors.js";
-import type {
-  RelayAgentProfile,
-  RelayEventsPage,
-  RelayOutgoingPart,
-  RelayReplyRef,
-  RelaySendResult,
-} from "./types.js";
-import { normalizeRelayBaseUrl } from "./url.js";
-
-type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
-
-export type RelayClientOptions = {
-  token: string;
-  baseUrl?: string;
-  fetchImpl?: FetchLike;
-  requestTimeoutMs?: number;
-};
-
-export type RelayClient = {
-  readonly baseUrl: string;
-  getMe: (params?: { signal?: AbortSignal }) => Promise<RelayAgentProfile>;
-  pollEvents: (params: {
-    cursor: number;
-    timeoutSeconds?: number;
-    limit?: number;
-    signal?: AbortSignal;
-  }) => Promise<RelayEventsPage>;
-  sendMessage: (params: {
-    conversationId: string;
-    parts: RelayOutgoingPart[];
-    replyTo?: RelayReplyRef;
-    invocationId?: string;
-    idempotencyKey: string;
-    signal?: AbortSignal;
-  }) => Promise<RelaySendResult>;
-  sendText: (params: {
-    conversationId: string;
-    text: string;
-    replyTo?: RelayReplyRef;
-    invocationId?: string;
-    idempotencyKey: string;
-    signal?: AbortSignal;
-  }) => Promise<RelaySendResult>;
-  setTyping: (params: {
-    conversationId: string;
-    started: boolean;
-    label?: string;
-    invocationId?: string;
-    signal?: AbortSignal;
-  }) => Promise<void>;
-  setResponding: (params: {
-    conversationId: string;
-    messageId: string;
-    label?: string;
-    invocationId?: string;
-    signal?: AbortSignal;
-  }) => Promise<void>;
-  /**
-   * Advance the delivered watermark to `messageId`, and every earlier message
-   * from other participants with it.
-   *
-   * Most agents never call this. Delivered means the agent's endpoint has the
-   * message, so Relay records it from the transport itself: a webhook gets it
-   * when the endpoint answers `2xx`, and a `GET /v1/events` consumer gets it
-   * when the cursor moves past the event. Neither needs a line of code, and
-   * neither can suppress it.
-   *
-   * The exception is a transcript poller — a client that reads
-   * `GET /v1/conversations/:id/messages` on a timer. Reading history records
-   * no receipt, so nothing on the server ever learns the message arrived.
-   * That client, and only that client, has to say so itself.
-   *
-   * Send it on ingest, before anything that implies a read. The server
-   * advances the delivered watermark whenever it records a read, so a
-   * delivered receipt that arrives after a read for the same message is
-   * silently dropped: the sender goes straight from "Sent" to "Read" and never
-   * sees "Delivered". Skipping this call costs the middle rung of the ladder,
-   * not the top one.
-   */
-  markDelivered: (params: {
-    conversationId: string;
-    messageId: string;
-    signal?: AbortSignal;
-  }) => Promise<void>;
-  markRead: (params: {
-    conversationId: string;
-    messageId: string;
-    signal?: AbortSignal;
-  }) => Promise<void>;
-};
-
-async function readErrorDetail(response: Response): Promise<{
-  code?: string;
-  message: string;
-  details?: Record<string, unknown>;
-}> {
-  try {
-    const body = (await response.json()) as {
-      error?: { code?: string; message?: string; details?: Record<string, unknown> };
-      message?: string;
-    };
-    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: RelayClientOptions): RelayClient {
-  if (!options.token.trim()) {
-    throw new Error("relay: Agent Token is required");
-  }
-  const baseUrl = normalizeRelayBaseUrl(options.baseUrl);
-  const fetchImpl: FetchLike =
-    options.fetchImpl ?? ((input, init) => fetch(input, init));
-  const requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
-
-  const request = async (params: {
-    method: string;
-    path: string;
-    query?: Record<string, string | number | boolean | undefined>;
-    body?: unknown;
-    headers?: Record<string, string>;
-    signal?: AbortSignal;
-    timeoutMs?: number;
-  }): Promise<Response> => {
-    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: 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: RelayClient = {
-    baseUrl,
-
-    getMe: async (params) => {
-      const response = await request({
-        method: "GET",
-        path: "/v1/agents/me",
-        ...(params?.signal ? { signal: params.signal } : {}),
-      });
-      const body = (await response.json()) as { agent: RelayAgentProfile };
-      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()) as {
-        events?: RelayEventsPage["events"];
-        next_cursor?: number;
-      };
-      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()) as {
-        messages: RelaySendResult["messages"];
-      };
-      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/src/vendor/relay-sdk/errors.ts

@@ -1,61 +0,0 @@
-export type RelayApiErrorKind = "auth" | "conflict" | "retryable" | "rejected";
-
-/** Classified Relay API failure. `terminal` means retrying the same request cannot succeed. */
-export class RelayApiError extends Error {
-  readonly status: number | undefined;
-  readonly kind: RelayApiErrorKind;
-  readonly code: string | undefined;
-  /** Structured `error.details` from the response body, e.g. `highest_delivered_cursor` on 422. */
-  readonly details: Record<string, unknown> | undefined;
-
-  constructor(
-    message: string,
-    params: {
-      status?: number;
-      kind: RelayApiErrorKind;
-      code?: string;
-      details?: Record<string, unknown>;
-    },
-  ) {
-    super(message);
-    this.name = "RelayApiError";
-    this.status = params.status;
-    this.kind = params.kind;
-    this.code = params.code;
-    this.details = params.details;
-  }
-
-  get terminal(): boolean {
-    return this.kind !== "retryable";
-  }
-
-  get retryable(): boolean {
-    return this.kind === "retryable";
-  }
-}
-
-export class WebhookVerificationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "WebhookVerificationError";
-  }
-}
-
-export function classifyRelayHttpStatus(status: number): RelayApiErrorKind {
-  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: unknown): boolean {
-  return error instanceof Error && error.name === "AbortError";
-}
-
-export function isRelayWebhookConflict(error: unknown): error is RelayApiError {
-  return (
-    error instanceof RelayApiError &&
-    error.status === 409 &&
-    error.code !== "terminated_by_other_consumer"
-  );
-}