@newbase-clawchat/openclaw-clawchat 2026.4.15

package/src/media-runtime.ts

@@ -0,0 +1,143 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+import { loadWebMedia } from "openclaw/plugin-sdk/web-media";
+import type { OpenclawClawlingApiClient } from "./api-client.ts";
+
+/**
+ * Local structural superset of the SDK's media fragment narrow types.
+ *
+ * `@clawling/chat-sdk@^0.2.0` exports each narrow type
+ * (`ImageFragment` / `FileFragment` / `AudioFragment` / `VideoFragment`)
+ * with a literal `kind` that distinguishes them. Building the wide
+ * shape locally avoids per-kind switch statements when constructing
+ * outbound fragments; structural compatibility lets a single object
+ * satisfy whichever narrow type matches its runtime `kind`. We cast
+ * to `Fragment[]` only at the SDK boundary (outbound.ts).
+ */
+export interface MediaItem {
+  kind: "image" | "file" | "audio" | "video";
+  url: string;
+  name?: string;
+  mime?: string;
+  size?: number;
+  width?: number;
+  height?: number;
+  duration?: number;
+}
+
+/** Outbound fragment shape sent in `body.fragments`. Same wide shape as `MediaItem`. */
+export type ClawlingMediaFragment = MediaItem;
+
+export interface LogSink {
+  info?: (m: string) => void;
+  error?: (m: string) => void;
+}
+
+export interface FetchInboundCtx {
+  runtime: PluginRuntime;
+  log?: LogSink;
+  maxBytes?: number;
+}
+
+export interface UploadOutboundCtx {
+  apiClient: OpenclawClawlingApiClient;
+  runtime: PluginRuntime;
+  log?: LogSink;
+  maxBytes?: number;
+  /** Allowed local roots for path-based uploads. Empty/undefined = use loadWebMedia defaults. */
+  mediaLocalRoots?: readonly string[];
+}
+
+export function inferMediaKindFromMime(mime: string | undefined): MediaItem["kind"] {
+  if (!mime) return "file";
+  if (mime.startsWith("image/")) return "image";
+  if (mime.startsWith("audio/")) return "audio";
+  if (mime.startsWith("video/")) return "video";
+  return "file";
+}
+
+const DEFAULT_MEDIA_MAX_BYTES = 20 * 1024 * 1024;
+
+/**
+ * Fetch each remote URL via the shared media runtime, persist to a local
+ * cache, and return the list of local paths.
+ *
+ * Failed items are logged at info level and dropped; the remaining items
+ * still resolve so a single bad URL doesn't blow up the whole inbound turn.
+ */
+export async function fetchInboundMedia(
+  items: MediaItem[],
+  ctx: FetchInboundCtx,
+): Promise<string[]> {
+  if (items.length === 0) return [];
+  const maxBytes = ctx.maxBytes ?? DEFAULT_MEDIA_MAX_BYTES;
+  const paths: string[] = [];
+  for (const item of items) {
+    try {
+      const fetched = await ctx.runtime.channel.media.fetchRemoteMedia({
+        url: item.url,
+        maxBytes,
+      });
+      const saved = await ctx.runtime.channel.media.saveMediaBuffer(
+        fetched.buffer,
+        fetched.contentType ?? item.mime,
+        "openclaw-clawchat-inbound",
+        maxBytes,
+        item.name ?? fetched.fileName,
+      );
+      paths.push(saved.path);
+    } catch (err) {
+      ctx.log?.info?.(
+        `openclaw-clawchat inbound media skipped: ${item.url} (${err instanceof Error ? err.message : String(err)})`,
+      );
+    }
+  }
+  return paths;
+}
+
+/**
+ * Upload each URL (remote or local path) to /media/upload via the api
+ * client and return a fragment ready to splice into `body.fragments`.
+ *
+ * Uses `loadWebMedia` from `openclaw/plugin-sdk/web-media` (not the channel
+ * runtime media helpers, which only expose fetchRemoteMedia/saveMediaBuffer).
+ *
+ * Single-upload failures log at error and are dropped; the remaining
+ * fragments still come back so a partially-failing batch still sends the
+ * working media.
+ */
+export async function uploadOutboundMedia(
+  urls: string[],
+  ctx: UploadOutboundCtx,
+): Promise<ClawlingMediaFragment[]> {
+  if (urls.length === 0) return [];
+  const maxBytes = ctx.maxBytes ?? DEFAULT_MEDIA_MAX_BYTES;
+  const out: ClawlingMediaFragment[] = [];
+  for (const url of urls) {
+    try {
+      const loaded = await loadWebMedia(url, {
+        maxBytes,
+        ...(ctx.mediaLocalRoots && ctx.mediaLocalRoots.length > 0
+          ? { localRoots: ctx.mediaLocalRoots }
+          : {}),
+      });
+      const uploaded = await ctx.apiClient.uploadMedia({
+        buffer: loaded.buffer,
+        filename: loaded.fileName ?? "upload.bin",
+        mime: loaded.contentType,
+      });
+      const fragment: ClawlingMediaFragment = {
+        kind: inferMediaKindFromMime(uploaded.mime),
+        url: uploaded.url,
+        mime: uploaded.mime,
+        size: uploaded.size,
+      };
+      if (loaded.fileName) fragment.name = loaded.fileName;
+      out.push(fragment);
+    } catch (err) {
+      ctx.log?.error?.(
+        `openclaw-clawchat outbound media upload failed: ${url} (${err instanceof Error ? err.message : String(err)})`,
+      );
+    }
+  }
+  return out;
+}

package/src/message-mapper.test.ts

@@ -0,0 +1,131 @@
+import type { Fragment } from "@newbase-clawchat/sdk";
+import { describe, expect, it } from "vitest";
+import { extractMediaFragments, fragmentsToText, textToFragments } from "./message-mapper.ts";
+
+describe("openclaw-clawchat message-mapper", () => {
+  it("flattens text fragments", () => {
+    const fragments: Fragment[] = [
+      { kind: "text", text: "hello " },
+      { kind: "text", text: "world" },
+    ];
+    expect(fragmentsToText(fragments)).toBe("hello world");
+  });
+
+  it("renders mention fragments using display text", () => {
+    const fragments: Fragment[] = [
+      { kind: "text", text: "hi " },
+      { kind: "mention", display: "@Clawling Assistant" } as unknown as Fragment,
+      { kind: "text", text: "!" },
+    ];
+    expect(fragmentsToText(fragments)).toBe("hi @Clawling Assistant!");
+  });
+
+  it("falls back to mention ids when display missing", () => {
+    const fragments: Fragment[] = [
+      { kind: "text", text: "hi " },
+      { kind: "mention", user_id: "agent-1" } as unknown as Fragment,
+    ];
+    expect(fragmentsToText(fragments, { mentionFallbackIds: ["agent-1"] })).toBe("hi @agent-1");
+  });
+
+  it("renders image fragments inline and skips unknown kinds without crashing", () => {
+    const fragments: Fragment[] = [
+      { kind: "text", text: "see " },
+      { kind: "image", url: "https://example/i.png" } as unknown as Fragment,
+      { kind: "text", text: "this" },
+    ];
+    expect(fragmentsToText(fragments)).toBe("see ![image](https://example/i.png)this");
+  });
+
+  it("trims the final result", () => {
+    const fragments: Fragment[] = [{ kind: "text", text: "  hi  " }];
+    expect(fragmentsToText(fragments)).toBe("hi");
+  });
+
+  it("textToFragments produces a single text fragment", () => {
+    expect(textToFragments("ok")).toEqual([{ kind: "text", text: "ok" }]);
+  });
+
+  it("textToFragments returns empty array for empty input", () => {
+    expect(textToFragments("")).toEqual([]);
+    expect(textToFragments("   ")).toEqual([]);
+  });
+
+  it("renders image fragments as markdown image", () => {
+    const fragments: Fragment[] = [
+      { kind: "text", text: "look: " },
+      { kind: "image", url: "https://cdn/x.png", name: "logo" } as unknown as Fragment,
+    ];
+    expect(fragmentsToText(fragments)).toBe("look: ![logo](https://cdn/x.png)");
+  });
+
+  it("renders file/audio/video fragments as markdown link", () => {
+    const fragments: Fragment[] = [
+      { kind: "file", url: "https://cdn/a.pdf", name: "doc.pdf" } as unknown as Fragment,
+      { kind: "audio", url: "https://cdn/b.mp3" } as unknown as Fragment,
+      { kind: "video", url: "https://cdn/c.mp4", name: "demo" } as unknown as Fragment,
+    ];
+    expect(fragmentsToText(fragments)).toBe(
+      "[doc.pdf](https://cdn/a.pdf)[audio](https://cdn/b.mp3)[demo](https://cdn/c.mp4)",
+    );
+  });
+
+  it("renders image without name as ![image](url)", () => {
+    const fragments: Fragment[] = [
+      { kind: "image", url: "https://cdn/x.png" } as unknown as Fragment,
+    ];
+    expect(fragmentsToText(fragments)).toBe("![image](https://cdn/x.png)");
+  });
+
+  it("extractMediaFragments returns only media fragments", () => {
+    const fragments: Fragment[] = [
+      { kind: "text", text: "hi " },
+      { kind: "image", url: "https://cdn/a.png", mime: "image/png" } as unknown as Fragment,
+      { kind: "mention", display: "@bob" } as unknown as Fragment,
+      { kind: "file", url: "https://cdn/b.pdf", name: "b.pdf" } as unknown as Fragment,
+    ];
+    const items = extractMediaFragments(fragments);
+    expect(items).toEqual([
+      { kind: "image", url: "https://cdn/a.png", mime: "image/png" },
+      { kind: "file", url: "https://cdn/b.pdf", name: "b.pdf" },
+    ]);
+  });
+
+  it("extractMediaFragments preserves all optional metadata", () => {
+    const fragments: Fragment[] = [
+      {
+        kind: "video",
+        url: "https://cdn/v.mp4",
+        name: "v",
+        mime: "video/mp4",
+        size: 1234,
+        width: 1280,
+        height: 720,
+        duration: 30,
+      } as unknown as Fragment,
+    ];
+    expect(extractMediaFragments(fragments)).toEqual([
+      {
+        kind: "video",
+        url: "https://cdn/v.mp4",
+        name: "v",
+        mime: "video/mp4",
+        size: 1234,
+        width: 1280,
+        height: 720,
+        duration: 30,
+      },
+    ]);
+  });
+
+  it("extractMediaFragments skips media fragments without url", () => {
+    // Note: SDK 0.2.0 requires `url` on image fragments — using a partial
+    // object here exercises the runtime guard. Casting here is intentional
+    // (we want to verify defensive handling of malformed input).
+    const fragments: Fragment[] = [
+      { kind: "image" } as unknown as Fragment,
+      { kind: "image", url: "https://cdn/a.png" } as unknown as Fragment,
+    ];
+    expect(extractMediaFragments(fragments)).toEqual([{ kind: "image", url: "https://cdn/a.png" }]);
+  });
+});

package/src/message-mapper.ts

@@ -0,0 +1,82 @@
+import type { Fragment } from "@newbase-clawchat/sdk";
+import type { MediaItem } from "./media-runtime.ts";
+
+interface FlattenOptions {
+  mentionFallbackIds?: 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()) return display;
+      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 }];
+}
+
+/**
+ * Extract media fragments from a body (image/file/audio/video). Skips
+ * entries missing `url`. Preserves all optional metadata fields the
+ * SDK passes 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/outbound.test.ts

@@ -0,0 +1,244 @@
+import type { ClawlingChatClient } from "@newbase-clawchat/sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
+import { describe, expect, it, vi } from "vitest";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+import { sendOpenclawClawlingMedia, sendOpenclawClawlingText } from "./outbound.ts";
+
+function baseAccount(
+  overrides: Partial<ResolvedOpenclawClawlingAccount> = {},
+): ResolvedOpenclawClawlingAccount {
+  return {
+    accountId: DEFAULT_ACCOUNT_ID,
+    name: "openclaw-clawchat",
+    enabled: true,
+    configured: true,
+    websocketUrl: "ws://t",
+    baseUrl: "",
+    token: "tk",
+    userId: "agent-1",
+    replyMode: "static",
+    forwardThinking: true,
+    forwardToolCalls: false,
+    allowFrom: [],
+    stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+    reconnect: {
+      initialDelay: 1000,
+      maxDelay: 30000,
+      jitterRatio: 0.3,
+      maxRetries: Number.POSITIVE_INFINITY,
+    },
+    heartbeat: { interval: 25000, timeout: 10000 },
+    ack: { timeout: 10000, autoResendOnTimeout: false },
+    ...overrides,
+  };
+}
+
+function mockClient() {
+  return {
+    sendMessage: vi.fn().mockResolvedValue({
+      version: "2",
+      event: "message.ack",
+      trace_id: "trace-ack",
+      emitted_at: Date.now(),
+      payload: { message_id: "server-m1", accepted_at: 1234 },
+    }),
+    replyMessage: vi.fn().mockResolvedValue({
+      version: "2",
+      event: "message.ack",
+      trace_id: "trace-ack-r",
+      emitted_at: Date.now(),
+      payload: { message_id: "server-r1", accepted_at: 5678 },
+    }),
+    typing: vi.fn(),
+    emitRaw: vi.fn(),
+  } as unknown as ClawlingChatClient;
+}
+
+describe("openclaw-clawchat outbound", () => {
+  it("routes to sendMessage when no replyCtx", async () => {
+    const client = mockClient();
+    const result = await sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      text: "hello",
+    });
+    expect((client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).toMatchObject({
+      to: { id: "user-1", type: "direct" },
+      body: { fragments: [{ kind: "text", text: "hello" }] },
+    });
+    expect(client.replyMessage).not.toHaveBeenCalled();
+    expect(result?.messageId).toBe("server-m1");
+    expect(result?.acceptedAt).toBe(1234);
+  });
+
+  it("routes to replyMessage when replyCtx is provided", async () => {
+    const client = mockClient();
+    await sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      text: "reply",
+      replyCtx: {
+        replyToMessageId: "m-orig",
+        replyPreviewSenderId: "user-2",
+        replyPreviewDisplayName: "Sender",
+        replyPreviewText: "original",
+      },
+    });
+    expect((client.replyMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).toMatchObject({
+      to: { id: "user-1", type: "direct" },
+      replyTo: {
+        msgId: "m-orig",
+        senderId: "user-2",
+        displayName: "Sender",
+        fragments: [{ kind: "text", text: "original" }],
+      },
+      body: { fragments: [{ kind: "text", text: "reply" }] },
+    });
+    expect(client.sendMessage).not.toHaveBeenCalled();
+  });
+
+  it("suppresses send when text is empty after trim", async () => {
+    const client = mockClient();
+    const result = await sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "u", chatType: "direct" },
+      text: "   ",
+    });
+    expect(client.sendMessage).not.toHaveBeenCalled();
+    expect(client.replyMessage).not.toHaveBeenCalled();
+    expect(result).toBeNull();
+  });
+
+  it("propagates SDK errors", async () => {
+    const client = {
+      ...mockClient(),
+      sendMessage: vi.fn().mockRejectedValue(new Error("boom")),
+    } as unknown as ClawlingChatClient;
+    await expect(
+      sendOpenclawClawlingText({
+        client,
+        account: baseAccount(),
+        to: { chatId: "u", chatType: "direct" },
+        text: "hi",
+      }),
+    ).rejects.toThrow("boom");
+  });
+
+  it("appends mediaFragments after text in body.fragments", async () => {
+    const client = mockClient();
+    await sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      text: "look",
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png", mime: "image/png", size: 12 }],
+    });
+    const callArg = (client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(callArg.body.fragments).toEqual([
+      { kind: "text", text: "look" },
+      { kind: "image", url: "https://cdn/x.png", mime: "image/png", size: 12 },
+    ]);
+  });
+
+  it("sends media-only message when text empty but mediaFragments present", async () => {
+    const client = mockClient();
+    const result = await sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      text: "",
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],
+    });
+    const callArg = (client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(callArg.body.fragments).toEqual([{ kind: "image", url: "https://cdn/x.png" }]);
+    expect(result?.messageId).toBe("server-m1");
+  });
+
+  it("downgrades replyCtx + media to sendMessage", async () => {
+    const client = mockClient();
+    const log = { info: vi.fn(), error: vi.fn() };
+    await sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      text: "hi",
+      replyCtx: {
+        replyToMessageId: "m-orig",
+        replyPreviewSenderId: "user-2",
+        replyPreviewDisplayName: "Sender",
+        replyPreviewText: "original",
+      },
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],
+      log,
+    });
+    expect(client.replyMessage).not.toHaveBeenCalled();
+    expect(client.sendMessage).toHaveBeenCalled();
+    expect(log.info).toHaveBeenCalledWith(
+      expect.stringMatching(/replyCtx \+ media: downgraded to sendMessage/),
+    );
+  });
+
+  it("suppresses send when both text and mediaFragments are empty", async () => {
+    const client = mockClient();
+    const result = await sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "u", chatType: "direct" },
+      text: "   ",
+      mediaFragments: [],
+    });
+    expect(client.sendMessage).not.toHaveBeenCalled();
+    expect(result).toBeNull();
+  });
+
+  it("sendOpenclawClawlingMedia with image and caption sends both fragments", async () => {
+    const client = mockClient();
+    const result = await sendOpenclawClawlingMedia({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      text: "look at this",
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png", mime: "image/png", size: 12 }],
+    });
+    const callArg = (client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(callArg.body.fragments).toEqual([
+      { kind: "text", text: "look at this" },
+      { kind: "image", url: "https://cdn/x.png", mime: "image/png", size: 12 },
+    ]);
+    expect(result?.messageId).toBe("server-m1");
+  });
+
+  it("sendOpenclawClawlingMedia with image only (no text) sends just the media fragment", async () => {
+    const client = mockClient();
+    const result = await sendOpenclawClawlingMedia({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],
+    });
+    const callArg = (client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(callArg.body.fragments).toEqual([{ kind: "image", url: "https://cdn/x.png" }]);
+    expect(result?.messageId).toBe("server-m1");
+  });
+
+  it("sendOpenclawClawlingMedia returns null and does not call SDK when mediaFragments is empty", async () => {
+    const client = mockClient();
+    const log = { info: vi.fn(), error: vi.fn() };
+    const result = await sendOpenclawClawlingMedia({
+      client,
+      account: baseAccount(),
+      to: { chatId: "u", chatType: "direct" },
+      mediaFragments: [],
+      log,
+    });
+    expect(client.sendMessage).not.toHaveBeenCalled();
+    expect(client.replyMessage).not.toHaveBeenCalled();
+    expect(result).toBeNull();
+    expect(log.info).toHaveBeenCalledWith(
+      expect.stringMatching(/sendMedia called with empty mediaFragments/),
+    );
+  });
+});