dsh-ntr 0.3.2 → 0.3.4

package/lib/impl.js

@@ -834,6 +834,42 @@ export function childEnv(parent, extra) {
     return out;
 }
 // ---- Model catalog (pure parsing of ACP `configOptions`) ----
+/**
+ * ACP categories are free-form UX hints, not identity. Qoder CN tags
+ * `reasoning_effort` as `category: 'model'` (the spec means `thought_level`),
+ * and nothing stops an agent from reusing a category for several options.
+ * Slots are therefore assigned by `configId` first and category second, and a
+ * same-category option NEVER replaces another option's slot: whatever loses
+ * stays reachable through `extras` instead of silently becoming the model list.
+ */
+const EFFORT_OPTION_HINT = /effort|thinking|thought|reason/i;
+function isModelSelector(configId, name) {
+    return configId === 'model' || name.trim().toLowerCase() === 'model';
+}
+function catalogSlotFor(category, configId, name) {
+    const effortish = EFFORT_OPTION_HINT.test(configId) || EFFORT_OPTION_HINT.test(name);
+    if (category === 'model') {
+        // The option explicitly named `model` is the selector even when other
+        // model-scoped options are present.
+        if (isModelSelector(configId, name))
+            return { slot: 'model', rank: 3 };
+        // A model-scoped effort is mislabelled, not a model: route it to the
+        // thought chip when no real `thought_level` option is published.
+        if (effortish)
+            return { slot: 'thought', rank: 1 };
+        // An unknown model-scoped select: a last-resort selector only.
+        return { slot: 'model', rank: 1 };
+    }
+    if (category === 'thought_level')
+        return { slot: 'thought', rank: 3 };
+    if (category === 'mode')
+        return { slot: 'mode', rank: 2 };
+    // `model_config` is where the spec puts model-dependent knobs (effort,
+    // context size); only the effort-shaped ones have a dedicated control.
+    if (category === 'model_config' && effortish)
+        return { slot: 'thought', rank: 1 };
+    return undefined;
+}
 /**
  * Extract select options from a raw ACP `configOptions` payload.
  *
@@ -848,19 +884,13 @@ export function parseCatalogOptions(configOptions) {
     const out = {};
     if (!Array.isArray(configOptions))
         return out;
-    const extras = new Map();
+    const definitions = [];
+    const candidates = [];
     for (const raw of configOptions) {
         if (typeof raw !== 'object' || raw === null)
             continue;
         const row = raw;
         const category = typeof row.category === 'string' ? row.category : undefined;
-        const slot = category === 'model'
-            ? 'model'
-            : category === 'thought_level'
-                ? 'thought'
-                : category === 'mode'
-                    ? 'mode'
-                    : undefined;
         const configIdRaw = row.configId ?? row.id;
         if (typeof configIdRaw !== 'string' && typeof configIdRaw !== 'number')
             continue;
@@ -869,6 +899,7 @@ export function parseCatalogOptions(configOptions) {
             continue;
         const choices = [];
         collectCatalogChoices(row.options, choices);
+        const name = typeof row.name === 'string' && row.name !== '' ? row.name : configId;
         // A boolean toggle has no `options` at all; its current value is a JSON
         // boolean. It is encoded as 'true' / 'false' so the catalog stays
         // string-typed for every existing reader, and carries `kind` so the
@@ -877,7 +908,7 @@ export function parseCatalogOptions(configOptions) {
             || (typeof row.currentValue === 'boolean' && choices.length === 0);
         const option = {
             configId,
-            name: typeof row.name === 'string' && row.name !== '' ? row.name : configId,
+            name,
             ...(booleanKind ? { kind: 'boolean' } : {}),
             currentValue: booleanKind
                 ? row.currentValue === true || row.currentValue === 'true'
@@ -886,22 +917,81 @@ export function parseCatalogOptions(configOptions) {
                 : typeof row.currentValue === 'string' && row.currentValue !== '' ? row.currentValue : null,
             choices,
         };
+        definitions.push(option);
         // A toggle is never a model / thought / mode SELECT: those controls pick
         // among choices. It belongs to the advanced base, where it is a checkbox.
-        if (slot !== undefined && !booleanKind) {
-            out[slot] = option;
+        if (booleanKind)
             continue;
+        const slot = catalogSlotFor(category, configId, name);
+        if (slot !== undefined)
+            candidates.push({ ...slot, option });
+    }
+    const winnerIds = new Set();
+    for (const slot of ['model', 'thought', 'mode']) {
+        let winner;
+        for (const candidate of candidates) {
+            if (candidate.slot !== slot)
+                continue;
+            if (winner === undefined || candidate.rank > winner.rank) {
+                winner = candidate;
+            }
+            else if (candidate.rank === winner.rank && candidate.option.configId === winner.option.configId) {
+                // The same option redefined later in one answer: the last definition
+                // is the current one.
+                winner = candidate;
+            }
         }
-        // Choice-less options have nothing to pick; they would render an empty
-        // section in the advanced menu, so they stay out of the catalog entirely —
-        // except a boolean, whose whole point is that it has no choices.
-        if (choices.length > 0 || booleanKind)
-            extras.set(configId, option);
+        if (winner === undefined)
+            continue;
+        out[slot] = winner.option;
+        winnerIds.add(winner.option.configId);
+    }
+    // Choice-less options have nothing to pick; they would render an empty
+    // section in the advanced menu, so they stay out of the catalog entirely —
+    // except a boolean, whose whole point is that it has no choices. Anything
+    // that lost a slot race is still a real, settable option: keep it here.
+    const extras = new Map();
+    for (const option of definitions) {
+        if (winnerIds.has(option.configId))
+            continue;
+        if (option.choices.length > 0 || option.kind === 'boolean')
+            extras.set(option.configId, option);
     }
     if (extras.size > 0)
         out.extras = [...extras.values()];
     return out;
 }
+/**
+ * Whether a payload names ONE model selector without relying on category
+ * alone. When an agent publishes several `category: 'model'` options and none
+ * is explicitly the `model` id, the category is not trustworthy enough to
+ * reject the user's pick — callers must fail open instead of reporting
+ * `model_unavailable`.
+ */
+export function hasUnambiguousModelSelector(configOptions) {
+    if (!Array.isArray(configOptions))
+        return true;
+    let scoped = 0;
+    let explicit = false;
+    for (const raw of configOptions) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const row = raw;
+        if (row.category !== 'model')
+            continue;
+        const configIdRaw = row.configId ?? row.id;
+        if (typeof configIdRaw !== 'string' && typeof configIdRaw !== 'number')
+            continue;
+        const configId = String(configIdRaw);
+        if (configId === '')
+            continue;
+        scoped += 1;
+        const name = typeof row.name === 'string' ? row.name : '';
+        if (isModelSelector(configId, name))
+            explicit = true;
+    }
+    return explicit || scoped <= 1;
+}
 /**
  * Fold one per-session option answer's SHAPE into an agent-level catalog.
  *
@@ -1310,6 +1400,1068 @@ export function describeUnhandledUpdate(kind, update) {
     }
     return `${label}\n${dumpJson(update)}`;
 }
+/** Helper: guess MIME type from file extension or URL */
+export function guessImageMimeType(pathOrUrl) {
+    if (!pathOrUrl)
+        return undefined;
+    const clean = pathOrUrl.split('?')[0].split('#')[0].toLowerCase();
+    if (clean.endsWith('.jpg') || clean.endsWith('.jpeg'))
+        return 'image/jpeg';
+    if (clean.endsWith('.png'))
+        return 'image/png';
+    if (clean.endsWith('.gif'))
+        return 'image/gif';
+    if (clean.endsWith('.webp'))
+        return 'image/webp';
+    if (clean.endsWith('.svg') || clean.endsWith('.svgz'))
+        return 'image/svg+xml';
+    if (clean.endsWith('.bmp'))
+        return 'image/bmp';
+    if (clean.endsWith('.ico'))
+        return 'image/x-icon';
+    if (clean.endsWith('.tiff') || clean.endsWith('.tif'))
+        return 'image/tiff';
+    if (clean.endsWith('.avif'))
+        return 'image/avif';
+    if (clean.endsWith('.heic'))
+        return 'image/heic';
+    if (clean.endsWith('.heif'))
+        return 'image/heif';
+    if (clean.endsWith('.apng'))
+        return 'image/apng';
+    return undefined;
+}
+/** Helper: parse Data URI */
+export function parseImageDataUrl(url) {
+    if (!url.startsWith('data:'))
+        return undefined;
+    const commaIdx = url.indexOf(',');
+    if (commaIdx === -1)
+        return undefined;
+    const header = url.slice(5, commaIdx);
+    const raw = url.slice(commaIdx + 1).trim();
+    const parts = header.split(';');
+    const mimeType = parts[0] && parts[0].trim() !== '' ? parts[0].trim().toLowerCase() : 'image/png';
+    if (!mimeType.startsWith('image/'))
+        return undefined;
+    const isBase64 = parts.some(p => p.trim() === 'base64');
+    let data;
+    if (isBase64) {
+        data = raw.replace(/\s+/g, '');
+    }
+    else {
+        try {
+            const decoded = decodeURIComponent(raw);
+            data = typeof Buffer !== 'undefined' ? Buffer.from(decoded).toString('base64') : btoa(decoded);
+        }
+        catch {
+            data = typeof Buffer !== 'undefined' ? Buffer.from(raw).toString('base64') : btoa(raw);
+        }
+    }
+    return { mimeType, data };
+}
+export function isLocalFilePath(str) {
+    if (typeof str !== 'string' || str === '')
+        return false;
+    return isAbsolutePath(str) || str.startsWith('./') || str.startsWith('.\\') || str.startsWith('../') || str.startsWith('..\\');
+}
+export function normalizeFileUrlToPath(uri) {
+    if (!uri.startsWith('file://'))
+        return uri;
+    let raw = uri.slice('file://'.length);
+    try {
+        raw = decodeURIComponent(raw);
+    }
+    catch { }
+    if (raw.startsWith('localhost/')) {
+        raw = raw.slice('localhost'.length);
+    }
+    if (/^\/?[a-zA-Z]:/.test(raw)) {
+        return raw.startsWith('/') ? raw.slice(1) : raw;
+    }
+    if (raw.startsWith('/')) {
+        return raw;
+    }
+    return `//${raw}`;
+}
+function expandHomePath(p) {
+    if (p === '~' || p.startsWith('~/') || p.startsWith('~\\')) {
+        if (typeof process !== 'undefined' && process.env) {
+            const env = process.env;
+            const home = env.HOME || env.USERPROFILE || (env.HOMEDRIVE && env.HOMEPATH ? `${env.HOMEDRIVE}${env.HOMEPATH}` : undefined);
+            if (home) {
+                const cleanHome = home.replaceAll('\\', '/').replace(/\/+$/, '');
+                return p === '~' ? cleanHome : `${cleanHome}/${p.slice(2).replaceAll('\\', '/')}`;
+            }
+        }
+    }
+    return p;
+}
+function readImageFileFromContext(filePath, context) {
+    const target = normalizeFileUrlToPath(filePath);
+    const expanded = expandHomePath(target);
+    const pathsToTry = target === expanded ? [target] : [target, expanded];
+    const builtinFs = typeof process !== 'undefined' && typeof process.getBuiltinModule === 'function'
+        ? process.getBuiltinModule('fs')
+        : null;
+    for (const p of pathsToTry) {
+        if (context && typeof context.readFile === 'function') {
+            try {
+                const res = context.readFile(p);
+                if (res !== undefined)
+                    return res;
+            }
+            catch { }
+        }
+        if (context && typeof context.fs?.readFileSync === 'function') {
+            try {
+                const res = context.fs.readFileSync(p);
+                if (res !== undefined)
+                    return res;
+            }
+            catch { }
+        }
+        if (builtinFs && typeof builtinFs.existsSync === 'function' && typeof builtinFs.readFileSync === 'function') {
+            try {
+                if (builtinFs.existsSync(p))
+                    return builtinFs.readFileSync(p);
+            }
+            catch { }
+        }
+    }
+    return undefined;
+}
+/**
+ * Detect image MIME type by examining binary magic numbers.
+ * Supports Buffer, Uint8Array, and base64 strings.
+ */
+export function detectImageMimeFromMagic(raw) {
+    if (!raw)
+        return undefined;
+    let bytes;
+    if (typeof raw === 'string') {
+        const trimmed = raw.trim();
+        if (trimmed.startsWith('<svg') || (trimmed.startsWith('<?xml') && trimmed.includes('<svg'))) {
+            return 'image/svg+xml';
+        }
+        try {
+            const prefix = trimmed.slice(0, 64).replace(/\s+/g, '');
+            if (typeof Buffer !== 'undefined') {
+                bytes = Buffer.from(prefix, 'base64');
+            }
+            else if (typeof atob !== 'undefined') {
+                const bin = atob(prefix);
+                bytes = new Uint8Array(bin.length);
+                for (let i = 0; i < bin.length; i++)
+                    bytes[i] = bin.charCodeAt(i);
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    else if (raw instanceof Uint8Array || (typeof Buffer !== 'undefined' && Buffer.isBuffer(raw))) {
+        bytes = raw instanceof Uint8Array ? raw : new Uint8Array(raw);
+    }
+    if (!bytes || bytes.length < 3)
+        return undefined;
+    // PNG: 89 50 4E 47 0D 0A 1A 0A
+    if (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) {
+        return 'image/png';
+    }
+    // JPEG: FF D8 FF
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        return 'image/jpeg';
+    }
+    // GIF: GIF87a or GIF89a (47 49 46 38)
+    if (bytes.length >= 6 &&
+        bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38 &&
+        (bytes[4] === 0x37 || bytes[4] === 0x39) && bytes[5] === 0x61) {
+        return 'image/gif';
+    }
+    // WebP: RIFF....WEBP (52 49 46 46 .... 57 45 42 50)
+    if (bytes.length >= 12 &&
+        bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46 &&
+        bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50) {
+        return 'image/webp';
+    }
+    // BMP: 42 4D ("BM")
+    if (bytes.length >= 2 && bytes[0] === 0x42 && bytes[1] === 0x4d) {
+        return 'image/bmp';
+    }
+    // ICO: 00 00 01 00
+    if (bytes.length >= 4 && bytes[0] === 0x00 && bytes[1] === 0x00 && bytes[2] === 0x01 && bytes[3] === 0x00) {
+        return 'image/x-icon';
+    }
+    // TIFF: II*. (49 49 2A 00) or MM.* (4D 4D 00 2A)
+    if (bytes.length >= 4 &&
+        ((bytes[0] === 0x49 && bytes[1] === 0x49 && bytes[2] === 0x2a && bytes[3] === 0x00) ||
+            (bytes[0] === 0x4d && bytes[1] === 0x4d && bytes[2] === 0x00 && bytes[3] === 0x2a))) {
+        return 'image/tiff';
+    }
+    // AVIF / HEIC: ftyp box at offset 4 (bytes 4..7 === 'ftyp')
+    if (bytes.length >= 12 &&
+        bytes[4] === 0x66 && bytes[5] === 0x74 && bytes[6] === 0x79 && bytes[7] === 0x70) {
+        const brand = String.fromCharCode(bytes[8], bytes[9], bytes[10], bytes[11]).toLowerCase();
+        if (brand === 'avif' || brand === 'avis')
+            return 'image/avif';
+        if (brand === 'heic' || brand === 'heix' || brand === 'hevc' || brand === 'mif1' || brand === 'msf1')
+            return 'image/heic';
+    }
+    return undefined;
+}
+function tryResolveFromAttachmentStore(store, id, context, attachmentMeta) {
+    const idWithoutPrefix = id.startsWith('sha256:') ? id.slice('sha256:'.length) : undefined;
+    const idWithPrefix = id.startsWith('sha256:') ? id : `sha256:${id}`;
+    const candidates = [];
+    if (attachmentMeta && typeof attachmentMeta === 'object') {
+        candidates.push(attachmentMeta);
+    }
+    candidates.push({ attachmentId: idWithPrefix });
+    if (idWithoutPrefix !== undefined) {
+        candidates.push({ attachmentId: idWithoutPrefix });
+    }
+    candidates.push({ attachmentId: id });
+    candidates.push({ id: idWithPrefix });
+    candidates.push({ id });
+    if (idWithoutPrefix !== undefined) {
+        candidates.push({ id: idWithoutPrefix });
+    }
+    candidates.push(id);
+    if (idWithoutPrefix !== undefined) {
+        candidates.push(idWithoutPrefix);
+    }
+    // Cordis proxies wrap the underlying service instance; if a method call on the proxy fails
+    // or loses this context, fall back to the unwrapped instance (never the class prototype,
+    // which lacks instance state such as `this.root`).
+    const cordisOriginal = Reflect.get(store, Symbol.for('cordis.original'));
+    // A. LocalAttachmentStore.imageHostPath(ref) -> synchronous local absolute path
+    if (typeof store.imageHostPath === 'function') {
+        const fn = store.imageHostPath;
+        for (const cand of candidates) {
+            if (cand === undefined)
+                continue;
+            try {
+                let hostPath;
+                try {
+                    hostPath = fn.call(store, cand);
+                }
+                catch {
+                    if (cordisOriginal && typeof cordisOriginal.imageHostPath === 'function') {
+                        hostPath = cordisOriginal.imageHostPath.call(cordisOriginal, cand);
+                    }
+                }
+                if (hostPath && typeof hostPath.then === 'function') {
+                    if (typeof hostPath.catch === 'function') {
+                        hostPath.catch(() => { });
+                    }
+                }
+                else if (typeof hostPath === 'string' && hostPath.trim() !== '') {
+                    const fileContent = readImageFileFromContext(hostPath, context);
+                    return {
+                        path: hostPath,
+                        ...(fileContent !== undefined ? { data: fileContent } : {}),
+                    };
+                }
+            }
+            catch { }
+        }
+    }
+    // B. LocalAttachmentStore.fileHostPath(ref) -> fallback for file-type attachments
+    if (typeof store.fileHostPath === 'function') {
+        const fn = store.fileHostPath;
+        for (const cand of candidates) {
+            if (cand === undefined)
+                continue;
+            try {
+                let hostPath;
+                try {
+                    hostPath = fn.call(store, cand);
+                }
+                catch {
+                    if (cordisOriginal && typeof cordisOriginal.fileHostPath === 'function') {
+                        hostPath = cordisOriginal.fileHostPath.call(cordisOriginal, cand);
+                    }
+                }
+                if (hostPath && typeof hostPath.then === 'function') {
+                    if (typeof hostPath.catch === 'function') {
+                        hostPath.catch(() => { });
+                    }
+                }
+                else if (typeof hostPath === 'string' && hostPath.trim() !== '') {
+                    const fileContent = readImageFileFromContext(hostPath, context);
+                    return {
+                        path: hostPath,
+                        ...(fileContent !== undefined ? { data: fileContent } : {}),
+                    };
+                }
+            }
+            catch { }
+        }
+    }
+    // C. LocalAttachmentStore.readImage(ref) -> { ref, data: Uint8Array }
+    if (typeof store.readImage === 'function') {
+        const fn = store.readImage;
+        for (const cand of candidates) {
+            if (cand === undefined)
+                continue;
+            try {
+                let res;
+                try {
+                    res = fn.call(store, cand);
+                }
+                catch {
+                    if (cordisOriginal && typeof cordisOriginal.readImage === 'function') {
+                        res = cordisOriginal.readImage.call(cordisOriginal, cand);
+                    }
+                }
+                if (res && typeof res === 'object') {
+                    // If it's a Promise (async), safely attach catch to avoid unhandledRejection crashes
+                    if (typeof res.then === 'function') {
+                        if (typeof res.catch === 'function') {
+                            res.catch(() => { });
+                        }
+                    }
+                    else {
+                        if (res instanceof Uint8Array || (typeof Buffer !== 'undefined' && Buffer.isBuffer(res))) {
+                            return res;
+                        }
+                        const data = res.data;
+                        if (data instanceof Uint8Array || (typeof Buffer !== 'undefined' && Buffer.isBuffer(data)) || typeof data === 'string') {
+                            return { data };
+                        }
+                    }
+                }
+            }
+            catch { }
+        }
+    }
+    // D. readAttachment
+    if (typeof store.readAttachment === 'function') {
+        try {
+            let res;
+            try {
+                res = store.readAttachment.call(store, id);
+            }
+            catch {
+                if (cordisOriginal && typeof cordisOriginal.readAttachment === 'function') {
+                    res = cordisOriginal.readAttachment.call(cordisOriginal, id);
+                }
+            }
+            if (res && typeof res.then === 'function') {
+                if (typeof res.catch === 'function') {
+                    res.catch(() => { });
+                }
+            }
+            else if (res !== undefined) {
+                return res;
+            }
+        }
+        catch { }
+    }
+    // E. getAttachment
+    if (typeof store.getAttachment === 'function') {
+        try {
+            let res;
+            try {
+                res = store.getAttachment.call(store, id);
+            }
+            catch {
+                if (cordisOriginal && typeof cordisOriginal.getAttachment === 'function') {
+                    res = cordisOriginal.getAttachment.call(cordisOriginal, id);
+                }
+            }
+            if (res && typeof res.then === 'function') {
+                if (typeof res.catch === 'function') {
+                    res.catch(() => { });
+                }
+            }
+            else if (res !== undefined) {
+                return res;
+            }
+        }
+        catch { }
+    }
+    return undefined;
+}
+function tryStoreFreeDiskAttachment(id, context) {
+    if (typeof id !== 'string')
+        return undefined;
+    let hash;
+    const trimmed = id.trim();
+    if (trimmed.startsWith('sha256:')) {
+        hash = trimmed.slice('sha256:'.length).toLowerCase();
+    }
+    else if (/^[0-9a-f]{64}$/i.test(trimmed)) {
+        hash = trimmed.toLowerCase();
+    }
+    if (!hash || hash.length < 2)
+        return undefined;
+    const prefix = hash.slice(0, 2);
+    const relPaths = [
+        `attachments/v1/objects/${prefix}/${hash}`,
+        `attachments/v1/file-objects/${prefix}/${hash}`,
+    ];
+    const candidatePaths = [];
+    if (typeof process !== 'undefined' && process.env) {
+        const env = process.env;
+        if (env.DSH_NTR_STATE_DIR) {
+            const stateDir = env.DSH_NTR_STATE_DIR.replaceAll('\\', '/').replace(/\/+$/, '');
+            const hostDir = stateDir.endsWith('/dsh-ntr') ? stateDir.slice(0, -'/dsh-ntr'.length) : stateDir;
+            for (const rel of relPaths)
+                candidatePaths.push(`${hostDir}/${rel}`);
+        }
+        if (env.DSH_DIR) {
+            const dshDir = env.DSH_DIR.replaceAll('\\', '/').replace(/\/+$/, '');
+            for (const rel of relPaths)
+                candidatePaths.push(`${dshDir}/${rel}`);
+        }
+        const home = env.HOME || env.USERPROFILE || (env.HOMEDRIVE && env.HOMEPATH ? `${env.HOMEDRIVE}${env.HOMEPATH}` : undefined);
+        if (home) {
+            const cleanHome = home.replaceAll('\\', '/').replace(/\/+$/, '');
+            for (const rel of relPaths) {
+                candidatePaths.push(`${cleanHome}/.dsh/${rel}`);
+                candidatePaths.push(`${cleanHome}\\.dsh\\${rel.replaceAll('/', '\\')}`);
+            }
+        }
+    }
+    for (const rel of relPaths)
+        candidatePaths.push(`~/.dsh/${rel}`);
+    for (const p of candidatePaths) {
+        const fileContent = readImageFileFromContext(p, context);
+        if (fileContent !== undefined) {
+            return {
+                path: p,
+                data: fileContent,
+            };
+        }
+    }
+    return undefined;
+}
+export function resolveImageAttachmentFromContext(id, context, attachmentMeta, rootContext) {
+    const root = rootContext ?? context;
+    if (context && typeof context === 'object') {
+        const ctx = context;
+        const direct = tryResolveFromAttachmentStore(ctx, id, root, attachmentMeta);
+        if (direct !== undefined)
+            return direct;
+        if (typeof ctx.get === 'function') {
+            try {
+                const svc = ctx.get('attachments') ?? ctx.get('attachmentService');
+                if (svc && typeof svc === 'object') {
+                    const res = resolveImageAttachmentFromContext(id, svc, attachmentMeta, root);
+                    if (res !== undefined)
+                        return res;
+                }
+            }
+            catch { }
+        }
+        try {
+            if (ctx.attachmentService && typeof ctx.attachmentService === 'object') {
+                const res = resolveImageAttachmentFromContext(id, ctx.attachmentService, attachmentMeta, root);
+                if (res !== undefined)
+                    return res;
+            }
+        }
+        catch { }
+        try {
+            const attStore = ctx.attachments;
+            if (attStore) {
+                if (typeof attStore === 'object') {
+                    const fromStore = tryResolveFromAttachmentStore(attStore, id, root, attachmentMeta);
+                    if (fromStore !== undefined)
+                        return fromStore;
+                }
+                if (attStore instanceof Map || typeof attStore.get === 'function') {
+                    try {
+                        return attStore.get(id);
+                    }
+                    catch { }
+                }
+                if (typeof attStore === 'object' && Object.prototype.hasOwnProperty.call(attStore, id)) {
+                    return attStore[id];
+                }
+            }
+        }
+        catch { }
+    }
+    return tryStoreFreeDiskAttachment(id, root);
+}
+function toBase64(data) {
+    if (typeof data === 'string')
+        return data.replace(/\s+/g, '');
+    if (typeof Buffer !== 'undefined')
+        return Buffer.from(data).toString('base64');
+    let binary = '';
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    for (let i = 0; i < bytes.byteLength; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/**
+ * Extract an image payload (Base64 data + MIME type) from an image block and optional context.
+ */
+export function resolveImageContent(block, context) {
+    if (!block || typeof block !== 'object')
+        return undefined;
+    const b = block;
+    const attRecord = b.attachment && typeof b.attachment === 'object' ? b.attachment : undefined;
+    const isExplicitImageBlock = b.type === 'image' || b.type === 'image_url' || b.type === 'attachment';
+    const explicitMime = (typeof attRecord?.mediaType === 'string' && attRecord.mediaType.trim().toLowerCase()) ||
+        (typeof attRecord?.mimeType === 'string' && attRecord.mimeType.trim().toLowerCase()) ||
+        (typeof b.mediaType === 'string' && b.mediaType.trim().toLowerCase()) ||
+        (typeof b.mimeType === 'string' && b.mimeType.trim().toLowerCase()) ||
+        (typeof b.contentType === 'string' && b.contentType.trim().toLowerCase()) ||
+        undefined;
+    // 1. Direct base64 data: { data: string | Buffer | Uint8Array, mimeType?: string }
+    if (typeof b.data === 'string' && b.data.trim() !== '') {
+        if (b.data.startsWith('data:')) {
+            const parsed = parseImageDataUrl(b.data);
+            if (parsed) {
+                const mimeType = explicitMime || parsed.mimeType || detectImageMimeFromMagic(parsed.data) || 'image/png';
+                return { type: 'image', data: parsed.data, mimeType, ...(typeof b.uri === 'string' ? { uri: b.uri } : {}) };
+            }
+            return undefined;
+        }
+        const mimeType = explicitMime || detectImageMimeFromMagic(b.data) || (isExplicitImageBlock ? 'image/png' : undefined);
+        if (mimeType && mimeType.startsWith('image/')) {
+            return {
+                type: 'image',
+                data: b.data.trim().replace(/\s+/g, ''),
+                mimeType,
+                ...(typeof b.uri === 'string' ? { uri: b.uri } : {}),
+            };
+        }
+    }
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(b.data)) {
+        const mimeType = explicitMime || detectImageMimeFromMagic(b.data) || (isExplicitImageBlock ? 'image/png' : undefined);
+        if (mimeType && mimeType.startsWith('image/')) {
+            return { type: 'image', data: b.data.toString('base64'), mimeType, ...(typeof b.uri === 'string' ? { uri: b.uri } : {}) };
+        }
+    }
+    if (b.data instanceof Uint8Array) {
+        const mimeType = explicitMime || detectImageMimeFromMagic(b.data) || (isExplicitImageBlock ? 'image/png' : undefined);
+        if (mimeType && mimeType.startsWith('image/')) {
+            return { type: 'image', data: toBase64(b.data), mimeType, ...(typeof b.uri === 'string' ? { uri: b.uri } : {}) };
+        }
+    }
+    // 2. Anthropic style: source: { type: 'base64', media_type: string, data: string }
+    if (b.source && typeof b.source === 'object') {
+        const src = b.source;
+        const srcMime = (typeof src.media_type === 'string' && src.media_type.trim().toLowerCase()) ||
+            (typeof src.mimeType === 'string' && src.mimeType.trim().toLowerCase()) ||
+            explicitMime ||
+            (typeof src.data === 'string' || src.data instanceof Uint8Array || (typeof Buffer !== 'undefined' && Buffer.isBuffer(src.data)) ? detectImageMimeFromMagic(src.data) : undefined) ||
+            'image/png';
+        if (srcMime.startsWith('image/')) {
+            if (typeof src.data === 'string' && src.data.trim() !== '') {
+                return {
+                    type: 'image',
+                    data: src.data.trim().replace(/\s+/g, ''),
+                    mimeType: srcMime,
+                    ...(typeof b.uri === 'string' ? { uri: b.uri } : {}),
+                };
+            }
+            if (typeof Buffer !== 'undefined' && Buffer.isBuffer(src.data)) {
+                return { type: 'image', data: src.data.toString('base64'), mimeType: srcMime, ...(typeof b.uri === 'string' ? { uri: b.uri } : {}) };
+            }
+            if (src.data instanceof Uint8Array) {
+                return { type: 'image', data: toBase64(src.data), mimeType: srcMime, ...(typeof b.uri === 'string' ? { uri: b.uri } : {}) };
+            }
+        }
+    }
+    // 3. Image property: { image: string | Buffer | Uint8Array }
+    if (typeof b.image === 'string' && b.image.trim() !== '') {
+        if (b.image.startsWith('data:')) {
+            const parsed = parseImageDataUrl(b.image);
+            if (parsed)
+                return { type: 'image', data: parsed.data, mimeType: explicitMime || parsed.mimeType || detectImageMimeFromMagic(parsed.data) || 'image/png' };
+            return undefined;
+        }
+        const mimeType = explicitMime || detectImageMimeFromMagic(b.image) || (isExplicitImageBlock ? 'image/png' : undefined);
+        if (mimeType && mimeType.startsWith('image/')) {
+            return { type: 'image', data: b.image.trim().replace(/\s+/g, ''), mimeType };
+        }
+    }
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(b.image)) {
+        const mimeType = explicitMime || detectImageMimeFromMagic(b.image) || (isExplicitImageBlock ? 'image/png' : undefined);
+        if (mimeType && mimeType.startsWith('image/'))
+            return { type: 'image', data: b.image.toString('base64'), mimeType };
+    }
+    if (b.image instanceof Uint8Array) {
+        const mimeType = explicitMime || detectImageMimeFromMagic(b.image) || (isExplicitImageBlock ? 'image/png' : undefined);
+        if (mimeType && mimeType.startsWith('image/'))
+            return { type: 'image', data: toBase64(b.image), mimeType };
+    }
+    // 4. OpenAI style image_url: { image_url: string | { url: string } }
+    if (b.image_url) {
+        const urlStr = typeof b.image_url === 'string'
+            ? b.image_url
+            : (typeof b.image_url === 'object' && b.image_url !== null ? b.image_url.url : undefined);
+        if (typeof urlStr === 'string' && urlStr.trim() !== '') {
+            if (urlStr.startsWith('data:')) {
+                const parsed = parseImageDataUrl(urlStr);
+                if (parsed)
+                    return { type: 'image', data: parsed.data, mimeType: explicitMime || parsed.mimeType || detectImageMimeFromMagic(parsed.data) || 'image/png', uri: urlStr };
+                return undefined;
+            }
+            if (urlStr.startsWith('http://') || urlStr.startsWith('https://')) {
+                const mimeType = explicitMime || guessImageMimeType(urlStr) || 'image/png';
+                return { type: 'image', data: '', mimeType, uri: urlStr };
+            }
+            if (urlStr.startsWith('file://') || isLocalFilePath(urlStr)) {
+                const fileContent = readImageFileFromContext(urlStr, context);
+                if (fileContent !== undefined) {
+                    let data;
+                    let resolvedMime;
+                    if (typeof fileContent === 'string') {
+                        if (fileContent.startsWith('data:')) {
+                            const parsed = parseImageDataUrl(fileContent);
+                            if (parsed) {
+                                data = parsed.data;
+                                resolvedMime = parsed.mimeType;
+                            }
+                            else {
+                                return undefined;
+                            }
+                        }
+                        else {
+                            data = fileContent.trim().replace(/\s+/g, '');
+                        }
+                    }
+                    else {
+                        data = toBase64(fileContent);
+                    }
+                    const mimeType = explicitMime || resolvedMime || guessImageMimeType(urlStr) || detectImageMimeFromMagic(fileContent) || (isExplicitImageBlock ? 'image/png' : undefined);
+                    if (mimeType && mimeType.startsWith('image/')) {
+                        return { type: 'image', data, mimeType, uri: urlStr };
+                    }
+                }
+            }
+        }
+    }
+    // 5. Direct buffer / content on block: { buffer: Buffer } or { content: Buffer }
+    if (b.buffer && (typeof Buffer !== 'undefined' && Buffer.isBuffer(b.buffer) || b.buffer instanceof Uint8Array)) {
+        const data = typeof Buffer !== 'undefined' && Buffer.isBuffer(b.buffer) ? b.buffer.toString('base64') : toBase64(b.buffer);
+        const mimeType = explicitMime || detectImageMimeFromMagic(b.buffer) || (isExplicitImageBlock ? 'image/png' : undefined);
+        if (mimeType && mimeType.startsWith('image/')) {
+            return { type: 'image', data, mimeType, ...(typeof b.uri === 'string' ? { uri: b.uri } : {}) };
+        }
+    }
+    if (b.content && (typeof Buffer !== 'undefined' && Buffer.isBuffer(b.content) || b.content instanceof Uint8Array)) {
+        const data = typeof Buffer !== 'undefined' && Buffer.isBuffer(b.content) ? b.content.toString('base64') : toBase64(b.content);
+        const mimeType = explicitMime || detectImageMimeFromMagic(b.content) || (isExplicitImageBlock ? 'image/png' : undefined);
+        if (mimeType && mimeType.startsWith('image/')) {
+            return { type: 'image', data, mimeType, ...(typeof b.uri === 'string' ? { uri: b.uri } : {}) };
+        }
+    }
+    // 6. Data URL or Remote URL in `url`
+    if (typeof b.url === 'string') {
+        if (b.url.startsWith('data:')) {
+            const parsed = parseImageDataUrl(b.url);
+            if (parsed)
+                return { type: 'image', data: parsed.data, mimeType: explicitMime || parsed.mimeType || detectImageMimeFromMagic(parsed.data) || 'image/png', uri: b.url };
+            return undefined;
+        }
+        if (b.url.startsWith('http://') || b.url.startsWith('https://')) {
+            const mimeType = explicitMime || guessImageMimeType(b.url) || 'image/png';
+            return { type: 'image', data: '', mimeType, uri: b.url };
+        }
+    }
+    // 7. File path in `path`, `filePath`, or `url: file://...`
+    let filePath;
+    if (typeof b.path === 'string' && b.path !== '')
+        filePath = b.path;
+    else if (typeof b.filePath === 'string' && b.filePath !== '')
+        filePath = b.filePath;
+    else if (typeof b.url === 'string' && (b.url.startsWith('file://') || isLocalFilePath(b.url)))
+        filePath = b.url;
+    if (filePath !== undefined) {
+        const fileContent = readImageFileFromContext(filePath, context);
+        if (fileContent !== undefined) {
+            let data;
+            let resolvedMime;
+            if (typeof fileContent === 'string') {
+                if (fileContent.startsWith('data:')) {
+                    const parsed = parseImageDataUrl(fileContent);
+                    if (parsed) {
+                        data = parsed.data;
+                        resolvedMime = parsed.mimeType;
+                    }
+                    else {
+                        return undefined;
+                    }
+                }
+                else {
+                    data = fileContent.trim().replace(/\s+/g, '');
+                }
+            }
+            else {
+                data = toBase64(fileContent);
+            }
+            const mimeType = explicitMime ||
+                resolvedMime ||
+                guessImageMimeType(filePath) ||
+                detectImageMimeFromMagic(fileContent) ||
+                (isExplicitImageBlock ? 'image/png' : undefined);
+            if (mimeType && mimeType.startsWith('image/')) {
+                let uri = typeof b.url === 'string' ? b.url : undefined;
+                if (!uri) {
+                    if (filePath.startsWith('file://')) {
+                        uri = filePath;
+                    }
+                    else if (isAbsolutePath(filePath)) {
+                        if (filePath.startsWith('//') || filePath.startsWith('\\\\')) {
+                            uri = `file://${filePath.replace(/^[\/\\]+/, '').replace(/\\/g, '/')}`;
+                        }
+                        else if (/^[a-zA-Z]:/.test(filePath)) {
+                            uri = `file:///${filePath.replace(/\\/g, '/')}`;
+                        }
+                        else {
+                            uri = `file://${filePath.startsWith('/') ? filePath : `/${filePath}`}`;
+                        }
+                    }
+                    else {
+                        uri = filePath;
+                    }
+                }
+                return {
+                    type: 'image',
+                    data,
+                    mimeType,
+                    uri,
+                };
+            }
+        }
+    }
+    // 8. Attachment resolution via context
+    let attachmentId;
+    if (attRecord && typeof attRecord.attachmentId === 'string' && attRecord.attachmentId.trim() !== '') {
+        attachmentId = attRecord.attachmentId.trim();
+    }
+    else if (typeof b.attachmentId === 'string' && b.attachmentId.trim() !== '') {
+        attachmentId = b.attachmentId.trim();
+    }
+    else if (attRecord && typeof attRecord.id === 'string' && attRecord.id.trim() !== '') {
+        attachmentId = attRecord.id.trim();
+    }
+    else if (typeof b.id === 'string' && b.id.trim() !== '') {
+        attachmentId = b.id.trim();
+    }
+    else if (typeof b.attachment === 'string' && b.attachment.trim() !== '') {
+        attachmentId = b.attachment.trim();
+    }
+    else if (typeof b.url === 'string' && b.url.startsWith('attachment:')) {
+        attachmentId = b.url.replace(/^attachment:\/\/|^attachment:/, '');
+    }
+    else if (typeof b.image_url === 'string' && b.image_url.startsWith('attachment:')) {
+        attachmentId = b.image_url.replace(/^attachment:\/\/|^attachment:/, '');
+    }
+    else if (b.image_url && typeof b.image_url === 'object' && typeof b.image_url.url === 'string' && b.image_url.url.startsWith('attachment:')) {
+        attachmentId = b.image_url.url.replace(/^attachment:\/\/|^attachment:/, '');
+    }
+    if (attachmentId !== undefined) {
+        const rawAtt = resolveImageAttachmentFromContext(attachmentId, context, b.attachment);
+        if (rawAtt !== undefined) {
+            if (typeof rawAtt === 'string') {
+                if (rawAtt.startsWith('data:')) {
+                    const parsed = parseImageDataUrl(rawAtt);
+                    if (parsed) {
+                        const mimeType = explicitMime || parsed.mimeType || detectImageMimeFromMagic(parsed.data) || 'image/png';
+                        return {
+                            type: 'image',
+                            data: parsed.data,
+                            mimeType,
+                            uri: typeof b.uri === 'string' ? b.uri : `attachment://${attachmentId}`,
+                        };
+                    }
+                    return undefined;
+                }
+                else if (rawAtt.startsWith('file://') || isLocalFilePath(rawAtt)) {
+                    const fileContent = readImageFileFromContext(rawAtt, context);
+                    if (fileContent !== undefined) {
+                        let data;
+                        let resolvedMime;
+                        if (typeof fileContent === 'string') {
+                            if (fileContent.startsWith('data:')) {
+                                const parsed = parseImageDataUrl(fileContent);
+                                if (parsed) {
+                                    data = parsed.data;
+                                    resolvedMime = parsed.mimeType;
+                                }
+                                else {
+                                    return undefined;
+                                }
+                            }
+                            else {
+                                data = fileContent.trim().replace(/\s+/g, '');
+                            }
+                        }
+                        else {
+                            data = toBase64(fileContent);
+                        }
+                        const mimeType = explicitMime ||
+                            resolvedMime ||
+                            (typeof attRecord?.name === 'string' ? guessImageMimeType(attRecord.name) : undefined) ||
+                            guessImageMimeType(rawAtt) ||
+                            detectImageMimeFromMagic(fileContent) ||
+                            (isExplicitImageBlock ? 'image/png' : undefined);
+                        if (mimeType && mimeType.startsWith('image/')) {
+                            return { type: 'image', data, mimeType, uri: typeof b.uri === 'string' ? b.uri : `attachment://${attachmentId}` };
+                        }
+                    }
+                }
+                const mimeType = explicitMime ||
+                    (typeof attRecord?.name === 'string' ? guessImageMimeType(attRecord.name) : undefined) ||
+                    guessImageMimeType(attachmentId) ||
+                    detectImageMimeFromMagic(rawAtt) ||
+                    (isExplicitImageBlock ? 'image/png' : undefined);
+                if (mimeType && mimeType.startsWith('image/')) {
+                    return { type: 'image', data: rawAtt.trim().replace(/\s+/g, ''), mimeType, uri: typeof b.uri === 'string' ? b.uri : `attachment://${attachmentId}` };
+                }
+            }
+            if (typeof rawAtt === 'object' && rawAtt !== null) {
+                if (typeof Buffer !== 'undefined' && Buffer.isBuffer(rawAtt)) {
+                    const mimeType = explicitMime ||
+                        (typeof attRecord?.name === 'string' ? guessImageMimeType(attRecord.name) : undefined) ||
+                        guessImageMimeType(attachmentId) ||
+                        detectImageMimeFromMagic(rawAtt) ||
+                        (isExplicitImageBlock ? 'image/png' : undefined);
+                    if (mimeType && mimeType.startsWith('image/')) {
+                        return {
+                            type: 'image',
+                            data: rawAtt.toString('base64'),
+                            mimeType,
+                            uri: typeof b.uri === 'string' ? b.uri : `attachment://${attachmentId}`,
+                        };
+                    }
+                }
+                if (rawAtt instanceof Uint8Array) {
+                    const mimeType = explicitMime ||
+                        (typeof attRecord?.name === 'string' ? guessImageMimeType(attRecord.name) : undefined) ||
+                        guessImageMimeType(attachmentId) ||
+                        detectImageMimeFromMagic(rawAtt) ||
+                        (isExplicitImageBlock ? 'image/png' : undefined);
+                    if (mimeType && mimeType.startsWith('image/')) {
+                        return {
+                            type: 'image',
+                            data: toBase64(rawAtt),
+                            mimeType,
+                            uri: typeof b.uri === 'string' ? b.uri : `attachment://${attachmentId}`,
+                        };
+                    }
+                }
+                const attObj = rawAtt;
+                let data;
+                let resolvedMime;
+                const attPath = typeof attObj.path === 'string' && attObj.path !== ''
+                    ? attObj.path
+                    : (typeof attObj.filePath === 'string' && attObj.filePath !== ''
+                        ? attObj.filePath
+                        : (typeof attObj.url === 'string' && (attObj.url.startsWith('file://') || isLocalFilePath(attObj.url)) ? attObj.url : undefined));
+                let fileContentForMagic;
+                if (attPath !== undefined) {
+                    const fileContent = readImageFileFromContext(attPath, context);
+                    if (fileContent !== undefined) {
+                        fileContentForMagic = fileContent;
+                        if (typeof fileContent === 'string') {
+                            if (fileContent.startsWith('data:')) {
+                                const parsed = parseImageDataUrl(fileContent);
+                                if (parsed) {
+                                    data = parsed.data;
+                                    resolvedMime = parsed.mimeType;
+                                }
+                            }
+                            else {
+                                data = fileContent.trim().replace(/\s+/g, '');
+                            }
+                        }
+                        else {
+                            data = toBase64(fileContent);
+                        }
+                        if (!resolvedMime)
+                            resolvedMime = guessImageMimeType(attPath);
+                    }
+                }
+                if (data === undefined) {
+                    if (typeof attObj.data === 'string' && attObj.data.trim() !== '') {
+                        if (attObj.data.startsWith('data:')) {
+                            const parsed = parseImageDataUrl(attObj.data);
+                            if (parsed) {
+                                data = parsed.data;
+                                resolvedMime = parsed.mimeType;
+                            }
+                        }
+                        else {
+                            data = attObj.data.trim().replace(/\s+/g, '');
+                            fileContentForMagic = attObj.data;
+                        }
+                    }
+                    else if (typeof Buffer !== 'undefined' && Buffer.isBuffer(attObj.data)) {
+                        data = attObj.data.toString('base64');
+                        fileContentForMagic = attObj.data;
+                    }
+                    else if (attObj.data instanceof Uint8Array) {
+                        data = toBase64(attObj.data);
+                        fileContentForMagic = attObj.data;
+                    }
+                    else if (typeof Buffer !== 'undefined' && Buffer.isBuffer(attObj.buffer)) {
+                        data = attObj.buffer.toString('base64');
+                        fileContentForMagic = attObj.buffer;
+                    }
+                    else if (attObj.buffer instanceof Uint8Array) {
+                        data = toBase64(attObj.buffer);
+                        fileContentForMagic = attObj.buffer;
+                    }
+                    else if (typeof Buffer !== 'undefined' && Buffer.isBuffer(attObj.content)) {
+                        data = attObj.content.toString('base64');
+                        fileContentForMagic = attObj.content;
+                    }
+                    else if (attObj.content instanceof Uint8Array) {
+                        data = toBase64(attObj.content);
+                        fileContentForMagic = attObj.content;
+                    }
+                    else if (typeof attObj.content === 'string') {
+                        if (attObj.content.startsWith('data:')) {
+                            const parsed = parseImageDataUrl(attObj.content);
+                            if (parsed) {
+                                data = parsed.data;
+                                resolvedMime = parsed.mimeType;
+                            }
+                        }
+                        else {
+                            data = attObj.content.trim().replace(/\s+/g, '');
+                            fileContentForMagic = attObj.content;
+                        }
+                    }
+                }
+                if (data !== undefined) {
+                    const mimeType = explicitMime ||
+                        (typeof attObj.mediaType === 'string' && attObj.mediaType.toLowerCase()) ||
+                        (typeof attObj.mimeType === 'string' && attObj.mimeType.toLowerCase()) ||
+                        resolvedMime ||
+                        (typeof attRecord?.name === 'string' ? guessImageMimeType(attRecord.name) : undefined) ||
+                        (typeof attObj.name === 'string' ? guessImageMimeType(attObj.name) : undefined) ||
+                        guessImageMimeType(attachmentId) ||
+                        detectImageMimeFromMagic(fileContentForMagic ?? data) ||
+                        (isExplicitImageBlock ? 'image/png' : undefined);
+                    if (mimeType && mimeType.startsWith('image/')) {
+                        return {
+                            type: 'image',
+                            data,
+                            mimeType,
+                            uri: typeof b.uri === 'string' ? b.uri : `attachment://${attachmentId}`,
+                        };
+                    }
+                }
+            }
+        }
+    }
+    // 9. Direct b.attachment object
+    if (b.attachment && typeof b.attachment === 'object') {
+        const attObj = b.attachment;
+        let data;
+        let resolvedMime;
+        const attPath = typeof attObj.path === 'string' && attObj.path !== ''
+            ? attObj.path
+            : (typeof attObj.filePath === 'string' && attObj.filePath !== ''
+                ? attObj.filePath
+                : (typeof attObj.url === 'string' && (attObj.url.startsWith('file://') || isLocalFilePath(attObj.url)) ? attObj.url : undefined));
+        let fileContentForMagic;
+        if (attPath !== undefined) {
+            const fileContent = readImageFileFromContext(attPath, context);
+            if (fileContent !== undefined) {
+                fileContentForMagic = fileContent;
+                if (typeof fileContent === 'string') {
+                    if (fileContent.startsWith('data:')) {
+                        const parsed = parseImageDataUrl(fileContent);
+                        if (parsed) {
+                            data = parsed.data;
+                            resolvedMime = parsed.mimeType;
+                        }
+                    }
+                    else {
+                        data = fileContent.trim().replace(/\s+/g, '');
+                    }
+                }
+                else {
+                    data = toBase64(fileContent);
+                }
+                if (!resolvedMime)
+                    resolvedMime = guessImageMimeType(attPath);
+            }
+        }
+        if (data === undefined) {
+            if (typeof attObj.data === 'string' && attObj.data.trim() !== '') {
+                if (attObj.data.startsWith('data:')) {
+                    const parsed = parseImageDataUrl(attObj.data);
+                    if (parsed) {
+                        data = parsed.data;
+                        resolvedMime = parsed.mimeType;
+                    }
+                }
+                else {
+                    data = attObj.data.trim().replace(/\s+/g, '');
+                    fileContentForMagic = attObj.data;
+                }
+            }
+            else if (typeof Buffer !== 'undefined' && Buffer.isBuffer(attObj.data)) {
+                data = attObj.data.toString('base64');
+                fileContentForMagic = attObj.data;
+            }
+            else if (attObj.data instanceof Uint8Array) {
+                data = toBase64(attObj.data);
+                fileContentForMagic = attObj.data;
+            }
+            else if (typeof Buffer !== 'undefined' && Buffer.isBuffer(attObj.buffer)) {
+                data = attObj.buffer.toString('base64');
+                fileContentForMagic = attObj.buffer;
+            }
+            else if (attObj.buffer instanceof Uint8Array) {
+                data = toBase64(attObj.buffer);
+                fileContentForMagic = attObj.buffer;
+            }
+            else if (typeof Buffer !== 'undefined' && Buffer.isBuffer(attObj.content)) {
+                data = attObj.content.toString('base64');
+                fileContentForMagic = attObj.content;
+            }
+            else if (attObj.content instanceof Uint8Array) {
+                data = toBase64(attObj.content);
+                fileContentForMagic = attObj.content;
+            }
+            else if (typeof attObj.content === 'string') {
+                if (attObj.content.startsWith('data:')) {
+                    const parsed = parseImageDataUrl(attObj.content);
+                    if (parsed) {
+                        data = parsed.data;
+                        resolvedMime = parsed.mimeType;
+                    }
+                }
+                else {
+                    data = attObj.content.trim().replace(/\s+/g, '');
+                    fileContentForMagic = attObj.content;
+                }
+            }
+        }
+        if (data !== undefined) {
+            const mimeType = explicitMime ||
+                (typeof attObj.mediaType === 'string' && attObj.mediaType.toLowerCase()) ||
+                (typeof attObj.mimeType === 'string' && attObj.mimeType.toLowerCase()) ||
+                resolvedMime ||
+                (typeof attObj.name === 'string' ? guessImageMimeType(attObj.name) : undefined) ||
+                (attPath ? guessImageMimeType(attPath) : undefined) ||
+                detectImageMimeFromMagic(fileContentForMagic ?? data) ||
+                (isExplicitImageBlock ? 'image/png' : undefined);
+            if (mimeType && mimeType.startsWith('image/')) {
+                return { type: 'image', data, mimeType, ...(typeof b.uri === 'string' ? { uri: b.uri } : {}) };
+            }
+        }
+    }
+    return undefined;
+}
 /**
  * Select the user's own words out of a host-built request.
  *
@@ -1323,9 +2475,10 @@ export function describeUnhandledUpdate(kind, update) {
  * (tests, headless callers) and counts as user input.
  *
  * @param messages - the request's ordered messages, exactly as the host built them.
- * @returns the last real user message's text, or why there is none to forward.
+ * @param context - optional host context or attachment resolver for reading attachments.
+ * @returns the last real user message's text and any image content blocks, or why there is none to forward.
  */
-export function selectForwardPrompt(messages) {
+export function selectForwardPrompt(messages, context) {
     let sawUserRole = false;
     let last;
     for (const message of messages) {
@@ -1335,14 +2488,43 @@ export function selectForwardPrompt(messages) {
         const kind = message.source?.kind;
         if (kind !== undefined && kind !== 'user')
             continue;
-        const text = (message.content ?? [])
+        const content = message.content ?? message.parts;
+        const rawBlocks = Array.isArray(content)
+            ? content
+            : (typeof content === 'string'
+                ? [{ type: 'text', text: content }]
+                : (typeof content === 'object' && content !== null ? [content] : []));
+        const text = rawBlocks
             .filter(block => block.type === 'text' && typeof block.text === 'string')
             .map(block => block.text)
             .join('\n')
             .trim();
-        if (text === '')
+        const images = [];
+        const contentBlocks = [];
+        for (const block of rawBlocks) {
+            if (!block || typeof block !== 'object')
+                continue;
+            if (block.type === 'text' && typeof block.text === 'string') {
+                if (block.text.trim() !== '') {
+                    contentBlocks.push({ type: 'text', text: block.text });
+                }
+            }
+            else {
+                const resolved = resolveImageContent(block, context);
+                if (resolved !== undefined) {
+                    images.push(resolved);
+                    contentBlocks.push(resolved);
+                }
+            }
+        }
+        if (text === '' && images.length === 0)
             continue;
-        last = { text, ...(message.id === undefined ? {} : { id: message.id }) };
+        const item = { text, ...(message.id === undefined ? {} : { id: message.id }) };
+        if (images.length > 0) {
+            item.images = images;
+            item.content = contentBlocks;
+        }
+        last = item;
     }
     if (last !== undefined)
         return { kind: 'prompt', ...last };
@@ -1469,7 +2651,36 @@ export function acpPresetStatusFromRoster(rows, id) {
         : { id, source: ACP_PRESET_SOURCE, installed: false, problem: broken };
 }
 // ---- Transcript ----
-/** Bounded append-only log of raw ACP session updates with monotone seq. */
+/**
+ * The kind of a state-only tick that consecutive repeats may share one entry.
+ *
+ * These are the frames the client folds to nothing (`STATE_ONLY_UPDATES`):
+ * only their latest value is ever read. `session_info_update` qualifies only
+ * while it carries no title — a title is content the replay must keep, so it
+ * never lets a later tick replace its entry.
+ */
+function coalescibleStateKind(update) {
+    if (typeof update !== 'object' || update === null || Array.isArray(update))
+        return undefined;
+    const row = update;
+    const kind = row.sessionUpdate;
+    if (kind === 'usage_update' || kind === 'config_option_update')
+        return kind;
+    if (kind !== 'session_info_update')
+        return undefined;
+    const title = row.title;
+    return title === undefined || title === null || title === '' ? kind : undefined;
+}
+/**
+ * Bounded log of raw ACP session updates with monotone seq.
+ *
+ * Consecutive ticks of the same state-only kind share one entry (the entry is
+ * replaced in place, not appended): chatty agents emit a usage / phase tick
+ * every few hundred milliseconds, and letting each occupy the ring evicts the
+ * conversation itself. This costs nothing on the live path — `append` still
+ * allocates a fresh seq and the bridge broadcasts that frame — but replay via
+ * `since` only sees the newest tick of each run.
+ */
 export class Transcript {
     max;
     entries = [];
@@ -1479,6 +2690,16 @@ export class Transcript {
     }
     append(update) {
         const seq = this.next++;
+        const last = this.entries[this.entries.length - 1];
+        const kind = coalescibleStateKind(update);
+        // Replace, don't push: `since(afterSeq)` keeps its filter, so intermediate
+        // seq values are simply absent from replayed entries. Live SSE frames are
+        // broadcast per append (the returned seq), and the client's live fold does
+        // not depend on transcript contiguity — only `head` must keep advancing.
+        if (kind !== undefined && last !== undefined && coalescibleStateKind(last.update) === kind) {
+            this.entries[this.entries.length - 1] = { seq, update };
+            return seq;
+        }
         this.entries.push({ seq, update });
         if (this.entries.length > this.max)
             this.entries.splice(0, this.entries.length - this.max);
@@ -1673,7 +2894,44 @@ export async function dispatchRpc(manager, endpoint, payload) {
             case 'session/start':
                 return ok(await manager.startSession(str(body, 'agentId', 64), optionalStr(body, 'cwd', 4096)));
             case 'session/prompt': {
-                const { turnId } = await manager.prompt(str(body, 'sessionId', 64), str(body, 'text', 1 << 20));
+                let promptInput;
+                if (Array.isArray(body.prompt)) {
+                    if (body.prompt.length === 0) {
+                        throw new AcpError('bad_payload', 'acp: prompt array cannot be empty');
+                    }
+                    for (const b of body.prompt) {
+                        if (!b || typeof b !== 'object')
+                            throw new AcpError('bad_payload', 'acp: prompt blocks must be objects');
+                        const block = b;
+                        if (block.type === 'text') {
+                            if (typeof block.text !== 'string')
+                                throw new AcpError('bad_payload', 'acp: text block requires string text');
+                            if (block.text.length > (1 << 20))
+                                throw new AcpError('bad_payload', 'acp: text block exceeds max length');
+                        }
+                        else if (block.type === 'image') {
+                            if (typeof block.data !== 'string' || typeof block.mimeType !== 'string') {
+                                throw new AcpError('bad_payload', 'acp: image block requires string data and mimeType');
+                            }
+                            if (!block.mimeType.toLowerCase().startsWith('image/')) {
+                                throw new AcpError('bad_payload', 'acp: image block mimeType must start with image/');
+                            }
+                            if (block.uri !== undefined && typeof block.uri !== 'string') {
+                                throw new AcpError('bad_payload', 'acp: image block uri must be string');
+                            }
+                            if (block.data.length > (20 << 20))
+                                throw new AcpError('bad_payload', 'acp: image block exceeds max data length');
+                        }
+                        else {
+                            throw new AcpError('bad_payload', `acp: unsupported prompt block type: ${String(block.type)}`);
+                        }
+                    }
+                    promptInput = body.prompt;
+                }
+                else {
+                    promptInput = str(body, 'text', 1 << 20);
+                }
+                const { turnId } = await manager.prompt(str(body, 'sessionId', 64), promptInput);
                 return ok({ accepted: true, turnId });
             }
             case 'session/cancel':