@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/protocol-types.typecheck.ts

@@ -0,0 +1,89 @@
+import type {
+  ConnectPayload,
+  EmptyPayload,
+  Envelope,
+  Fragment,
+  MessagePayload,
+  OfflineBatchPayload,
+  ProtocolFragment,
+  Sender,
+  StreamAddPayload,
+  StreamDonePayload,
+} from "./protocol-types.ts";
+
+type Assert<T extends true> = T;
+type IsAssignable<From, To> = [From] extends [To] ? true : false;
+type IsEqual<Actual, Expected> =
+  (<T>() => T extends Actual ? 1 : 2) extends <T>() => T extends Expected ? 1 : 2
+    ? true
+    : false;
+type Not<T extends boolean> = T extends true ? false : true;
+
+type _SenderRequiresType = Assert<
+  Not<IsAssignable<{ id: string; nick_name: string }, Sender>>
+>;
+
+type _MaterializedMessageIdMayBeOmittedOnUplink = Assert<
+  IsAssignable<
+    { message_mode: string; message: MessagePayload["message"] },
+    MessagePayload
+  >
+>;
+
+type _KnownTextFragmentRequiresText = Assert<
+  Not<IsAssignable<{ kind: "text" }, Fragment>>
+>;
+
+type _KnownMentionFragmentRequiresUserId = Assert<
+  Not<IsAssignable<{ kind: "mention" }, Fragment>>
+>;
+
+type _UnknownWireFragmentsAreRepresentable = Assert<
+  IsAssignable<{ kind: "sticker"; sticker_id: string }, ProtocolFragment>
+>;
+
+type _MaterializedMessageBodyUsesWireFragments = Assert<
+  IsEqual<MessagePayload["message"]["body"]["fragments"], Fragment[]>
+>;
+
+type _MaterializedMessageRejectsMalformedKnownFragments = Assert<
+  Not<
+    IsAssignable<
+      {
+        message_mode: string;
+        message: {
+          body: { fragments: [{ kind: "text" }] };
+          context: MessagePayload["message"]["context"];
+        };
+      },
+      MessagePayload
+    >
+  >
+>;
+
+type _StreamCompletionUsesWireFragments = Assert<
+  IsEqual<StreamDonePayload["fragments"], Fragment[]>
+>;
+
+type _StreamCompletionPayloadIsFlat = Assert<
+  Not<"message" extends keyof StreamDonePayload ? true : false>
+>;
+
+type _ConnectPayloadAllowsCanonicalMinimum = Assert<
+  IsAssignable<{ token: string; nonce: string }, ConnectPayload>
+>;
+
+type _StreamAddPayloadAllowsCanonicalMinimum = Assert<
+  IsAssignable<
+    { message_id: string; sequence: number; fragments: Fragment[] },
+    StreamAddPayload
+  >
+>;
+
+type _OfflineBatchPayloadCarriesEnvelopes = Assert<
+  IsAssignable<{ batch_id: number; items: Envelope[]; remaining: number }, OfflineBatchPayload>
+>;
+
+type _ControlPayloadsAreEmptyObjects = Assert<
+  IsAssignable<Record<string, never>, EmptyPayload>
+>;

package/src/protocol.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { isInboundMessagePayload, hasRenderableText } from "./protocol.ts";
+
+describe("clawchat-plugin-openclaw protocol guards", () => {
+  it("accepts a well-formed downlink message payload", () => {
+    const payload = {
+      message_id: "m1",
+      message_mode: "normal",
+      message: {
+        body: { fragments: [{ kind: "text", text: "hi" }] },
+        context: { mentions: [], reply: null },
+        streaming: {
+          status: "static",
+          sequence: 0,
+          mutation_policy: "sealed",
+          started_at: null,
+          completed_at: null,
+        },
+      },
+    };
+    expect(isInboundMessagePayload(payload)).toBe(true);
+  });
+
+  it("rejects payload missing message_id", () => {
+    expect(isInboundMessagePayload({ message: { body: { fragments: [] } } })).toBe(false);
+  });
+
+  it("rejects payload missing message", () => {
+    expect(isInboundMessagePayload({ message_id: "m1" })).toBe(false);
+  });
+
+  it("detects renderable text", () => {
+    expect(hasRenderableText({ body: { fragments: [{ kind: "text", text: "hi" }] } })).toBe(true);
+    expect(hasRenderableText({ body: { fragments: [{ kind: "image", url: "x" }] } })).toBe(true);
+    expect(hasRenderableText({ body: { fragments: [{ kind: "file", url: "x" }] } })).toBe(true);
+    expect(hasRenderableText({ body: { fragments: [{ kind: "text", text: "  " }] } })).toBe(false);
+    expect(hasRenderableText({ body: { fragments: [{ kind: "image" }] } })).toBe(false);
+  });
+});

package/src/protocol.ts

@@ -0,0 +1,42 @@
+/**
+ * Local narrow guards for inbound protocol envelopes.
+ *
+ * Raw client events hand us `Envelope<unknown>`. Before casting the
+ * payload to `MessagePayload` we run these cheap structural checks
+ * so runtime errors surface as skipped messages, not crashes.
+ */
+
+export function isInboundMessagePayload(payload: unknown): payload is {
+  message_id: string;
+  message_mode: string;
+  message: {
+    body: { fragments: Array<Record<string, unknown>> };
+    context: { mentions: unknown[]; reply: unknown };
+  };
+} {
+  if (!payload || typeof payload !== "object") return false;
+  const p = payload as Record<string, unknown>;
+  if (typeof p.message_id !== "string" || !p.message_id) return false;
+  if (typeof p.message !== "object" || p.message === null) return false;
+  const m = p.message as Record<string, unknown>;
+  if (typeof m.body !== "object" || m.body === null) return false;
+  const body = m.body as Record<string, unknown>;
+  if (!Array.isArray(body.fragments)) return false;
+  return true;
+}
+
+export function hasRenderableText(message: {
+  body?: { fragments?: Array<Record<string, unknown>> };
+}): boolean {
+  const fragments = message?.body?.fragments ?? [];
+  return fragments.some(
+    (f) =>
+      (((f as { kind?: string }).kind === "text" &&
+        typeof (f as { text?: unknown }).text === "string" &&
+        (f as { text: string }).text.trim().length > 0) ||
+        (typeof (f as { kind?: unknown }).kind === "string" &&
+          ["image", "file", "audio", "video"].includes((f as { kind: string }).kind) &&
+          typeof (f as { url?: unknown }).url === "string" &&
+          (f as { url: string }).url.trim().length > 0)),
+  );
+}