@relaymessenger/openclaw-plugin 0.3.0 → 0.3.4

package/src/invocations.ts

@@ -0,0 +1,58 @@
+/**
+ * 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/outbound.ts

@@ -4,8 +4,7 @@
 // (server contract: commitMessage.ts idempotent replay).
 import { createHash } from "node:crypto";
 import { RelayApiError } from "./client.js";
-import type { RelayClient } from "./client.js";
-import type { RelayMessage } from "./types.js";
+import type { RelayClient, RelaySentMessage } from "./client.js";
 
 /**
  * Per-part text ceiling declared to core's renderer so long agent replies are
@@ -72,7 +71,7 @@ export type RelayOutboundSendResult = {
    * commits exactly one, but the 202 is always an array and the receipt
    * should name everything the server stored.
    */
-  messages: RelayMessage[];
+  messages: RelaySentMessage[];
 };
 
 export async function sendRelayText(params: {
@@ -80,6 +79,11 @@ export async function sendRelayText(params: {
   conversationId: string;
   text: string;
   replyToId?: string | null;
+  /**
+   * Required when replying into a group: the server refuses an agent's group
+   * message that does not name the invocation it is answering.
+   */
+  invocationId?: string;
   idempotencyKey: string;
   signal?: AbortSignal;
 }): Promise<RelayOutboundSendResult> {
@@ -90,6 +94,7 @@ export async function sendRelayText(params: {
         conversationId: params.conversationId,
         parts: [{ type: "text", text: params.text }],
         ...(params.replyToId ? { replyTo: { message_id: params.replyToId } } : {}),
+        ...(params.invocationId ? { invocationId: params.invocationId } : {}),
         idempotencyKey: params.idempotencyKey,
         ...(params.signal ? { signal: params.signal } : {}),
       });
@@ -109,7 +114,7 @@ export async function sendRelayText(params: {
 }
 
 export type RelayUnknownSendVerdict =
-  | { status: "sent"; messageId: string; messages: RelayMessage[] }
+  | { status: "sent"; messageId: string; messages: RelaySentMessage[] }
   | { status: "not_sent" }
   | { status: "unresolved"; error?: string; retryable?: boolean };
 
@@ -125,6 +130,7 @@ export async function reconcileRelayUnknownSend(params: {
   conversationId: string;
   text: string;
   replyToId?: string | null;
+  invocationId?: string;
   idempotencyKey: string;
 }): Promise<RelayUnknownSendVerdict> {
   try {
@@ -133,6 +139,7 @@ export async function reconcileRelayUnknownSend(params: {
       conversationId: params.conversationId,
       text: params.text,
       replyToId: params.replyToId ?? null,
+      ...(params.invocationId ? { invocationId: params.invocationId } : {}),
       idempotencyKey: params.idempotencyKey,
     });
     return { status: "sent", messageId: result.messageId, messages: result.messages };

package/src/poll-loop.ts

@@ -130,6 +130,18 @@ export async function runRelayPollLoop(params: RelayPollLoopParams): Promise<voi
         } 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;

package/src/responding.ts

@@ -0,0 +1,52 @@
+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/state-files.ts

@@ -95,6 +95,89 @@ function lockRetryDelayMs(attempt: number, remainingMs: number): number {
   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) &&
@@ -147,53 +230,56 @@ export function openRelayStateDocument<T>(params: {
   });
   const withMutationLock = async <R>(run: () => Promise<R>): Promise<R> => {
     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,
+    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),
             },
-            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;
+            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 {

package/src/types.ts

@@ -3,7 +3,10 @@
 // { events, next_cursor }, cursor N acknowledges everything <= N.
 
 export type RelaySender = {
-  kind: "user" | "agent";
+  // `system` is real on the wire: a group's own notices are authored by it
+  // (creating a group commits "<name> created <title>"). Only `user` messages
+  // start a turn, and `buildRelayInboundFacts` drops everything else.
+  kind: "user" | "agent" | "system";
   id: string;
 };
 
@@ -105,6 +108,17 @@ export type RelayEvent = {
   created_at: string;
   data: {
     message?: RelayMessage;
+    /**
+     * Present only when this event belongs to a group invocation: a human
+     * mentioned the agent, replied to it, or picked it. In a group the server
+     * delivers nothing to an agent that was not invoked, and every call the
+     * agent then makes about the message must carry this id back
+     * (`/typing`, `/responding`, and the reply itself all refuse without it).
+     * A direct message never carries one — the server rejects
+     * `invoked_agent_ids` outside a group — so its presence is also how the
+     * plugin knows it is in a group.
+     */
+    invocation_id?: string;
     [key: string]: unknown;
   };
 };

package/src/vendor/relay-sdk/README.md

@@ -0,0 +1,28 @@
+# 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.