@clawling/clawchat-plugin-openclaw 2026.5.12-38 → 2026.5.13-dev.0

package/dist/src/protocol-types.js

@@ -13,6 +13,8 @@ export const EVENT = {
     MESSAGE_FAILED: "message.failed",
     TYPING_UPDATE: "typing.update",
     CHAT_METADATA_INVALIDATED: "chat.metadata.invalidated",
+    NOTIFY_SIGNAL: "notify.signal",
+    REPLAY_DONE: "replay.done",
     OFFLINE_BATCH: "offline.batch",
     OFFLINE_ACK: "offline.ack",
     OFFLINE_DONE: "offline.done",

package/dist/src/runtime.js

@@ -12,7 +12,7 @@ import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.js";
 import { runWithTerminalClawChatSendScope } from "./terminal-send.js";
 import { flushAlignedOutboundQueue, getAlignedOutboundQueueSize, sendOpenclawClawlingText, setAlignedOutboundLogContext, } from "./outbound.js";
 import { formatWsLog } from "./ws-log.js";
-import { createProtocolControlHandler, createReconnectTracker } from "./ws-alignment.js";
+import { createNotifySignalObserver, createProtocolControlHandler, createReconnectTracker } from "./ws-alignment.js";
 import { clawChatDbPathForStateDir, getClawChatStore, } from "./storage.js";
 import { getClawChatGroupPrompt, getClawChatUserPrompt } from "./plugin-prompts.js";
 import { loadClawChatPromptMetadata, renderClawChatProfilePrompt, resolveSenderRelation, } from "./profile-prompt.js";
@@ -641,6 +641,11 @@ export async function startOpenclawClawlingGateway(params) {
         send: () => { },
         context: wsLogContext,
     });
+    const notifySignalObserver = createNotifySignalObserver({
+        accountId,
+        log: (msg) => log?.info?.(msg),
+        context: wsLogContext,
+    });
     const logAuthFailure = (reason) => {
         if (authFailureLogged)
             return;
@@ -863,6 +868,19 @@ export async function startOpenclawClawlingGateway(params) {
     client.on("metadata:invalidated", (env) => {
         void handleMetadataInvalidation(env);
     });
+    client.on("notify:signal", (env) => {
+        // §9.4 reliable system notification. The plugin holds no friend/roster
+        // cache (friends are fetched on demand via REST tools), so there is nothing
+        // to invalidate — observe + dedup only. The live frame and its reliable
+        // inbox replay carry the same event_id and collapse to one observation.
+        notifySignalObserver.observe(env);
+    });
+    client.on("replay:done", (env) => {
+        // §11.5 terminal control frame: device replay drained, live delivery begins.
+        // Fires on every reconnect (even zero-backlog). Replayed messages are
+        // processed inline, so this is a logged boundary marker, not a gate.
+        log?.info?.(`[${accountId}] clawchat-plugin-openclaw replay.done trace=${env.trace_id}`);
+    });
     client.on("error", (err) => {
         const classified = classifyClawlingClientError(err);
         if (classified.kind === "auth") {

package/dist/src/ws-alignment.js

@@ -176,3 +176,70 @@ export function createProtocolControlHandler(options) {
         },
     };
 }
+/**
+ * Observes reliable `notify.signal` frames (§9.4). The agent plugin keeps no
+ * friend/roster cache (friends are fetched on demand via REST tools), so there
+ * is nothing to invalidate — this is a pure observability hook: it dedups by
+ * `event_id` (the live frame and its reliable-inbox replay collapse to one),
+ * structured-logs the signal, and returns the outcome. It deliberately takes no
+ * action on the agent; wire a real reaction here if the product later needs one.
+ */
+export function createNotifySignalObserver(options) {
+    const maxSeen = options.maxSeen ?? 512;
+    const seen = new Set();
+    const order = [];
+    const context = () => options.context?.() ?? { attempt: 1, reconnectCount: 0, state: "ready" };
+    const logSignal = (event, action, fields) => {
+        const current = context();
+        options.log(formatWsLog({
+            event,
+            accountId: options.accountId,
+            attempt: current.attempt,
+            reconnectCount: current.reconnectCount,
+            state: current.state,
+            action,
+            fields,
+        }));
+    };
+    return {
+        /** Returns whether this signal was newly observed, a duplicate, or malformed. */
+        observe(env) {
+            const payload = env.payload && typeof env.payload === "object"
+                ? env.payload
+                : undefined;
+            const eventId = typeof payload?.event_id === "string" ? payload.event_id : "";
+            const type = typeof payload?.type === "string" ? payload.type : "";
+            const entityId = typeof payload?.entity_id === "string" ? payload.entity_id : "";
+            const version = typeof payload?.version === "number" ? payload.version : undefined;
+            if (!eventId || !type) {
+                logSignal("notify_signal_invalid", "ignore", [
+                    ["trace_id", env.trace_id],
+                    ["type", type || null],
+                    ["event_id", eventId || null],
+                ]);
+                return "invalid";
+            }
+            if (seen.has(eventId)) {
+                logSignal("notify_signal_duplicate", "ignore", [
+                    ["type", type],
+                    ["event_id", eventId],
+                ]);
+                return "duplicate";
+            }
+            seen.add(eventId);
+            order.push(eventId);
+            while (order.length > maxSeen) {
+                const evicted = order.shift();
+                if (evicted !== undefined)
+                    seen.delete(evicted);
+            }
+            logSignal("notify_signal_observed", "observe", [
+                ["type", type],
+                ["entity_id", entityId || null],
+                ["version", version ?? null],
+                ["event_id", eventId],
+            ]);
+            return "observed";
+        },
+    };
+}

package/dist/src/ws-client.js

@@ -301,6 +301,10 @@ export class ClawChatClient extends EventEmitter {
             this.emit("typing", env);
         if (env.event === EVENT.CHAT_METADATA_INVALIDATED)
             this.emit("metadata:invalidated", env);
+        if (env.event === EVENT.NOTIFY_SIGNAL)
+            this.emit("notify:signal", env);
+        if (env.event === EVENT.REPLAY_DONE)
+            this.emit("replay:done", env);
         if (env.event === EVENT.OFFLINE_DONE)
             this.emit("offline:done");
     }
@@ -322,7 +326,15 @@ export class ClawChatClient extends EventEmitter {
             token: this.opts.token,
             nonce,
             ...(this.opts.deviceId ? { device_id: this.opts.deviceId } : {}),
-            capabilities: { multi_device: true, device_replay: true, chat_meta_events: true },
+            // Agent runtime is single-device: multi_device stays off so the server
+            // never self-fans-out this connection's own messages. notify_signals is
+            // advertised because we now handle the notify.signal frame (§9.4).
+            capabilities: {
+                multi_device: false,
+                device_replay: true,
+                chat_meta_events: true,
+                notify_signals: true,
+            },
         };
         const traceId = this.nextTraceId();
         this.expectedConnectTraceId = traceId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.5.12-38",
+  "version": "2026.5.13-dev.0",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "files": [

package/src/protocol-types.ts

@@ -13,6 +13,8 @@ export const EVENT = {
   MESSAGE_FAILED: "message.failed",
   TYPING_UPDATE: "typing.update",
   CHAT_METADATA_INVALIDATED: "chat.metadata.invalidated",
+  NOTIFY_SIGNAL: "notify.signal",
+  REPLAY_DONE: "replay.done",
   OFFLINE_BATCH: "offline.batch",
   OFFLINE_ACK: "offline.ack",
   OFFLINE_DONE: "offline.done",
@@ -78,6 +80,11 @@ export interface ConnectCapabilities {
   multi_device?: boolean;
   device_replay?: boolean;
   chat_meta_events?: boolean;
+  delivery_receipt?: boolean;
+  notify_signals?: boolean;
+  permission_events?: boolean;
+  history_sync?: boolean;
+  e2ee?: boolean;
 }
 
 export interface ConnectPayload {
@@ -207,6 +214,25 @@ export interface ChatMetadataInvalidatedPayload {
   updated_at?: number;
 }
 
+/**
+ * Reliable, inbox-coalesced system notification (§9.4). Content-free — only
+ * enough identity to dedup and to decide which REST surface to refetch. The
+ * agent plugin keeps no friend/roster cache, so this is consumed as an
+ * observability signal (see `createNotifySignalObserver`), not a cache refresh.
+ */
+export interface NotifySignalPayload {
+  /** Logical event type the client routes on, e.g. `friend.added`. */
+  type: string;
+  /** Id of the changed entity (meaning depends on `type`). */
+  entity_id: string;
+  /** Monotonic cursor (ms since epoch at mutation time). */
+  version: number;
+  /** Globally-unique id for this signal occurrence — cross-channel dedup key. */
+  event_id: string;
+  /** Inbox coalesce key, formatted `notify:{type}:{entity_id}`. */
+  message_id: string;
+}
+
 export interface StreamCreatedPayload {
   message_id: string;
   message_mode?: string;

package/src/runtime.ts

@@ -35,7 +35,7 @@ import {
   setAlignedOutboundLogContext,
 } from "./outbound.ts";
 import { formatWsLog } from "./ws-log.ts";
-import { createProtocolControlHandler, createReconnectTracker } from "./ws-alignment.ts";
+import { createNotifySignalObserver, createProtocolControlHandler, createReconnectTracker } from "./ws-alignment.ts";
 import {
   clawChatDbPathForStateDir,
   getClawChatStore,
@@ -837,6 +837,11 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     send: () => {},
     context: wsLogContext,
   });
+  const notifySignalObserver = createNotifySignalObserver({
+    accountId,
+    log: (msg) => log?.info?.(msg),
+    context: wsLogContext,
+  });
   const logAuthFailure = (reason: string) => {
     if (authFailureLogged) return;
     authFailureLogged = true;
@@ -1076,6 +1081,21 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     void handleMetadataInvalidation(env);
   });
 
+  client.on("notify:signal", (env: Envelope) => {
+    // §9.4 reliable system notification. The plugin holds no friend/roster
+    // cache (friends are fetched on demand via REST tools), so there is nothing
+    // to invalidate — observe + dedup only. The live frame and its reliable
+    // inbox replay carry the same event_id and collapse to one observation.
+    notifySignalObserver.observe(env);
+  });
+
+  client.on("replay:done", (env: Envelope) => {
+    // §11.5 terminal control frame: device replay drained, live delivery begins.
+    // Fires on every reconnect (even zero-backlog). Replayed messages are
+    // processed inline, so this is a logged boundary marker, not a gate.
+    log?.info?.(`[${accountId}] clawchat-plugin-openclaw replay.done trace=${env.trace_id}`);
+  });
+
   client.on("error", (err: unknown) => {
     const classified = classifyClawlingClientError(err);
     if (classified.kind === "auth") {

package/src/ws-alignment.ts

@@ -273,3 +273,100 @@ export function createProtocolControlHandler(options: CreateProtocolControlHandl
     },
   };
 }
+
+export interface NotifySignalEnvelope {
+  event?: string;
+  trace_id?: string;
+  payload?: unknown;
+}
+
+export interface CreateNotifySignalObserverOptions {
+  accountId: string;
+  log: (msg: string) => void;
+  context?: () => WsLogContext;
+  /** Upper bound on retained event_ids for dedup (FIFO eviction). */
+  maxSeen?: number;
+}
+
+export type NotifySignalOutcome = "observed" | "duplicate" | "invalid";
+
+/**
+ * Observes reliable `notify.signal` frames (§9.4). The agent plugin keeps no
+ * friend/roster cache (friends are fetched on demand via REST tools), so there
+ * is nothing to invalidate — this is a pure observability hook: it dedups by
+ * `event_id` (the live frame and its reliable-inbox replay collapse to one),
+ * structured-logs the signal, and returns the outcome. It deliberately takes no
+ * action on the agent; wire a real reaction here if the product later needs one.
+ */
+export function createNotifySignalObserver(options: CreateNotifySignalObserverOptions) {
+  const maxSeen = options.maxSeen ?? 512;
+  const seen = new Set<string>();
+  const order: string[] = [];
+
+  const context = (): WsLogContext =>
+    options.context?.() ?? { attempt: 1, reconnectCount: 0, state: "ready" };
+
+  const logSignal = (
+    event: string,
+    action: string,
+    fields: Array<[string, string | number | boolean | null | undefined]>,
+  ) => {
+    const current = context();
+    options.log(
+      formatWsLog({
+        event,
+        accountId: options.accountId,
+        attempt: current.attempt,
+        reconnectCount: current.reconnectCount,
+        state: current.state,
+        action,
+        fields,
+      }),
+    );
+  };
+
+  return {
+    /** Returns whether this signal was newly observed, a duplicate, or malformed. */
+    observe(env: NotifySignalEnvelope): NotifySignalOutcome {
+      const payload = env.payload && typeof env.payload === "object"
+        ? env.payload as Record<string, unknown>
+        : undefined;
+      const eventId = typeof payload?.event_id === "string" ? payload.event_id : "";
+      const type = typeof payload?.type === "string" ? payload.type : "";
+      const entityId = typeof payload?.entity_id === "string" ? payload.entity_id : "";
+      const version = typeof payload?.version === "number" ? payload.version : undefined;
+
+      if (!eventId || !type) {
+        logSignal("notify_signal_invalid", "ignore", [
+          ["trace_id", env.trace_id],
+          ["type", type || null],
+          ["event_id", eventId || null],
+        ]);
+        return "invalid";
+      }
+
+      if (seen.has(eventId)) {
+        logSignal("notify_signal_duplicate", "ignore", [
+          ["type", type],
+          ["event_id", eventId],
+        ]);
+        return "duplicate";
+      }
+
+      seen.add(eventId);
+      order.push(eventId);
+      while (order.length > maxSeen) {
+        const evicted = order.shift();
+        if (evicted !== undefined) seen.delete(evicted);
+      }
+
+      logSignal("notify_signal_observed", "observe", [
+        ["type", type],
+        ["entity_id", entityId || null],
+        ["version", version ?? null],
+        ["event_id", eventId],
+      ]);
+      return "observed";
+    },
+  };
+}

package/src/ws-client.ts

@@ -369,6 +369,8 @@ export class ClawChatClient extends EventEmitter {
     if (env.event === EVENT.MESSAGE_FAILED) this.emit("message:failed", env);
     if (env.event === EVENT.TYPING_UPDATE) this.emit("typing", env);
     if (env.event === EVENT.CHAT_METADATA_INVALIDATED) this.emit("metadata:invalidated", env);
+    if (env.event === EVENT.NOTIFY_SIGNAL) this.emit("notify:signal", env);
+    if (env.event === EVENT.REPLAY_DONE) this.emit("replay:done", env);
     if (env.event === EVENT.OFFLINE_DONE) this.emit("offline:done");
   }
 
@@ -389,7 +391,15 @@ export class ClawChatClient extends EventEmitter {
       token: this.opts.token,
       nonce,
       ...(this.opts.deviceId ? { device_id: this.opts.deviceId } : {}),
-      capabilities: { multi_device: true, device_replay: true, chat_meta_events: true },
+      // Agent runtime is single-device: multi_device stays off so the server
+      // never self-fans-out this connection's own messages. notify_signals is
+      // advertised because we now handle the notify.signal frame (§9.4).
+      capabilities: {
+        multi_device: false,
+        device_replay: true,
+        chat_meta_events: true,
+        notify_signals: true,
+      },
     };
     const traceId = this.nextTraceId();
     this.expectedConnectTraceId = traceId;

package/dist/src/buffered-stream.js

@@ -1,177 +0,0 @@
-import { emitStreamAdd, emitStreamCreated, emitStreamDone, emitStreamFailed, } from "./client.js";
-/**
- * Merge two views of the same progressively-revealed text.
- *
- * The agent runner may give us either:
- *   - full snapshots   ("Hel", "Hello", "Hello, world") where each item is
- *     a superset of the previous; or
- *   - overlapping slices ("hello ", "world hello ") that don't share a
- *     prefix but share an overlap at the join.
- *
- * This helper returns a longest-sensible combined string. Ported from
- * `clawling-channel/src/reply-dispatcher.ts`.
- */
-export function mergeStreamingText(previousText, nextText) {
-    const currentSnapshot = typeof previousText === "string" ? previousText : "";
-    const incomingText = typeof nextText === "string" ? nextText : "";
-    if (!incomingText)
-        return currentSnapshot;
-    if (!currentSnapshot || incomingText === currentSnapshot)
-        return incomingText;
-    if (incomingText.startsWith(currentSnapshot))
-        return incomingText;
-    if (currentSnapshot.startsWith(incomingText))
-        return currentSnapshot;
-    if (incomingText.includes(currentSnapshot))
-        return incomingText;
-    if (currentSnapshot.includes(incomingText))
-        return currentSnapshot;
-    const maxOverlap = Math.min(currentSnapshot.length, incomingText.length);
-    for (let overlap = maxOverlap; overlap > 0; overlap -= 1) {
-        if (currentSnapshot.slice(-overlap) === incomingText.slice(0, overlap)) {
-            return `${currentSnapshot}${incomingText.slice(overlap)}`;
-        }
-    }
-    return `${currentSnapshot}${incomingText}`;
-}
-function resolveRouting(options) {
-    if (options.routing)
-        return options.routing;
-    if (options.to)
-        return { chatId: options.to.id, chatType: options.to.type };
-    throw new Error("openclaw-clawchat buffered stream requires routing");
-}
-/**
- * Build a streaming session wrapper around message.created/add/done events.
- *
- * Usage pattern (matching clawling-channel):
- *   const session = openBufferedStreamingSession({...});
- *   await session.queueSnapshot("Hel");
- *   await session.queueSnapshot("Hello");
- *   await session.queueDelta(", world");
- *   await session.done();
- */
-export function openBufferedStreamingSession(options) {
-    const routing = resolveRouting(options);
-    const emitTyping = options.emitTyping !== false;
-    if (emitTyping)
-        options.client.typing(routing.chatId, true);
-    emitStreamCreated(options.client, {
-        messageId: options.messageId,
-        routing,
-    });
-    let bufferedSnapshot = "";
-    let flushedSnapshot = "";
-    let sequence = -1;
-    let flushTimer = null;
-    let pendingFlush = Promise.resolve();
-    let closed = false;
-    const clearTimer = () => {
-        if (flushTimer) {
-            clearTimeout(flushTimer);
-            flushTimer = null;
-        }
-    };
-    const performFlush = async () => {
-        clearTimer();
-        if (closed)
-            return;
-        if (bufferedSnapshot === flushedSnapshot)
-            return;
-        const snapshot = bufferedSnapshot;
-        const delta = snapshot.slice(flushedSnapshot.length);
-        if (!delta)
-            return;
-        sequence += 1;
-        emitStreamAdd(options.client, {
-            messageId: options.messageId,
-            routing,
-            sequence,
-            fullText: snapshot,
-            textDelta: delta,
-        });
-        flushedSnapshot = snapshot;
-    };
-    const flush = async () => {
-        pendingFlush = pendingFlush.then(performFlush);
-        await pendingFlush;
-    };
-    const scheduleFlush = () => {
-        if (flushTimer || closed)
-            return;
-        flushTimer = setTimeout(() => {
-            flushTimer = null;
-            void flush();
-        }, options.flushIntervalMs);
-    };
-    const queueSnapshot = async (snapshot) => {
-        if (closed || !snapshot)
-            return;
-        const base = bufferedSnapshot.length >= flushedSnapshot.length ? bufferedSnapshot : flushedSnapshot;
-        const merged = mergeStreamingText(base, snapshot);
-        if (merged === bufferedSnapshot)
-            return;
-        bufferedSnapshot = merged;
-        const deltaChars = Math.max(0, bufferedSnapshot.length - flushedSnapshot.length);
-        if (deltaChars >= options.minChunkChars || bufferedSnapshot.length >= options.maxBufferChars) {
-            await flush();
-        }
-        else {
-            scheduleFlush();
-        }
-    };
-    const queueDelta = async (delta) => {
-        if (closed || !delta)
-            return;
-        bufferedSnapshot = `${bufferedSnapshot}${delta}`;
-        const deltaChars = Math.max(0, bufferedSnapshot.length - flushedSnapshot.length);
-        if (deltaChars >= options.minChunkChars || bufferedSnapshot.length >= options.maxBufferChars) {
-            await flush();
-        }
-        else {
-            scheduleFlush();
-        }
-    };
-    const done = async () => {
-        if (closed)
-            return;
-        await flush();
-        closed = true;
-        clearTimer();
-        emitStreamDone(options.client, {
-            messageId: options.messageId,
-            routing,
-            finalSequence: Math.max(sequence, 0),
-            finalText: bufferedSnapshot,
-        });
-        if (emitTyping)
-            options.client.typing(routing.chatId, false);
-    };
-    const fail = async (reason) => {
-        if (closed)
-            return;
-        closed = true;
-        clearTimer();
-        emitStreamFailed(options.client, {
-            messageId: options.messageId,
-            routing,
-            sequence: Math.max(sequence, 0),
-            ...(reason !== undefined ? { reason } : {}),
-        });
-        if (emitTyping)
-            options.client.typing(routing.chatId, false);
-    };
-    return {
-        get currentText() {
-            return bufferedSnapshot;
-        },
-        get flushedText() {
-            return flushedSnapshot;
-        },
-        queueSnapshot,
-        queueDelta,
-        flush,
-        done,
-        fail,
-    };
-}

package/dist/src/streaming.js

@@ -1,65 +0,0 @@
-import { emitStreamAdd, emitStreamCreated, emitStreamDone, emitStreamFailed, } from "./client.js";
-function resolveRouting(params) {
-    if (params.routing)
-        return params.routing;
-    if (params.to)
-        return { chatId: params.to.id, chatType: params.to.type };
-    throw new Error("openclaw-clawchat streaming requires routing");
-}
-/**
- * Emit one full streaming lifecycle for a pre-chunked reply.
- *
- * Sequence:
- *   typing(true)
- *   message.created   (sequence 0)
- *   message.add       (sequence 1..N, one per chunk)
- *   message.done      (sequence N)
- *   typing(false)
- *
- * With zero chunks: typing(true) -> created -> done -> typing(false).
- */
-export async function sendStreamingText(params) {
-    const routing = resolveRouting(params);
-    const emitTyping = params.emitTyping !== false;
-    if (emitTyping) {
-        params.client.typing(routing.chatId, true);
-    }
-    emitStreamCreated(params.client, {
-        messageId: params.messageId,
-        routing,
-    });
-    let sequence = -1;
-    let fullText = "";
-    for (const chunk of params.chunks) {
-        sequence += 1;
-        fullText += chunk;
-        emitStreamAdd(params.client, {
-            messageId: params.messageId,
-            routing,
-            sequence,
-            fullText,
-            textDelta: chunk,
-        });
-    }
-    emitStreamDone(params.client, {
-        messageId: params.messageId,
-        routing,
-        finalSequence: Math.max(sequence, 0),
-        finalText: fullText,
-    });
-    if (emitTyping) {
-        params.client.typing(routing.chatId, false);
-    }
-}
-export async function sendStreamingFailure(params) {
-    const routing = resolveRouting(params);
-    emitStreamFailed(params.client, {
-        messageId: params.messageId,
-        routing,
-        sequence: params.currentSequence,
-        reason: params.reason,
-    });
-    if (params.emitTyping !== false) {
-        params.client.typing(routing.chatId, false);
-    }
-}