@hue-run/sdk 0.17.0 → 0.18.1

package/dist/evals/runner.js

@@ -520,9 +520,10 @@ export async function runExperiment(options) {
         // copies of its inputs, its work, the evaluator's downloads and the staged outputs.
         // A retry gets its own, so an agent a dead run left behind cannot write into it.
         const worldDirectoryOf = (itemId, attempt) => join(filesRoot, `world-case-${uuid(itemId)}${attempt ? `-${uuid(attempt)}` : ""}`);
+        const directDirectoryOf = (itemId) => join(filesRoot, `case-${uuid(itemId)}`);
         const runCase = async (item, files) => {
             const file = `case-${uuid(item.id)}`;
-            const directDirectory = join(filesRoot, `case-${uuid(item.id)}`);
+            const directDirectory = directDirectoryOf(item.id);
             const caseDirectoryOf = (frozen) => frozen.environmentVersionId ? files.directory : directDirectory;
             let checkpoint;
             try {
@@ -605,122 +606,139 @@ export async function runExperiment(options) {
                 const outputDirectory = join(caseDirectory, "work");
                 await mkdir(outputDirectory, { recursive: true, mode: 0o700 });
                 const failureSequenceBefore = options.hue.transport.getFailureSequence();
-                checkpoint = await options.hue.withSpan("hue.experiment.case", async (span) => {
-                    const start = {
-                        stage: "starting",
-                        startKey: randomUUID(),
-                        traceExternalId: span.traceId,
-                        ...(retryOf ? { previousExecutionId: retryOf } : {}),
-                    };
-                    await store.write(file, start);
-                    const execution = await options.client.startExecution(experiment.id, item.id, {
-                        idempotencyKey: start.startKey,
-                        traceExternalId: span.traceId,
-                        ...retry(retryOf),
-                    });
-                    const attempt = retryOf ? { attempt: retryOf } : {};
-                    await store.write(file, { stage: "running", executionId: execution.id, ...attempt });
-                    let state = "succeeded";
-                    let output;
-                    let generated;
-                    let targetError;
-                    try {
-                        const result = await options.target(targetInputs, {
-                            config: targetConfig,
-                            item: structuredClone(frozenCase),
-                            span,
-                            executionId: execution.id,
-                            files: structuredClone(inputFiles),
-                            outputDirectory,
+                let outcome;
+                try {
+                    checkpoint = await options.hue.withSpan("hue.experiment.case", async (span) => {
+                        const start = {
+                            stage: "starting",
+                            startKey: randomUUID(),
+                            traceExternalId: span.traceId,
+                            ...(retryOf ? { previousExecutionId: retryOf } : {}),
+                        };
+                        await store.write(file, start);
+                        const execution = await options.client.startExecution(experiment.id, item.id, {
+                            idempotencyKey: start.startKey,
+                            traceExternalId: span.traceId,
+                            ...retry(retryOf),
                         });
-                        if (result instanceof TargetResult) {
-                            output = result.output;
-                            generated = result.files;
-                        }
-                        else
-                            output = result;
-                    }
-                    catch (error) {
-                        if (error instanceof TargetOutcomeUncertainError)
-                            throw error;
-                        // A stop the caller asked for is no outcome: the execution stays open for the
-                        // resumed run to replace instead of being scored as cancelled.
-                        if (error instanceof TargetCancelledError && options.signal?.aborted) {
-                            options.hue.recordError(span.span, error);
-                            await store.write(file, {
-                                stage: "interrupted",
+                        const attempt = retryOf ? { attempt: retryOf } : {};
+                        await store.write(file, { stage: "running", executionId: execution.id, ...attempt });
+                        let state = "succeeded";
+                        let output;
+                        let generated;
+                        let targetError;
+                        try {
+                            const result = await options.target(targetInputs, {
+                                config: targetConfig,
+                                item: structuredClone(frozenCase),
+                                span,
                                 executionId: execution.id,
-                                ...attempt,
+                                files: structuredClone(inputFiles),
+                                outputDirectory,
                             });
-                            throw error;
-                        }
-                        state = error instanceof TargetCancelledError ? "cancelled" : "error";
-                        targetError = error;
-                        options.hue.recordError(span.span, error);
-                    }
-                    // Output validation is outside the target catch: a successful target never becomes an agent error because upload serialization failed.
-                    if (output !== undefined) {
-                        try {
-                            output = json(output);
+                            if (result instanceof TargetResult) {
+                                output = result.output;
+                                generated = result.files;
+                            }
+                            else
+                                output = result;
                         }
                         catch (error) {
-                            // An output over the size, count or depth bounds is the target's own failure, as
-                            // a file it cannot deliver is: the case completes as an error and the run goes
-                            // on. Output that is not JSON at all still stops the run for inspection.
-                            const limit = error instanceof RangeError ? outputLimits.get(error.message) : undefined;
-                            if (limit === undefined) {
+                            if (error instanceof TargetOutcomeUncertainError)
+                                throw error;
+                            // A stop the caller asked for is no outcome: the execution stays open for the
+                            // resumed run to replace instead of being scored as cancelled.
+                            if (error instanceof TargetCancelledError && options.signal?.aborted) {
+                                options.hue.recordError(span.span, error);
                                 await store.write(file, {
-                                    stage: "serialization_failed",
+                                    stage: "interrupted",
                                     executionId: execution.id,
+                                    ...attempt,
                                 });
-                                throw new OutcomeSerializationError(execution.id);
-                            }
-                            state = "error";
-                            output = undefined;
-                            targetError = new OutputTooLargeError(limit);
-                            options.hue.recordError(span.span, targetError);
-                        }
-                    }
-                    if (output !== undefined)
-                        span.setOutput(output);
-                    let staged = [];
-                    // An empty declared list (a direct case answered only through stdout, or
-                    // `withFiles(output, [])`) means no generated files, not a missing-files error.
-                    if (generated !== undefined && generated.length > 0 && state === "succeeded") {
-                        try {
-                            staged = await stageOutputFiles(generated, join(caseDirectory, "outputs"));
-                        }
-                        catch (error) {
-                            // Files the target declared but did not deliver are its own failure; the
-                            // outcome is still saved instead of leaving the execution uncertain.
-                            if (!(error instanceof OutputFileError))
                                 throw error;
-                            state = "error";
+                            }
+                            state = error instanceof TargetCancelledError ? "cancelled" : "error";
                             targetError = error;
                             options.hue.recordError(span.span, error);
                         }
+                        // Output validation is outside the target catch: a successful target never becomes an agent error because upload serialization failed.
+                        if (output !== undefined) {
+                            try {
+                                output = json(output);
+                            }
+                            catch (error) {
+                                // An output over the size, count or depth bounds is the target's own failure, as
+                                // a file it cannot deliver is: the case completes as an error and the run goes
+                                // on. Output that is not JSON at all still stops the run for inspection.
+                                const limit = error instanceof RangeError ? outputLimits.get(error.message) : undefined;
+                                if (limit === undefined) {
+                                    await store.write(file, {
+                                        stage: "serialization_failed",
+                                        executionId: execution.id,
+                                    });
+                                    throw new OutcomeSerializationError(execution.id);
+                                }
+                                state = "error";
+                                output = undefined;
+                                targetError = new OutputTooLargeError(limit);
+                                options.hue.recordError(span.span, targetError);
+                            }
+                        }
+                        if (output !== undefined)
+                            span.setOutput(output);
+                        let staged = [];
+                        // An empty declared list (a direct case answered only through stdout, or
+                        // `withFiles(output, [])`) means no generated files, not a missing-files error.
+                        if (generated !== undefined && generated.length > 0 && state === "succeeded") {
+                            try {
+                                staged = await stageOutputFiles(generated, join(caseDirectory, "outputs"));
+                            }
+                            catch (error) {
+                                // Files the target declared but did not deliver are its own failure; the
+                                // outcome is still saved instead of leaving the execution uncertain.
+                                if (!(error instanceof OutputFileError))
+                                    throw error;
+                                state = "error";
+                                targetError = error;
+                                options.hue.recordError(span.span, error);
+                            }
+                        }
+                        const uploading = {
+                            stage: "uploading",
+                            executionId: execution.id,
+                            trace: { traceId: span.traceId, spanId: span.spanId },
+                            state,
+                            hasOutput: output !== undefined,
+                            ...(options.persistResultContent && output !== undefined ? { output } : {}),
+                            ...(state === "error" ? { error: errorPayload(targetError) } : {}),
+                            files: staged,
+                            ...attempt,
+                        };
+                        // Without persisted result content a restart cannot reconstruct the outcome; the
+                        // saved stage then reports the execution as uncertain instead of guessing.
+                        files.keepOutputs = true;
+                        await store.write(file, uploading);
+                        outcome = uploading;
+                        return prepare(file, uploading, frozenCase, caseDirectory, output);
+                    }, {
+                        parentContext: ROOT_CONTEXT,
+                        input: frozenCase.inputs,
+                        attributes: { "hue.experiment.id": experiment.id, "hue.dataset.case.id": item.id },
+                    });
+                }
+                catch (error) {
+                    // A failure after the outcome was saved (fetching the scorers' files, uploading the
+                    // target's files): the root has ended, so the count of spans the case ended is saved with
+                    // the outcome, and a resume holds the trace's receipt to it before completing.
+                    const spans = outcome?.trace
+                        ? options.hue.transport.spansEnded?.(outcome.trace.traceId)
+                        : undefined;
+                    if (outcome?.trace && spans !== undefined) {
+                        outcome.trace.spans = spans;
+                        await store.write(file, outcome);
                     }
-                    const uploading = {
-                        stage: "uploading",
-                        executionId: execution.id,
-                        trace: { traceId: span.traceId, spanId: span.spanId },
-                        state,
-                        hasOutput: output !== undefined,
-                        ...(options.persistResultContent && output !== undefined ? { output } : {}),
-                        ...(state === "error" ? { error: errorPayload(targetError) } : {}),
-                        files: staged,
-                        ...attempt,
-                    };
-                    // Without persisted result content a restart cannot reconstruct the outcome; the
-                    // saved stage then reports the execution as uncertain instead of guessing.
-                    files.keepOutputs = true;
-                    await store.write(file, uploading);
-                    return prepare(file, uploading, frozenCase, caseDirectory, output);
-                }, {
-                    parentContext: ROOT_CONTEXT,
-                    input: frozenCase.inputs,
-                    attributes: { "hue.experiment.id": experiment.id, "hue.dataset.case.id": item.id },
-                });
+                    throw error;
+                }
                 files.keepOutputs = false;
                 // End root before waiting for both OTLP signals. Export failure leaves the prepared checkpoint intact.
                 let exportError;
@@ -888,9 +906,14 @@ export async function runExperiment(options) {
         await pool(items, concurrency, async (item) => {
             // A world case's directory goes however the case ends, a forced exit included. An
             // interrupted upload keeps only the staged outputs it resumes from; inputs are downloaded
-            // anew for scoring. A direct case has no such directory, so nothing is removed for it.
+            // anew for scoring. A direct case's directory stays for inspection, except the scorers'
+            // copies of evaluator-only files, which go too, so no later case's target finds them.
             const files = { keepOutputs: true, directory: worldDirectoryOf(item.id) };
-            const untrack = onForcedExit(() => releaseWorldFilesSync(files.directory, files.keepOutputs));
+            const evaluatorInputs = join(directDirectoryOf(item.id), "evaluator-inputs");
+            const untrack = onForcedExit(() => {
+                releaseWorldFilesSync(files.directory, files.keepOutputs);
+                rmSync(evaluatorInputs, { recursive: true, force: true });
+            });
             try {
                 await runCase(item, files);
                 await releaseWorldFiles(files.directory, false);
@@ -900,6 +923,7 @@ export async function runExperiment(options) {
                 throw error;
             }
             finally {
+                await removeCaseFiles(evaluatorInputs);
                 untrack();
             }
         });

package/dist/evals/types.d.ts

@@ -172,7 +172,54 @@ export interface CaseWrite {
     metadata?: Record<string, JsonValue>;
     /** Immutable simulated-world version selected for this case. */
     environmentVersionId?: string | null;
+    /** Input files pinned to the case, at most 32: artifacts this project already holds, or bytes
+     * the client uploads first. Roles other than `org_template` and `evaluator_reference` reach the
+     * target; those two reach only scorers. */
+    files?: CaseFileWrite[];
 }
+/** A pinned input file as the case API takes it. */
+export interface CaseFileReference {
+    /** A ready artifact of this project. */
+    artifactId: string;
+    /** Who receives the file. */
+    role: CaseFile["role"];
+}
+/**
+ * A pinned input file for {@link CaseWrite.files}: a {@link CaseFileReference}, or a file the
+ * client uploads as a verified artifact, from `bytes` or read from `path`: hashed a slice at a
+ * time when the case is checked, then read again as it is uploaded, one file at a time. An
+ * uploaded file must have one of `outputContentTypes`, a well-formed name of 1–255 UTF-16 code
+ * units without path separators or control characters, and 1 byte to 25 MiB.
+ */
+export type CaseFileWrite = (CaseFileReference & {
+    /** Not set on an artifact reference: the artifact keeps its own name. */
+    filename?: undefined;
+    /** Not set on an artifact reference: the artifact keeps its own type. */
+    contentType?: undefined;
+    /** Not set in this form. */
+    bytes?: undefined;
+    /** Not set in this form. */
+    path?: undefined;
+}) | ({
+    /** Who receives the file. */
+    role: CaseFile["role"];
+    /** File name Hue stores. */
+    filename: string;
+    /** One of `outputContentTypes`, the media types Hue stores as artifacts. */
+    contentType: string;
+    /** Not set when the file is given as bytes or a path. */
+    artifactId?: undefined;
+} & ({
+    /** The file's bytes. */
+    bytes: Uint8Array;
+    /** Not set in this form. */
+    path?: undefined;
+} | {
+    /** Path of the file on this machine. */
+    path: string;
+    /** Not set in this form. */
+    bytes?: undefined;
+}));
 /** A typed metric a scorer declares and must report exactly once per scored result. */
 export type MetricDefinition = {
     /** Metric name. */
@@ -851,11 +898,13 @@ export type OutputFile = {
     /** Path of the generated file on this machine. */
     path: string;
     /** Not used when `path` is given. */
+    /** Not set in this form. */
     bytes?: undefined;
 } | {
     /** Generated bytes held in memory. */
     bytes: Uint8Array;
     /** Not used when `bytes` is given. */
+    /** Not set in this form. */
     path?: undefined;
 });
 /** A target's saved outcome when it produced files. Create it with `withFiles`. */

package/dist/evals.d.ts

@@ -1,5 +1,7 @@
 export { ArtifactSizeError, createEvaluationClient, EvaluationClient, HueApiError, isTransientApiError, } from "./evals/client.js";
 export type { EvaluationClientOptions } from "./evals/client.js";
+export { MediaFetchError, rehydrateMedia } from "./evals/media.js";
+export type { MediaClient, MediaFetchErrorReason, MediaFetchOptions, MediaFetchTarget, MediaFile, MediaResolution, MediaResolveFailure, MediaResolveOptions, MediaSourceFile, MediaWriteOptions, } from "./evals/media.js";
 export { runExperiment, rescore, UncertainExecutionError, OutcomeSerializationError, TargetCancelledError, TargetOutcomeUncertainError, TargetTimeoutError, TraceExportUnacknowledgedError, } from "./evals/runner.js";
 export type { RunExperimentOptions, RunExperimentTargetContext, RescoreOptions, RunnerReport, TelemetryIssueCount, TelemetryNotAccepted, TracePending, } from "./evals/runner.js";
 export { TargetResult, withFiles } from "./evals/types.js";

package/dist/evals.js

@@ -1,4 +1,5 @@
 export { ArtifactSizeError, createEvaluationClient, EvaluationClient, HueApiError, isTransientApiError, } from "./evals/client.js";
+export { MediaFetchError, rehydrateMedia } from "./evals/media.js";
 export { runExperiment, rescore, UncertainExecutionError, OutcomeSerializationError, TargetCancelledError, TargetOutcomeUncertainError, TargetTimeoutError, TraceExportUnacknowledgedError, } from "./evals/runner.js";
 export { TargetResult, withFiles } from "./evals/types.js";
 export { CaseFileError, outputContentTypes, outputFileLimits, OutputFileError, safeFilename, targetFileRoles, } from "./evals/files.js";

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createHue, createHueSafe, HueClient, HueConnectionError, type ExistingHueProviders, } from "./client.js";
+export { Attachment, type AttachmentOptions } from "./attachment.js";
 export { createHueTransport, HueTransport, HueExportError } from "./transport.js";
 export type { RecordValue } from "./transport.js";
 export { hueExperimentalTelemetry } from "./experimental-telemetry.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { createHue, createHueSafe, HueClient, HueConnectionError, } from "./client.js";
+export { Attachment } from "./attachment.js";
 export { createHueTransport, HueTransport, HueExportError } from "./transport.js";
 export { hueExperimentalTelemetry } from "./experimental-telemetry.js";
 export { contentPrefixes } from "./privacy.js";

package/dist/inline-files.d.ts

@@ -1,3 +1,4 @@
+import { type JsonEdit } from "./json-edits.js";
 /** Text media above this decoded byte limit is offloaded; binary media always uses a digest. */
 export declare const INLINE_FILE_LIMIT: number;
 /** The longest message text, in UTF-16 code units, inspected for inline files. */
@@ -6,12 +7,29 @@ export declare const MAX_INLINE_FILE_TEXT: number;
 export declare const INLINE_FILE_TEXT_PER_RECORD: number;
 /** Whether an attribute is one of the recorded message attributes that can inline files. */
 export declare function isMessageKey(key: string): boolean;
+/** How an attribute's text is read for files: JSON by convention, metadata, an OpenLLMetry parts
+ * list, or a URL that is the file. */
+export type MediaReading = "json" | "metadata" | "parts" | "url";
+/** How an attribute's text is read for files, when it is read at all. */
+export declare function readingOf(key: string): MediaReading | 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 declare function literalKeys(attributes: unknown): ReadonlySet<string>;
+/** Whether a span attribute is one whose value the SDK inspects for inline media: the attributes
+ * Hue's reader reads files from. */
+export declare function isMediaKey(key: string): boolean;
 /** An inline file's bytes, whether they were decoded from the part's text (base64 or
  * percent-escapes) rather than taken as its UTF-8, and the media type its `data:` URL names. */
 export interface InlineFileBytes {
     bytes: Buffer;
     decoded: boolean;
     urlMediaType?: string;
+    /** The bytes were decoded from text that reads as base64 by its alphabet alone, not from a
+     * `data:` URL or a field its convention declares base64. */
+    bareBase64?: boolean;
 }
 /**
  * The bytes an inline file part carries, the file's own bytes whatever its media type: a `data:`
@@ -20,29 +38,117 @@ export interface InlineFileBytes {
  * `data:` URL whose data does not decode is taken as UTF-8 too.
  */
 export declare function inlineFileBytes(content: string): InlineFileBytes;
+/** JSON text a placed file sits in: its edits, at JSON pointers relative to `at`, the pointer of
+ * the text in the recorded value ("" for the value itself). */
+export interface MediaDocument {
+    at: string;
+    edits: JsonEdit[];
+}
+/** A string inside a recorded value whose JSON the walk read (a tool call's arguments, a tool
+ * result): written again once a file inside it is placed, every byte the placement does not
+ * change kept as recorded. */
+export interface EncodedValue extends MediaDocument {
+    owner: Record<string, unknown>;
+    key: string;
+    value: unknown;
+    dirty: boolean;
+    /** The string as recorded. */
+    text: string;
+    /** The JSON text the string sits in: an encoded string's, else the recorded value's. */
+    parent: MediaDocument;
+}
 /** A part and the exact leaf that contains its bytes. Nested provider metadata stays in place. */
 export interface InlineFilePart {
+    /** The part that carries the digest: the provider part, or for OpenAI assistant audio the
+     * message. Unused for a whole string. */
     part: Record<string, unknown>;
-    owner: Record<string, unknown>;
-    key: string;
+    owner: Record<string, unknown> | unknown[];
+    key: string | number;
     content: string;
     pointer: string;
     partPointer: string;
     contentType?: string;
     name?: string;
     base64?: boolean;
+    /** A whole string that is a `data:` URL: replaced by a GenAI `blob` part in digest form. */
+    whole?: boolean;
+    /** The JSON-encoded strings the file sits in, outermost first: no `hue.blobs` key can address
+     * inside a string, so such a file is placed by its digest. */
+    encoded?: EncodedValue[];
+    /** The JSON text the file sits in, which records its placement as edits. */
+    document?: MediaDocument;
 }
 export declare function isMediaName(value: unknown): value is string;
 /** Whether the receiver can preview these bytes as text. */
 export declare function isTextMediaType(contentType: string): boolean;
-/** Cheap shared prefilter before bounded parsing of span message attributes. */
+/** Cheap shared prefilter before bounded parsing of the attributes inspected for media. */
 export declare function mayInlineFiles(key: string, value: unknown): boolean;
+/** Whether text may hold inline media at all: cheap, before it is parsed or walked. */
+export declare function mayHoldMedia(value: unknown): value is string;
 /** A printable MIME type with optional parameters, accepted by the upload contract. */
 export declare function isMediaContentType(value: unknown): value is string;
 /** Detect the content pointer, MIME, name, and encoding contract of a provider media part. */
 export declare function contentPath(part: Record<string, unknown>, pointer?: string): InlineFilePart | undefined;
-/** Inline media in document order. The caller applies the decoded text threshold. */
-export declare function largeInlineFileParts(value: unknown): InlineFilePart[];
+/** The modality a media type implies, as Hue's reader names it. */
+export declare function modalityOf(mediaType: string): "image" | "audio" | "video" | "document" | "file";
+/** 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 declare 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 declare function readerParses(value: unknown): boolean;
+/** The files a recorded value holds, the box holding the value (so a whole-string file at its
+ * root can be replaced), the JSON-encoded strings the walk read, innermost first, to write again
+ * once a file inside one is placed, and the value's own JSON text when it was read from text. */
+export interface MediaValue {
+    box: {
+        value: unknown;
+    };
+    files: InlineFilePart[];
+    encoded: EncodedValue[];
+    /** The value's JSON text as recorded, edited in place when its files are placed. */
+    source?: string;
+    document: MediaDocument;
+}
+/**
+ * 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 declare function mediaIn(value: unknown, source?: string): MediaValue;
+/**
+ * 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 declare function readMediaText(key: string, text: string): MediaValue | 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 declare function placedMediaText(media: MediaValue): string;
+/** Each JSON-encoded string a placed file sits in, written again, innermost first: the string as
+ * recorded with only its placed files changed. */
+export declare function reencodeMedia(media: MediaValue): void;
+/** Whether a found file has bytes to place: nonempty, and a whole string's `data:` URL decodes. */
+export declare function placeable(file: InlineFilePart, decoded: InlineFileBytes): boolean;
+/** 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 declare function keepsPrefix(file: InlineFilePart, textual: boolean, decoded: InlineFileBytes): boolean;
+/** 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 declare function mediaBytes(file: InlineFilePart): InlineFileBytes;
 export declare function mediaContentType(file: InlineFilePart, decoded: InlineFileBytes): string;
 export interface FileDigest {
@@ -57,10 +163,36 @@ export declare class MediaDigestMemo {
     digest(file: InlineFilePart, decoded?: InlineFileBytes, traceId?: string): FileDigest;
     bytes(bytes: Uint8Array, traceId: string): FileDigest;
 }
-/** Digest placement removes only the leaf and adds identity to the provider part. */
+/** 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 declare function digestPart(file: InlineFilePart, digest: FileDigest): void;
+/** Prefix placement keeps the first 16 KiB of a text file's content in place. */
+export declare function prefixPart(file: InlineFilePart, prefix: string): void;
+/**
+ * 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 declare function hashInlineFiles(key: string, value: unknown, count?: {
     files: number;
-}, memo?: MediaDigestMemo, traceId?: string): unknown;
+}, memo?: MediaDigestMemo, traceId?: string, anyKey?: boolean): unknown;
 /** Nested message attributes retain small media and digest larger media without upload state. */
-export declare function hashNestedInlineFiles(key: string, value: unknown): unknown;
+export declare function hashNestedInlineFiles(key: string, value: unknown, count?: {
+    files: number;
+}): unknown;
+/**
+ * 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 declare function digestMedia(media: MediaValue, nested: boolean, count?: {
+    files: number;
+}, memo?: MediaDigestMemo, traceId?: string): boolean;
+/**
+ * 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 declare function digestFormBytes(value: unknown): number;