@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/media-runtime.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  inferMediaKindFromMime,
+  fetchInboundMedia,
+  uploadOutboundMedia,
+  type MediaItem,
+} from "./media-runtime.ts";
+
+describe("inferMediaKindFromMime", () => {
+  it("maps image/* to image", () => {
+    expect(inferMediaKindFromMime("image/png")).toBe("image");
+    expect(inferMediaKindFromMime("image/jpeg")).toBe("image");
+  });
+  it("maps audio/* to audio", () => {
+    expect(inferMediaKindFromMime("audio/mpeg")).toBe("audio");
+  });
+  it("maps video/* to video", () => {
+    expect(inferMediaKindFromMime("video/mp4")).toBe("video");
+  });
+  it("maps anything else to file", () => {
+    expect(inferMediaKindFromMime("application/pdf")).toBe("file");
+    expect(inferMediaKindFromMime("text/plain")).toBe("file");
+  });
+  it("maps undefined / empty to file", () => {
+    expect(inferMediaKindFromMime(undefined)).toBe("file");
+    expect(inferMediaKindFromMime("")).toBe("file");
+  });
+});
+
+describe("fetchInboundMedia", () => {
+  function buildRuntime() {
+    const fetchRemoteMedia = vi.fn().mockImplementation(async ({ url }: { url: string }) => ({
+      buffer: Buffer.from(`bytes-of-${url}`),
+      contentType: "image/png",
+      fileName: "x.png",
+    }));
+    const saveMediaBuffer = vi
+      .fn()
+      .mockImplementation(
+        async (_buf: Buffer, _ct?: string, _sub?: string, _max?: number, name?: string) => ({
+          path: `/cache/${name ?? "auto"}`,
+          contentType: "image/png",
+        }),
+      );
+    const runtime = {
+      channel: {
+        media: { fetchRemoteMedia, saveMediaBuffer },
+      },
+    } as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+    return { runtime, fetchRemoteMedia, saveMediaBuffer };
+  }
+
+  it("fetches each item and returns local paths", async () => {
+    const { runtime } = buildRuntime();
+    const items: MediaItem[] = [
+      { kind: "image", url: "https://cdn/a.png", mime: "image/png" },
+      { kind: "image", url: "https://cdn/b.png", mime: "image/png" },
+    ];
+    const paths = await fetchInboundMedia(items, { runtime, maxBytes: 1000 });
+    expect(paths).toEqual(["/cache/x.png", "/cache/x.png"]);
+  });
+
+  it("drops a single item that fails, keeps others", async () => {
+    const { runtime, fetchRemoteMedia } = buildRuntime();
+    fetchRemoteMedia.mockImplementationOnce(async () => {
+      throw new Error("network");
+    });
+    const items: MediaItem[] = [
+      { kind: "image", url: "https://cdn/bad.png" },
+      { kind: "image", url: "https://cdn/good.png" },
+    ];
+    const log = { info: vi.fn(), error: vi.fn() };
+    const paths = await fetchInboundMedia(items, { runtime, log });
+    expect(paths).toHaveLength(1);
+    expect(log.info).toHaveBeenCalled();
+  });
+
+  it("returns empty array for empty input", async () => {
+    const { runtime } = buildRuntime();
+    expect(await fetchInboundMedia([], { runtime })).toEqual([]);
+  });
+});
+
+describe("uploadOutboundMedia", () => {
+  function buildApiClient() {
+    return {
+      uploadMedia: vi.fn().mockResolvedValue({
+        kind: "image",
+        url: "https://cdn/uploaded.png",
+        name: "uploaded.png",
+        size: 12,
+        mime: "image/png",
+      }),
+    } as unknown as ReturnType<typeof import("./api-client.ts").createOpenclawClawlingApiClient>;
+  }
+
+  function buildRuntime() {
+    const loadWebMedia = vi.fn().mockResolvedValue({
+      buffer: Buffer.from("loaded-bytes"),
+      contentType: "image/png",
+      fileName: "img.png",
+    });
+    const runtime = {
+      media: { loadWebMedia },
+    } as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+    return { runtime, loadWebMedia };
+  }
+
+  it("loads each url and uploads", async () => {
+    const { runtime, loadWebMedia } = buildRuntime();
+    const apiClient = buildApiClient();
+    const fragments = await uploadOutboundMedia(["https://cdn/in.png", "https://cdn/in2.png"], {
+      apiClient,
+      runtime,
+    });
+    expect(loadWebMedia).toHaveBeenCalledTimes(2);
+    expect(fragments).toEqual([
+      {
+        kind: "image",
+        url: "https://cdn/uploaded.png",
+        mime: "image/png",
+        size: 12,
+        name: "uploaded.png",
+      },
+      {
+        kind: "image",
+        url: "https://cdn/uploaded.png",
+        mime: "image/png",
+        size: 12,
+        name: "uploaded.png",
+      },
+    ]);
+  });
+
+  it("uses server-returned kind and name for uploaded media fragments", async () => {
+    const { runtime } = buildRuntime();
+    const apiClient = buildApiClient();
+    (apiClient.uploadMedia as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      kind: "file",
+      url: "https://cdn/server.bin",
+      name: "server.bin",
+      size: 12,
+      mime: "image/png",
+    });
+
+    const fragments = await uploadOutboundMedia(["https://cdn/in.png"], {
+      apiClient,
+      runtime,
+    });
+
+    expect(fragments).toEqual([
+      {
+        kind: "file",
+        url: "https://cdn/server.bin",
+        mime: "image/png",
+        size: 12,
+        name: "server.bin",
+      },
+    ]);
+  });
+
+  it("passes host media access options to loadWebMedia", async () => {
+    const { runtime, loadWebMedia } = buildRuntime();
+    const apiClient = buildApiClient();
+    const readFile = vi.fn(async () => Buffer.from("host-read"));
+
+    await uploadOutboundMedia(["relative/image.png"], {
+      apiClient,
+      runtime,
+      mediaAccess: {
+        localRoots: ["/workspace"],
+        readFile,
+        workspaceDir: "/workspace",
+      },
+    });
+
+    expect(loadWebMedia).toHaveBeenCalledWith(
+      "relative/image.png",
+      expect.objectContaining({
+        localRoots: ["/workspace"],
+        readFile,
+        hostReadCapability: true,
+        workspaceDir: "/workspace",
+      }),
+    );
+  });
+
+  it("drops a single failed upload, returns the rest", async () => {
+    const { runtime } = buildRuntime();
+    const apiClient = buildApiClient();
+    (apiClient.uploadMedia as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error("boom"));
+    const log = { info: vi.fn(), error: vi.fn() };
+    const fragments = await uploadOutboundMedia(["https://cdn/a.png", "https://cdn/b.png"], {
+      apiClient,
+      runtime,
+      log,
+    });
+    expect(fragments).toHaveLength(1);
+    expect(log.error).toHaveBeenCalled();
+  });
+
+  it("returns empty array for empty input", async () => {
+    const apiClient = buildApiClient();
+    const { runtime } = buildRuntime();
+    expect(await uploadOutboundMedia([], { apiClient, runtime })).toEqual([]);
+  });
+});

package/src/media-runtime.ts

@@ -0,0 +1,152 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+import {
+  buildOutboundMediaLoadOptions,
+  type OutboundMediaAccess,
+  type OutboundMediaReadFile,
+} from "openclaw/plugin-sdk/media-runtime";
+import type { OpenclawClawlingApiClient } from "./api-client.ts";
+
+/**
+ * Local structural superset of the protocol media fragment narrow types.
+ *
+ * Each media fragment has a literal `kind` that distinguishes it. 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`.
+ */
+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;
+  /** Host-authorized outbound media access from OpenClaw message delivery. */
+  mediaAccess?: OutboundMediaAccess;
+  /** Allowed local roots for path-based uploads. Empty/undefined = use loadWebMedia defaults. */
+  mediaLocalRoots?: readonly string[] | "any";
+  /** Host-provided read bridge for sandbox/allowed local media paths. */
+  mediaReadFile?: OutboundMediaReadFile;
+}
+
+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,
+        "clawchat-plugin-openclaw-inbound",
+        maxBytes,
+        item.name ?? fetched.fileName,
+      );
+      paths.push(saved.path);
+    } catch (err) {
+      ctx.log?.info?.(
+        `clawchat-plugin-openclaw 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 the host runtime's `runtime.media.loadWebMedia`, so local-root
+ * enforcement and media-loading policy stay aligned with the current
+ * OpenClaw runtime instead of a directly imported helper.
+ *
+ * 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 ctx.runtime.media.loadWebMedia(
+        url,
+        buildOutboundMediaLoadOptions({
+          maxBytes,
+          ...(ctx.mediaAccess ? { mediaAccess: ctx.mediaAccess } : {}),
+          ...(ctx.mediaLocalRoots ? { mediaLocalRoots: ctx.mediaLocalRoots } : {}),
+          ...(ctx.mediaReadFile ? { mediaReadFile: ctx.mediaReadFile } : {}),
+        }),
+      );
+      const uploaded = await ctx.apiClient.uploadMedia({
+        buffer: loaded.buffer,
+        filename: loaded.fileName ?? "upload.bin",
+        mime: loaded.contentType,
+      });
+      const fragment: ClawlingMediaFragment = {
+        kind: uploaded.kind,
+        url: uploaded.url,
+        name: uploaded.name,
+        mime: uploaded.mime,
+        size: uploaded.size,
+      };
+      out.push(fragment);
+    } catch (err) {
+      ctx.log?.error?.(
+        `clawchat-plugin-openclaw outbound media upload failed: ${url} (${err instanceof Error ? err.message : String(err)})`,
+      );
+    }
+  }
+  return out;
+}

package/src/message-mapper.test.ts

@@ -0,0 +1,201 @@
+import type { Fragment } from "./protocol-types.ts";
+import { describe, expect, it } from "vitest";
+import {
+  buildMentionMessageFragments,
+  extractMediaFragments,
+  fragmentsToText,
+  normalizeMentionTargets,
+  textToFragments,
+} from "./message-mapper.ts";
+
+describe("clawchat-plugin-openclaw 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("adds visible @ for mention display labels that omit it", () => {
+    const fragments: Fragment[] = [
+      { kind: "text", text: "请 " },
+      { kind: "mention", user_id: "usr_bob_456", display: "Bob" } as unknown as Fragment,
+      { kind: "text", text: " 下午处理" },
+    ];
+    expect(fragmentsToText(fragments)).toBe("请 @Bob 下午处理");
+  });
+
+  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("normalizes mention targets with optional display and dedupe", () => {
+    expect(
+      normalizeMentionTargets([
+        { userId: " user-a ", display: "Alice" },
+        { userId: "user-a", display: "Ignored" },
+        { userId: "user-b", display: "@Bob" },
+        { userId: "user-c" },
+      ]),
+    ).toEqual([
+      { userId: "user-a", display: "Alice" },
+      { userId: "user-b", display: "Bob" },
+      { userId: "user-c" },
+    ]);
+  });
+
+  it("builds mention fragments followed by spaced text", () => {
+    expect(
+      buildMentionMessageFragments({
+        mentions: [{ userId: "user-a", display: "Alice" }],
+        text: "请看这个",
+      }),
+    ).toEqual([
+      { kind: "mention", user_id: "user-a", display: "Alice" },
+      { kind: "text", text: " 请看这个" },
+    ]);
+  });
+
+  it("uses leading visible @text as mention display without duplicating text", () => {
+    expect(
+      buildMentionMessageFragments({
+        mentions: [{ userId: "user-a" }],
+        text: "@Alice",
+      }),
+    ).toEqual([
+      { kind: "mention", user_id: "user-a", display: "Alice" },
+    ]);
+  });
+
+  it("keeps spaces in a text-only mention display label", () => {
+    expect(
+      buildMentionMessageFragments({
+        mentions: [{ userId: "user-a" }],
+        text: "@Super Zero",
+      }),
+    ).toEqual([
+      { kind: "mention", user_id: "user-a", display: "Super Zero" },
+    ]);
+  });
+
+  it("throws when mention targets are missing user ids", () => {
+    expect(() => normalizeMentionTargets([{ userId: " " }])).toThrow(
+      "clawchat_mention_message requires mentions[0].userId",
+    );
+  });
+
+  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: the protocol type 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" }]);
+  });
+});