@sider-ai/chrome-openclaw-sider 1.0.31

package/dist/src/media-upload.js

@@ -0,0 +1,1308 @@
+import os from "node:os";
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { loadWebMedia } from "openclaw/plugin-sdk/web-media";
+import { formatAuthorizationHeader } from "./auth.js";
+import {
+  DEFAULT_MEDIA_SAVE_MAX_BYTES,
+  DEFAULT_MEDIA_UPLOAD_SKIP_MAX_BYTES
+} from "./channel-types.js";
+import { buildSourceFields } from "./channel-builders.js";
+import { siderOutboundLogger } from "./channel-runtime.js";
+import { resolveSiderDownloadUrl } from "./inbound-media.js";
+import { SIDER_USER_AGENT } from "./user-agent.js";
+const DEFAULT_MIME = "application/octet-stream";
+const DEFAULT_DEFERRED_UPLOAD_MAX_ATTEMPTS = 3;
+const DEFAULT_DEFERRED_UPLOAD_RETRY_BASE_MS = 1e3;
+async function sleepMs(delayMs) {
+  await new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+const MIME_BY_EXTENSION = {
+  ".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 = {
+  "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) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function normalizeMime(raw) {
+  const value = raw?.trim().toLowerCase();
+  if (!value) {
+    return void 0;
+  }
+  const normalized = value.split(";")[0]?.trim();
+  return normalized || void 0;
+}
+function extFromPath(raw) {
+  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) {
+  try {
+    if (/^https?:\/\//i.test(raw) || /^file:\/\//i.test(raw)) {
+      const pathname = new URL(raw).pathname;
+      const seg2 = pathname.split("/").filter(Boolean).pop();
+      return seg2 || void 0;
+    }
+  } catch {
+  }
+  const qPos = raw.indexOf("?");
+  const sanitized = qPos >= 0 ? raw.slice(0, qPos) : raw;
+  const seg = sanitized.split(/[\\/]/).filter(Boolean).pop();
+  return seg || void 0;
+}
+function normalizeFileName(raw, fallback) {
+  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) {
+  const ext = extFromPath(fileName);
+  return MIME_BY_EXTENSION[ext];
+}
+function inferFallbackFileName(params) {
+  const ext = EXTENSION_BY_MIME[params.mimeType];
+  if (ext) {
+    return `attachment${ext}`;
+  }
+  return params.mediaKind === "image" ? "attachment.png" : "attachment.bin";
+}
+function parsePositiveInteger(raw) {
+  if (!raw) {
+    return void 0;
+  }
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) {
+    return void 0;
+  }
+  return Math.floor(value);
+}
+function resolveSource(...candidates) {
+  for (const candidate of candidates) {
+    const trimmed = candidate?.trim();
+    if (trimmed) {
+      return trimmed;
+    }
+  }
+  return void 0;
+}
+function inferSourceMeta(sourceRef) {
+  const value = sourceRef?.trim();
+  if (!value) {
+    return void 0;
+  }
+  if (value.startsWith("/") || value.startsWith("./") || value.startsWith("../") || value.startsWith("~/") || /^[A-Za-z]:[\\/]/.test(value) || /^\\\\/.test(value) || /^file:\/\//i.test(value)) {
+    return { path: value };
+  }
+  return { mediaUrl: value };
+}
+function resolveMediaKind(params) {
+  const contentType = normalizeMime(params.contentType);
+  return params.kind === "image" || contentType?.startsWith("image/") ? "image" : "file";
+}
+function resolveDirectMediaUrl(loadUrl, source) {
+  const primary = loadUrl.trim();
+  if (primary) {
+    return primary;
+  }
+  const fallback = source?.trim();
+  return fallback || void 0;
+}
+function buildCoreFilePayloadFields(params) {
+  const source = params.source?.trim() || resolveDirectMediaUrl(params.loadUrl ?? "", params.source);
+  return {
+    ...buildSourceFields(source),
+    ...params.mediaKind ? { media_kind: params.mediaKind } : {}
+  };
+}
+function buildCoreFilePayloadBase(params) {
+  return {
+    ...buildCoreFilePayloadFields({
+      source: params.source,
+      loadUrl: params.loadUrl,
+      mediaKind: params.mediaKind
+    }),
+    name: params.fileName,
+    ...typeof params.size === "number" && Number.isFinite(params.size) ? { size: params.size } : {},
+    mime: params.mimeType
+  };
+}
+function resolveLocalMediaPath(loadUrl) {
+  const trimmed = loadUrl.trim();
+  if (!trimmed || /^https?:\/\//i.test(trimmed) || /^data:/i.test(trimmed)) {
+    return void 0;
+  }
+  if (/^file:\/\//i.test(trimmed)) {
+    try {
+      return path.resolve(new URL(trimmed).pathname);
+    } catch {
+      return void 0;
+    }
+  }
+  if (SCHEME_RE.test(trimmed)) {
+    return void 0;
+  }
+  return path.resolve(trimmed);
+}
+function estimateDataUrlSizeBytes(loadUrl) {
+  if (!/^data:/i.test(loadUrl)) {
+    return void 0;
+  }
+  const commaIndex = loadUrl.indexOf(",");
+  if (commaIndex < 0) {
+    return void 0;
+  }
+  const metadata = loadUrl.slice(0, commaIndex);
+  const body = loadUrl.slice(commaIndex + 1);
+  if (/;base64/i.test(metadata)) {
+    const normalized = body.replace(/\s+/g, "");
+    const padding = normalized.endsWith("==") ? 2 : normalized.endsWith("=") ? 1 : 0;
+    return Math.max(0, Math.floor(normalized.length * 3 / 4) - padding);
+  }
+  try {
+    return Buffer.byteLength(decodeURIComponent(body), "utf8");
+  } catch {
+    return Buffer.byteLength(body, "utf8");
+  }
+}
+async function probeRemoteContentLengthBytes(params) {
+  if (!/^https?:\/\//i.test(params.loadUrl)) {
+    return void 0;
+  }
+  try {
+    const response = await fetch(params.loadUrl, {
+      method: "HEAD",
+      headers: {
+        "User-Agent": SIDER_USER_AGENT
+      },
+      signal: AbortSignal.timeout(params.account.sendTimeoutMs)
+    });
+    if (!response.ok) {
+      return void 0;
+    }
+    return parsePositiveInteger(response.headers.get("content-length"));
+  } catch (error) {
+    params.logger?.warn?.("sider media size probe failed; falling back to buffered load", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      mediaUrl: params.loadUrl,
+      error: String(error)
+    });
+    return void 0;
+  }
+}
+async function probeMediaSizeBytes(params) {
+  const dataUrlSize = estimateDataUrlSizeBytes(params.loadUrl);
+  if (typeof dataUrlSize === "number") {
+    return dataUrlSize;
+  }
+  const localPath = resolveLocalMediaPath(params.loadUrl);
+  if (localPath) {
+    try {
+      const stats = await stat(localPath);
+      if (stats.isFile()) {
+        return stats.size;
+      }
+    } catch {
+    }
+    return void 0;
+  }
+  return await probeRemoteContentLengthBytes(params);
+}
+function buildDirectFilePart(params) {
+  const directUrl = resolveDirectMediaUrl(params.loadUrl ?? "", params.source);
+  const inferredKind = resolveMediaKind({
+    kind: params.mediaKind,
+    contentType: params.contentType
+  });
+  const fallbackName = inferFallbackFileName({
+    mimeType: normalizeMime(params.contentType) ?? DEFAULT_MIME,
+    mediaKind: inferredKind
+  });
+  const fileName = normalizeFileName(
+    params.fileName || fileNameFromMediaUrl(params.source ?? "") || fileNameFromMediaUrl(directUrl ?? ""),
+    fallbackName
+  );
+  const mimeType = normalizeMime(params.contentType) || inferMimeFromFileName(fileName) || DEFAULT_MIME;
+  return {
+    type: "core.file",
+    spec_version: 1,
+    payload: {
+      ...directUrl ? { url: directUrl } : {},
+      ...buildCoreFilePayloadBase({
+        source: params.source,
+        loadUrl: params.loadUrl,
+        mediaKind: inferredKind,
+        fileName,
+        size: params.size,
+        mimeType
+      }),
+      upload_status: "skipped"
+    },
+    meta: {
+      ...params.meta ?? {},
+      upload_skipped: true,
+      upload_skip_max_bytes: DEFAULT_MEDIA_UPLOAD_SKIP_MAX_BYTES
+    }
+  };
+}
+function sha256Hex(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+function resolveGatewayApiUrl(gatewayUrl, path2) {
+  const url = new URL(gatewayUrl);
+  const basePath = url.pathname.replace(/\/+$/, "");
+  const suffix = path2.startsWith("/") ? path2 : `/${path2}`;
+  url.pathname = `${basePath}${suffix}`;
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+async function readResponseErrorBody(response) {
+  try {
+    const text = (await response.text()).trim();
+    return text;
+  } catch {
+    return "";
+  }
+}
+function describeError(error) {
+  if (error instanceof Error) {
+    return error.message || String(error);
+  }
+  return String(error);
+}
+async function resolveDownloadUrlBestEffort(params) {
+  try {
+    return await resolveSiderDownloadUrl({
+      gatewayUrl: params.account.gatewayUrl,
+      objectKey: params.objectKey,
+      token: params.account.token,
+      timeoutMs: params.account.sendTimeoutMs
+    });
+  } catch (error) {
+    params.logger?.warn?.("sider failed to resolve outbound download url after files/init", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      objectKey: params.objectKey,
+      error: describeError(error)
+    });
+    return void 0;
+  }
+}
+function stripQueryAndHash(raw) {
+  return raw.split(/[?#]/, 1)[0] ?? raw;
+}
+function parseMarkdownLinkTarget(rawTarget) {
+  const trimmed = rawTarget.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  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 || void 0;
+}
+function shouldTreatMarkdownLinkAsMediaTarget(target) {
+  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) {
+  if (!text) {
+    return [];
+  }
+  const urls = [];
+  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) {
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  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, candidatePath) {
+  const relative = path.relative(rootDir, candidatePath);
+  return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function isPathWithinAnyRoot(filePath, roots) {
+  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) {
+  try {
+    const stats = await stat(filePath);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
+function looksLikeGeneratedAttachmentName(params) {
+  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) {
+  return Array.from(
+    /* @__PURE__ */ 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) {
+  let bestPath;
+  let bestMtimeMs = -1;
+  for (const dir of buildAttachmentLookupDirs(params.rootDir)) {
+    if (!isPathWithinRoot(params.rootDir, dir)) {
+      continue;
+    }
+    let entries;
+    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) {
+  const raw = params.attachmentRef.slice(ATTACHMENT_REF_PREFIX.length).trim();
+  if (!raw || !params.mediaLocalRoots?.length) {
+    return void 0;
+  }
+  let decoded;
+  try {
+    decoded = decodeURIComponent(raw);
+  } catch {
+    return void 0;
+  }
+  const decodedPath = stripQueryAndHash(decoded).trim();
+  if (!decodedPath) {
+    return void 0;
+  }
+  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 void 0;
+  }
+  const segments = normalizedSlash.split("/").filter(Boolean);
+  if (segments.length === 0 || segments.some((segment) => segment === "." || segment === "..")) {
+    return void 0;
+  }
+  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 void 0;
+}
+function stripSentMarkdownMediaLinks(text, sentSourceUrls) {
+  const input = text ?? "";
+  if (!input.trim()) {
+    return "";
+  }
+  if (sentSourceUrls.size === 0) {
+    return input.trim();
+  }
+  const strippedImages = input.replace(MARKDOWN_IMAGE_RE, (match, rawTarget) => {
+    const target = parseMarkdownLinkTarget(rawTarget);
+    if (!target || !sentSourceUrls.has(target)) {
+      return match;
+    }
+    return "";
+  });
+  const strippedLinks = strippedImages.replace(
+    MARKDOWN_LINK_RE,
+    (match, rawTarget, offset, source) => {
+      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(params) {
+  const headers = {
+    "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 = {};
+  if (text.trim()) {
+    try {
+      parsed = JSON.parse(text);
+    } catch (error) {
+      throw new Error(`invalid JSON response from ${params.url}: ${String(error)}`);
+    }
+  }
+  return parsed;
+}
+function parseFileInitResult(value) {
+  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) {
+  const url = resolveGatewayApiUrl(params.account.gatewayUrl, "/v1/files/init");
+  try {
+    const response = await postJson({
+      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 : void 0
+    });
+  }
+}
+async function uploadToObjectStore(params) {
+  const headers = {
+    "User-Agent": SIDER_USER_AGENT
+  };
+  if (params.mimeType) {
+    headers["Content-Type"] = params.mimeType;
+  }
+  if (params.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 : void 0
+    });
+  }
+}
+async function completeFileUploadBestEffort(params) {
+  const url = resolveGatewayApiUrl(params.account.gatewayUrl, "/v1/files/complete");
+  try {
+    await postJson({
+      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) {
+  return {
+    type: "core.file",
+    spec_version: 1,
+    payload: {
+      file_id: params.uploaded.fileId,
+      object_key: params.uploaded.objectKey,
+      download_url: params.uploaded.downloadUrl,
+      ...buildCoreFilePayloadBase({
+        source: params.source,
+        loadUrl: params.loadUrl,
+        mediaKind: params.uploaded.mediaKind,
+        fileName: params.uploaded.fileName,
+        size: params.uploaded.size,
+        mimeType: params.uploaded.mimeType
+      }),
+      sha256: params.uploaded.sha256,
+      upload_status: params.uploadStatus ?? "uploaded"
+    },
+    meta: {
+      ...params.meta ?? {}
+    }
+  };
+}
+function buildDeferredSiderUpload(params) {
+  return {
+    fileName: params.uploaded.fileName,
+    size: params.uploaded.size,
+    source: params.source,
+    upload: async () => {
+      await uploadInitializedMediaToSider({
+        account: params.account,
+        sessionId: params.sessionId,
+        uploaded: params.uploaded,
+        logger: params.logger
+      });
+    }
+  };
+}
+function startDeferredSiderUploads(params) {
+  for (const item of params.uploads) {
+    void (async () => {
+      let lastError;
+      for (let attempt = 1; attempt <= DEFAULT_DEFERRED_UPLOAD_MAX_ATTEMPTS; attempt += 1) {
+        if (attempt > 1) {
+          const delayMs = DEFAULT_DEFERRED_UPLOAD_RETRY_BASE_MS * 2 ** (attempt - 2);
+          siderOutboundLogger.warn?.("sider deferred upload retry scheduled", {
+            accountId: params.account.accountId,
+            sessionId: params.sessionId,
+            fileName: item.fileName,
+            source: item.source,
+            size: item.size,
+            context: params.context,
+            attempt,
+            maxAttempts: DEFAULT_DEFERRED_UPLOAD_MAX_ATTEMPTS,
+            delayMs,
+            error: describeError(lastError)
+          });
+          await sleepMs(delayMs);
+        }
+        try {
+          await item.upload();
+          siderOutboundLogger.debug?.(
+            attempt === 1 ? "sider deferred upload completed" : "sider deferred upload completed after retry",
+            {
+              accountId: params.account.accountId,
+              sessionId: params.sessionId,
+              fileName: item.fileName,
+              source: item.source,
+              size: item.size,
+              context: params.context,
+              attempt
+            }
+          );
+          return;
+        } catch (error) {
+          lastError = error;
+        }
+      }
+      siderOutboundLogger.warn?.("sider deferred upload failed", {
+        accountId: params.account.accountId,
+        sessionId: params.sessionId,
+        fileName: item.fileName,
+        source: item.source,
+        size: item.size,
+        context: params.context,
+        attempts: DEFAULT_DEFERRED_UPLOAD_MAX_ATTEMPTS,
+        error: describeError(lastError)
+      });
+    })();
+  }
+}
+async function initializePreparedMediaUpload(params) {
+  const contentType = normalizeMime(params.media.contentType);
+  const inferredKind = params.media.kind === "image" || contentType?.startsWith("image/") ? "image" : "file";
+  const sourceName = params.media.fileName || fileNameFromMediaUrl(params.media.source ?? "");
+  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.source ? ` from ${params.media.source}` : "";
+    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
+  });
+  const downloadUrl = await resolveDownloadUrlBestEffort({
+    account: params.account,
+    sessionId: params.sessionId,
+    objectKey: initResult.objectKey,
+    logger: params.logger
+  });
+  return {
+    fileId: initResult.fileId,
+    objectKey: initResult.objectKey,
+    downloadUrl,
+    uploadUrl: initResult.uploadUrl,
+    fileName,
+    mimeType,
+    size,
+    sha256,
+    mediaKind: inferredKind,
+    buffer: params.media.buffer
+  };
+}
+async function uploadInitializedMediaToSider(params) {
+  await uploadToObjectStore({
+    uploadUrl: params.uploaded.uploadUrl,
+    mimeType: params.uploaded.mimeType,
+    sha256: params.uploaded.sha256,
+    buffer: params.uploaded.buffer,
+    timeoutMs: params.account.sendTimeoutMs,
+    logger: params.logger,
+    accountId: params.account.accountId,
+    sessionId: params.sessionId,
+    fileId: params.uploaded.fileId,
+    objectKey: params.uploaded.objectKey,
+    fileName: params.uploaded.fileName
+  });
+  await completeFileUploadBestEffort({
+    account: params.account,
+    sessionId: params.sessionId,
+    fileId: params.uploaded.fileId,
+    objectKey: params.uploaded.objectKey,
+    size: params.uploaded.size,
+    sha256: params.uploaded.sha256,
+    logger: params.logger
+  });
+}
+async function uploadPreparedMediaToSider(params) {
+  const initialized = await initializePreparedMediaUpload(params);
+  await uploadInitializedMediaToSider({
+    account: params.account,
+    sessionId: params.sessionId,
+    uploaded: initialized,
+    logger: params.logger
+  });
+  return initialized;
+}
+async function uploadMediaToSider(params) {
+  const source = resolveSource(params.source, params.loadUrl);
+  const meta = params.meta ?? inferSourceMeta(source);
+  const sizeHint = await probeMediaSizeBytes({
+    account: params.account,
+    sessionId: params.sessionId,
+    loadUrl: params.loadUrl,
+    logger: params.logger
+  });
+  if (typeof sizeHint === "number" && Number.isFinite(sizeHint) && sizeHint > DEFAULT_MEDIA_UPLOAD_SKIP_MAX_BYTES) {
+    params.logger?.warn?.("sider skipping object-store upload for oversized outbound media", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      mediaUrl: params.loadUrl,
+      source,
+      size: sizeHint,
+      uploadSkipMaxBytes: DEFAULT_MEDIA_UPLOAD_SKIP_MAX_BYTES,
+      phase: "preflight"
+    });
+    return {
+      part: buildDirectFilePart({
+        loadUrl: params.loadUrl,
+        source,
+        meta,
+        fileName: fileNameFromMediaUrl(source ?? params.loadUrl),
+        size: sizeHint
+      })
+    };
+  }
+  const loaded = await loadWebMedia(params.loadUrl, DEFAULT_MEDIA_SAVE_MAX_BYTES, {
+    localRoots: params.mediaLocalRoots
+  });
+  const fileName = loaded.fileName || fileNameFromMediaUrl(source ?? params.loadUrl);
+  if (loaded.buffer.length > DEFAULT_MEDIA_UPLOAD_SKIP_MAX_BYTES) {
+    params.logger?.warn?.("sider skipping object-store upload for oversized outbound media", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      mediaUrl: params.loadUrl,
+      source,
+      size: loaded.buffer.length,
+      uploadSkipMaxBytes: DEFAULT_MEDIA_UPLOAD_SKIP_MAX_BYTES,
+      phase: "post-load"
+    });
+    return {
+      part: buildDirectFilePart({
+        loadUrl: params.loadUrl,
+        source,
+        meta,
+        fileName,
+        contentType: loaded.contentType,
+        mediaKind: loaded.kind,
+        size: loaded.buffer.length
+      })
+    };
+  }
+  const initialized = await initializePreparedMediaUpload({
+    account: params.account,
+    sessionId: params.sessionId,
+    media: {
+      buffer: loaded.buffer,
+      contentType: loaded.contentType,
+      fileName,
+      kind: loaded.kind,
+      source
+    },
+    logger: params.logger
+  });
+  if (params.deferUpload) {
+    return {
+      part: buildSiderFilePart({
+        uploaded: initialized,
+        source,
+        loadUrl: params.loadUrl,
+        meta,
+        uploadStatus: "accepted"
+      }),
+      deferredUpload: buildDeferredSiderUpload({
+        account: params.account,
+        sessionId: params.sessionId,
+        uploaded: initialized,
+        source,
+        logger: params.logger
+      })
+    };
+  }
+  await uploadInitializedMediaToSider({
+    account: params.account,
+    sessionId: params.sessionId,
+    uploaded: initialized,
+    logger: params.logger
+  });
+  return {
+    part: buildSiderFilePart({
+      uploaded: initialized,
+      source,
+      loadUrl: params.loadUrl,
+      meta
+    })
+  };
+}
+function buildReplyPayloadMediaMeta(params) {
+  if (params.sourceKey === "mediaUrls") {
+    return { mediaUrls: [params.source] };
+  }
+  return { mediaUrl: params.source };
+}
+function collectReplyPayloadMediaCandidates(payload) {
+  const candidates = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (source, sourceKey) => {
+    if (typeof source !== "string") {
+      return;
+    }
+    const trimmed = source.trim();
+    if (!trimmed || seen.has(trimmed)) {
+      return;
+    }
+    seen.add(trimmed);
+    candidates.push({ source: trimmed, sourceKey });
+  };
+  if (Array.isArray(payload.mediaUrls)) {
+    for (const source of payload.mediaUrls) {
+      push(source, "mediaUrls");
+    }
+  }
+  push(payload.mediaUrl, "mediaUrl");
+  for (const source of extractMarkdownMediaUrls(payload.text)) {
+    push(source, "text");
+  }
+  return candidates;
+}
+async function resolveOutboundMediaLoadUrl(params) {
+  const source = params.source.trim();
+  const trimmed = source.trim();
+  if (!trimmed) {
+    return trimmed;
+  }
+  if (source.toLowerCase().startsWith(ATTACHMENT_REF_PREFIX)) {
+    const localPath = await resolveAttachmentRefToLocalPath({
+      attachmentRef: source,
+      mediaLocalRoots: params.mediaLocalRoots
+    });
+    if (!localPath) {
+      siderOutboundLogger.warn?.("sider skipped unresolved attachment:// media reference", {
+        mediaUrl: source,
+        mediaLocalRootsCount: params.mediaLocalRoots?.length ?? 0
+      });
+    }
+    return localPath;
+  }
+  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) {
+  const mediaItems = [];
+  for (const candidate of collectReplyPayloadMediaCandidates(params.payload)) {
+    const source = candidate.source;
+    const loadUrl = await resolveOutboundMediaLoadUrl({
+      source,
+      mediaLocalRoots: params.mediaLocalRoots
+    });
+    if (loadUrl) {
+      mediaItems.push({
+        loadUrl,
+        source,
+        meta: buildReplyPayloadMediaMeta({
+          source,
+          sourceKey: candidate.sourceKey
+        })
+      });
+    }
+  }
+  return mediaItems;
+}
+async function buildSiderPartFromInlineAttachment(params) {
+  const prepared = await prepareInlineAttachmentPart({
+    account: params.account,
+    sessionId: params.sessionId,
+    buffer: params.buffer,
+    contentType: params.contentType,
+    fileName: params.fileName,
+    mediaKind: params.mediaKind,
+    source: params.source,
+    logger: params.logger
+  });
+  return prepared.part;
+}
+async function prepareInlineAttachmentPart(params) {
+  const meta = params.source ? inferSourceMeta(params.source) : void 0;
+  if (params.buffer.length > DEFAULT_MEDIA_UPLOAD_SKIP_MAX_BYTES) {
+    params.logger?.warn?.("sider skipping object-store upload for oversized inline attachment", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      source: params.source,
+      size: params.buffer.length,
+      uploadSkipMaxBytes: DEFAULT_MEDIA_UPLOAD_SKIP_MAX_BYTES
+    });
+    return {
+      part: buildDirectFilePart({
+        loadUrl: params.source,
+        source: params.source,
+        meta,
+        fileName: params.fileName,
+        contentType: params.contentType,
+        mediaKind: params.mediaKind,
+        size: params.buffer.length
+      })
+    };
+  }
+  const initialized = await initializePreparedMediaUpload({
+    account: params.account,
+    sessionId: params.sessionId,
+    media: {
+      buffer: params.buffer,
+      contentType: params.contentType,
+      fileName: params.fileName,
+      kind: params.mediaKind,
+      source: params.source
+    },
+    logger: params.logger ?? siderOutboundLogger
+  });
+  if (params.deferUpload) {
+    return {
+      part: buildSiderFilePart({
+        uploaded: initialized,
+        source: params.source,
+        loadUrl: params.source,
+        meta,
+        uploadStatus: "accepted"
+      }),
+      deferredUpload: buildDeferredSiderUpload({
+        account: params.account,
+        sessionId: params.sessionId,
+        uploaded: initialized,
+        source: params.source,
+        logger: params.logger ?? siderOutboundLogger
+      })
+    };
+  }
+  await uploadInitializedMediaToSider({
+    account: params.account,
+    sessionId: params.sessionId,
+    uploaded: initialized,
+    logger: params.logger
+  });
+  return {
+    part: buildSiderFilePart({
+      uploaded: initialized,
+      source: params.source,
+      loadUrl: params.source,
+      meta
+    })
+  };
+}
+async function buildOptimisticSiderPartFromInlineAttachment(params) {
+  return await prepareInlineAttachmentPart({
+    account: params.account,
+    sessionId: params.sessionId,
+    buffer: params.buffer,
+    contentType: params.contentType,
+    fileName: params.fileName,
+    mediaKind: params.mediaKind,
+    source: params.source,
+    logger: siderOutboundLogger,
+    deferUpload: true
+  });
+}
+async function buildSiderPartsFromReplyPayload(params) {
+  const mediaItems = await resolveOutboundMediaItems({
+    payload: params.payload,
+    mediaLocalRoots: params.mediaLocalRoots
+  });
+  const mediaParts = [];
+  const deferredUploads = [];
+  const failures = [];
+  const sentSourceUrls = /* @__PURE__ */ new Set();
+  for (const media of mediaItems) {
+    try {
+      const prepared = await uploadMediaToSider({
+        account: params.account,
+        sessionId: params.sessionId,
+        loadUrl: media.loadUrl,
+        source: media.source,
+        meta: media.meta,
+        mediaLocalRoots: params.mediaLocalRoots,
+        logger: siderOutboundLogger,
+        deferUpload: params.deferUploads === true
+      });
+      mediaParts.push(prepared.part);
+      if (prepared.deferredUpload) {
+        deferredUploads.push(prepared.deferredUpload);
+      }
+      sentSourceUrls.add(media.source);
+    } catch (error) {
+      const describedError = describeError(error);
+      failures.push({
+        source: media.source,
+        error: describedError
+      });
+      siderOutboundLogger.warn?.(
+        params.deferUploads ? "sider skipped optimistic outbound media after init failure" : "sider skipped outbound media after upload failure",
+        {
+          accountId: params.account.accountId,
+          sessionId: params.sessionId,
+          mediaUrl: media.source,
+          resolvedMediaUrl: media.loadUrl,
+          error: describedError
+        }
+      );
+    }
+  }
+  const parts = [];
+  const text = stripSentMarkdownMediaLinks(params.payload.text, sentSourceUrls);
+  if (text) {
+    parts.push({
+      type: "core.text",
+      spec_version: 1,
+      payload: {
+        text,
+        ...params.payload.isError ? { is_error: true } : {}
+      }
+    });
+  }
+  parts.push(...mediaParts);
+  if (parts.length === 0 && failures.length > 0) {
+    const lastFailure = failures[failures.length - 1];
+    throw new Error(
+      `sider failed to ${params.deferUploads ? "prepare" : "upload"} outbound media ${lastFailure?.source ?? ""}: ${lastFailure?.error ?? "unknown error"}`.trim()
+    );
+  }
+  return {
+    parts,
+    deferredUploads
+  };
+}
+export {
+  buildOptimisticSiderPartFromInlineAttachment,
+  buildSiderPartFromInlineAttachment,
+  buildSiderPartsFromReplyPayload,
+  inferSourceMeta,
+  resolveOutboundMediaLoadUrl,
+  startDeferredSiderUploads,
+  uploadMediaToSider
+};