refactor: centralize delivery/path/media/version lifecycle

src/plugin-sdk/index.ts

@@ -234,6 +234,8 @@ export {
   sendMediaWithLeadingCaption,
 } from "./reply-payload.js";
 export type { OutboundReplyPayload } from "./reply-payload.js";
+export type { OutboundMediaLoadOptions } from "./outbound-media.js";
+export { loadOutboundMediaFromUrl } from "./outbound-media.js";
 export { resolveChannelAccountConfigBasePath } from "./config-paths.js";
 export { buildMediaPayload } from "../channels/plugins/media-payload.js";
 export type { MediaPayload, MediaPayloadInput } from "../channels/plugins/media-payload.js";

src/plugin-sdk/outbound-media.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it, vi } from "vitest";
+import { loadOutboundMediaFromUrl } from "./outbound-media.js";
+
+const loadWebMediaMock = vi.hoisted(() => vi.fn());
+
+vi.mock("../web/media.js", () => ({
+  loadWebMedia: loadWebMediaMock,
+}));
+
+describe("loadOutboundMediaFromUrl", () => {
+  it("forwards maxBytes and mediaLocalRoots to loadWebMedia", async () => {
+    loadWebMediaMock.mockResolvedValueOnce({
+      buffer: Buffer.from("x"),
+      kind: "image",
+      contentType: "image/png",
+    });
+
+    await loadOutboundMediaFromUrl("file:///tmp/image.png", {
+      maxBytes: 1024,
+      mediaLocalRoots: ["/tmp/workspace-agent"],
+    });
+
+    expect(loadWebMediaMock).toHaveBeenCalledWith("file:///tmp/image.png", {
+      maxBytes: 1024,
+      localRoots: ["/tmp/workspace-agent"],
+    });
+  });
+
+  it("keeps options optional", async () => {
+    loadWebMediaMock.mockResolvedValueOnce({
+      buffer: Buffer.from("x"),
+      kind: "image",
+      contentType: "image/png",
+    });
+
+    await loadOutboundMediaFromUrl("https://example.com/image.png");
+
+    expect(loadWebMediaMock).toHaveBeenCalledWith("https://example.com/image.png", {
+      maxBytes: undefined,
+      localRoots: undefined,
+    });
+  });
+});

src/plugin-sdk/outbound-media.ts

@@ -0,0 +1,16 @@
+import { loadWebMedia } from "../web/media.js";
+
+export type OutboundMediaLoadOptions = {
+  maxBytes?: number;
+  mediaLocalRoots?: readonly string[];
+};
+
+export async function loadOutboundMediaFromUrl(
+  mediaUrl: string,
+  options: OutboundMediaLoadOptions = {},
+) {
+  return await loadWebMedia(mediaUrl, {
+    maxBytes: options.maxBytes,
+    localRoots: options.mediaLocalRoots,
+  });
+}