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

package/dist/src/invocations.js

@@ -1,47 +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();
-function slotKey(accountId, conversationId) {
-    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) {
-    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) {
-    return pendingInvocations.get(slotKey(params.accountId, params.conversationId));
-}
-/** Test seam: drop every slot. */
-export function resetRelayInvocationsForTest() {
-    pendingInvocations.clear();
-}

package/dist/src/lifecycle.js

@@ -1,35 +0,0 @@
-/** Owns exactly one abortable long-poll lifecycle per configured account. */
-export function createRelayAccountLifecycleRegistry() {
-    const controllers = new Map();
-    return {
-        acquire(accountId, parentSignal) {
-            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) {
-            const controller = controllers.get(accountId);
-            if (!controller) {
-                return false;
-            }
-            controller.abort();
-            return true;
-        },
-    };
-}

package/dist/src/poll-loop.js

@@ -1,137 +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";
-const TRANSIENT_BASE_DELAY_MS = 500;
-const TRANSIENT_MAX_DELAY_MS = 30_000;
-function defaultSleep(ms, signal) {
-    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) {
-    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/dist/src/responding.js

@@ -1,36 +0,0 @@
-import { RelayApiError } from "./client.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) {
-    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/dist/src/security.js

@@ -1,26 +0,0 @@
-function normalizeSenderId(value) {
-    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) {
-    const allowed = new Set();
-    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, senderId) {
-    return allowedSenderIds.includes(senderId);
-}

package/dist/src/state-files.js

@@ -1,243 +0,0 @@
-import { 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;
-export function emptyRelayStateDocument() {
-    return { version: RELAY_STATE_DOCUMENT_VERSION, entries: {} };
-}
-function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-export function assertRelayStateDocument(value, label, validateEntry) {
-    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) {
-    if (!isRecord(value))
-        return false;
-    return (value.version === RELAY_STATE_LOCK_VERSION &&
-        value.kind === "relay-state" &&
-        Number.isSafeInteger(value.pid) &&
-        value.pid > 0 &&
-        typeof value.host === "string" &&
-        value.host.length > 0 &&
-        typeof value.createdAt === "string" &&
-        Number.isFinite(Date.parse(value.createdAt)));
-}
-function localProcessIsLive(pid) {
-    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) {
-    if (process.platform !== "win32")
-        return false;
-    const code = error?.code;
-    return code === "EACCES" || code === "EPERM";
-}
-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() &&
-        !localProcessIsLive(value.pid));
-}
-function ensurePrivateStateDirectory(path) {
-    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(params) {
-    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({
-        filePath: join(relayStateRoot, params.fileName),
-        dirMode: 0o700,
-        mode: 0o600,
-    });
-    const withMutationLock = async (run) => {
-        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: () => ({
-                            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)),
-    };
-}