@relaymessenger/openclaw-plugin 0.3.0 → 0.3.4

package/dist/src/state-files.js

@@ -67,6 +67,80 @@ function lockRetryDelayMs(attempt, remainingMs) {
     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() {
+    const container = globalThis;
+    container[RELAY_STATE_MUTEX_KEY] ??= new Map();
+    return container[RELAY_STATE_MUTEX_KEY];
+}
+function fileLockTimeout(filePath) {
+    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, deadline, filePath) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw fileLockTimeout(filePath);
+    let timer;
+    try {
+        await Promise.race([
+            turn,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(fileLockTimeout(filePath)), remaining);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function withStateFileMutex(filePath, deadline, run) {
+    const mutexes = stateFileMutexes();
+    const previous = mutexes.get(filePath);
+    let release;
+    const ours = new Promise((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) {
     return (isRelayStateLockOwner(value) &&
         value.host === hostname() &&
@@ -112,46 +186,48 @@ export function openRelayStateDocument(params) {
     });
     const withMutationLock = async (run) => {
         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: () => ({
-                        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;
+        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: () => ({
+                            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)));
                 }
-                await new Promise((resolve) => setTimeout(resolve, lockRetryDelayMs(attempt, remaining)));
             }
-        }
+        });
     };
     return {
         filePath: store.filePath,

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

@@ -0,0 +1,163 @@
+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

@@ -0,0 +1,45 @@
+/** 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

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

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

@@ -0,0 +1,39 @@
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relaymessenger/openclaw-plugin",
-  "version": "0.3.0",
+  "version": "0.3.4",
   "description": "Relay channel plugin for OpenClaw. Text your OpenClaw like a friend.",
   "license": "MIT",
   "publishConfig": {