@hue-run/sdk 0.15.2 → 0.17.0

package/dist/inline-files.js

@@ -1,12 +1,12 @@
 import { createHash } from "node:crypto";
 import { MAX_BODY_BYTES } from "./config.js";
-/** Inline file content larger than this many UTF-8 bytes is exported as its digest instead. */
+/** 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-8 bytes, inspected for inline files. */
+/** The longest message text, in UTF-16 code units, inspected for inline files. */
 export const MAX_INLINE_FILE_TEXT = 8 * MAX_BODY_BYTES;
 /** Message text one record inspects for inline files in all, in UTF-16 code units. */
 export const INLINE_FILE_TEXT_PER_RECORD = 2 * MAX_INLINE_FILE_TEXT;
-/** Message attributes whose JSON can inline files: GenAI blob parts and AI SDK 6 file parts. */
+/** The span message attributes whose JSON may contain inline media. */
 const messageKeys = new Set([
     "gen_ai.input.messages",
     "gen_ai.output.messages",
@@ -69,76 +69,200 @@ export function inlineFileBytes(content) {
         ...(mediaType ? { urlMediaType: mediaType } : {}),
     };
 }
-function fileBytes(content) {
-    return inlineFileBytes(content).bytes;
+const audioTypes = {
+    wav: "audio/wav",
+    mp3: "audio/mpeg",
+    flac: "audio/flac",
+    ogg: "audio/ogg",
+    opus: "audio/opus",
+    aac: "audio/aac",
+    m4a: "audio/mp4",
+    webm: "audio/webm",
+    pcm16: "audio/pcm",
+};
+const documentTypes = {
+    pdf: "application/pdf",
+    csv: "text/csv",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    html: "text/html",
+    txt: "text/plain",
+    md: "text/markdown",
+};
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
 }
-/** The key holding a part's inline content: GenAI `blob` parts and AI SDK 6 `file` parts. */
-export function contentKey(part) {
-    return part.type === "blob" ? "content" : part.type === "file" ? "data" : undefined;
+function string(value) {
+    return typeof value === "string" ? value : undefined;
 }
-function hashNode(value, state, depth) {
-    if (depth > 256)
-        throw new Error("Message exceeds the supported nesting limit");
-    if (Array.isArray(value))
-        return value.map((item) => hashNode(item, state, depth + 1));
-    if (value === null || typeof value !== "object")
-        return value;
-    const part = value;
-    const key = contentKey(part);
-    const inline = key === undefined ? undefined : part[key];
-    if (key !== undefined && typeof inline === "string") {
-        const bytes = fileBytes(inline);
-        if (bytes.byteLength > INLINE_FILE_LIMIT) {
-            const { [key]: _omitted, ...rest } = part;
-            state.changed = true;
-            state.files++;
-            return {
-                ...rest,
-                sha256: createHash("sha256").update(bytes).digest("hex"),
-                size: bytes.byteLength,
-            };
-        }
-    }
-    return Object.fromEntries(Object.entries(part).map(([name, item]) => [name, hashNode(item, state, depth + 1)]));
-}
-/**
- * Replaces inline files longer than {@link INLINE_FILE_LIMIT} in a recorded message attribute
- * with their SHA-256 and byte size, so a span that inlines a large file exports the file's
- * identity instead of being rejected for its size. The part keeps its other fields (`type`,
- * `mime_type`, `modality`, `mediaType`, …). Other attributes, shorter messages and values that
- * are not JSON are returned unchanged.
- */
-export function hashInlineFiles(key, value, 
-/** Counts the files replaced by their digest, when given. */
-count) {
-    if (!messageKeys.has(key) ||
-        typeof value !== "string" ||
-        Buffer.byteLength(value, "utf8") <= INLINE_FILE_LIMIT ||
-        Buffer.byteLength(value, "utf8") > MAX_INLINE_FILE_TEXT ||
-        !(value.includes('"blob"') || value.includes('"file"')))
-        return value;
-    try {
-        const parsed = JSON.parse(value);
-        const state = { changed: false, files: 0 };
-        const hashed = hashNode(parsed, state, 0);
-        if (count)
-            count.files += state.files;
-        return state.changed ? JSON.stringify(hashed) : value;
-    }
-    catch {
-        // Not JSON, or nested too deeply to inspect: export decides the value's fate as before.
-        return value;
-    }
+export function isMediaName(value) {
+    return (typeof value === "string" &&
+        value.trim().length > 0 &&
+        value.length <= 256 &&
+        value.isWellFormed() &&
+        !Array.from(value).some((character) => {
+            const code = character.charCodeAt(0);
+            return code < 32 || code === 127;
+        }));
 }
 function pointerSegment(segment) {
     return segment.replaceAll("~", "~0").replaceAll("/", "~1");
 }
-/**
- * The inline file parts of a parsed message whose content text is longer than
- * {@link INLINE_FILE_LIMIT} UTF-8 bytes, in document order: the caller decodes each and keeps the
- * ones whose file bytes are over the limit. The parts are the parsed value's own objects, so the
- * caller may replace their content in place.
- */
+/** Whether the receiver can preview these bytes as text. */
+export function isTextMediaType(contentType) {
+    const type = contentType.split(";", 1)[0].trim().toLowerCase();
+    return (type.startsWith("text/") ||
+        type === "application/json" ||
+        type.endsWith("+json") ||
+        type === "application/xml" ||
+        type.endsWith("+xml") ||
+        type === "application/yaml" ||
+        type === "application/x-yaml" ||
+        type === "application/javascript" ||
+        type === "application/x-javascript" ||
+        type === "application/x-www-form-urlencoded");
+}
+/** Cheap shared prefilter before bounded parsing of span message attributes. */
+export function mayInlineFiles(key, value) {
+    return (isMessageKey(key) &&
+        typeof value === "string" &&
+        [
+            "blob",
+            "file",
+            "image",
+            "document",
+            "media",
+            "inlineData",
+            "inline_data",
+            "input_audio",
+            "\\u",
+        ].some((marker) => value.includes(marker)));
+}
+/** A printable MIME type with optional parameters, accepted by the upload contract. */
+export function isMediaContentType(value) {
+    return (typeof value === "string" &&
+        value.length >= 3 &&
+        value.length <= 255 &&
+        /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9!#$&^_.+-]+(?: *;[ -~]*)?$/.test(value));
+}
+/** Detect the content pointer, MIME, name, and encoding contract of a provider media part. */
+export function contentPath(part, pointer = "") {
+    let owner = part;
+    let key;
+    let path = "";
+    let contentType = string(part.mime_type ?? part.mimeType ?? part.mediaType ?? part.media_type);
+    let name = string(part.name ?? part.filename);
+    let encoded = false;
+    let dataUrlOnly = false;
+    const source = object(part.source);
+    const inline = object(part.inlineData ?? part.inline_data);
+    const audio = object(part.input_audio);
+    const chatFile = object(part.file);
+    const bedrock = object(part.image ?? part.document);
+    if (inline) {
+        owner = inline;
+        key = "data";
+        path = part.inlineData ? "/inlineData" : "/inline_data";
+        contentType = string(inline.mimeType ?? inline.mime_type);
+        encoded = true;
+        name = undefined;
+    }
+    else if (audio && part.type === "input_audio") {
+        owner = audio;
+        key = "data";
+        path = "/input_audio";
+        contentType = audioTypes[string(audio.format) ?? ""];
+        encoded = true;
+        name = undefined;
+    }
+    else if (chatFile && part.type === "file") {
+        owner = chatFile;
+        key = "file_data";
+        path = "/file";
+        name = string(chatFile.filename);
+        dataUrlOnly = true;
+    }
+    else if (bedrock && object(bedrock.source)) {
+        const isImage = object(part.image) !== undefined;
+        owner = object(bedrock.source);
+        key = "bytes";
+        path = isImage ? "/image/source" : "/document/source";
+        const format = string(bedrock.format) ?? "";
+        contentType =
+            isImage && ["png", "jpeg", "gif", "webp"].includes(format)
+                ? `image/${format}`
+                : documentTypes[format];
+        name = isImage ? undefined : string(bedrock.name);
+        encoded = true;
+    }
+    else if (source && ["image", "document"].includes(string(part.type) ?? "")) {
+        if (source.type !== "base64")
+            return undefined;
+        owner = source;
+        key = "data";
+        path = "/source";
+        contentType = string(source.media_type);
+        name = string(part.title);
+        encoded = true;
+    }
+    else if (part.type === "image_url") {
+        const image = object(part.image_url);
+        owner = image ?? part;
+        key = image ? "url" : "image_url";
+        path = image ? "/image_url" : "";
+        contentType = undefined;
+        name = undefined;
+        dataUrlOnly = true;
+    }
+    else if (part.type === "input_image") {
+        key = "image_url";
+        contentType = undefined;
+        name = undefined;
+        dataUrlOnly = true;
+    }
+    else if (part.type === "input_file") {
+        key = "file_data";
+        contentType = undefined;
+        name = string(part.filename);
+        dataUrlOnly = true;
+    }
+    else if (part.type === "image") {
+        key = "image";
+        name = undefined;
+    }
+    else if (part.type === "media") {
+        key = "data";
+        name = undefined;
+    }
+    else
+        key = part.type === "blob" ? "content" : part.type === "file" ? "data" : undefined;
+    if (!key)
+        return undefined;
+    const content = owner[key];
+    if (typeof content !== "string" || /^(?:https?:|s3:|gs:|file:|blob:)/i.test(content))
+        return undefined;
+    if (dataUrlOnly && !content.startsWith("data:"))
+        return undefined;
+    // A declared base64 source must actually decode; malformed payloads stay as recorded.
+    if (encoded && !(content.length % 4 === 0 && base64.test(content)))
+        return undefined;
+    return {
+        part,
+        owner,
+        key,
+        content,
+        pointer: `${pointer}${path}/${key}`,
+        partPointer: pointer,
+        ...(contentType ? { contentType } : {}),
+        ...(isMediaName(name) ? { name } : {}),
+        ...(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) => {
@@ -148,17 +272,12 @@ export function largeInlineFileParts(value) {
             node.forEach((item, index) => visit(item, `${pointer}/${index}`, depth + 1));
             return;
         }
-        if (node === null || typeof node !== "object")
+        const part = object(node);
+        if (!part)
             return;
-        const part = node;
-        const key = contentKey(part);
-        const inline = key === undefined ? undefined : part[key];
-        // Decoding only shrinks the text, so text of at most the limit holds no file over it.
-        if (key !== undefined &&
-            typeof inline === "string" &&
-            inline.length * 3 > INLINE_FILE_LIMIT &&
-            Buffer.byteLength(inline, "utf8") > INLINE_FILE_LIMIT) {
-            found.push({ part, key, content: inline, pointer: `${pointer}/${key}` });
+        const file = contentPath(part, pointer);
+        if (file) {
+            found.push(file);
             return;
         }
         for (const [name, item] of Object.entries(part))
@@ -167,10 +286,96 @@ export function largeInlineFileParts(value) {
     visit(value, "", 0);
     return found;
 }
-/** The digest an inline file part is exported as when its bytes are not uploaded: the part's
- * other fields with the file's SHA-256 and byte size, as {@link hashInlineFiles} writes it. */
-export function digestPart(part, key, digest) {
-    delete part[key];
-    part.sha256 = digest.sha256;
-    part.size = digest.size;
+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) {
+    return ((isMediaContentType(file.contentType) ? file.contentType : undefined) ??
+        (isMediaContentType(decoded.urlMediaType) ? decoded.urlMediaType : undefined) ??
+        (decoded.decoded ? "application/octet-stream" : "text/plain; charset=utf-8"));
+}
+/** Bounded payload identity memo, shared by admission and export, cleared at shutdown. */
+export class MediaDigestMemo {
+    entries = new Map();
+    units = 0;
+    clear() {
+        this.entries.clear();
+        this.units = 0;
+    }
+    digest(file, decoded, traceId = "") {
+        return this.bytes((decoded ?? mediaBytes(file)).bytes, traceId);
+    }
+    bytes(bytes, traceId) {
+        const digest = {
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            size: bytes.byteLength,
+        };
+        const key = `${traceId}:${digest.sha256}`;
+        const known = this.entries.get(key);
+        if (known)
+            return known;
+        const limit = 32 * 1024 * 1024;
+        if (key.length <= limit) {
+            while (this.entries.size >= 4096 || this.units + key.length > limit) {
+                const first = this.entries.keys().next().value;
+                this.units -= first.length;
+                this.entries.delete(first);
+            }
+            this.entries.set(key, digest);
+            this.units += key.length;
+        }
+        return digest;
+    }
+}
+/** Digest placement removes only the leaf and adds identity to the provider part. */
+export function digestPart(file, digest) {
+    delete file.owner[file.key];
+    file.part.sha256 = digest.sha256;
+    file.part.size = digest.size;
+}
+export function hashInlineFiles(key, value, count, memo, traceId = "") {
+    return hashFiles(key, value, false, count, memo, traceId);
+}
+/** Nested message attributes retain small media and digest larger media without upload state. */
+export function hashNestedInlineFiles(key, value) {
+    return hashFiles(key, value, true);
+}
+function hashFiles(key, value, nested, count, memo, traceId = "") {
+    if (typeof value !== "string" ||
+        !mayInlineFiles(key, value) ||
+        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;
+    }
+    catch {
+        return value;
+    }
 }

package/dist/privacy.d.ts

@@ -33,7 +33,7 @@ export interface RedactionLimits {
     valueBytes?: number;
     /** The record's value strings cut when it was queued. */
     cut?: ReadonlySet<string>;
-    /** The span's own messages whose large inline files were shrunk to their digest when it was
+    /** The span's own messages whose inline media were shrunk to their digest when it was
      * queued, with how many files each: reported as not uploaded when values may be. */
     digested?: ReadonlyMap<string, DigestedMessage> | undefined;
     /**

package/dist/privacy.js

@@ -2,7 +2,7 @@ import { SpanStatusCode } from "@opentelemetry/api";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { MAX_CONTENT_BYTES, MAX_RECORD_NODES, REDACTION_CONTEXT_UNITS } from "./config.js";
 import { scrubToolCredentials, withToolCatalogSummary } from "./tool-definitions.js";
-import { hashInlineFiles, INLINE_FILE_LIMIT, isMessageKey } from "./inline-files.js";
+import { hashInlineFiles, mayInlineFiles } from "./inline-files.js";
 import { truncateUtf8 } from "./safety.js";
 export { truncateUtf8 };
 /** Attribute keys (and their dotted children) removed in metadata-only mode. */
@@ -142,18 +142,12 @@ function redactedText(value, path, options, cap) {
         throw new Error("Redaction produced unsupported text");
     return result;
 }
-/** Whether a recorded message's text may inline a file over the inline file limit. */
-function mayInlineFiles(key, text) {
-    return (isMessageKey(key) &&
-        text.length * 3 > INLINE_FILE_LIMIT &&
-        (text.includes('"blob"') || text.includes('"file"')));
-}
 /** Marks a value the upload step does not place. */
 const NOT_HELD = Symbol("not held");
 /**
  * One of a span's own attribute values, when its values may be uploaded: text through the
  * credential scrub and the redactor, whole, and collected when it is over the cap or may inline
- * a large file; bytes over the cap collected as they are. {@link NOT_HELD} for any other value,
+ * media; bytes over the cap collected as they are. {@link NOT_HELD} for any other value,
  * and for text the queue cut when the record was admitted, which is never the whole value.
  */
 function offloadValue(key, value, path, options, budget) {
@@ -168,7 +162,7 @@ function offloadValue(key, value, path, options, budget) {
     }
     if (typeof value !== "string")
         return NOT_HELD;
-    // Each large inline file the queue shrank to its digest is reported as not uploaded; what is
+    // Each inline media part the queue shrank to its digest is reported as not uploaded; what is
     // left of the message is placed like any other value, and reported too if it is cut.
     const digested = budget.digested?.get(key);
     const files = digested?.text === value ? digested.files : 0;
@@ -271,7 +265,7 @@ function attributes(source, options, path, budget, listPrefix = "", own = false)
         return [
             [
                 key,
-                redactValue(scrubToolCredentials(key, hashInlineFiles(key, value)), `${path}.${key}`, options, budget, 0, `${listPrefix}${key}`),
+                redactValue(scrubToolCredentials(key, own ? hashInlineFiles(key, value) : value), `${path}.${key}`, options, budget, 0, `${listPrefix}${key}`),
             ],
         ];
     }));

package/dist/safety.d.ts

@@ -1,6 +1,7 @@
 import { type Span } from "@opentelemetry/api";
 export declare function noopSpan(): Span;
 export declare function safeSpan(source: Span, failed: () => void): Span;
+export declare function spanSource(span: Span): Span;
 /** The bounds `encodeContent` enforces while it copies a value. */
 export interface EncodeLimits {
     bytes: number;

package/dist/safety.js

@@ -96,8 +96,14 @@ class SafeSpan {
         this.write(() => this.source.recordException(...args));
     }
 }
+const spanSources = new WeakMap();
 export function safeSpan(source, failed) {
-    return new SafeSpan(source, failed);
+    const span = new SafeSpan(source, failed);
+    spanSources.set(span, spanSource(source));
+    return span;
+}
+export function spanSource(span) {
+    return spanSources.get(span) ?? span;
 }
 /** One content attribute's bounds: the value cap, and as many values as the Python SDK's content
  * snapshot allows, so a structured value of small members is cut at the cap rather than refused

package/dist/snapshot.d.ts

@@ -1,5 +1,6 @@
 import type { ReadableSpan } from "@opentelemetry/sdk-trace";
 import type { ReadableLogRecord, ReadWriteLogRecord } from "@opentelemetry/sdk-logs";
+import { type MediaDigestMemo } from "./inline-files.js";
 /**
  * How a span's own values over the receiver's value cap are held whole for export to upload:
  * the cap, the bytes the held-value budget has left, and whether nothing else is held (a single
@@ -12,7 +13,7 @@ export interface HoldLimits {
     budget: number;
     first: boolean;
 }
-/** A span's own message whose large inline files shrank to their digest when it was queued: the
+/** A span's own message whose inline media shrank to their digest when it was queued: the
  * text queued, and how many files it lost. */
 export interface DigestedMessage {
     text: string;
@@ -20,7 +21,7 @@ export interface DigestedMessage {
 }
 /** What admission keeps of a record: its copy, the bytes charged for it, whether resource
  * attributes were still unresolved, the value strings it cut, the bytes of the values it held
- * whole for upload, and the span's own messages whose large inline files it shrank to their
+ * whole for upload, and the span's own messages whose inline media it shrank to their
  * digest (with how many files each). */
 export interface RecordSnapshot<T> {
     record: T;
@@ -29,6 +30,8 @@ export interface RecordSnapshot<T> {
     cut: ReadonlySet<string>;
     held: number;
     digested: ReadonlyMap<string, DigestedMessage>;
+    /** The span's own message attributes admission inspected or left to export to inspect. */
+    inspected: ReadonlySet<string>;
 }
-export declare function snapshotSpan(source: ReadableSpan, limit: number, captureContent?: boolean, valueUnits?: number, hold?: HoldLimits): RecordSnapshot<ReadableSpan>;
+export declare function snapshotSpan(source: ReadableSpan, limit: number, captureContent?: boolean, valueUnits?: number, hold?: HoldLimits, memo?: MediaDigestMemo): RecordSnapshot<ReadableSpan>;
 export declare function snapshotLog(source: ReadableLogRecord, limit: number, captureContent?: boolean, valueUnits?: number): RecordSnapshot<ReadWriteLogRecord>;