@relaymessenger/openclaw-plugin 0.3.0 → 0.3.4

package/src/channel.ts

@@ -42,6 +42,7 @@ import { createRelayCursorStore, openRelayCursorStateStore } from "./cursor-stor
 import { createRelayInboundDedupeGuard, createRelayInboundDeduper } from "./inbound-dedupe.js";
 import { buildRelayInboundFacts } from "./inbound.js";
 import type { RelayInboundFacts } from "./inbound.js";
+import { relayInvocationFor, rememberRelayInvocation } from "./invocations.js";
 import { createRelayAccountLifecycleRegistry } from "./lifecycle.js";
 import {
   deriveRelayIdempotencyKey,
@@ -50,6 +51,7 @@ import {
   sendRelayText,
 } from "./outbound.js";
 import { runRelayPollLoop } from "./poll-loop.js";
+import { markRespondingBeforeAttempt } from "./responding.js";
 import { getRelayRuntime } from "./runtime.js";
 import { relaySenderIsAllowed, resolveRelayAllowedSenderIds } from "./security.js";
 import type { RelayCoreConfig, ResolvedRelayAccount } from "./types.js";
@@ -137,11 +139,16 @@ const relayMessageAdapter = defineChannelMessageAdapter({
       if (text === null) {
         return null;
       }
+      const invocationId = relayInvocationFor({
+        accountId: account.accountId,
+        conversationId: ctx.to,
+      });
       const verdict = await reconcileRelayUnknownSend({
         client: relayClientForAccount(account),
         conversationId: ctx.to,
         text,
         replyToId: ctx.effectiveReplyToId ?? ctx.replyToId ?? null,
+        ...(invocationId ? { invocationId } : {}),
         idempotencyKey: deriveRelayIdempotencyKey({ deliveryQueueId: ctx.queueId }),
       });
       if (verdict.status === "sent") {
@@ -170,11 +177,19 @@ const relayMessageAdapter = defineChannelMessageAdapter({
       if (!account.configured) {
         throw new Error(`relay: account "${account.accountId}" has no Agent Token configured`);
       }
+      // A group reply must name the invocation it answers. Core's send context
+      // has no field for it, so the turn parks it in the invocation registry
+      // under (accountId, conversationId) and it is read back here.
+      const invocationId = relayInvocationFor({
+        accountId: account.accountId,
+        conversationId: ctx.to,
+      });
       const result = await sendRelayText({
         client: relayClientForAccount(account),
         conversationId: ctx.to,
         text: ctx.text,
         replyToId: ctx.replyToId ?? null,
+        ...(invocationId ? { invocationId } : {}),
         // Stable per (queueId, part): internal retries replay the same key,
         // so the server-side idempotent commit makes duplicates impossible by
         // contract. On a core with no part index the text names the part.
@@ -217,6 +232,7 @@ async function dispatchRelayInbound(params: {
   client: RelayClient;
   allowedSenderIds: readonly string[];
   markAttempt: () => Promise<void>;
+  warn?: (line: string) => void;
 }): Promise<void> {
   const { account, facts } = params;
   // Public Relay agents are discoverable, so contact membership is not an
@@ -283,76 +299,97 @@ async function dispatchRelayInbound(params: {
   const recordDeliveryError = (error: unknown) => {
     deliveryError ??= error;
   };
-  // Admission, runtime resolution, route/session lookup, envelope building,
-  // and context finalization above are replay-safe. The durable attempt starts
-  // immediately before OpenClaw can invoke the agent or its tools.
-  await params.markAttempt();
-  await runtime.channel.inbound.dispatchReply({
-    cfg: params.cfg,
-    channel: RELAY_CHANNEL_ID,
-    accountId: account.accountId,
-    agentId: route.agentId,
-    routeSessionKey: route.sessionKey,
-    storePath,
-    ctxPayload,
-    recordInboundSession: runtime.channel.session.recordInboundSession,
-    dispatchReplyWithBufferedBlockDispatcher:
-      runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher,
-    delivery: {
-      // Final replies go through the durable message adapter: core renders
-      // and chunks them (chunker + textChunkLimit) and tracks the send as a
-      // durable queue intent. Requiring reconcileUnknownSend forces
-      // `durability: "required"`, so single-payload finals carry a stable
-      // deliveryQueueId into send.text (stable idempotency key + exact
-      // replay), and multi-chunk finals get core's queue-level crash
-      // recovery. Replies land as plain messages, not quotes
-      // (`replyToId: null`).
-      durable: {
-        to: facts.conversationId,
-        replyToId: null,
-        requiredCapabilities: { reconcileUnknownSend: true },
-      },
-      // Fallback for payloads the durable path does not carry (non-final
-      // visible blocks). The event id + block/chunk ordinals identify each
-      // logical send: retries reuse it while identical intentional blocks and
-      // chunks remain distinct.
-      deliver: async (payload) => {
-        const text =
-          payload && typeof payload === "object" && "text" in payload
-            ? ((payload as { text?: string }).text ?? "")
-            : "";
-        if (!text.trim()) {
-          return;
-        }
-        const logicalBlockId = `${facts.eventId}:block:${fallbackDeliveryIndex}`;
-        fallbackDeliveryIndex += 1;
-        try {
-          let chunkIndex = 0;
-          for (const chunk of chunkText(text, RELAY_TEXT_CHUNK_LIMIT)) {
-            await sendRelayText({
-              client: params.client,
-              conversationId: facts.conversationId,
-              text: chunk,
-              idempotencyKey: deriveRelayIdempotencyKey({
-                deliveryQueueId: logicalBlockId,
-                deliveryPartIndex: chunkIndex,
-              }),
-            });
-            chunkIndex += 1;
+  // Park the group invocation for the life of the turn. Core's durable send
+  // adapter is a separate entry point with no inbound context, so this is how
+  // the reply learns which invocation it answers.
+  const releaseInvocation = facts.invocationId
+    ? rememberRelayInvocation({
+      accountId: account.accountId,
+      conversationId: facts.conversationId,
+      invocationId: facts.invocationId,
+    })
+    : () => {};
+  try {
+    // Admission, runtime resolution, route/session lookup, envelope building,
+    // and context finalization above are replay-safe. The durable attempt starts
+    // immediately before OpenClaw can invoke the agent or its tools.
+    await markRespondingBeforeAttempt({
+      client: params.client,
+      facts,
+      label: "OpenClaw",
+      markAttempt: params.markAttempt,
+      ...(params.warn ? { onReceiptFailure: params.warn } : {}),
+    });
+    await runtime.channel.inbound.dispatchReply({
+      cfg: params.cfg,
+      channel: RELAY_CHANNEL_ID,
+      accountId: account.accountId,
+      agentId: route.agentId,
+      routeSessionKey: route.sessionKey,
+      storePath,
+      ctxPayload,
+      recordInboundSession: runtime.channel.session.recordInboundSession,
+      dispatchReplyWithBufferedBlockDispatcher:
+        runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher,
+      delivery: {
+        // Final replies go through the durable message adapter: core renders
+        // and chunks them (chunker + textChunkLimit) and tracks the send as a
+        // durable queue intent. Requiring reconcileUnknownSend forces
+        // `durability: "required"`, so single-payload finals carry a stable
+        // deliveryQueueId into send.text (stable idempotency key + exact
+        // replay), and multi-chunk finals get core's queue-level crash
+        // recovery. Replies land as plain messages, not quotes
+        // (`replyToId: null`).
+        durable: {
+          to: facts.conversationId,
+          replyToId: null,
+          requiredCapabilities: { reconcileUnknownSend: true },
+        },
+        // Fallback for payloads the durable path does not carry (non-final
+        // visible blocks). The event id + block/chunk ordinals identify each
+        // logical send: retries reuse it while identical intentional blocks and
+        // chunks remain distinct.
+        deliver: async (payload) => {
+          const text =
+            payload && typeof payload === "object" && "text" in payload
+              ? ((payload as { text?: string }).text ?? "")
+              : "";
+          if (!text.trim()) {
+            return;
           }
-        } catch (error) {
-          recordDeliveryError(error);
-          throw error;
-        }
+          const logicalBlockId = `${facts.eventId}:block:${fallbackDeliveryIndex}`;
+          fallbackDeliveryIndex += 1;
+          try {
+            let chunkIndex = 0;
+            for (const chunk of chunkText(text, RELAY_TEXT_CHUNK_LIMIT)) {
+              await sendRelayText({
+                client: params.client,
+                conversationId: facts.conversationId,
+                text: chunk,
+                ...(facts.invocationId ? { invocationId: facts.invocationId } : {}),
+                idempotencyKey: deriveRelayIdempotencyKey({
+                  deliveryQueueId: logicalBlockId,
+                  deliveryPartIndex: chunkIndex,
+                }),
+              });
+              chunkIndex += 1;
+            }
+          } catch (error) {
+            recordDeliveryError(error);
+            throw error;
+          }
+        },
+        onError: recordDeliveryError,
       },
-      onError: recordDeliveryError,
-    },
-    replyPipeline: {},
-  });
-  if (deliveryError) {
-    throw deliveryError instanceof Error
-      ? deliveryError
-      : new Error(`relay reply delivery failed: ${String(deliveryError)}`);
+      replyPipeline: {},
+    });
+    if (deliveryError) {
+      throw deliveryError instanceof Error
+        ? deliveryError
+        : new Error(`relay reply delivery failed: ${String(deliveryError)}`);
+    }
+  } finally {
+    releaseInvocation();
   }
 }
 
@@ -491,19 +528,19 @@ async function startRelayAccount(ctx: ChannelGatewayContext<ResolvedRelayAccount
           client,
           allowedSenderIds,
           markAttempt,
+          warn,
         });
-        // Read watermark after the turn is handled: read implies delivered;
-        // best effort — a failed receipt must not replay the event.
-        await client
-          .markRead({ conversationId: facts.conversationId, messageId: facts.messageId })
-          .catch((error) => log(`[relay] markRead failed: ${String(error)}`));
       },
     });
   } catch (error) {
     if (abortSignal.aborted || isAbortError(error)) {
       return;
     }
-    if (error instanceof RelayApiError && error.terminal) {
+    // Named as `kind === "auth"`, not `error.terminal`. The SDK client counts
+    // every non-retryable kind as terminal, which would swallow the 409 cases
+    // below — including `terminated_by_other_consumer`, whose whole point is
+    // to fall through to the supervisor's restart arbitration.
+    if (error instanceof RelayApiError && error.kind === "auth") {
       markTerminalDisconnect(error);
     } else if (isRelayWebhookConflict(error)) {
       // Webhook XOR: long polling stays 409 until the operator

package/src/client.ts

@@ -1,313 +1,51 @@
-// Thin Relay REST client for the OpenClaw channel plugin. Bespoke fetch until
-// the Relay SDK ships. Owns the abort-aware long poll, idempotent
-// sends, typing, and read watermarks. No SDK imports so unit tests run
-// without an OpenClaw runtime.
-import { isIP } from "node:net";
-import type {
-  RelayAgentProfile,
-  RelayEventsPage,
-  RelayPart,
-  RelayReplyRef,
-  RelaySendResult,
-} from "./types.js";
-
-export const DEFAULT_RELAY_BASE_URL = "https://api.relayapp.im";
-
-function isLoopbackHostname(hostname: string): boolean {
-  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")
-  );
-}
-
+// 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";
 /**
- * Validate and canonicalize the API origin before a bearer token can be sent
- * to it. Production/custom remote origins must use HTTPS. Plain HTTP remains
- * available only for an explicit loopback development server.
+ * 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 function normalizeRelayBaseUrl(raw?: string): string {
-  const candidate = raw?.trim() || DEFAULT_RELAY_BASE_URL;
-  let url: 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;
-}
-
-export type RelayApiErrorKind = "auth" | "conflict" | "retryable" | "rejected";
-
-/** Classified Relay API failure. `terminal` means operator action (bad token). */
-export class RelayApiError extends Error {
-  readonly status: number | undefined;
-  readonly kind: RelayApiErrorKind;
-  /** Server error code from the response body (`error.code`), when present. */
-  readonly code: string | undefined;
-
-  constructor(
-    message: string,
-    params: { status?: number; kind: RelayApiErrorKind; code?: string },
-  ) {
-    super(message);
-    this.name = "RelayApiError";
-    this.status = params.status;
-    this.kind = params.kind;
-    this.code = params.code;
-  }
-
-  get terminal(): boolean {
-    return this.kind === "auth";
-  }
-
-  get retryable(): boolean {
-    return this.kind === "retryable";
-  }
-}
+export type { RelayMessage as RelaySentMessage } from "./vendor/relay-sdk/types.js";
 
 /**
- * 409 from the webhook XOR rule: an enabled webhook endpoint makes long
- * polling unavailable until the operator disables it (server code
- * `conflict`, distinct from `terminated_by_other_consumer`).
+ * 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 function isRelayWebhookConflict(error: unknown): error is RelayApiError {
-  return (
-    error instanceof RelayApiError &&
-    error.status === 409 &&
-    error.code !== "terminated_by_other_consumer"
-  );
-}
-
-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";
-}
-
-type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
-
-export type RelayClientOptions = {
-  baseUrl?: string;
-  token: string;
-  fetchImpl?: FetchLike;
-  /** Bounds non-poll API operations; long polls use hold time plus slack. */
-  requestTimeoutMs?: number;
-};
-
-export type RelayClient = {
-  getMe: (params?: { signal?: AbortSignal }) => Promise<RelayAgentProfile>;
+export type RelayClient = Omit<VendoredRelayClient, "pollEvents"> & {
   pollEvents: (params: {
     cursor: number;
     timeoutSeconds?: number;
     limit?: number;
     signal?: AbortSignal;
   }) => Promise<RelayEventsPage>;
-  sendMessage: (params: {
-    conversationId: string;
-    parts: Array<Pick<RelayPart, never> & Record<string, unknown>>;
-    replyTo?: RelayReplyRef;
-    idempotencyKey: string;
-    signal?: AbortSignal;
-  }) => Promise<RelaySendResult>;
-  setTyping: (params: {
-    conversationId: string;
-    started: boolean;
-    label?: 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 }> {
-  try {
-    const body = (await response.json()) as {
-      error?: { code?: string; message?: string };
-      message?: string;
-    };
-    return {
-      ...(body?.error?.code ? { code: body.error.code } : {}),
-      message: body?.error?.message ?? body?.message ?? "",
-    };
-  } catch {
-    return { message: "" };
-  }
-}
-
-export function createRelayClient(options: RelayClientOptions): RelayClient {
-  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));
-      }
-    }
-    let response: Response;
-    const timeoutSignal = AbortSignal.timeout(params.timeoutMs ?? requestTimeoutMs);
-    const signal = params.signal
-      ? AbortSignal.any([params.signal, timeoutSignal])
-      : timeoutSignal;
-    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;
-      }
-      // Network-level failure (DNS, reset, offline): always retryable.
-      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 } : {}),
-        },
-      );
-    }
-    return response;
-  };
-
-  return {
-    getMe: async (params) => {
-      const response = await request({
-        method: "GET",
-        path: "/v1/agents/me",
-        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);
-      // Guard against a wedged connection: the server holds <= timeout seconds,
-      // so anything past timeout + slack is a dead socket, not a slow poll.
-      const response = await request({
-        method: "GET",
-        path: "/v1/events",
-        query: {
-          cursor: params.cursor,
-          timeout: timeoutSeconds,
-          ...(params.limit === undefined ? {} : { limit: params.limit }),
-        },
-        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.replyTo ? { reply_to: params.replyTo } : {}),
-        },
-        signal: params.signal,
-      });
-      const body = (await response.json()) as {
-        messages: RelaySendResult["messages"];
-      };
-      return { messages: body.messages };
-    },
-
-    setTyping: async (params) => {
-      await request({
-        method: "POST",
-        path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/typing`,
-        body: {
-          started: params.started,
-          ...(params.label ? { label: params.label } : {}),
-        },
-        signal: params.signal,
-      });
-    },
-
-    markRead: async (params) => {
-      await request({
-        method: "POST",
-        path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/read`,
-        body: { message_id: params.messageId },
-        signal: params.signal,
-      });
-    },
-  };
-}
+export const createRelayClient = createVendoredRelayClient as (
+  options: Parameters<typeof createVendoredRelayClient>[0],
+) => RelayClient;

package/src/inbound.ts

@@ -86,6 +86,12 @@ export type RelayInboundFacts = {
   replyToId?: string;
   text: string;
   timestamp?: number;
+  /**
+   * The group invocation this message belongs to, when it is group work.
+   * Every subsequent server call about this message must carry it back, and
+   * because only a group mints one, its presence is also the group signal.
+   */
+  invocationId?: string;
 };
 
 /**
@@ -115,6 +121,10 @@ export function buildRelayInboundFacts(
     return null;
   }
   const createdAtMs = Date.parse(message.created_at);
+  const invocationId = typeof event.data.invocation_id === "string"
+    && event.data.invocation_id.trim()
+    ? event.data.invocation_id
+    : undefined;
   return {
     eventId: event.event_id,
     messageId: message.id,
@@ -124,5 +134,6 @@ export function buildRelayInboundFacts(
     ...(message.reply_to?.message_id ? { replyToId: message.reply_to.message_id } : {}),
     text,
     ...(Number.isFinite(createdAtMs) ? { timestamp: createdAtMs } : {}),
+    ...(invocationId ? { invocationId } : {}),
   };
 }