@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/message-mapper.ts

@@ -0,0 +1,174 @@
+import type { Fragment } from "./protocol-types.ts";
+import type { MediaItem } from "./media-runtime.ts";
+
+interface FlattenOptions {
+  mentionFallbackIds?: string[];
+}
+
+export interface MentionTarget {
+  userId: string;
+  display?: string;
+}
+
+export interface NormalizedMentionTarget {
+  userId: string;
+  display?: string;
+}
+
+export interface MentionedUser {
+  id: string;
+  display?: string;
+}
+
+const MEDIA_KINDS = new Set(["image", "file", "audio", "video"]);
+
+function isMediaKind(kind: string): kind is MediaItem["kind"] {
+  return MEDIA_KINDS.has(kind);
+}
+
+function renderMediaPlaceholder(fragment: Record<string, unknown>): string {
+  const kind = String(fragment.kind ?? "");
+  const url = typeof fragment.url === "string" ? fragment.url : "";
+  if (!url) return "";
+  const name =
+    typeof fragment.name === "string" && fragment.name.trim()
+      ? fragment.name
+      : kind === "image"
+        ? "image"
+        : kind === "audio"
+          ? "audio"
+          : kind === "video"
+            ? "video"
+            : "file";
+  return kind === "image" ? `![${name}](${url})` : `[${name}](${url})`;
+}
+
+export function fragmentsToText(fragments: Fragment[], opts: FlattenOptions = {}): string {
+  const fallback = opts.mentionFallbackIds ?? [];
+  let fallbackCursor = 0;
+  const parts = fragments.map((fragment) => {
+    const f = fragment as unknown as Record<string, unknown>;
+    if (f.kind === "text" && typeof f.text === "string") {
+      return f.text;
+    }
+    if (f.kind === "mention") {
+      const display = typeof f.display === "string" ? f.display : undefined;
+      if (display && display.trim()) {
+        const trimmed = display.trim();
+        return trimmed.startsWith("@") ? trimmed : `@${trimmed}`;
+      }
+      const id = typeof f.user_id === "string" ? f.user_id : undefined;
+      if (id && id.trim()) return `@${id}`;
+      const fallbackId = fallback[fallbackCursor++];
+      if (fallbackId) return `@${fallbackId}`;
+      return "";
+    }
+    if (typeof f.kind === "string" && isMediaKind(f.kind)) {
+      return renderMediaPlaceholder(f);
+    }
+    return "";
+  });
+  return parts.join("").trim();
+}
+
+export function textToFragments(text: string): Fragment[] {
+  if (!text || !text.trim()) return [];
+  return [{ kind: "text", text }];
+}
+
+export function normalizeMentionTargets(mentions: MentionTarget[]): NormalizedMentionTarget[] {
+  if (!Array.isArray(mentions) || mentions.length === 0) {
+    throw new Error("clawchat_mention_message requires at least one mention");
+  }
+
+  const seen = new Set<string>();
+  const normalized: NormalizedMentionTarget[] = [];
+  for (let i = 0; i < mentions.length; i += 1) {
+    const mention = mentions[i] as Partial<MentionTarget> | undefined;
+    const userId = typeof mention?.userId === "string" ? mention.userId.trim() : "";
+    if (!userId) {
+      throw new Error(`clawchat_mention_message requires mentions[${i}].userId`);
+    }
+    if (seen.has(userId)) continue;
+
+    const rawDisplay = typeof mention?.display === "string" ? mention.display.trim() : "";
+    const display = rawDisplay ? (rawDisplay.startsWith("@") ? rawDisplay.slice(1) : rawDisplay) : undefined;
+    seen.add(userId);
+    normalized.push(display ? { userId, display } : { userId });
+  }
+  return normalized;
+}
+
+const MENTION_LABEL_RE = /^@(?<label>\S+)(?<rest>(?:\s+.*)?)$/s;
+
+export function applyTextMentionLabels(
+  mentions: NormalizedMentionTarget[],
+  text?: string,
+): { mentions: NormalizedMentionTarget[]; text: string } {
+  let remaining = typeof text === "string" ? text.trim() : "";
+  if (!remaining) return { mentions, text: "" };
+
+  const normalized = mentions.map((mention) => ({ ...mention }));
+  const missingDisplay = normalized.filter((mention) => !mention.display);
+  if (normalized.length === 1 && missingDisplay.length === 1 && remaining.startsWith("@")) {
+    const label = remaining.slice(1).trim();
+    if (label) {
+      missingDisplay[0].display = label;
+      return { mentions: normalized, text: "" };
+    }
+  }
+
+  for (const mention of normalized) {
+    if (mention.display) continue;
+    const match = MENTION_LABEL_RE.exec(remaining);
+    if (!match?.groups?.label) break;
+    mention.display = match.groups.label.trim();
+    remaining = (match.groups.rest ?? "").trim();
+  }
+  return { mentions: normalized, text: remaining };
+}
+
+export function buildMentionMessageFragments({
+  mentions,
+  text,
+}: {
+  mentions: MentionTarget[];
+  text?: string;
+}): Fragment[] {
+  const { mentions: normalized, text: remainingText } = applyTextMentionLabels(normalizeMentionTargets(mentions), text);
+  const fragments: Fragment[] = normalized.map((mention) => {
+    const fragment: Fragment = {
+      kind: "mention",
+      user_id: mention.userId,
+    };
+    if (mention.display) fragment.display = mention.display;
+    return fragment;
+  });
+  if (remainingText) {
+    fragments.push({ kind: "text", text: ` ${remainingText}` });
+  }
+  return fragments;
+}
+
+/**
+ * Extract media fragments from a body (image/file/audio/video). Skips
+ * entries missing `url`. Preserves all optional metadata fields the
+ * protocol carries through (mime/size/width/height/duration/name).
+ */
+export function extractMediaFragments(fragments: Fragment[]): MediaItem[] {
+  const out: MediaItem[] = [];
+  for (const fragment of fragments) {
+    const f = fragment as unknown as Record<string, unknown>;
+    if (typeof f.kind !== "string" || !isMediaKind(f.kind)) continue;
+    if (typeof f.url !== "string" || !f.url) continue;
+    const item: MediaItem = { kind: f.kind, url: f.url };
+    if (typeof f.name === "string") item.name = f.name;
+    if (typeof f.mime === "string") item.mime = f.mime;
+    if (typeof f.size === "number") item.size = f.size;
+    if (typeof f.width === "number") item.width = f.width;
+    if (typeof f.height === "number") item.height = f.height;
+    if (typeof f.duration === "number") item.duration = f.duration;
+    out.push(item);
+  }
+  return out;
+}

package/src/mock-transport.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it, vi } from "vitest";
+import { MockTransport } from "./mock-transport.ts";
+
+describe("MockTransport", () => {
+  it("opens, records sent frames, emits inbound frames, and closes", async () => {
+    const transport = new MockTransport();
+    const onOpen = vi.fn();
+    const onMessage = vi.fn();
+    const onClose = vi.fn();
+    const onError = vi.fn();
+
+    await transport.connect("ws://test", { onOpen, onMessage, onClose, onError });
+    expect(transport.state).toBe("open");
+    expect(onOpen).toHaveBeenCalledTimes(1);
+
+    transport.send("frame-1");
+    expect(transport.sent).toEqual(["frame-1"]);
+
+    transport.emitInbound("frame-2");
+    expect(onMessage).toHaveBeenCalledWith("frame-2");
+
+    const buffer = Buffer.from("frame-3");
+    transport.emitInbound(buffer);
+    expect(onMessage).toHaveBeenCalledWith(buffer);
+
+    const err = new Error("boom");
+    transport.emitError(err);
+    expect(onError).toHaveBeenCalledWith(err);
+
+    transport.close(1000, "done");
+    expect(transport.state).toBe("closed");
+    expect(onClose).toHaveBeenCalledWith(1000, "done");
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+});

package/src/mock-transport.ts

@@ -0,0 +1,38 @@
+import type { Transport, TransportEvents, TransportState } from "./protocol-types.ts";
+
+export class MockTransport implements Transport {
+  private handlers?: TransportEvents;
+  private currentState: TransportState = "closed";
+  readonly sent: string[] = [];
+
+  get state(): TransportState {
+    return this.currentState;
+  }
+
+  async connect(_url: string, handlers: TransportEvents): Promise<void> {
+    this.handlers = handlers;
+    this.currentState = "open";
+    handlers.onOpen();
+  }
+
+  send(data: string): void {
+    if (this.currentState !== "open") {
+      throw new Error("transport is not open");
+    }
+    this.sent.push(data);
+  }
+
+  close(code = 1000, reason = "client close"): void {
+    if (this.currentState === "closed") return;
+    this.currentState = "closed";
+    this.handlers?.onClose(code, reason);
+  }
+
+  emitInbound(data: string | Buffer): void {
+    this.handlers?.onMessage(data);
+  }
+
+  emitError(err: Error): void {
+    this.handlers?.onError(err);
+  }
+}