@hue-run/sdk 0.17.0 → 0.18.1

package/dist/attachment.js

@@ -0,0 +1,225 @@
+import { createHash } from "node:crypto";
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { types as utilTypes } from "node:util";
+import { MAX_FILE_DATA_BYTES } from "./config.js";
+import { inlineFileBytes, isMediaContentType, isMediaName } from "./inline-files.js";
+/** How deep in a value an attachment's part may sit and still be uploaded: Hue reads media parts
+ * within ten levels of the value's root. */
+export const MAX_ATTACHMENT_DEPTH = 10;
+const states = new WeakMap();
+/** A strict base64 string: alphabet characters only, padded to a multiple of four. */
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+/** The bytes of a string attachment: a `data:` URL by its own encoding, else strict base64. */
+function stringBytes(text) {
+    if (text.startsWith("data:")) {
+        const decoded = inlineFileBytes(text);
+        return decoded.decoded ? decoded.bytes : undefined;
+    }
+    if (text.length % 4 !== 0 || !BASE64.test(text))
+        return undefined;
+    return Buffer.from(text, "base64");
+}
+/** A file's bytes, read through one descriptor and never past the limit. */
+function fileBytes(path) {
+    const descriptor = openSync(path, "r");
+    try {
+        if (fstatSync(descriptor).size > MAX_FILE_DATA_BYTES)
+            return undefined;
+        // Read to its end, which may lie past its size as stated (a file that grew, a pipe), but
+        // never more than one byte past the limit.
+        const parts = [];
+        let total = 0;
+        for (;;) {
+            const room = Math.min(1 << 20, MAX_FILE_DATA_BYTES + 1 - total);
+            if (room <= 0)
+                return undefined;
+            const buffer = Buffer.alloc(room);
+            const read = readSync(descriptor, buffer, 0, room, null);
+            if (read === 0)
+                break;
+            parts.push(buffer.subarray(0, read));
+            total += read;
+        }
+        return Buffer.concat(parts, total);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function attachmentBytes(options) {
+    const { data, path } = options;
+    if ((data === undefined) === (path === undefined))
+        return undefined;
+    let bytes;
+    if (typeof path === "string")
+        bytes = path ? fileBytes(path) : undefined;
+    else if (typeof data === "string") {
+        if (data.length > 4 * MAX_FILE_DATA_BYTES)
+            return undefined;
+        bytes = stringBytes(data);
+    }
+    // A copy, so a later change to the caller's buffer cannot change what the digest describes;
+    // bytes over the limit are refused before anything is copied.
+    else if (ArrayBuffer.isView(data)) {
+        if (data.byteLength > MAX_FILE_DATA_BYTES)
+            return undefined;
+        bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice();
+    }
+    else if (data instanceof ArrayBuffer) {
+        if (data.byteLength > MAX_FILE_DATA_BYTES)
+            return undefined;
+        bytes = new Uint8Array(data.slice(0));
+    }
+    return bytes && bytes.byteLength <= MAX_FILE_DATA_BYTES ? bytes : undefined;
+}
+/**
+ * A file placed in a recorded value, the equivalent of Langfuse's `LangfuseMedia` and
+ * Braintrust's `Attachment`. Put it anywhere in a `withSpan()` input or output, in `model()`
+ * messages, in a tool's arguments or result, in `recordMessages()` messages or in a span
+ * attribute passed to `withSpan()`. Hue records it at that position as a GenAI `blob` part that
+ * names the file by digest (`{ type: "blob", mime_type, modality, sha256, size, name }`) and
+ * uploads its bytes during export, listed under the record's `hue.blobs`.
+ *
+ * The bytes are read and hashed when the attachment is created; `data` and `path` are limited to
+ * 25 MiB. Creating one never throws: an attachment without exactly one of `data` and `path`, with
+ * unreadable data, larger data or an invalid `contentType` records `null` where it is placed and
+ * counts an instrumentation failure; an invalid `name` alone is omitted and counted.
+ */
+export class Attachment {
+    /** The media type given. */
+    contentType;
+    /** The name given, when it is a valid media name. */
+    name;
+    /** Lowercase hex SHA-256 of the bytes; undefined for an invalid attachment. */
+    sha256;
+    /** Size of the bytes; undefined for an invalid attachment. */
+    size;
+    constructor(options) {
+        const contentType = options?.contentType;
+        const name = options?.name;
+        let bytes;
+        try {
+            bytes = isMediaContentType(contentType) ? attachmentBytes(options) : undefined;
+        }
+        catch {
+            // An unreadable path, or data that is not bytes: the attachment is invalid.
+            bytes = undefined;
+        }
+        const sha256 = bytes ? createHash("sha256").update(bytes).digest("hex") : undefined;
+        this.contentType = typeof contentType === "string" ? contentType : "";
+        this.name = isMediaName(name) ? name : undefined;
+        this.sha256 = sha256;
+        this.size = bytes?.byteLength;
+        states.set(this, {
+            ...(bytes ? { bytes, sha256 } : {}),
+            contentType: this.contentType,
+            ...(this.name === undefined ? {} : { name: this.name }),
+            invalidName: name !== undefined && name !== null && this.name === undefined,
+        });
+    }
+}
+/** @internal The attachment's bytes and validated fields; undefined for anything else. */
+export function attachmentState(value) {
+    return value instanceof Attachment ? states.get(value) : undefined;
+}
+/** The modality a media type implies, as Hue reads a part's media type. */
+export function modalityOf(contentType) {
+    const type = contentType.split(";", 1)[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";
+}
+/** An attachment's digest-form GenAI part, the name only with content capture; undefined for an
+ * invalid attachment. */
+export function attachmentPart(state, captureContent) {
+    if (!state.bytes || !state.sha256)
+        return undefined;
+    return {
+        type: "blob",
+        mime_type: state.contentType,
+        modality: modalityOf(state.contentType),
+        sha256: state.sha256,
+        size: state.bytes.byteLength,
+        ...(captureContent && state.name !== undefined ? { name: state.name } : {}),
+    };
+}
+/** Whether a value holds an attachment anywhere, within the encoder's bounds. */
+export function holdsAttachment(value) {
+    let nodes = 0;
+    const visit = (item, depth) => {
+        // Proxies and accessors are never touched: reading them could run application code.
+        if (item === null || typeof item !== "object" || utilTypes.isProxy(item))
+            return false;
+        if (item instanceof Attachment)
+            return true;
+        if (depth > 32 || ++nodes > 65_536)
+            return false;
+        const prototype = Object.getPrototypeOf(item);
+        if (!Array.isArray(item) && prototype !== Object.prototype && prototype !== null)
+            return false;
+        return Object.keys(item).some((key) => {
+            const descriptor = Object.getOwnPropertyDescriptor(item, key);
+            return (descriptor !== undefined && "value" in descriptor && visit(descriptor.value, depth + 1));
+        });
+    };
+    try {
+        return visit(value, 0);
+    }
+    catch {
+        return false;
+    }
+}
+/** A JSON pointer's reference token. */
+export function pointerSegment(segment) {
+    return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+/** The digest parts in `value` (within {@link MAX_ATTACHMENT_DEPTH}) that are the `files`' own
+ * parts: an object with `type` `blob`, no `content`, and the file's `sha256`, `size` and
+ * `mime_type`. Each found part takes one file of that digest, in the value's order; a part's
+ * `name`, when valid, is the one it carries. */
+export function locateParts(value, files) {
+    const pending = [...files];
+    const found = [];
+    let nodes = 0;
+    const visit = (node, pointer, depth) => {
+        if (!pending.length || depth > MAX_ATTACHMENT_DEPTH || ++nodes > 1_048_576)
+            return;
+        if (Array.isArray(node)) {
+            node.forEach((item, index) => visit(item, `${pointer}/${index}`, depth + 1));
+            return;
+        }
+        if (node === null || typeof node !== "object")
+            return;
+        const part = node;
+        if (part.type === "blob" && !Object.hasOwn(part, "content")) {
+            const index = pending.findIndex((file) => part.sha256 === file.digest.sha256 &&
+                part.size === file.digest.size &&
+                part.mime_type === file.contentType);
+            if (index !== -1) {
+                const [file] = pending.splice(index, 1);
+                found.push({
+                    file: file,
+                    pointer,
+                    ...(isMediaName(part.name) ? { name: part.name } : {}),
+                });
+                return;
+            }
+        }
+        for (const [key, item] of Object.entries(part))
+            visit(item, `${pointer}/${pointerSegment(key)}`, depth + 1);
+    };
+    visit(value, "", 0);
+    return found;
+}

package/dist/blobs.d.ts

@@ -39,10 +39,21 @@ export interface OffloadCollector {
     candidates: OffloadCandidate[];
     cut: string[];
     attachments?: MediaAttachment[];
-    /** The span's own message attributes admission inspected within the record's allowance:
-     * export inspects only these. Absent for a record admission did not copy, which export
-     * inspects within its own allowance. */
+    /** The span's own attributes admission inspected for media within the record's allowance:
+     * export inspects only these. Absent for a record admission did not copy, and for a log record,
+     * which export inspects within its own allowance. */
     inspected?: ReadonlySet<string> | undefined;
+    /** Set for a log record: its values over the inline limit are cut, never uploaded whole; only
+     * the media in its inspected attributes and its body upload, with the attachments placed in
+     * its body (`attachments`, keyed `body#<pointer>`). */
+    log?: boolean;
+    /** A log record's structured body, redacted whole, whose media upload under `body#<pointer>`. */
+    body?: {
+        value: unknown;
+    };
+    /** The strings of a log record's body the queue cut when the record was admitted: never read
+     * as files, since their bytes are not the file's. */
+    bodyCut?: Set<string>;
 }
 export interface MediaAttachment {
     bytes: Uint8Array;
@@ -50,7 +61,14 @@ export interface MediaAttachment {
     contentType: string;
     name?: string;
     eventTime?: HrTime;
+    /** For an attachment placed in a value: the record's attribute (or `body`) that holds its part. */
+    attribute?: string;
+    /** For a placed attachment found in its value: its `hue.blobs` key, `<attribute>#<pointer>`. */
+    key?: string;
 }
+/** The `hue.blobs` key of a staged file: its part's for an attachment placed in a value, else
+ * its `hue.file` event's. */
+export declare function mediaKey(file: MediaAttachment): string;
 /** The outcome of one export's uploads, reported once the export's records are placed. */
 export interface OffloadTally {
     uploaded: number;
@@ -172,6 +190,19 @@ export interface OffloadOptions {
  * uploaded listed under `hue.truncated`. Every fallback is counted in the tally.
  */
 export declare function offloadAttributes(attributes: Record<string, unknown>, collector: OffloadCollector, options: OffloadOptions): Promise<Record<string, unknown>>;
+/**
+ * A record's own attributes, and a log record's body, with each candidate placed (see
+ * {@link offloadAttributes}). A file is uploaded and placed in its digest form (a text file in a
+ * provider part keeps a 16 KiB prefix), its `hue.blobs` entry keyed `<attribute>#<pointer>` or, in
+ * a log record's body, `body#<pointer>`. A file that is not uploaded keeps its bytes inline, except
+ * in a span's own recorded messages, where it keeps its digest as before. A log record's values
+ * over the inline limit are cut, never uploaded whole, and a body still over it is replaced by the
+ * receiver's marker, as before.
+ */
+export declare function offloadRecord(attributes: Record<string, unknown>, collector: OffloadCollector, options: OffloadOptions): Promise<{
+    attributes: Record<string, unknown>;
+    body?: unknown;
+}>;
 /**
  * The span's own attributes with every candidate placed as it was before uploads existed, for an
  * upload step that failed unexpectedly: a message's large inline files as their digest, a value
@@ -179,4 +210,11 @@ export declare function offloadAttributes(attributes: Record<string, unknown>, c
  * `hue.truncated`.
  */
 export declare function fallbackAttributes(attributes: Record<string, unknown>, collector: OffloadCollector, valueBytes: number, tally: OffloadTally, traceId: string, memo?: MediaDigestMemo): Record<string, unknown>;
+/** A record's attributes, and a log record's body, placed as {@link fallbackAttributes} places
+ * them: a log record's files keep their bytes inline, and its body over the inline limit is
+ * replaced by the receiver's marker, as before. */
+export declare function fallbackRecord(attributes: Record<string, unknown>, collector: OffloadCollector, valueBytes: number, tally: OffloadTally, traceId: string, memo?: MediaDigestMemo): {
+    attributes: Record<string, unknown>;
+    body?: unknown;
+};
 export {};

package/dist/blobs.js

@@ -2,8 +2,8 @@ import { createHash } from "node:crypto";
 import { context } from "@opentelemetry/api";
 import { suppressTracing } from "@opentelemetry/core";
 import { isLoopbackHost } from "./config.js";
-import { digestPart, hashInlineFiles, INLINE_FILE_LIMIT, INLINE_FILE_TEXT_PER_RECORD, mediaBytes, mediaContentType, isTextMediaType, mayInlineFiles, isMediaContentType, largeInlineFileParts, MAX_INLINE_FILE_TEXT, } from "./inline-files.js";
-import { TRUNCATED_KEY, truncatedMarker, withTruncatedKeys } from "./privacy.js";
+import { digestPart, hashInlineFiles, hashNestedInlineFiles, INLINE_FILE_LIMIT, INLINE_FILE_TEXT_PER_RECORD, isMessageKey, keepsPrefix, literalKeys, mediaBytes, mediaContentType, mediaIn, isTextMediaType, mayInlineFiles, isMediaContentType, MAX_INLINE_FILE_TEXT, placeable, placedMediaText, prefixPart, readMediaText, reencodeMedia, } from "./inline-files.js";
+import { capLogBody, TRUNCATED_KEY, truncatedMarker, withTruncatedKeys } from "./privacy.js";
 import { truncateUtf8 } from "./safety.js";
 /**
  * Large values and binary media travel apart from their span through reservation, presigned PUT,
@@ -53,6 +53,11 @@ export const FALLBACK_MESSAGES = {
     tooLarge: "Content over its upload limit kept inline fallback or file metadata",
     budget: "Content did not fit the SDK's upload budget; large values were cut inline and media kept digest metadata",
 };
+/** The `hue.blobs` key of a staged file: its part's for an attachment placed in a value, else
+ * its `hue.file` event's. */
+export function mediaKey(file) {
+    return file.key ?? `event:hue.file:${file.digest.sha256}`;
+}
 export function newTally() {
     return { uploaded: 0, fallbacks: new Map() };
 }
@@ -579,6 +584,18 @@ export class BlobUploader {
  * uploaded listed under `hue.truncated`. Every fallback is counted in the tally.
  */
 export async function offloadAttributes(attributes, collector, options) {
+    return (await offloadRecord(attributes, collector, options)).attributes;
+}
+/**
+ * A record's own attributes, and a log record's body, with each candidate placed (see
+ * {@link offloadAttributes}). A file is uploaded and placed in its digest form (a text file in a
+ * provider part keeps a 16 KiB prefix), its `hue.blobs` entry keyed `<attribute>#<pointer>` or, in
+ * a log record's body, `body#<pointer>`. A file that is not uploaded keeps its bytes inline, except
+ * in a span's own recorded messages, where it keeps its digest as before. A log record's values
+ * over the inline limit are cut, never uploaded whole, and a body still over it is replaced by the
+ * receiver's marker, as before.
+ */
+export async function offloadRecord(attributes, collector, options) {
     const { uploader, traceId, valueBytes, upload, tally } = options;
     const result = { ...attributes };
     const existing = Array.isArray(attributes[BLOBS_KEY])
@@ -594,44 +611,25 @@ export async function offloadAttributes(attributes, collector, options) {
     for (let index = 0; index < collector.cut.length; index++)
         fallback(uploader.unsupported() ? "unsupported" : "budget");
     let inspected = 0;
-    const parts = async (index, key, text) => {
-        // Both bounds count UTF-16 code units, as admission does.
-        if (!mayInlineFiles(key, text) || text.length > MAX_INLINE_FILE_TEXT)
-            return text;
-        if (collector.inspected) {
-            // A message admission skipped stays as recorded.
-            if (!collector.inspected.has(key))
-                return text;
-        }
-        else {
-            if (inspected + text.length > INLINE_FILE_TEXT_PER_RECORD)
-                return text;
-            inspected += text.length;
-        }
-        let parsed;
-        let found;
-        try {
-            parsed = JSON.parse(text);
-            found = largeInlineFileParts(parsed);
-        }
-        catch {
-            return text;
-        }
-        if (!found.length)
-            return text;
+    /** Uploads each file of a value and places it; whether any was placed. A file that is not
+     * uploaded keeps its bytes inline, except in a recorded message: a span's own message keeps its
+     * digest, and a log record's keeps the digest of a file over the inline limit, as nested
+     * messages kept them before log records uploaded. */
+    const placeFiles = async (index, key, files) => {
+        const message = isMessageKey(key);
         let changed = false;
-        await Promise.all(found.map((file, position) => {
+        await Promise.all(files.map((file, position) => {
             const decoded = mediaBytes(file);
-            if (!decoded.bytes.byteLength)
+            if (!placeable(file, decoded))
                 return Promise.resolve();
             const contentType = mediaContentType(file, decoded);
             const textual = isTextMediaType(contentType);
             if (textual && decoded.bytes.byteLength <= INLINE_FILE_LIMIT)
                 return Promise.resolve();
-            const partKey = `${key}#${textual ? file.pointer : file.partPointer}`;
+            const prefix = keepsPrefix(file, textual, decoded);
+            const partKey = `${key}#${prefix ? file.pointer : file.partPointer}`;
             const slot = slots > 0 && isBlobKey(partKey) ? (slots--, true) : false;
             return (async () => {
-                changed = true;
                 const digest = options.memo
                     ? options.memo.digest(file, decoded, traceId)
                     : await digestOf(decoded.bytes);
@@ -639,10 +637,11 @@ export async function offloadAttributes(attributes, collector, options) {
                     ? await uploader.store(traceId, partKey, decoded.bytes, contentType, digest, upload)
                     : { ok: false, reason: "budget" };
                 if (outcome.ok) {
-                    if (textual)
-                        file.owner[file.key] = blobPrefix(file.content);
+                    if (prefix)
+                        prefixPart(file, blobPrefix(file.content));
                     else
                         digestPart(file, digest);
+                    changed = true;
                     entries.push({
                         order: [index, position],
                         entry: blobEntry(partKey, digest.sha256, digest.size, outcome.contentType, file.name),
@@ -650,12 +649,65 @@ export async function offloadAttributes(attributes, collector, options) {
                     tally.uploaded++;
                 }
                 else {
-                    digestPart(file, digest);
+                    if (message && (!collector.log || decoded.bytes.byteLength > INLINE_FILE_LIMIT)) {
+                        digestPart(file, digest);
+                        changed = true;
+                    }
                     fallback(outcome.reason);
                 }
             })();
         }));
-        return changed ? JSON.stringify(parsed) : text;
+        return changed;
+    };
+    const literal = literalKeys(attributes);
+    const parts = async (index, key, text) => {
+        // Both bounds count UTF-16 code units, as admission does. Literal text holds no file.
+        if (!mayInlineFiles(key, text) || text.length > MAX_INLINE_FILE_TEXT || literal.has(key))
+            return text;
+        if (collector.inspected) {
+            // A value admission skipped stays as recorded.
+            if (!collector.inspected.has(key))
+                return text;
+        }
+        else {
+            if (inspected + text.length > INLINE_FILE_TEXT_PER_RECORD)
+                return text;
+            inspected += text.length;
+        }
+        let media;
+        try {
+            media = readMediaText(key, text);
+        }
+        catch {
+            return text;
+        }
+        if (!media?.files.length)
+            return text;
+        return (await placeFiles(index, key, media.files)) ? placedMediaText(media) : text;
+    };
+    /** A log record's body with its files placed. Each file's content counts toward the record's
+     * inspection bounds, as an attribute's text does. */
+    const placeBody = async (body) => {
+        let media;
+        try {
+            media = mediaIn(body);
+        }
+        catch {
+            return body;
+        }
+        const files = media.files.filter((file) => {
+            // A string the queue cut holds only the start of its file: it stays as cut.
+            if (collector.bodyCut?.has(file.content))
+                return false;
+            const units = file.content.length;
+            if (units > MAX_INLINE_FILE_TEXT || inspected + units > INLINE_FILE_TEXT_PER_RECORD)
+                return false;
+            inspected += units;
+            return true;
+        });
+        if (await placeFiles(-1, "body", files))
+            reencodeMedia(media);
+        return media.box.value;
     };
     const place = async (index, { key, value }) => {
         const placed = typeof value === "string" ? await parts(index, key, value) : value;
@@ -666,6 +718,11 @@ export async function offloadAttributes(attributes, collector, options) {
         }
         listed.push({ order: index, key });
         const cut = () => typeof placed === "string" ? truncateUtf8(placed, valueBytes) : truncatedMarker(size);
+        // A log record's value is cut, as no log reader pages an uploaded text value.
+        if (collector.log) {
+            result[key] = cut();
+            return;
+        }
         if (slots <= 0) {
             result[key] = cut();
             fallback("budget");
@@ -694,13 +751,14 @@ export async function offloadAttributes(attributes, collector, options) {
             fallback(stored.reason);
         }
     };
+    const body = collector.body ? placeBody(collector.body.value) : undefined;
     await Promise.all(collector.candidates.map((candidate, index) => place(index, candidate)));
     await Promise.all((collector.attachments ?? []).map((file, position) => {
         if (!file.bytes.byteLength)
             return Promise.resolve();
         const slot = slots > 0 ? (slots--, true) : false;
         return (async () => {
-            const key = `event:hue.file:${file.digest.sha256}`;
+            const key = mediaKey(file);
             const outcome = slot
                 ? await uploader.store(traceId, key, file.bytes, file.contentType, file.digest, upload)
                 : { ok: false, reason: "budget" };
@@ -715,13 +773,20 @@ export async function offloadAttributes(attributes, collector, options) {
                 fallback(outcome.reason);
         })();
     }));
+    let placedBody;
+    if (body) {
+        const capped = capLogBody(await body, valueBytes);
+        placedBody = capped.body;
+        if (capped.cut)
+            listed.push({ order: -1, key: "body" });
+    }
     if (listed.length)
         result[TRUNCATED_KEY] = withTruncatedKeys(result[TRUNCATED_KEY], listed.sort((a, b) => a.order - b.order).map(({ key }) => key));
     if (entries.length) {
         entries.sort((a, b) => a.order[0] - b.order[0] || a.order[1] - b.order[1]);
         result[BLOBS_KEY] = [...existing, ...entries.map(({ entry }) => entry)];
     }
-    return result;
+    return { attributes: result, ...(collector.body ? { body: placedBody } : {}) };
 }
 /**
  * The span's own attributes with every candidate placed as it was before uploads existed, for an
@@ -730,8 +795,21 @@ export async function offloadAttributes(attributes, collector, options) {
  * `hue.truncated`.
  */
 export function fallbackAttributes(attributes, collector, valueBytes, tally, traceId, memo) {
+    return fallbackRecord(attributes, collector, valueBytes, tally, traceId, memo).attributes;
+}
+/** A record's attributes, and a log record's body, placed as {@link fallbackAttributes} places
+ * them: a log record's files keep their bytes inline, and its body over the inline limit is
+ * replaced by the receiver's marker, as before. */
+export function fallbackRecord(attributes, collector, valueBytes, tally, traceId, memo) {
     const result = { ...attributes };
     const listed = [];
+    let body;
+    if (collector.body) {
+        const capped = capLogBody(collector.body.value, valueBytes);
+        body = capped.body;
+        if (capped.cut)
+            listed.push("body");
+    }
     for (const _file of collector.attachments ?? [])
         countFallback(tally, "failed", traceId);
     for (let index = 0; index < collector.cut.length; index++)
@@ -741,7 +819,11 @@ export function fallbackAttributes(attributes, collector, valueBytes, tally, tra
         // Each large inline file is reported as a value not uploaded, as the upload step reports it.
         const count = { files: 0 };
         try {
-            if (!collector.inspected || collector.inspected.has(key))
+            // A log record's files stay inline, its messages' files over the inline limit as their
+            // digest, as nested messages kept them before log records uploaded.
+            if (collector.log)
+                placed = hashNestedInlineFiles(key, value, count);
+            else if (!collector.inspected || collector.inspected.has(key))
                 placed = hashInlineFiles(key, value, count, memo, traceId);
         }
         catch {
@@ -749,21 +831,24 @@ export function fallbackAttributes(attributes, collector, valueBytes, tally, tra
         }
         for (let file = 0; file < count.files; file++)
             countFallback(tally, "failed", traceId);
+        // A log record's value over the limit is cut whether or not uploads work.
         if (typeof placed === "string") {
             if (Buffer.byteLength(placed, "utf8") > valueBytes) {
                 placed = truncateUtf8(placed, valueBytes);
                 listed.push(key);
-                countFallback(tally, "failed", traceId);
+                if (!collector.log)
+                    countFallback(tally, "failed", traceId);
             }
         }
         else if (placed instanceof Uint8Array && placed.byteLength > valueBytes) {
             placed = truncatedMarker(placed.byteLength);
             listed.push(key);
-            countFallback(tally, "failed", traceId);
+            if (!collector.log)
+                countFallback(tally, "failed", traceId);
         }
         result[key] = placed;
     }
     if (listed.length)
         result[TRUNCATED_KEY] = withTruncatedKeys(result[TRUNCATED_KEY], listed);
-    return result;
+    return { attributes: result, ...(collector.body ? { body } : {}) };
 }

package/dist/cli/import.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `hue import langfuse`: copies a Langfuse project's traces into Hue from this machine. Langfuse
+ * is read with the project's own keys through its public API; each observation becomes the span
+ * the Langfuse OpenTelemetry SDKs would have recorded and is exported through the SDK's own
+ * transport, so batching, retries, limits, content capture and large-value uploads are the SDK's.
+ * Ids are kept or derived from Langfuse's, so a second run sends the same spans again and Hue
+ * keeps one copy of each: an interrupted or partly failed import is resumed by running it again.
+ */
+/** Streams, environment and timing seams for {@link runImportCommand}; tests inject these. */
+export interface ImportCommandIo {
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    stdin?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    fetch?: typeof fetch;
+    /** Waits `ms`, resolving early when the import is stopped. */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    /** Registers the stop request (SIGINT and SIGTERM by default) and returns its removal. */
+    onInterrupt?: (listener: () => void) => () => void;
+    /** The current time, for the default end of the window. */
+    now?: () => Date;
+    /** Ends the process after a second stop request (`process.exit` by default), so exports still
+     * in flight do not hold it until their requests time out. */
+    exit?: (code: number) => void;
+}
+export declare const IMPORT_USAGE = "Usage: hue import langfuse [options]\n\nCopy traces from a Langfuse project into Hue. The import runs on this machine with your own\nLangfuse keys, which are sent only to Langfuse. Each observation becomes a span with the\nlangfuse.* attributes Hue reads; ids are kept, so running the same command again resumes an\nimport without duplicating what was already sent.\n\nLangfuse (keys from the environment or --env-path; the secret key never from the command line):\n  LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY  The Langfuse project's API keys\n  LANGFUSE_BASE_URL or LANGFUSE_HOST        Langfuse host (default https://cloud.langfuse.com)\n  --langfuse-host URL                       Langfuse host, instead of the variables\n  --langfuse-public-key KEY                 Public key, instead of LANGFUSE_PUBLIC_KEY\n\nHue:\n  HUE_API_KEY            The Hue project key the traces are sent with (environment, --env-path\n                         or ./.env.hue); not needed with --dry-run\n  --origin URL           Hue origin (default HUE_BASE_URL, then https://app.hue.run)\n  --service-name NAME    service.name of the imported spans (default langfuse)\n\nSelection (newest first):\n  --from TIME            Traces that started at or after TIME: an ISO 8601 date (midnight UTC)\n                         or a date and time with a zone, such as 2026-01-01T09:00:00Z\n  --to TIME              Traces that started before TIME (default: an hour before the command\n                         starts, so traces still running are left for a later run)\n  --limit N              At most N traces\n  --trace-id ID          This Langfuse trace (repeatable); not with --from, --to or --limit\n\nContent:\n  --media                Download the files Langfuse media references (@@@langfuseMedia:\u2026@@@)\n                         point to and upload them to Hue; without it, references stay as text\n  --no-content           Send metadata only: no inputs, outputs, status messages or model\n                         parameters (content is sent by default, as the SDK records it)\n\nRun:\n  --dry-run              Read Langfuse and count what would be imported; send nothing to Hue\n  --yes                  Import without asking for confirmation (required without a terminal)\n  --env-path PATH        Load a dotenv file first (--env-file also works when it exists);\n                         ./.env.hue loads when HUE_API_KEY is not set. Variables already set win\n  -h, --help             Show this help\n\nExit codes: 0 every trace was imported, 1 a trace, span or file was not, 2 usage error,\n130 stopped (run the same command again to resume).";
+/** An instant of the window: an ISO 8601 date (midnight UTC) or a date and time with a zone. */
+export declare function parseInstant(option: string, value: string): string;
+/** The Langfuse host as a base URL without a trailing slash, or why it is refused. */
+export declare function parseLangfuseHost(value: string): string;
+/** Runs `hue import langfuse`; resolves to the exit code. */
+export declare function runImportCommand(argv: string[], io?: ImportCommandIo): Promise<number>;