@hywkp/test-openclaw-sider 1.0.2

package/src/media-upload.ts

@@ -0,0 +1,983 @@
+import os from "node:os";
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { resolveOutboundMediaUrls } from "openclaw/plugin-sdk/reply-payload";
+import { loadWebMedia } from "openclaw/plugin-sdk/web-media";
+import { formatAuthorizationHeader } from "./auth.js";
+import { SIDER_USER_AGENT } from "./user-agent.js";
+
+export type SiderUploadAccount = {
+  accountId: string;
+  gatewayUrl: string;
+  sendTimeoutMs: number;
+  token?: string;
+};
+
+export type SiderPart = {
+  id?: string;
+  type: string;
+  spec_version?: number;
+  payload?: unknown;
+  meta?: unknown;
+};
+
+type SiderReplyLike = {
+  text?: string;
+  mediaUrl?: string;
+  mediaUrls?: string[];
+};
+
+type SiderUploadLogger = {
+  debug?: (message: string, data?: Record<string, unknown>) => void;
+  warn?: (message: string, data?: Record<string, unknown>) => void;
+};
+
+type BuildSiderPartsParams = {
+  account: SiderUploadAccount;
+  sessionId: string;
+  payload: SiderReplyLike;
+  mediaLocalRoots?: readonly string[];
+  logger?: SiderUploadLogger;
+};
+
+type UploadedSiderFile = {
+  fileId: string;
+  objectKey: string;
+  fileName: string;
+  mimeType: string;
+  size: number;
+  sha256: string;
+  mediaKind: "image" | "file";
+};
+
+type PreparedSiderMedia = {
+  buffer: Buffer;
+  contentType?: string;
+  fileName?: string;
+  kind?: string;
+  sourceLabel?: string;
+};
+
+const DEFAULT_MIME = "application/octet-stream";
+
+const MIME_BY_EXTENSION: Record<string, string> = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".bmp": "image/bmp",
+  ".svg": "image/svg+xml",
+  ".pdf": "application/pdf",
+  ".txt": "text/plain",
+  ".json": "application/json",
+  ".zip": "application/zip",
+};
+
+const EXTENSION_BY_MIME: Record<string, string> = {
+  "image/jpeg": ".jpg",
+  "image/png": ".png",
+  "image/gif": ".gif",
+  "image/webp": ".webp",
+  "image/bmp": ".bmp",
+  "image/svg+xml": ".svg",
+  "application/pdf": ".pdf",
+  "text/plain": ".txt",
+  "application/json": ".json",
+  "application/zip": ".zip",
+};
+
+const ATTACHMENT_REF_PREFIX = "attachment://";
+const MARKDOWN_IMAGE_RE = /!\[[^\]]*]\(([^)\r\n]+)\)/g;
+const MARKDOWN_LINK_RE = /\[[^\]]*]\(([^)\r\n]+)\)/g;
+const LOCAL_PATH_PREFIX_RE = /^(\/|\.\/|\.\.\/|~\/|[a-zA-Z]:[\\/]|\\\\)/;
+const SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+const FILE_EXT_RE = /\.[a-z0-9]{1,10}$/i;
+const GENERATED_ATTACHMENT_SUFFIX_RE =
+  /---[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}(?:\.[a-z0-9]{1,10})?$/i;
+
+function toRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function normalizeMime(raw?: string): string | undefined {
+  const value = raw?.trim().toLowerCase();
+  if (!value) {
+    return undefined;
+  }
+  const normalized = value.split(";")[0]?.trim();
+  return normalized || undefined;
+}
+
+function extFromPath(raw: string): string {
+  const qPos = raw.indexOf("?");
+  const sanitized = qPos >= 0 ? raw.slice(0, qPos) : raw;
+  const slashPos = Math.max(sanitized.lastIndexOf("/"), sanitized.lastIndexOf("\\"));
+  const last = slashPos >= 0 ? sanitized.slice(slashPos + 1) : sanitized;
+  const dotPos = last.lastIndexOf(".");
+  return dotPos >= 0 ? last.slice(dotPos).toLowerCase() : "";
+}
+
+function fileNameFromMediaUrl(raw: string): string | undefined {
+  try {
+    if (/^https?:\/\//i.test(raw) || /^file:\/\//i.test(raw)) {
+      const pathname = new URL(raw).pathname;
+      const seg = pathname.split("/").filter(Boolean).pop();
+      return seg || undefined;
+    }
+  } catch {
+    // no-op
+  }
+  const qPos = raw.indexOf("?");
+  const sanitized = qPos >= 0 ? raw.slice(0, qPos) : raw;
+  const seg = sanitized.split(/[\\/]/).filter(Boolean).pop();
+  return seg || undefined;
+}
+
+function normalizeFileName(raw: string | undefined, fallback: string): string {
+  const base = (raw ?? "").trim().split(/[\\/]/).filter(Boolean).pop() ?? "";
+  const cleaned = base.replace(/[\u0000-\u001f]/g, "");
+  if (!cleaned || cleaned === "." || cleaned === "..") {
+    return fallback;
+  }
+  return cleaned.slice(0, 255);
+}
+
+function inferMimeFromFileName(fileName: string): string | undefined {
+  const ext = extFromPath(fileName);
+  return MIME_BY_EXTENSION[ext];
+}
+
+function inferFallbackFileName(params: { mimeType: string; mediaKind: "image" | "file" }): string {
+  const ext = EXTENSION_BY_MIME[params.mimeType];
+  if (ext) {
+    return `attachment${ext}`;
+  }
+  return params.mediaKind === "image" ? "attachment.png" : "attachment.bin";
+}
+
+function sha256Hex(buffer: Buffer): string {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+function resolveGatewayApiUrl(gatewayUrl: string, path: string): string {
+  const url = new URL(gatewayUrl);
+  const basePath = url.pathname.replace(/\/+$/, "");
+  const suffix = path.startsWith("/") ? path : `/${path}`;
+  url.pathname = `${basePath}${suffix}`;
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
+async function readResponseErrorBody(response: Response): Promise<string> {
+  try {
+    const text = (await response.text()).trim();
+    return text;
+  } catch {
+    return "";
+  }
+}
+
+function describeError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message || String(error);
+  }
+  return String(error);
+}
+
+function stripQueryAndHash(raw: string): string {
+  return raw.split(/[?#]/, 1)[0] ?? raw;
+}
+
+function parseMarkdownLinkTarget(rawTarget: string): string | undefined {
+  const trimmed = rawTarget.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  let target = trimmed;
+  const wrappedInAngles = target.startsWith("<") && target.endsWith(">");
+  if (wrappedInAngles) {
+    target = target.slice(1, -1).trim();
+  }
+  if (!wrappedInAngles) {
+    const whitespaceIndex = target.search(/\s/);
+    if (whitespaceIndex > 0) {
+      target = target.slice(0, whitespaceIndex);
+    }
+  }
+  target = target.trim();
+  return target || undefined;
+}
+
+function shouldTreatMarkdownLinkAsMediaTarget(target: string): boolean {
+  const normalized = target.trim();
+  if (!normalized) {
+    return false;
+  }
+  if (normalized.toLowerCase().startsWith(ATTACHMENT_REF_PREFIX)) {
+    return true;
+  }
+  if (/^file:\/\//i.test(normalized)) {
+    return true;
+  }
+  if (LOCAL_PATH_PREFIX_RE.test(normalized)) {
+    return true;
+  }
+  if (!SCHEME_RE.test(normalized)) {
+    if (normalized.includes("/") || normalized.includes("\\")) {
+      return true;
+    }
+    if (FILE_EXT_RE.test(stripQueryAndHash(normalized))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function extractMarkdownMediaUrls(text: string | undefined): string[] {
+  if (!text) {
+    return [];
+  }
+  const urls: string[] = [];
+  for (const match of text.matchAll(MARKDOWN_IMAGE_RE)) {
+    const target = parseMarkdownLinkTarget(match[1] ?? "");
+    if (target) {
+      urls.push(target);
+    }
+  }
+  for (const match of text.matchAll(MARKDOWN_LINK_RE)) {
+    const start = match.index ?? 0;
+    if (start > 0 && text[start - 1] === "!") {
+      continue;
+    }
+    const target = parseMarkdownLinkTarget(match[1] ?? "");
+    if (target && shouldTreatMarkdownLinkAsMediaTarget(target)) {
+      urls.push(target);
+    }
+  }
+  return urls;
+}
+
+function dedupeMediaUrls(values: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const deduped: string[] = [];
+  for (const raw of values) {
+    const trimmed = raw.trim();
+    if (!trimmed || seen.has(trimmed)) {
+      continue;
+    }
+    seen.add(trimmed);
+    deduped.push(trimmed);
+  }
+  return deduped;
+}
+
+function isPathWithinRoot(rootDir: string, candidatePath: string): boolean {
+  const relative = path.relative(rootDir, candidatePath);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function isPathWithinAnyRoot(filePath: string, roots?: readonly string[]): boolean {
+  if (!roots?.length) {
+    return false;
+  }
+  for (const rootEntry of roots) {
+    const trimmedRoot = rootEntry?.trim();
+    if (!trimmedRoot) {
+      continue;
+    }
+    if (isPathWithinRoot(path.resolve(trimmedRoot), filePath)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function isExistingFile(filePath: string): Promise<boolean> {
+  try {
+    const stats = await stat(filePath);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function looksLikeGeneratedAttachmentName(params: {
+  requestedFileName: string;
+  candidateName: string;
+}): boolean {
+  const requested = params.requestedFileName.trim();
+  const candidate = params.candidateName.trim();
+  if (!requested || !candidate) {
+    return false;
+  }
+  if (requested === candidate) {
+    return true;
+  }
+  if (!GENERATED_ATTACHMENT_SUFFIX_RE.test(candidate)) {
+    return false;
+  }
+  const requestedExt = path.extname(requested).toLowerCase();
+  const requestedBase = requestedExt ? requested.slice(0, -requestedExt.length) : requested;
+  if (!requestedBase) {
+    return false;
+  }
+  if (!candidate.startsWith(`${requestedBase}---`)) {
+    return false;
+  }
+  if (requestedExt && !candidate.toLowerCase().endsWith(requestedExt)) {
+    return false;
+  }
+  return true;
+}
+
+function buildAttachmentLookupDirs(rootDir: string): string[] {
+  return Array.from(
+    new Set([
+      rootDir,
+      path.join(rootDir, "tmp"),
+      path.join(rootDir, "out"),
+      path.join(rootDir, "outbound"),
+      path.join(rootDir, "inbound"),
+      path.join(rootDir, "media"),
+      path.join(rootDir, "media", "outbound"),
+      path.join(rootDir, "media", "inbound"),
+      path.join(rootDir, "workspace"),
+      path.join(rootDir, "sandboxes"),
+    ]),
+  );
+}
+
+async function resolveStoredAttachmentByFileName(params: {
+  rootDir: string;
+  fileName: string;
+}): Promise<string | undefined> {
+  let bestPath: string | undefined;
+  let bestMtimeMs = -1;
+  for (const dir of buildAttachmentLookupDirs(params.rootDir)) {
+    if (!isPathWithinRoot(params.rootDir, dir)) {
+      continue;
+    }
+    let entries: string[] | undefined;
+    try {
+      entries = await readdir(dir, { encoding: "utf8" });
+    } catch {
+      continue;
+    }
+    if (!entries) {
+      continue;
+    }
+    for (const entryName of entries) {
+      if (
+        !looksLikeGeneratedAttachmentName({
+          requestedFileName: params.fileName,
+          candidateName: entryName,
+        })
+      ) {
+        continue;
+      }
+      const candidate = path.join(dir, entryName);
+      if (!isPathWithinRoot(params.rootDir, candidate)) {
+        continue;
+      }
+      try {
+        const fileStat = await stat(candidate);
+        if (!fileStat.isFile()) {
+          continue;
+        }
+        if (fileStat.mtimeMs >= bestMtimeMs) {
+          bestMtimeMs = fileStat.mtimeMs;
+          bestPath = candidate;
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  return bestPath;
+}
+
+async function resolveAttachmentRefToLocalPath(params: {
+  attachmentRef: string;
+  mediaLocalRoots?: readonly string[];
+}): Promise<string | undefined> {
+  const raw = params.attachmentRef.slice(ATTACHMENT_REF_PREFIX.length).trim();
+  if (!raw || !params.mediaLocalRoots?.length) {
+    return undefined;
+  }
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(raw);
+  } catch {
+    return undefined;
+  }
+  const decodedPath = stripQueryAndHash(decoded).trim();
+  if (!decodedPath) {
+    return undefined;
+  }
+  if (path.isAbsolute(decodedPath)) {
+    const absoluteCandidate = path.resolve(decodedPath);
+    if (
+      isPathWithinAnyRoot(absoluteCandidate, params.mediaLocalRoots) &&
+      (await isExistingFile(absoluteCandidate))
+    ) {
+      return absoluteCandidate;
+    }
+  }
+
+  const normalizedSlash = decodedPath.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!normalizedSlash) {
+    return undefined;
+  }
+  const segments = normalizedSlash.split("/").filter(Boolean);
+  if (segments.length === 0 || segments.some((segment) => segment === "." || segment === "..")) {
+    return undefined;
+  }
+  const relativePath = segments.join(path.sep);
+  const fileNameOnly = segments[segments.length - 1];
+  for (const rootEntry of params.mediaLocalRoots) {
+    const trimmedRoot = rootEntry?.trim();
+    if (!trimmedRoot) {
+      continue;
+    }
+    const rootDir = path.resolve(trimmedRoot);
+    const directCandidate = path.resolve(rootDir, relativePath);
+    if (isPathWithinRoot(rootDir, directCandidate) && (await isExistingFile(directCandidate))) {
+      return directCandidate;
+    }
+    if (!fileNameOnly) {
+      continue;
+    }
+    const fallbackCandidates = [
+      path.resolve(rootDir, fileNameOnly),
+      path.resolve(rootDir, "tmp", fileNameOnly),
+      path.resolve(rootDir, "out", fileNameOnly),
+      path.resolve(rootDir, "outbound", fileNameOnly),
+      path.resolve(rootDir, "inbound", fileNameOnly),
+      path.resolve(rootDir, "media", fileNameOnly),
+      path.resolve(rootDir, "media", "outbound", fileNameOnly),
+      path.resolve(rootDir, "media", "inbound", fileNameOnly),
+      path.resolve(rootDir, "workspace", fileNameOnly),
+      path.resolve(rootDir, "sandboxes", fileNameOnly),
+    ];
+    for (const candidate of fallbackCandidates) {
+      if (!isPathWithinRoot(rootDir, candidate)) {
+        continue;
+      }
+      if (await isExistingFile(candidate)) {
+        return candidate;
+      }
+    }
+    const generatedCandidate = await resolveStoredAttachmentByFileName({
+      rootDir,
+      fileName: fileNameOnly,
+    });
+    if (generatedCandidate) {
+      return generatedCandidate;
+    }
+  }
+  return undefined;
+}
+
+function stripSentMarkdownMediaLinks(
+  text: string | undefined,
+  sentSourceUrls: ReadonlySet<string>,
+): string {
+  const input = text ?? "";
+  if (!input.trim()) {
+    return "";
+  }
+  if (sentSourceUrls.size === 0) {
+    return input.trim();
+  }
+  const strippedImages = input.replace(MARKDOWN_IMAGE_RE, (match, rawTarget: string) => {
+    const target = parseMarkdownLinkTarget(rawTarget);
+    if (!target || !sentSourceUrls.has(target)) {
+      return match;
+    }
+    return "";
+  });
+  const strippedLinks = strippedImages.replace(
+    MARKDOWN_LINK_RE,
+    (match: string, rawTarget: string, offset: number, source: string) => {
+      if (offset > 0 && source[offset - 1] === "!") {
+        return match;
+      }
+      const target = parseMarkdownLinkTarget(rawTarget);
+      if (!target || !sentSourceUrls.has(target)) {
+        return match;
+      }
+      return "";
+    },
+  );
+  return strippedLinks
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+async function postJson<T>(params: {
+  url: string;
+  body: Record<string, unknown>;
+  timeoutMs: number;
+  authorization?: string;
+}): Promise<T> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "User-Agent": SIDER_USER_AGENT,
+  };
+  if (params.authorization?.trim()) {
+    headers.Authorization = formatAuthorizationHeader(params.authorization);
+  }
+  const response = await fetch(params.url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(params.body),
+    signal: AbortSignal.timeout(params.timeoutMs),
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    const hint = text ? `: ${text.slice(0, 300)}` : "";
+    throw new Error(`HTTP ${response.status} ${response.statusText}${hint}`);
+  }
+  let parsed: unknown = {};
+  if (text.trim()) {
+    try {
+      parsed = JSON.parse(text) as unknown;
+    } catch (error) {
+      throw new Error(`invalid JSON response from ${params.url}: ${String(error)}`);
+    }
+  }
+  return parsed as T;
+}
+
+function parseFileInitResult(value: unknown): { fileId: string; objectKey: string; uploadUrl: string } {
+  const record = toRecord(value);
+  if (!record) {
+    throw new Error("files/init returned invalid response");
+  }
+  const fileId = typeof record.file_id === "string" ? record.file_id.trim() : "";
+  const objectKey = typeof record.object_key === "string" ? record.object_key.trim() : "";
+  const uploadUrl = typeof record.upload_url === "string" ? record.upload_url.trim() : "";
+  if (!fileId || !objectKey || !uploadUrl) {
+    throw new Error("files/init response missing file_id/object_key/upload_url");
+  }
+  return { fileId, objectKey, uploadUrl };
+}
+
+async function initFileUpload(params: {
+  account: SiderUploadAccount;
+  sessionId: string;
+  fileName: string;
+  size: number;
+  mimeType: string;
+  sha256: string;
+  logger?: SiderUploadLogger;
+}): Promise<{ fileId: string; objectKey: string; uploadUrl: string }> {
+  const url = resolveGatewayApiUrl(params.account.gatewayUrl, "/v1/files/init");
+  try {
+    const response = await postJson<unknown>({
+      url,
+      timeoutMs: params.account.sendTimeoutMs,
+      authorization: params.account.token,
+      body: {
+        session_id: params.sessionId,
+        name: params.fileName,
+        size: params.size,
+        mime: params.mimeType,
+        sha256: params.sha256,
+      },
+    });
+    return parseFileInitResult(response);
+  } catch (error) {
+    params.logger?.warn?.("sider files/init failed", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      fileName: params.fileName,
+      size: params.size,
+      mimeType: params.mimeType,
+      sha256: params.sha256,
+      error: String(error),
+    });
+    throw new Error(`sider files/init failed: ${describeError(error)}`, {
+      cause: error instanceof Error ? error : undefined,
+    });
+  }
+}
+
+async function uploadToObjectStore(params: {
+  uploadUrl: string;
+  mimeType: string;
+  sha256: string;
+  buffer: Buffer;
+  timeoutMs: number;
+  logger?: SiderUploadLogger;
+  accountId?: string;
+  sessionId?: string;
+  fileId?: string;
+  objectKey?: string;
+  fileName?: string;
+}): Promise<void> {
+  const headers: Record<string, string> = {
+    "User-Agent": SIDER_USER_AGENT,
+  };
+  if (params.mimeType) {
+    headers["Content-Type"] = params.mimeType;
+  }
+  if (params.sha256) {
+    // Required by gateway presign input (PutObjectInput.Metadata["sha256"]).
+    headers["x-amz-meta-sha256"] = params.sha256;
+  }
+  try {
+    const response = await fetch(params.uploadUrl, {
+      method: "PUT",
+      headers,
+      body: new Uint8Array(params.buffer),
+      signal: AbortSignal.timeout(params.timeoutMs),
+    });
+    if (!response.ok) {
+      const detail = await readResponseErrorBody(response);
+      const hint = detail ? `: ${detail.slice(0, 300)}` : "";
+      throw new Error(`upload failed (${response.status} ${response.statusText})${hint}`);
+    }
+  } catch (error) {
+    params.logger?.warn?.("sider object upload failed", {
+      accountId: params.accountId,
+      sessionId: params.sessionId,
+      fileId: params.fileId,
+      objectKey: params.objectKey,
+      fileName: params.fileName,
+      mimeType: params.mimeType,
+      size: params.buffer.length,
+      hasSha256Header: Boolean(params.sha256),
+      error: String(error),
+    });
+    const label = params.fileName ?? params.objectKey ?? "attachment";
+    throw new Error(`sider object upload failed (${label}): ${describeError(error)}`, {
+      cause: error instanceof Error ? error : undefined,
+    });
+  }
+}
+
+async function completeFileUploadBestEffort(params: {
+  account: SiderUploadAccount;
+  sessionId: string;
+  fileId: string;
+  objectKey: string;
+  size: number;
+  sha256: string;
+  logger?: SiderUploadLogger;
+}): Promise<void> {
+  const url = resolveGatewayApiUrl(params.account.gatewayUrl, "/v1/files/complete");
+  try {
+    await postJson<unknown>({
+      url,
+      timeoutMs: params.account.sendTimeoutMs,
+      authorization: params.account.token,
+      body: {
+        session_id: params.sessionId,
+        file_id: params.fileId,
+        object_key: params.objectKey,
+        size: params.size,
+        sha256: params.sha256,
+      },
+    });
+  } catch (error) {
+    params.logger?.warn?.("sider files/complete failed (ignored)", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      fileId: params.fileId,
+      objectKey: params.objectKey,
+      error: String(error),
+    });
+  }
+}
+
+function buildSiderFilePart(params: {
+  uploaded: UploadedSiderFile;
+  sourceLabel?: string;
+}): SiderPart {
+  return {
+    type: "core.file",
+    spec_version: 1,
+    payload: {
+      file_id: params.uploaded.fileId,
+      object_key: params.uploaded.objectKey,
+      name: params.uploaded.fileName,
+      size: params.uploaded.size,
+      mime: params.uploaded.mimeType,
+      sha256: params.uploaded.sha256,
+      upload_status: "uploaded",
+    },
+    meta: {
+      ...(params.sourceLabel ? { source_media_url: params.sourceLabel } : {}),
+      media_kind: params.uploaded.mediaKind,
+    },
+  };
+}
+
+async function uploadPreparedMediaToSider(params: {
+  account: SiderUploadAccount;
+  sessionId: string;
+  media: PreparedSiderMedia;
+  logger?: SiderUploadLogger;
+}): Promise<UploadedSiderFile> {
+  const contentType = normalizeMime(params.media.contentType);
+  const inferredKind: "image" | "file" =
+    params.media.kind === "image" || contentType?.startsWith("image/") ? "image" : "file";
+  const sourceName = params.media.fileName || fileNameFromMediaUrl(params.media.sourceLabel ?? "");
+  const fallbackName = inferFallbackFileName({
+    mimeType: contentType ?? DEFAULT_MIME,
+    mediaKind: inferredKind,
+  });
+  const fileName = normalizeFileName(sourceName, fallbackName);
+  const mimeType = contentType || inferMimeFromFileName(fileName) || DEFAULT_MIME;
+  const size = params.media.buffer.length;
+  if (size <= 0) {
+    const suffix = params.media.sourceLabel ? ` from ${params.media.sourceLabel}` : "";
+    throw new Error(`empty media buffer${suffix}`);
+  }
+  const sha256 = sha256Hex(params.media.buffer);
+  const initResult = await initFileUpload({
+    account: params.account,
+    sessionId: params.sessionId,
+    fileName,
+    size,
+    mimeType,
+    sha256,
+    logger: params.logger,
+  });
+  params.logger?.debug?.("sider files/init success", {
+    accountId: params.account.accountId,
+    sessionId: params.sessionId,
+    fileId: initResult.fileId,
+    objectKey: initResult.objectKey,
+    size,
+    mimeType,
+  });
+  await uploadToObjectStore({
+    uploadUrl: initResult.uploadUrl,
+    mimeType,
+    sha256,
+    buffer: params.media.buffer,
+    timeoutMs: params.account.sendTimeoutMs,
+    logger: params.logger,
+    accountId: params.account.accountId,
+    sessionId: params.sessionId,
+    fileId: initResult.fileId,
+    objectKey: initResult.objectKey,
+    fileName,
+  });
+  await completeFileUploadBestEffort({
+    account: params.account,
+    sessionId: params.sessionId,
+    fileId: initResult.fileId,
+    objectKey: initResult.objectKey,
+    size,
+    sha256,
+    logger: params.logger,
+  });
+  return {
+    fileId: initResult.fileId,
+    objectKey: initResult.objectKey,
+    fileName,
+    mimeType,
+    size,
+    sha256,
+    mediaKind: inferredKind,
+  };
+}
+
+async function uploadMediaToSider(params: {
+  account: SiderUploadAccount;
+  sessionId: string;
+  mediaUrl: string;
+  sourceLabel?: string;
+  mediaLocalRoots?: readonly string[];
+  logger?: SiderUploadLogger;
+}): Promise<UploadedSiderFile> {
+  const loaded = await loadWebMedia(params.mediaUrl, undefined, {
+    localRoots: params.mediaLocalRoots,
+  });
+  return await uploadPreparedMediaToSider({
+    account: params.account,
+    sessionId: params.sessionId,
+    media: {
+      buffer: loaded.buffer,
+      contentType: loaded.contentType,
+      fileName: loaded.fileName || fileNameFromMediaUrl(params.sourceLabel ?? params.mediaUrl),
+      kind: loaded.kind,
+      sourceLabel: params.sourceLabel ?? params.mediaUrl,
+    },
+    logger: params.logger,
+  });
+}
+
+type ResolvedOutboundMediaItem = {
+  loadUrl: string;
+  sourceLabel: string;
+};
+
+function resolveOutboundMediaLoadUrl(sourceLabel: string): string {
+  const trimmed = sourceLabel.trim();
+  if (!trimmed) {
+    return trimmed;
+  }
+  if (/^https?:\/\//i.test(trimmed) || /^data:/i.test(trimmed)) {
+    return trimmed;
+  }
+  if (/^file:\/\//i.test(trimmed)) {
+    try {
+      return path.resolve(new URL(trimmed).pathname);
+    } catch {
+      return trimmed;
+    }
+  }
+  if (trimmed === "~") {
+    return os.homedir();
+  }
+  if (trimmed.startsWith("~/")) {
+    return path.join(os.homedir(), trimmed.slice(2));
+  }
+  if (path.isAbsolute(trimmed) || /^[A-Za-z]:[\\/]/.test(trimmed)) {
+    return path.resolve(trimmed);
+  }
+  if (!SCHEME_RE.test(trimmed)) {
+    return path.resolve(trimmed);
+  }
+  return trimmed;
+}
+
+async function resolveOutboundMediaItems(
+  params: Pick<BuildSiderPartsParams, "payload" | "mediaLocalRoots" | "logger">,
+): Promise<ResolvedOutboundMediaItem[]> {
+  const candidateUrls = dedupeMediaUrls([
+    ...resolveOutboundMediaUrls(params.payload),
+    ...extractMarkdownMediaUrls(params.payload.text),
+  ]);
+  const mediaItems: ResolvedOutboundMediaItem[] = [];
+  for (const sourceLabel of candidateUrls) {
+    if (sourceLabel.toLowerCase().startsWith(ATTACHMENT_REF_PREFIX)) {
+      const localPath = await resolveAttachmentRefToLocalPath({
+        attachmentRef: sourceLabel,
+        mediaLocalRoots: params.mediaLocalRoots,
+      });
+      if (!localPath) {
+        params.logger?.warn?.("sider skipped unresolved attachment:// media reference", {
+          mediaUrl: sourceLabel,
+          mediaLocalRootsCount: params.mediaLocalRoots?.length ?? 0,
+        });
+        continue;
+      }
+      mediaItems.push({
+        loadUrl: localPath,
+        sourceLabel,
+      });
+      continue;
+    }
+    mediaItems.push({
+      loadUrl: resolveOutboundMediaLoadUrl(sourceLabel),
+      sourceLabel,
+    });
+  }
+  return mediaItems;
+}
+
+export async function buildSiderPartFromInlineAttachment(params: {
+  account: SiderUploadAccount;
+  sessionId: string;
+  buffer: Buffer;
+  contentType?: string;
+  fileName?: string;
+  mediaKind?: "image" | "file";
+  sourceLabel?: string;
+  logger?: SiderUploadLogger;
+}): Promise<SiderPart> {
+  const uploaded = await uploadPreparedMediaToSider({
+    account: params.account,
+    sessionId: params.sessionId,
+    media: {
+      buffer: params.buffer,
+      contentType: params.contentType,
+      fileName: params.fileName,
+      kind: params.mediaKind,
+      sourceLabel: params.sourceLabel,
+    },
+    logger: params.logger,
+  });
+  return buildSiderFilePart({
+    uploaded,
+    sourceLabel: params.sourceLabel,
+  });
+}
+
+export async function buildSiderPartsFromReplyPayload(
+  params: BuildSiderPartsParams,
+): Promise<SiderPart[]> {
+  const mediaItems = await resolveOutboundMediaItems({
+    payload: params.payload,
+    mediaLocalRoots: params.mediaLocalRoots,
+    logger: params.logger,
+  });
+
+  const uploadedMediaParts: SiderPart[] = [];
+  const uploadFailures: Array<{ sourceLabel: string; error: string }> = [];
+  const sentSourceUrls = new Set<string>();
+  for (const media of mediaItems) {
+    try {
+      const uploaded = await uploadMediaToSider({
+        account: params.account,
+        sessionId: params.sessionId,
+        mediaUrl: media.loadUrl,
+        sourceLabel: media.sourceLabel,
+        mediaLocalRoots: params.mediaLocalRoots,
+        logger: params.logger,
+      });
+      uploadedMediaParts.push(
+        buildSiderFilePart({
+          uploaded,
+          sourceLabel: media.sourceLabel,
+        }),
+      );
+      sentSourceUrls.add(media.sourceLabel);
+    } catch (error) {
+      const describedError = describeError(error);
+      uploadFailures.push({
+        sourceLabel: media.sourceLabel,
+        error: describedError,
+      });
+      params.logger?.warn?.("sider skipped outbound media after upload failure", {
+        accountId: params.account.accountId,
+        sessionId: params.sessionId,
+        mediaUrl: media.sourceLabel,
+        resolvedMediaUrl: media.loadUrl,
+        error: describedError,
+      });
+    }
+  }
+
+  const parts: SiderPart[] = [];
+  const text = stripSentMarkdownMediaLinks(params.payload.text, sentSourceUrls);
+  if (text) {
+    parts.push({
+      type: "core.text",
+      spec_version: 1,
+      payload: { text },
+    });
+  }
+  parts.push(...uploadedMediaParts);
+
+  if (parts.length === 0 && uploadFailures.length > 0) {
+    const lastFailure = uploadFailures[uploadFailures.length - 1];
+    throw new Error(
+      `sider failed to upload outbound media ${lastFailure?.sourceLabel ?? ""}: ${lastFailure?.error ?? "unknown error"}`.trim(),
+    );
+  }
+
+  return parts;
+}