@parall/agent-core 1.23.0 → 1.25.0

package/dist/internal/attachment-input.js

@@ -0,0 +1,687 @@
+import { execSync } from "node:child_process";
+import { constants } from "node:fs";
+import * as fsSync from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { formatBytes, renderLocalAttachmentSection } from "../prompt-fragments.js";
+/**
+ * Per-dispatch cap on image bytes a runtime turn receives. Counts declared
+ * attachment sizes plus fresh download bytes; cache hits are NOT recharged
+ * against this budget — those are already on disk and bounded separately by
+ * `DEFAULT_ATTACHMENT_CACHE_MAX_BYTES` below. The cap exists to keep any one
+ * dispatch from saturating the bridge↔runtime hop with a single oversized
+ * batch; the cache cap exists to keep the workspace from growing unbounded.
+ */
+export const DEFAULT_MAX_TOTAL_IMAGE_BYTES = 20 * 1024 * 1024;
+/**
+ * Workspace cache ceiling. The default is generous for typical operator setups,
+ * but on small PVCs (e.g. 1 GiB) it can claim a meaningful fraction of disk.
+ * Operators on constrained storage should override via `LocalAttachmentOptions.maxCacheBytes`.
+ */
+export const DEFAULT_ATTACHMENT_CACHE_MAX_BYTES = 512 * 1024 * 1024;
+export const DEFAULT_ATTACHMENT_DOWNLOAD_TIMEOUT_MS = 30_000;
+export const DEFAULT_ATTACHMENT_TTL_MS = 24 * 60 * 60 * 1000;
+export const DEFAULT_MAINTENANCE_COOLDOWN_MS = 60 * 1000;
+const SUPPORTED_IMAGE_MIME_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/jpg",
+    "image/webp",
+    "image/gif",
+]);
+// Process-global state — correct under the current "one gateway per agent"
+// architecture (each runtime bridge is a single-tenant subprocess, so all
+// in-flight dispatches share one logical agent identity). If the gateway
+// ever multiplexes multiple agent identities in a single process, both
+// `activeAttachmentDirs` and `maintenanceStateByRoot` need to be scoped per
+// tenant — otherwise they leak active-dispatch and cooldown state across
+// agents that should not share cache visibility.
+const activeAttachmentDirs = new Set();
+export async function prepareLocalImageAttachments(event, context, opts) {
+    const attachments = event.attachments ?? [];
+    const imageAttachments = attachments.filter((att) => SUPPORTED_IMAGE_MIME_TYPES.has(att.mimeType.toLowerCase()));
+    if (imageAttachments.length === 0)
+        return { images: [], notes: [] };
+    const maxTotalImageBytes = opts.maxTotalImageBytes ?? DEFAULT_MAX_TOTAL_IMAGE_BYTES;
+    const totalDeclaredBytes = imageAttachments.reduce((sum, att) => sum + Math.max(0, att.fileSize), 0);
+    if (totalDeclaredBytes > maxTotalImageBytes) {
+        return {
+            images: [],
+            notes: [
+                `[Image attachments not downloaded: total size ${formatBytes(totalDeclaredBytes)} exceeds bridge limit ${formatBytes(maxTotalImageBytes)}]`,
+            ],
+        };
+    }
+    const rootDir = await ensureAttachmentRootDir(opts.workspaceDir);
+    // Pin this dispatch's message directory in `activeAttachmentDirs` BEFORE
+    // scheduling cache maintenance. The maintenance pass snapshots active dirs
+    // when it starts; if we scheduled first, a concurrent prune could observe
+    // the snapshot without our entry and delete a same-`messageId` cache from a
+    // prior dispatch (retry / replay) right under us.
+    const messageDir = path.join(rootDir, sanitizePathSegment(event.messageId));
+    await ensurePathIsNotSymlink(messageDir);
+    await fs.mkdir(messageDir, { recursive: true });
+    await ensurePathIsNotSymlink(messageDir);
+    const activeMessageDir = path.resolve(messageDir);
+    activeAttachmentDirs.add(activeMessageDir);
+    // Cache maintenance (TTL cleanup + LRU prune) walks every cached message
+    // directory and stats every file. Doing it synchronously per-dispatch turns
+    // dispatch latency into O(cache_dirs) and burns CPU under high concurrency
+    // (1000 in-flight dispatches → 1000 walks). Instead we throttle by root
+    // (one pass per cooldown window) and run it off the dispatch path. The
+    // cache cap is best-effort, not a hard ceiling — cooldown drift is fine.
+    const maintenanceCooldownMs = opts.maintenanceCooldownMs ?? DEFAULT_MAINTENANCE_COOLDOWN_MS;
+    const maintenancePromise = scheduleAttachmentMaintenance(rootDir, {
+        ttlMs: opts.attachmentTtlMs ?? DEFAULT_ATTACHMENT_TTL_MS,
+        maxBytes: opts.maxCacheBytes ?? DEFAULT_ATTACHMENT_CACHE_MAX_BYTES,
+        cooldownMs: maintenanceCooldownMs,
+        log: opts.log,
+    });
+    if (maintenanceCooldownMs === 0 && maintenancePromise) {
+        // Sync-mode for tests that need deterministic prune ordering relative to
+        // active-dispatch tracking. Production paths leave this on the background.
+        await maintenancePromise;
+    }
+    try {
+        const images = [];
+        const notes = [];
+        let downloadedBytes = 0;
+        for (const att of imageAttachments) {
+            const localPath = path.join(messageDir, localFileName(att.id, att.fileName, att.mimeType));
+            const downloadTimeoutMs = opts.downloadTimeoutMs ?? DEFAULT_ATTACHMENT_DOWNLOAD_TIMEOUT_MS;
+            const fetchFresh = async () => {
+                const fileInfo = await withTimeout(context.client.getFileUrl(att.id), downloadTimeoutMs, `file URL lookup timed out after ${downloadTimeoutMs}ms`);
+                downloadedBytes += await downloadAttachmentToFile(fileInfo.url, localPath, maxTotalImageBytes - downloadedBytes, downloadTimeoutMs, rootDir);
+            };
+            const cameFromCache = await existingUsableFile(localPath, att.fileSize, rootDir);
+            if (!cameFromCache) {
+                try {
+                    await fetchFresh();
+                }
+                catch (err) {
+                    opts.log?.warn?.(`agent-core: failed to prepare local image attachment ${att.id}: ${String(err)}`);
+                    notes.push(`[Image attachment unavailable locally: prll://${sanitizeMeta(att.id)}]`);
+                    continue;
+                }
+            }
+            let mimeOk = await downloadedFileMatchesImageMime(localPath, att.mimeType, rootDir);
+            if (!mimeOk && cameFromCache) {
+                // Cache hit produced a file whose magic bytes don't match the declared
+                // MIME — the cached copy is corrupt (partial write, agent edit,
+                // bit-rot). Drop it and try once with a fresh download before giving
+                // up; a genuinely broken upstream will fail the second MIME check
+                // too and fall through to the unavailable note.
+                await removeLocalFileIfInside(localPath, rootDir);
+                try {
+                    await fetchFresh();
+                }
+                catch (err) {
+                    opts.log?.warn?.(`agent-core: failed to re-download corrupted cache for ${att.id}: ${String(err)}`);
+                    notes.push(`[Image attachment unavailable locally: prll://${sanitizeMeta(att.id)}]`);
+                    continue;
+                }
+                mimeOk = await downloadedFileMatchesImageMime(localPath, att.mimeType, rootDir);
+            }
+            if (!mimeOk) {
+                await removeLocalFileIfInside(localPath, rootDir);
+                notes.push(`[Image attachment unavailable locally: prll://${sanitizeMeta(att.id)} (downloaded content does not match ${sanitizeMeta(att.mimeType)})]`);
+                continue;
+            }
+            images.push({
+                attachmentId: att.id,
+                fileName: att.fileName,
+                mimeType: att.mimeType,
+                fileSize: att.fileSize,
+                localPath,
+            });
+        }
+        return { images, notes };
+    }
+    finally {
+        activeAttachmentDirs.delete(activeMessageDir);
+    }
+}
+export function appendLocalAttachmentRefs(body, result) {
+    const section = renderLocalAttachmentSection(result);
+    return section ? `${body}\n\n${section}` : body;
+}
+export async function appendPreparedLocalAttachmentRefs(body, event, context, opts) {
+    const attachments = await prepareLocalImageAttachments(event, context, opts);
+    return { body: appendLocalAttachmentRefs(body, attachments), attachments };
+}
+export function pinLocalAttachmentPaths(images) {
+    const dirs = new Set(images.map((image) => path.resolve(path.dirname(image.localPath))));
+    for (const dir of dirs) {
+        activeAttachmentDirs.add(dir);
+    }
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        for (const dir of dirs) {
+            activeAttachmentDirs.delete(dir);
+        }
+    };
+}
+function attachmentRootDir(workspaceDir) {
+    return path.join(path.resolve(workspaceDir), ".parall", "attachments");
+}
+/**
+ * Append `.parall/` to the workspace's git info/exclude. Best-effort — a
+ * missing exclude entry should not block dispatch. Used by both Claude and
+ * Codex bridges' workspace bootstrap; lives here next to the attachment
+ * download logic so the directory convention stays in one place.
+ */
+export function ensureLocalAttachmentGitExclude(workingDirectory) {
+    try {
+        const rel = execSync("git rev-parse --git-path info/exclude", {
+            cwd: workingDirectory,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const excludePath = path.isAbsolute(rel) ? rel : path.join(workingDirectory, rel);
+        fsSync.mkdirSync(path.dirname(excludePath), { recursive: true });
+        const existing = fsSync.existsSync(excludePath) ? fsSync.readFileSync(excludePath, "utf8") : "";
+        if (existing.split(/\r?\n/).some((line) => line.trim() === ".parall/"))
+            return;
+        const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+        fsSync.appendFileSync(excludePath, `${prefix}.parall/\n`, "utf8");
+    }
+    catch {
+        // Best-effort only. A missing exclude entry should not block dispatch.
+    }
+}
+const maintenanceStateByRoot = new Map();
+/**
+ * Throttled, off-path cache maintenance. Returns a promise the caller can
+ * await in test mode; production callers ignore the return value so the prune
+ * walk runs in the background without blocking dispatch latency.
+ *
+ * Concurrency model: when a pass is in-flight, concurrent dispatches see the
+ * existing promise and skip; they don't pile up redundant walks. When the
+ * cooldown is unexpired, dispatches return null immediately. Worst case the
+ * cache exceeds `maxBytes` by a bounded amount until the next cooldown
+ * window — acceptable, since the cap is a soft ceiling, not a hard limit.
+ */
+function scheduleAttachmentMaintenance(rootDir, opts) {
+    const state = maintenanceStateByRoot.get(rootDir);
+    if (state?.inFlight)
+        return state.inFlight;
+    const now = Date.now();
+    if (state && now - state.lastRunMs < opts.cooldownMs)
+        return null;
+    const newState = state ?? { lastRunMs: 0, inFlight: null };
+    if (!state)
+        maintenanceStateByRoot.set(rootDir, newState);
+    const run = (async () => {
+        try {
+            await cleanupOldAttachmentFiles(rootDir, opts.ttlMs, opts.log, activeDirsForRoot(rootDir));
+            await pruneAttachmentCache(rootDir, opts.maxBytes, opts.log, activeDirsForRoot(rootDir));
+        }
+        catch (err) {
+            opts.log?.warn?.(`agent-core: attachment cache maintenance failed: ${String(err)}`);
+        }
+        finally {
+            newState.lastRunMs = Date.now();
+            newState.inFlight = null;
+        }
+    })();
+    newState.inFlight = run;
+    return run;
+}
+async function ensureAttachmentRootDir(workspaceDir) {
+    const workspaceRoot = path.resolve(workspaceDir);
+    const parallDir = path.join(workspaceRoot, ".parall");
+    const rootDir = attachmentRootDir(workspaceRoot);
+    await fs.mkdir(workspaceRoot, { recursive: true });
+    await ensurePathIsNotSymlink(parallDir);
+    await fs.mkdir(parallDir, { recursive: true, mode: 0o700 });
+    await ensurePathIsNotSymlink(parallDir);
+    await ensurePathIsNotSymlink(rootDir);
+    await fs.mkdir(rootDir, { recursive: true, mode: 0o700 });
+    await ensurePathIsNotSymlink(rootDir);
+    const realWorkspace = await fs.realpath(workspaceRoot);
+    const realRoot = await fs.realpath(rootDir);
+    if (!isPathInside(realRoot, realWorkspace)) {
+        throw new Error(`attachment root escapes workspace: ${rootDir}`);
+    }
+    return rootDir;
+}
+async function ensurePathIsNotSymlink(filePath) {
+    try {
+        const stat = await fs.lstat(filePath);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`refusing to use symlinked attachment path ${filePath}`);
+        }
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return;
+        throw err;
+    }
+}
+function isPathInside(childPath, parentPath) {
+    const rel = path.relative(parentPath, childPath);
+    return rel === "" || (!!rel && !rel.startsWith("..") && !path.isAbsolute(rel));
+}
+async function existingUsableFile(filePath, expectedSize, rootDir) {
+    try {
+        const stat = await localFileStatInsideRoot(filePath, rootDir);
+        return stat.isFile() && stat.size > 0 && (expectedSize <= 0 || stat.size === expectedSize);
+    }
+    catch {
+        return false;
+    }
+}
+async function localFileStatInsideRoot(filePath, rootDir) {
+    const stat = await fs.lstat(filePath);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`refusing to use symlinked attachment file ${filePath}`);
+    }
+    if (!stat.isFile()) {
+        throw new Error(`attachment path is not a file ${filePath}`);
+    }
+    const realRoot = await fs.realpath(rootDir);
+    const realFile = await fs.realpath(filePath);
+    if (!isPathInside(realFile, realRoot)) {
+        throw new Error(`attachment file escapes workspace: ${filePath}`);
+    }
+    return stat;
+}
+async function localDirectoryStatInsideRoot(dirPath, rootDir) {
+    const stat = await fs.lstat(dirPath);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`refusing to use symlinked attachment directory ${dirPath}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`attachment path is not a directory ${dirPath}`);
+    }
+    const realRoot = await fs.realpath(rootDir);
+    const realDir = await fs.realpath(dirPath);
+    if (!isPathInside(realDir, realRoot)) {
+        throw new Error(`attachment directory escapes workspace: ${dirPath}`);
+    }
+    return stat;
+}
+async function openLocalFileInsideRoot(filePath, rootDir) {
+    const checkedStat = await localFileStatInsideRoot(filePath, rootDir);
+    const file = await fs.open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let keepOpen = false;
+    try {
+        const openedStat = await file.stat();
+        if (!sameFile(checkedStat, openedStat)) {
+            throw new Error(`attachment file changed during validation: ${filePath}`);
+        }
+        keepOpen = true;
+        return file;
+    }
+    finally {
+        if (!keepOpen) {
+            await file.close();
+        }
+    }
+}
+async function openLocalTempFileInsideRoot(filePath, rootDir) {
+    // Trusted-workspace assumption: the workspace dir is owned by the runtime
+    // bridge and not shared with untrusted local writers. There is a narrow
+    // TOCTOU window between the parent-directory validation here and the
+    // O_NOFOLLOW open; closing it would require descriptor-relative (openat)
+    // operations, which Node's fs API does not expose. The post-open inode
+    // identity check below + the post-write rename validation in
+    // writeResponseToFileWithLimit ensure downloaded bytes can never escape
+    // the attachment root, even if the window is exploited — the worst case
+    // is a write that lands in a directory the attacker already controls.
+    await localDirectoryStatInsideRoot(path.dirname(filePath), rootDir);
+    const file = await fs.open(filePath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    let keepOpen = false;
+    try {
+        const checkedStat = await localFileStatInsideRoot(filePath, rootDir);
+        const openedStat = await file.stat();
+        if (!sameFileIdentity(checkedStat, openedStat)) {
+            throw new Error(`attachment temp file changed during validation: ${filePath}`);
+        }
+        keepOpen = true;
+        return { file, openedStat };
+    }
+    finally {
+        if (!keepOpen) {
+            await file.close();
+        }
+    }
+}
+async function assertLocalFileIdentity(filePath, rootDir, expected) {
+    const stat = await localFileStatInsideRoot(filePath, rootDir);
+    if (!sameFileIdentity(stat, expected)) {
+        throw new Error(`attachment file changed during validation: ${filePath}`);
+    }
+}
+async function removeLocalFileIfInside(filePath, rootDir) {
+    try {
+        await localFileStatInsideRoot(filePath, rootDir);
+        await fs.rm(filePath, { force: true });
+    }
+    catch {
+        // If the path no longer resolves inside the attachment root, do not follow it for cleanup.
+    }
+}
+function sameFileIdentity(a, b) {
+    return a.dev === b.dev && a.ino === b.ino;
+}
+function sameFile(a, b) {
+    return sameFileIdentity(a, b) && a.size === b.size && a.mtimeMs === b.mtimeMs;
+}
+async function cleanupOldAttachmentFiles(rootDir, ttlMs, log, preserveDirs) {
+    let entries;
+    try {
+        entries = await fs.readdir(rootDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const cutoff = Date.now() - ttlMs;
+    await Promise.all(entries.map(async (entry) => {
+        if (!entry.isDirectory())
+            return;
+        const fullPath = path.join(rootDir, entry.name);
+        try {
+            if (preserveDirs?.has(path.resolve(fullPath)))
+                return;
+            // lstat (not stat) for consistency with the symlink-hardened download
+            // path: if a racing local writer swapped the dir entry for a symlink
+            // between readdir and now, we don't want fs.rm to follow it and delete
+            // outside the attachment root.
+            const stat = await fs.lstat(fullPath);
+            if (!stat.isDirectory())
+                return;
+            if (stat.mtimeMs < cutoff) {
+                await fs.rm(fullPath, { recursive: true, force: true });
+            }
+        }
+        catch (err) {
+            log?.warn?.(`agent-core: failed to clean attachment temp dir ${fullPath}: ${String(err)}`);
+        }
+    }));
+}
+async function pruneAttachmentCache(rootDir, maxBytes, log, preserveDirs) {
+    if (maxBytes <= 0)
+        return;
+    let entries;
+    try {
+        entries = await fs.readdir(rootDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const dirs = [];
+    let total = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const fullPath = path.join(rootDir, entry.name);
+        try {
+            // lstat (not stat) for the same reason as cleanupOldAttachmentFiles —
+            // never follow a swapped-in symlink during the readdir → rm window.
+            const stat = await fs.lstat(fullPath);
+            if (!stat.isDirectory())
+                continue;
+            const size = await directorySize(fullPath);
+            dirs.push({ path: fullPath, mtimeMs: stat.mtimeMs, size });
+            total += size;
+        }
+        catch (err) {
+            log?.warn?.(`agent-core: failed to inspect attachment cache dir ${fullPath}: ${String(err)}`);
+        }
+    }
+    if (total <= maxBytes)
+        return;
+    dirs.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    for (const dir of dirs) {
+        if (total <= maxBytes)
+            break;
+        if (preserveDirs?.has(path.resolve(dir.path)))
+            continue;
+        try {
+            await fs.rm(dir.path, { recursive: true, force: true });
+            total -= dir.size;
+        }
+        catch (err) {
+            log?.warn?.(`agent-core: failed to prune attachment cache dir ${dir.path}: ${String(err)}`);
+        }
+    }
+}
+async function directorySize(dirPath) {
+    let total = 0;
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        // lstat (not stat) for consistency with cleanup/prune — never follow a
+        // racing-swap symlink during the recursive walk, even just to count
+        // bytes. Skip anything that isn't a real file or real directory.
+        let stat;
+        try {
+            stat = await fs.lstat(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            total += await directorySize(fullPath);
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        total += stat.size;
+    }
+    return total;
+}
+function activeDirsForRoot(rootDir) {
+    const root = path.resolve(rootDir);
+    const dirs = new Set();
+    for (const dir of activeAttachmentDirs) {
+        if (dir === root || dir.startsWith(`${root}${path.sep}`)) {
+            dirs.add(dir);
+        }
+    }
+    return dirs;
+}
+async function downloadAttachmentToFile(url, filePath, maxBytes, timeoutMs, rootDir) {
+    // Defense-in-depth: the SDK currently always returns HTTPS signed URLs, but a
+    // misconfigured API server (or a future regression) handing back `file://` /
+    // `data:` would let `fetch` read local files or inline payloads as if they
+    // were the attachment. Reject anything that isn't HTTP(S) before we open the
+    // network call. http:// stays allowed for local dev / tests.
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`invalid attachment URL`);
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new Error(`refusing attachment URL with scheme ${parsed.protocol}`);
+    }
+    const controller = new AbortController();
+    let timeout;
+    if (timeoutMs > 0) {
+        timeout = setTimeout(() => controller.abort(), timeoutMs);
+    }
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        if (!res.ok) {
+            throw new Error(`${res.status} ${res.statusText}`);
+        }
+        // Content-Length is only an early-exit hint; the stream byte counter below is authoritative.
+        const contentLength = parseContentLength(res.headers.get("content-length"));
+        if (contentLength !== undefined && contentLength > maxBytes) {
+            throw new Error(`download would exceed ${formatBytes(maxBytes)} remaining turn limit`);
+        }
+        return await writeResponseToFileWithLimit(res, filePath, maxBytes, rootDir);
+    }
+    catch (err) {
+        if (isAbortError(err)) {
+            throw new Error(`download timed out after ${timeoutMs}ms`);
+        }
+        throw err;
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+async function withTimeout(promise, timeoutMs, message) {
+    if (timeoutMs <= 0)
+        return promise;
+    let timeout;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => reject(new Error(message)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+async function writeResponseToFileWithLimit(res, filePath, maxBytes, rootDir) {
+    if (maxBytes <= 0) {
+        throw new Error("download would exceed turn limit");
+    }
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    const { file, openedStat } = await openLocalTempFileInsideRoot(tmpPath, rootDir);
+    let written = 0;
+    let completed = false;
+    let fileClosed = false;
+    let writtenStat = openedStat;
+    const closeFile = async () => {
+        if (fileClosed)
+            return;
+        await file.close();
+        fileClosed = true;
+    };
+    try {
+        if (!res.body) {
+            const buffer = Buffer.from(await res.arrayBuffer());
+            if (buffer.byteLength > maxBytes) {
+                throw new Error(`download exceeded ${formatBytes(maxBytes)} remaining turn limit`);
+            }
+            await file.write(buffer);
+            written = buffer.byteLength;
+        }
+        else {
+            const reader = res.body.getReader();
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                const chunk = Buffer.from(value);
+                written += chunk.byteLength;
+                if (written > maxBytes) {
+                    throw new Error(`download exceeded ${formatBytes(maxBytes)} remaining turn limit`);
+                }
+                await file.write(chunk);
+            }
+        }
+        writtenStat = await file.stat();
+        await closeFile();
+        await localDirectoryStatInsideRoot(path.dirname(filePath), rootDir);
+        await assertLocalFileIdentity(tmpPath, rootDir, writtenStat);
+        await fs.rename(tmpPath, filePath);
+        completed = true;
+        return written;
+    }
+    finally {
+        if (!fileClosed) {
+            try {
+                await closeFile();
+            }
+            catch {
+                // Preserve the original write/rename error; cleanup below is best-effort.
+            }
+        }
+        if (!completed) {
+            await removeLocalFileIfInside(tmpPath, rootDir);
+        }
+    }
+}
+function localFileName(attachmentId, fileName, mimeType) {
+    const safeName = sanitizePathSegment(path.basename(fileName || attachmentId));
+    const ext = path.extname(safeName) || extensionForMime(mimeType);
+    const stem = path.basename(safeName, path.extname(safeName)) || attachmentId;
+    return `${sanitizePathSegment(attachmentId)}-${stem}${ext}`;
+}
+function extensionForMime(mimeType) {
+    switch (mimeType.toLowerCase()) {
+        case "image/jpeg":
+        case "image/jpg":
+            return ".jpg";
+        case "image/webp":
+            return ".webp";
+        case "image/gif":
+            return ".gif";
+        case "image/png":
+        default:
+            return ".png";
+    }
+}
+function sanitizePathSegment(value) {
+    const safe = value.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^_+|_+$/g, "");
+    if (!safe || /^\.+$/.test(safe))
+        return "attachment";
+    return safe;
+}
+async function downloadedFileMatchesImageMime(filePath, mimeType, rootDir) {
+    const file = await openLocalFileInsideRoot(filePath, rootDir);
+    try {
+        const buffer = Buffer.alloc(16);
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+        return imageHeaderMatches(buffer.subarray(0, bytesRead), mimeType);
+    }
+    finally {
+        await file.close();
+    }
+}
+function imageHeaderMatches(bytes, mimeType) {
+    switch (mimeType.toLowerCase()) {
+        case "image/png":
+            return bytes.length >= 8
+                && bytes[0] === 0x89
+                && bytes[1] === 0x50
+                && bytes[2] === 0x4e
+                && bytes[3] === 0x47
+                && bytes[4] === 0x0d
+                && bytes[5] === 0x0a
+                && bytes[6] === 0x1a
+                && bytes[7] === 0x0a;
+        case "image/jpeg":
+        case "image/jpg":
+            return bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff;
+        case "image/gif":
+            return bytes.length >= 6
+                && (bytes.subarray(0, 6).toString("ascii") === "GIF87a"
+                    || bytes.subarray(0, 6).toString("ascii") === "GIF89a");
+        case "image/webp":
+            return bytes.length >= 12
+                && bytes.subarray(0, 4).toString("ascii") === "RIFF"
+                && bytes.subarray(8, 12).toString("ascii") === "WEBP";
+        default:
+            return false;
+    }
+}
+function isAbortError(err) {
+    return err instanceof DOMException && err.name === "AbortError";
+}
+function sanitizeMeta(value) {
+    return value.replace(/[\r\n]+/g, " ").replace(/[[\]|]/g, " ").trim();
+}
+function parseContentLength(value) {
+    if (!value)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    return n;
+}