@hue-run/sdk 0.17.0 → 0.18.1

package/dist/inline-files.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { MAX_BODY_BYTES } from "./config.js";
+import { applyJsonEdits } from "./json-edits.js";
 /** Text media above this decoded byte limit is offloaded; binary media always uses a digest. */
 export const INLINE_FILE_LIMIT = 64 * 1024;
 /** The longest message text, in UTF-16 code units, inspected for inline files. */
@@ -16,6 +17,78 @@ const messageKeys = new Set([
 export function isMessageKey(key) {
     return messageKeys.has(key);
 }
+/** Attributes whose value is JSON text by its convention, read for files anywhere in it: message
+ * sources (GenAI, AI SDK, OpenInference `input.value`/`output.value`, OpenLLMetry entities,
+ * Langfuse observations and traces) and tool arguments and results. */
+const jsonMediaKeys = new Set([
+    "gen_ai.input.messages",
+    "gen_ai.output.messages",
+    "ai.prompt.messages",
+    "ai.prompt",
+    "input.value",
+    "output.value",
+    "traceloop.entity.input",
+    "traceloop.entity.output",
+    "langfuse.observation.input",
+    "langfuse.observation.output",
+    "langfuse.trace.input",
+    "langfuse.trace.output",
+    "gen_ai.tool.call.arguments",
+    "gen_ai.tool.call.result",
+    "ai.toolCall.args",
+    "ai.toolCall.result",
+    "tool.parameters",
+    "tool_arguments",
+    "tool_response",
+]);
+/** Recorded metadata: JSON text when it reads as an object or array, otherwise the text itself. */
+const metadataKeys = new Set([
+    "metadata",
+    "langfuse.observation.metadata",
+    "langfuse.trace.metadata",
+]);
+const metadataPrefixes = [
+    "langfuse.observation.metadata.",
+    "langfuse.trace.metadata.",
+    "ai.telemetry.metadata.",
+];
+/** OpenLLMetry's indexed message content: the JSON text of a parts list. */
+const indexedContentKey = /^gen_ai\.(?:prompt|completion)\.\d{1,9}\.content$/;
+/** OpenInference's flattened image content: the image's URL. */
+const openInferenceImageKey = /^llm\.(?:input|output)_messages\.\d{1,9}\.message\.contents\.\d{1,9}\.message_content\.image\.image\.url$/;
+/** How an attribute's text is read for files, when it is read at all. */
+export function readingOf(key) {
+    if (jsonMediaKeys.has(key))
+        return "json";
+    if (metadataKeys.has(key) || metadataPrefixes.some((prefix) => key.startsWith(prefix)))
+        return "metadata";
+    if (indexedContentKey.test(key))
+        return "parts";
+    if (openInferenceImageKey.test(key))
+        return "url";
+    return undefined;
+}
+/**
+ * The attributes of a record that hold literal text: OpenInference's `input.value` and
+ * `output.value` when the record declares `input.mime_type` / `output.mime_type` as `text/plain`.
+ * Hue reads no JSON, and so no file, in them; neither does the SDK.
+ */
+export function literalKeys(attributes) {
+    const keys = new Set();
+    if (attributes === null || typeof attributes !== "object")
+        return keys;
+    for (const side of ["input", "output"]) {
+        const declared = Object.getOwnPropertyDescriptor(attributes, `${side}.mime_type`);
+        if (declared && "value" in declared && declared.value === "text/plain")
+            keys.add(`${side}.value`);
+    }
+    return keys;
+}
+/** Whether a span attribute is one whose value the SDK inspects for inline media: the attributes
+ * Hue's reader reads files from. */
+export function isMediaKey(key) {
+    return readingOf(key) !== undefined;
+}
 /** Strict base64: alphabet characters only, padded to a multiple of four. */
 const base64 = /^[A-Za-z0-9+/]*={0,2}$/;
 /** An RFC 2397 `data:` URL's header, up to the comma before its data. Its `;` parameters are read
@@ -67,6 +140,7 @@ export function inlineFileBytes(content) {
         bytes: decoded ?? Buffer.from(content, "utf8"),
         decoded: decoded !== undefined,
         ...(mediaType ? { urlMediaType: mediaType } : {}),
+        ...(decoded !== undefined && !url ? { bareBase64: true } : {}),
     };
 }
 const audioTypes = {
@@ -126,10 +200,13 @@ export function isTextMediaType(contentType) {
         type === "application/x-javascript" ||
         type === "application/x-www-form-urlencoded");
 }
-/** Cheap shared prefilter before bounded parsing of span message attributes. */
+/** Cheap shared prefilter before bounded parsing of the attributes inspected for media. */
 export function mayInlineFiles(key, value) {
-    return (isMessageKey(key) &&
-        typeof value === "string" &&
+    return isMediaKey(key) && mayHoldMedia(value);
+}
+/** Whether text may hold inline media at all: cheap, before it is parsed or walked. */
+export function mayHoldMedia(value) {
+    return (typeof value === "string" &&
         [
             "blob",
             "file",
@@ -138,7 +215,8 @@ export function mayInlineFiles(key, value) {
             "media",
             "inlineData",
             "inline_data",
-            "input_audio",
+            "audio",
+            "data:",
             "\\u",
         ].some((marker) => value.includes(marker)));
 }
@@ -218,7 +296,7 @@ export function contentPath(part, pointer = "") {
         name = undefined;
         dataUrlOnly = true;
     }
-    else if (part.type === "input_image") {
+    else if (part.type === "input_image" || part.type === "computer_screenshot") {
         key = "image_url";
         contentType = undefined;
         name = undefined;
@@ -262,14 +340,254 @@ export function contentPath(part, pointer = "") {
         ...(encoded ? { base64: true } : {}),
     };
 }
-/** Inline media in document order. The caller applies the decoded text threshold. */
-export function largeInlineFileParts(value) {
-    const found = [];
-    const visit = (node, pointer, depth) => {
-        if (depth > 256)
-            throw new Error("Message exceeds the supported nesting limit");
+/** A media type as a `data:` URL declares one: `type/subtype`, no parameters. */
+const declaredMediaType = /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9!#$&^_.+-]+$/;
+/** The media type a whole string that is a `data:` URL declares, when it declares one: such a
+ * string is a file wherever it sits. A web URL, or any other text, is not. */
+function dataUrlType(text) {
+    if (!text.startsWith("data:"))
+        return undefined;
+    const header = dataUrl.exec(text);
+    if (!header)
+        return undefined;
+    const type = header[1].split(";")[0].trim();
+    return declaredMediaType.test(type) && isMediaContentType(type) ? type : undefined;
+}
+/** The modality a media type implies, as Hue's reader names it. */
+export function modalityOf(mediaType) {
+    const type = mediaType.split(";")[0].trim().toLowerCase();
+    if (type.startsWith("image/"))
+        return "image";
+    if (type.startsWith("audio/"))
+        return "audio";
+    if (type.startsWith("video/"))
+        return "video";
+    if (type.startsWith("text/") ||
+        type === "application/pdf" ||
+        type === "application/rtf" ||
+        type === "application/msword" ||
+        type === "application/vnd.ms-excel" ||
+        type === "application/vnd.ms-powerpoint" ||
+        type.startsWith("application/vnd.openxmlformats-officedocument."))
+        return "document";
+    return "file";
+}
+/** The media types OpenAI's audio `format` names; any other valid name is `audio/<name>`. */
+const audioFormats = {
+    mp3: "audio/mpeg",
+    mpeg: "audio/mpeg",
+    mpga: "audio/mpeg",
+    wav: "audio/wav",
+    wave: "audio/wav",
+    ogg: "audio/ogg",
+    oga: "audio/ogg",
+    opus: "audio/opus",
+    flac: "audio/flac",
+    aac: "audio/aac",
+    m4a: "audio/mp4",
+    mp4: "audio/mp4",
+    webm: "audio/webm",
+    pcm16: "audio/pcm",
+    pcm: "audio/pcm",
+};
+function audioFormatMediaType(format) {
+    const name = format.trim().toLowerCase();
+    if (!/^[a-z0-9.+-]{1,32}$/.test(name))
+        return undefined;
+    return Object.hasOwn(audioFormats, name) ? audioFormats[name] : `audio/${name}`;
+}
+/** The media type the first bytes of base64 audio name by their container's signature (WAV,
+ * MP3, AAC, FLAC, Ogg): OpenAI's assistant audio keeps only the bytes, in the format the request
+ * asked for. Raw PCM has no signature and no type. */
+function audioSignatureMediaType(base64) {
+    const head = Buffer.from(base64.slice(0, 16), "base64");
+    const text = (start, end) => head.subarray(start, end).toString("latin1");
+    if (text(0, 4) === "RIFF" && text(8, 12) === "WAVE")
+        return "audio/wav";
+    if (text(0, 3) === "ID3")
+        return "audio/mpeg";
+    if (text(0, 4) === "fLaC")
+        return "audio/flac";
+    if (text(0, 4) === "OggS")
+        return "audio/ogg";
+    // An MPEG frame's sync word: layer bits 00 are an AAC ADTS frame, any other an MP3 frame.
+    if (head.length >= 2 && head[0] === 0xff && (head[1] & 0xf0) === 0xf0)
+        return (head[1] & 0x06) === 0 ? "audio/aac" : "audio/mpeg";
+    if (head.length >= 2 && head[0] === 0xff && (head[1] & 0xe0) === 0xe0)
+        return "audio/mpeg";
+    return undefined;
+}
+/** A label as Hue's reader takes one: nonempty once trimmed, at most 256 code units. */
+function readerLabel(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return false;
+    const text = value.trim();
+    return text.length > 0 && text.length <= 256;
+}
+/**
+ * The keys of a value Hue's reader reads as a file by its shape, where the SDK found no inline
+ * bytes to upload in it (a remote URL, a provider file id, an empty or malformed field): nothing
+ * inside them is read as another file, so nothing inside them is replaced either. Undefined for a
+ * value that is no file. Mirrors the reader's shapes (`mediaPartOf`).
+ */
+function readerConsumed(part) {
+    const type = typeof part.type === "string" ? part.type.toLowerCase().replaceAll("-", "_") : undefined;
+    const size = part.size ?? part.byte_size;
+    const digest = (typeof part.sha256 === "string" && /^[0-9a-f]{64}$/.test(part.sha256)) ||
+        (typeof size === "number" && Number.isSafeInteger(size) && size >= 0);
+    const identifies = (content, fileId) => (typeof content === "string" && content.length > 0) || readerLabel(fileId) || digest;
+    const anthropic = () => {
+        const source = object(part.source);
+        return source && source.type !== "content"
+            ? ["type", "source", "title", "name", "filename", "cache_control"]
+            : undefined;
+    };
+    switch (type) {
+        case "blob":
+            return ["type", "content", "mime_type", "modality", "name", "filename", "transcript"];
+        case "uri":
+            return ["type", "uri", "mime_type", "modality", "name", "filename", "transcript"];
+        case "file": {
+            const file = object(part.file);
+            if (file)
+                return identifies(file.file_data, file.file_id) ? ["type", "file"] : undefined;
+            if (typeof part.file_id === "string" || typeof part.modality === "string")
+                return identifies(undefined, part.file_id)
+                    ? ["type", "file_id", "mime_type", "modality", "name", "filename"]
+                    : undefined;
+            return identifies(part.data)
+                ? ["type", "data", "mediaType", "mimeType", "filename", "name", "providerOptions"]
+                : undefined;
+        }
+        case "image":
+            if (object(part.source))
+                return anthropic();
+            return typeof part.image === "string" || digest
+                ? ["type", "image", "mediaType", "mimeType", "filename", "name", "providerOptions"]
+                : undefined;
+        case "document":
+            return anthropic();
+        case "image_url":
+            return ["type", "image_url"];
+        case "input_image":
+            return ["type", "image_url", "file_id", "detail"];
+        case "input_audio":
+            return ["type", "input_audio", "data", "format", "transcript"];
+        case "input_file":
+            return ["type", "file_data", "file_url", "file_id", "filename", "name"];
+        case "computer_screenshot":
+            return ["type", "image_url", "file_id"];
+        case "media":
+            return ["type", "data", "mime_type", "file_uri", "fileUri", "name", "filename"];
+        case undefined: {
+            for (const key of ["inlineData", "inline_data", "fileData", "file_data"])
+                if (object(part[key]))
+                    return [key];
+            for (const key of ["image", "document"])
+                if (object(object(part[key])?.source))
+                    return [key];
+            const audio = object(part.audio);
+            if (audio &&
+                typeof audio.id === "string" &&
+                (typeof audio.data === "string" ||
+                    typeof audio.transcript === "string" ||
+                    typeof audio.expires_at === "number"))
+                return ["audio"];
+            return undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+/** The keys of a part whose string value is JSON by its convention, read as the value it encodes:
+ * a tool call's `arguments`, a tool result, and a `tool` or `function` message's `content`. A
+ * message's own text is never read as JSON. */
+function encodedJsonKeys(item) {
+    if (item.role === "tool" || item.role === "function")
+        return ["content"];
+    const type = typeof item.type === "string" ? item.type.toLowerCase().replaceAll("-", "_") : undefined;
+    if (type === "tool_call" || type === "function_call")
+        return ["arguments"];
+    if (type === "tool_result" || type === "function_call_output" || type === "tool_call_response")
+        return ["output", "result", "content", "response"];
+    if (typeof item.name === "string" && Object.hasOwn(item, "arguments"))
+        return ["arguments"];
+    return [];
+}
+/** The object or array a JSON-encoded string holds; undefined for any other string. */
+function encodedJsonValue(text) {
+    if (!/^\s*[[{]/.test(text))
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return parsed !== null && typeof parsed === "object" ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** How deep Hue's reader looks for files in a recorded value: a part more than ten levels below
+ * the value's root (an encoded string's JSON counting as a level) is not read as a file, so it is
+ * not inspected either. */
+export const MAX_MEDIA_DEPTH = 10;
+/**
+ * Whether Hue's reader reads JSON text as the value it encodes, and so reads files in it: nested
+ * at most 32 levels, with no number JavaScript cannot hold exactly (an integer past 2^53, or one
+ * past the double range). Hue keeps any other text as it is, so the SDK leaves it as recorded.
+ */
+export function readerParses(value) {
+    const stack = [[value, 0]];
+    while (stack.length) {
+        const [item, depth] = stack.pop();
+        if (depth > 32)
+            return false;
+        if (typeof item === "number" &&
+            (!Number.isFinite(item) || (Number.isInteger(item) && !Number.isSafeInteger(item))))
+            return false;
+        if (item !== null && typeof item === "object")
+            for (const child of Object.values(item))
+                stack.push([child, depth + 1]);
+    }
+    return true;
+}
+/**
+ * Every file a recorded value carries for upload, in reading order, as Hue's reader finds them
+ * (`forEachMediaPart`): a provider part with inline bytes, an OpenAI assistant message's audio,
+ * a whole string that is a typed `data:` URL, and the files inside a tool call's or tool result's
+ * JSON-encoded string. A part whose bytes are not inline (a remote URL, a file id) is left whole.
+ * The caller applies the decoded text threshold.
+ */
+export function mediaIn(value, source) {
+    const box = { value };
+    const files = [];
+    const encoded = [];
+    const document = { at: "", edits: [] };
+    const visit = (node, pointer, depth, owner, key, within) => {
+        if (depth > MAX_MEDIA_DEPTH)
+            return;
+        const add = (file) => files.push({
+            ...file,
+            ...(within.length ? { encoded: within } : {}),
+            document: within.at(-1) ?? document,
+        });
+        if (typeof node === "string") {
+            const type = dataUrlType(node);
+            if (type !== undefined)
+                add({
+                    part: {},
+                    owner,
+                    key,
+                    content: node,
+                    pointer,
+                    partPointer: pointer,
+                    contentType: type,
+                    whole: true,
+                });
+            return;
+        }
         if (Array.isArray(node)) {
-            node.forEach((item, index) => visit(item, `${pointer}/${index}`, depth + 1));
+            for (let index = 0; index < node.length; index++)
+                visit(node[index], `${pointer}/${index}`, depth + 1, node, index, within);
             return;
         }
         const part = object(node);
@@ -277,22 +595,137 @@ export function largeInlineFileParts(value) {
             return;
         const file = contentPath(part, pointer);
         if (file) {
-            found.push(file);
+            add(file);
             return;
         }
-        for (const [name, item] of Object.entries(part))
-            visit(item, `${pointer}/${pointerSegment(name)}`, depth + 1);
+        const consumed = readerConsumed(part);
+        // An OpenAI Chat assistant message's spoken reply: the message is the part.
+        const audio = consumed?.length === 1 && consumed[0] === "audio" ? object(part.audio) : undefined;
+        if (audio &&
+            typeof audio.data === "string" &&
+            audio.data.length % 4 === 0 &&
+            base64.test(audio.data)) {
+            const format = typeof audio.format === "string" && audio.format ? audio.format : undefined;
+            const contentType = format
+                ? audioFormatMediaType(format)
+                : audioSignatureMediaType(audio.data);
+            add({
+                part,
+                owner: audio,
+                key: "data",
+                content: audio.data,
+                pointer: `${pointer}/audio/data`,
+                partPointer: pointer,
+                ...(contentType ? { contentType } : {}),
+                base64: true,
+            });
+        }
+        const encodedKeys = encodedJsonKeys(part);
+        for (const [name, item] of Object.entries(part)) {
+            if (consumed?.includes(name))
+                continue;
+            const at = `${pointer}/${pointerSegment(name)}`;
+            const inner = typeof item === "string" && encodedKeys.includes(name) ? encodedJsonValue(item) : undefined;
+            if (inner !== undefined) {
+                const holder = {
+                    owner: part,
+                    key: name,
+                    value: inner,
+                    dirty: false,
+                    text: item,
+                    at,
+                    edits: [],
+                    parent: within.at(-1) ?? document,
+                };
+                const before = files.length;
+                visit(inner, at, depth + 1, holder, "value", [
+                    ...within,
+                    holder,
+                ]);
+                if (files.length > before)
+                    encoded.push(holder);
+                continue;
+            }
+            visit(item, at, depth + 1, part, name, within);
+        }
     };
-    visit(value, "", 0);
-    return found;
+    visit(value, "", 0, box, "value", []);
+    return { box, files, encoded, document, ...(source !== undefined ? { source } : {}) };
+}
+/**
+ * An attribute's recorded text read for files as Hue's reader reads that attribute: JSON by its
+ * convention; metadata as JSON when it reads as an object or array, otherwise as the text itself;
+ * an OpenLLMetry content as the parts list it encodes (any other content stays text); an
+ * OpenInference image URL as the text itself. Undefined for text that reading finds nothing in.
+ * Throws for JSON that does not parse or nests too deep.
+ */
+export function readMediaText(key, text) {
+    /** JSON text read as Hue's reader reads it: text it keeps as text holds no file. */
+    const json = (parsed) => (readerParses(parsed) ? mediaIn(parsed, text) : undefined);
+    switch (readingOf(key)) {
+        case "json":
+            return json(JSON.parse(text));
+        case "metadata":
+            return /^\s*[[{]/.test(text) ? json(JSON.parse(text)) : mediaIn(text);
+        case "parts": {
+            if (!/^\s*\[/.test(text))
+                return undefined;
+            const parsed = JSON.parse(text);
+            return Array.isArray(parsed) &&
+                parsed.length > 0 &&
+                parsed.every((part) => typeof object(part)?.type === "string")
+                ? json(parsed)
+                : undefined;
+        }
+        case "url":
+            return mediaIn(text);
+        default:
+            return undefined;
+    }
+}
+/** The recorded value's text once its files are placed: its JSON text as recorded with only the
+ * placed files' values (or their parts' members) replaced, each JSON-encoded string a placed file
+ * sits in written again the same way, innermost first. */
+export function placedMediaText(media) {
+    reencodeMedia(media);
+    return media.source !== undefined
+        ? applyJsonEdits(media.source, media.document.edits)
+        : JSON.stringify(media.box.value);
+}
+/** Each JSON-encoded string a placed file sits in, written again, innermost first: the string as
+ * recorded with only its placed files changed. */
+export function reencodeMedia(media) {
+    for (const holder of media.encoded) {
+        if (!holder.dirty)
+            continue;
+        const text = applyJsonEdits(holder.text, holder.edits);
+        holder.owner[holder.key] = text;
+        holder.dirty = false;
+        holder.parent.edits.push({
+            pointer: holder.at.slice(holder.parent.at.length),
+            value: JSON.stringify(text),
+        });
+    }
 }
+/** Whether a found file has bytes to place: nonempty, and a whole string's `data:` URL decodes. */
+export function placeable(file, decoded) {
+    return decoded.bytes.byteLength > 0 && (!file.whole || decoded.decoded);
+}
+/** Whether an uploaded file keeps a 16 KiB prefix of its content in place (text media in a
+ * provider part, whose entry names the content) rather than its digest. A whole string, a file
+ * inside a JSON-encoded string, and a text file a part holds as bare base64 (a GenAI `blob`,
+ * Vertex `media` or AI SDK part, whose content is not the text itself) take the digest form. */
+export function keepsPrefix(file, textual, decoded) {
+    return textual && !file.whole && !file.encoded?.length && !decoded.bareBase64;
+}
+/** A file's bytes: a field its convention declares base64 decoded, any other content read as
+ * Hue's reader reads it, whatever the part's media type (`inlineFileBytes`): a `data:` URL by its
+ * own encoding, text that reads as base64 decoded (what the GenAI conventions, and
+ * `client.media.resolve`, write in a `blob` or `media` part for every media type), anything else
+ * as its UTF-8. */
 export function mediaBytes(file) {
     if (file.base64)
         return { bytes: Buffer.from(file.content, "base64"), decoded: true };
-    if (isMediaContentType(file.contentType) &&
-        isTextMediaType(file.contentType) &&
-        !file.content.startsWith("data:"))
-        return { bytes: Buffer.from(file.content, "utf8"), decoded: false };
     return inlineFileBytes(file.content);
 }
 export function mediaContentType(file, decoded) {
@@ -333,18 +766,124 @@ export class MediaDigestMemo {
         return digest;
     }
 }
-/** Digest placement removes only the leaf and adds identity to the provider part. */
+/** The GenAI `blob` part in digest form a whole-string file is replaced by. */
+function blobPart(contentType, digest) {
+    return {
+        type: "blob",
+        mime_type: contentType,
+        modality: modalityOf(contentType),
+        sha256: digest.sha256,
+        size: digest.size,
+    };
+}
+/** Digest placement removes only the leaf and adds identity to the provider part (the message,
+ * for OpenAI assistant audio); a whole string becomes a GenAI `blob` part in digest form. */
 export function digestPart(file, digest) {
-    delete file.owner[file.key];
-    file.part.sha256 = digest.sha256;
-    file.part.size = digest.size;
+    const owner = file.owner;
+    const document = file.document;
+    const at = (pointer) => pointer.slice(document.at.length);
+    if (file.whole) {
+        const part = blobPart(file.contentType, digest);
+        owner[file.key] = part;
+        document?.edits.push({ pointer: at(file.pointer), value: JSON.stringify(part) });
+    }
+    else {
+        delete owner[file.key];
+        file.part.sha256 = digest.sha256;
+        file.part.size = digest.size;
+        if (document) {
+            const set = [
+                ["sha256", JSON.stringify(digest.sha256)],
+                ["size", String(digest.size)],
+            ];
+            const ownerPointer = file.pointer.slice(0, file.pointer.lastIndexOf("/"));
+            if (ownerPointer === file.partPointer)
+                document.edits.push({ pointer: at(ownerPointer), remove: String(file.key), set });
+            else {
+                document.edits.push({ pointer: at(ownerPointer), remove: String(file.key) });
+                document.edits.push({ pointer: at(file.partPointer), set });
+            }
+        }
+    }
+    for (const holder of file.encoded ?? [])
+        holder.dirty = true;
 }
-export function hashInlineFiles(key, value, count, memo, traceId = "") {
-    return hashFiles(key, value, false, count, memo, traceId);
+/** Prefix placement keeps the first 16 KiB of a text file's content in place. */
+export function prefixPart(file, prefix) {
+    file.owner[file.key] = prefix;
+    file.document?.edits.push({
+        pointer: file.pointer.slice(file.document.at.length),
+        value: JSON.stringify(prefix),
+    });
+    for (const holder of file.encoded ?? [])
+        holder.dirty = true;
+}
+/**
+ * A span's own attribute with its inline media replaced by their digest, as export places media
+ * it does not upload. Only the recorded message attributes (`isMessageKey`) shrink without an
+ * upload; every other inspected attribute keeps its bytes inline unless they upload, so `anyKey`
+ * asks for the digest form of any inspected attribute (what the queue is charged for a value it
+ * holds whole for upload).
+ */
+export function hashInlineFiles(key, value, count, memo, traceId = "", anyKey = false) {
+    return anyKey || isMessageKey(key) ? hashFiles(key, value, false, count, memo, traceId) : value;
 }
 /** Nested message attributes retain small media and digest larger media without upload state. */
-export function hashNestedInlineFiles(key, value) {
-    return hashFiles(key, value, true);
+export function hashNestedInlineFiles(key, value, count) {
+    return isMessageKey(key) ? hashFiles(key, value, true, count) : value;
+}
+/**
+ * Each file a recorded value holds replaced by its digest, as export places a file it does not
+ * upload: binary media of any size (`nested`: over the inline limit) and text media over the
+ * inline limit. Whether any was replaced; `count` counts them.
+ */
+export function digestMedia(media, nested, count, memo, traceId = "") {
+    let changed = false;
+    for (const file of media.files) {
+        const decoded = mediaBytes(file);
+        if (!placeable(file, decoded))
+            continue;
+        if ((nested || isTextMediaType(mediaContentType(file, decoded))) &&
+            decoded.bytes.byteLength <= INLINE_FILE_LIMIT)
+            continue;
+        const digest = memo
+            ? memo.digest(file, decoded, traceId)
+            : {
+                sha256: createHash("sha256").update(decoded.bytes).digest("hex"),
+                size: decoded.bytes.byteLength,
+            };
+        digestPart(file, digest);
+        changed = true;
+        if (count)
+            count.files++;
+    }
+    if (changed)
+        reencodeMedia(media);
+    return changed;
+}
+/**
+ * The UTF-8 size of a structured value's JSON once each file the SDK may upload from it, within
+ * the inspection limits, is placed in its digest form: whether a log body over the value cap fits
+ * it once its media upload. Mutates `value`, a copy the caller owns.
+ */
+export function digestFormBytes(value) {
+    const media = mediaIn(value);
+    let inspected = 0;
+    for (const file of media.files) {
+        const units = file.content.length;
+        if (units > MAX_INLINE_FILE_TEXT || inspected + units > INLINE_FILE_TEXT_PER_RECORD)
+            continue;
+        inspected += units;
+        const decoded = mediaBytes(file);
+        if (!placeable(file, decoded))
+            continue;
+        if (isTextMediaType(mediaContentType(file, decoded)) &&
+            decoded.bytes.byteLength <= INLINE_FILE_LIMIT)
+            continue;
+        digestPart(file, { sha256: "0".repeat(64), size: decoded.bytes.byteLength });
+    }
+    reencodeMedia(media);
+    return Buffer.byteLength(JSON.stringify(media.box.value));
 }
 function hashFiles(key, value, nested, count, memo, traceId = "") {
     if (typeof value !== "string" ||
@@ -352,28 +891,10 @@ function hashFiles(key, value, nested, count, memo, traceId = "") {
         value.length > MAX_INLINE_FILE_TEXT)
         return value;
     try {
-        const parsed = JSON.parse(value);
-        const files = largeInlineFileParts(parsed);
-        let changed = false;
-        for (const file of files) {
-            const decoded = mediaBytes(file);
-            if (!decoded.bytes.byteLength)
-                continue;
-            if ((nested || isTextMediaType(mediaContentType(file, decoded))) &&
-                decoded.bytes.byteLength <= INLINE_FILE_LIMIT)
-                continue;
-            const digest = memo
-                ? memo.digest(file, decoded, traceId)
-                : {
-                    sha256: createHash("sha256").update(decoded.bytes).digest("hex"),
-                    size: decoded.bytes.byteLength,
-                };
-            digestPart(file, digest);
-            changed = true;
-            if (count)
-                count.files++;
-        }
-        return changed ? JSON.stringify(parsed) : value;
+        const media = readMediaText(key, value);
+        if (!media || !digestMedia(media, nested, count, memo, traceId))
+            return value;
+        return placedMediaText(media);
     }
     catch {
         return value;