@hue-run/sdk 0.18.1 → 0.19.0

package/dist/cli/langfuse.d.ts

@@ -86,12 +86,15 @@ export declare function readObservation(value: unknown): LangfuseObservation | u
 /** A v1 trace from an API answer, or undefined when it lacks an id or timestamp. */
 export declare function readTrace(value: unknown): LangfuseTrace | undefined;
 /** An answer read whole: its status and body, or `tooLarge` for a body past the bound. */
-type Answer = {
+type Answer = ({
     status: number;
     body: Buffer;
 } | {
     status: number;
     tooLarge: true;
+}) & {
+    /** A redirect's `Location`, which no request follows itself. */
+    location?: string;
 };
 /** Reads one Langfuse project through its public API with Basic authentication. */
 export declare class LangfuseApi {
@@ -105,9 +108,10 @@ export declare class LangfuseApi {
     /**
      * One GET with retries: a rate limit (HTTP 429) is waited out for as long as its `Retry-After`
      * asks (up to 15 minutes, ten times in a row), and a connection failure, a timeout or a 5xx is
-     * tried again after 1, 2, 4, 8 and 16 seconds (or its `Retry-After`, up to a minute). An
-     * authenticated request never follows a redirect, so the keys go only to the configured host;
-     * `authenticated` is false for a presigned media download, which carries no Langfuse keys.
+     * tried again after 1, 2, 4, 8 and 16 seconds (or its `Retry-After`, up to a minute). No
+     * redirect is followed (its `Location` is answered), so the keys go only to the configured host
+     * and a media download reaches only links {@link LangfuseApi.media} checked; `authenticated` is
+     * false for a presigned media download, which carries no Langfuse keys.
      */
     get(url: URL, authenticated?: boolean, maxBytes?: number, timeoutMs?: number): Promise<Answer>;
     /** A GET of `path` under the API, answered with JSON; refusals of the keys are fatal. */
@@ -131,10 +135,22 @@ export declare class LangfuseApi {
     /**
      * A media file's bytes through `GET /api/public/media/{id}` and the download link it answers
      * (fetched without the Langfuse keys): `missing` when Langfuse holds no bytes for it (no record,
-     * no link, or a link whose object is gone), `tooLarge` past {@link MAX_FILE_DATA_BYTES}.
+     * no link, or a link whose object is gone), `tooLarge` past {@link MAX_FILE_DATA_BYTES}. The link
+     * and each redirect from it must pass {@link refusedDownload}; one that does not fails the file.
      */
     media(id: string): Promise<Uint8Array | "missing" | "tooLarge">;
 }
+/** Whether an IP address is one {@link INTERNAL_ADDRESSES} holds; false for anything else. */
+export declare function isInternalAddress(address: string): boolean;
+/**
+ * Why a media download link is refused, or undefined when it may be fetched: it must be HTTPS
+ * (plain HTTP only to this machine), at most 8192 characters, without credentials or a fragment,
+ * and name a host whose every address is public, unless it names the configured Langfuse host or
+ * that host is on this machine. Langfuse chooses the link, so this keeps a hostile or compromised
+ * deployment from sending requests to this machine's network. The name's lookup gives up after a
+ * minute or once `signal` stops the import.
+ */
+export declare function refusedDownload(url: URL, langfuse: URL, signal: AbortSignal): Promise<string | undefined>;
 /** The OpenTelemetry trace id of a Langfuse trace: its own id when it is one (32 lowercase hex
  * digits, as the Langfuse OpenTelemetry SDKs write), otherwise one derived from it by SHA-256, so
  * the same trace always takes the same id. */

package/dist/cli/langfuse.js

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
+import { lookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
 import { SpanKind, SpanStatusCode, TraceFlags, } from "@opentelemetry/api";
-import { MAX_CONTENT_BYTES, MAX_FILE_DATA_BYTES } from "../config.js";
+import { MAX_CONTENT_BYTES, MAX_FILE_DATA_BYTES, isLoopbackHost } from "../config.js";
 import { BLOBS_KEY, MAX_BLOB_ENTRIES, blobEntry, newTally, offloadAttributes, } from "../blobs.js";
 import { digestPart, isMediaContentType, mayInlineFiles, mediaIn, placedMediaText, readerParses, } from "../inline-files.js";
 import { sdkVersion } from "../version.js";
@@ -16,6 +18,10 @@ import { sdkVersion } from "../version.js";
 const REQUEST_TIMEOUT_MS = 60_000;
 /** A media file download's deadline: up to 25 MiB over a slow link. */
 const DOWNLOAD_TIMEOUT_MS = 300_000;
+/** Redirects a media download follows, each to a link checked as the first one was. */
+const MAX_DOWNLOAD_REDIRECTS = 5;
+/** The longest media download link accepted, as the Python SDK's media client accepts. */
+const MAX_LINK_LENGTH = 8192;
 /** The largest answer read from the API. Langfuse Cloud answers at most 5 MB; a larger answer is
  * asked for again in smaller pages. */
 const MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
@@ -210,9 +216,10 @@ export class LangfuseApi {
     /**
      * One GET with retries: a rate limit (HTTP 429) is waited out for as long as its `Retry-After`
      * asks (up to 15 minutes, ten times in a row), and a connection failure, a timeout or a 5xx is
-     * tried again after 1, 2, 4, 8 and 16 seconds (or its `Retry-After`, up to a minute). An
-     * authenticated request never follows a redirect, so the keys go only to the configured host;
-     * `authenticated` is false for a presigned media download, which carries no Langfuse keys.
+     * tried again after 1, 2, 4, 8 and 16 seconds (or its `Retry-After`, up to a minute). No
+     * redirect is followed (its `Location` is answered), so the keys go only to the configured host
+     * and a media download reaches only links {@link LangfuseApi.media} checked; `authenticated` is
+     * false for a presigned media download, which carries no Langfuse keys.
      */
     async get(url, authenticated = true, maxBytes = MAX_RESPONSE_BYTES, timeoutMs = REQUEST_TIMEOUT_MS) {
         let failures = 0;
@@ -227,9 +234,7 @@ export class LangfuseApi {
                         "user-agent": `hue-sdk-typescript/${sdkVersion} hue-import`,
                         ...(authenticated ? { authorization: this.authorization } : {}),
                     },
-                    // The keys go only to the configured host; a presigned download carries none and may
-                    // be redirected by its store.
-                    redirect: authenticated ? "manual" : "follow",
+                    redirect: "manual",
                     signal: AbortSignal.any([this.connection.signal, AbortSignal.timeout(timeoutMs)]),
                 });
             }
@@ -258,6 +263,11 @@ export class LangfuseApi {
                 failures++;
                 continue;
             }
+            const location = status >= 300 && status < 400 ? response.headers.get("location") : null;
+            if (location !== null) {
+                await response.body?.cancel().catch(() => undefined);
+                return { status, body: Buffer.alloc(0), location };
+            }
             let body;
             try {
                 body = await readBounded(response, maxBytes);
@@ -478,7 +488,8 @@ export class LangfuseApi {
     /**
      * A media file's bytes through `GET /api/public/media/{id}` and the download link it answers
      * (fetched without the Langfuse keys): `missing` when Langfuse holds no bytes for it (no record,
-     * no link, or a link whose object is gone), `tooLarge` past {@link MAX_FILE_DATA_BYTES}.
+     * no link, or a link whose object is gone), `tooLarge` past {@link MAX_FILE_DATA_BYTES}. The link
+     * and each redirect from it must pass {@link refusedDownload}; one that does not fails the file.
      */
     async media(id) {
         const answer = await this.json(`/api/public/media/${encodeURIComponent(id)}`, {});
@@ -499,16 +510,112 @@ export class LangfuseApi {
         }
         if (url.protocol !== "https:" && url.protocol !== "http:")
             return "missing";
-        const download = await this.get(url, false, MAX_FILE_DATA_BYTES, DOWNLOAD_TIMEOUT_MS);
-        if ("tooLarge" in download)
-            return download.status === 200 ? "tooLarge" : "missing";
-        if (download.status === 200)
-            return new Uint8Array(download.body);
-        if ([403, 404, 410].includes(download.status))
-            return "missing";
-        throw new LangfuseError(`The media download answered HTTP ${download.status}`);
+        const langfuse = new URL(this.connection.baseUrl);
+        for (let redirects = 0;; redirects++) {
+            const refused = await refusedDownload(url, langfuse, this.connection.signal);
+            this.stopped();
+            if (refused)
+                throw new LangfuseError(`Langfuse named a media download link that ${refused}`);
+            const download = await this.get(url, false, MAX_FILE_DATA_BYTES, DOWNLOAD_TIMEOUT_MS);
+            if (download.location !== undefined) {
+                if (redirects === MAX_DOWNLOAD_REDIRECTS)
+                    throw new LangfuseError("The media download redirected too many times");
+                try {
+                    url = new URL(download.location, url);
+                }
+                catch {
+                    throw new LangfuseError("The media download redirected to something other than a URL");
+                }
+                continue;
+            }
+            if ("tooLarge" in download)
+                return download.status === 200 ? "tooLarge" : "missing";
+            if (download.status === 200)
+                return new Uint8Array(download.body);
+            if ([403, 404, 410].includes(download.status))
+                return "missing";
+            throw new LangfuseError(`The media download answered HTTP ${download.status}`);
+        }
     }
 }
+/** Addresses a media download may not reach: this machine, private networks, link-local
+ * (cloud metadata), shared, benchmarking, multicast and reserved ranges. IPv4-mapped IPv6
+ * addresses are checked as their IPv4 address. */
+const INTERNAL_ADDRESSES = new BlockList();
+for (const [network, prefix] of [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["224.0.0.0", 3],
+])
+    INTERNAL_ADDRESSES.addSubnet(network, prefix, "ipv4");
+for (const [network, prefix] of [
+    ["::", 128],
+    ["::1", 128],
+    ["64:ff9b::", 96],
+    ["fc00::", 7],
+    ["fe80::", 10],
+    ["fec0::", 10],
+    ["ff00::", 8],
+])
+    INTERNAL_ADDRESSES.addSubnet(network, prefix, "ipv6");
+/** Whether an IP address is one {@link INTERNAL_ADDRESSES} holds; false for anything else. */
+export function isInternalAddress(address) {
+    const version = isIP(address);
+    return version !== 0 && INTERNAL_ADDRESSES.check(address, version === 4 ? "ipv4" : "ipv6");
+}
+/**
+ * Why a media download link is refused, or undefined when it may be fetched: it must be HTTPS
+ * (plain HTTP only to this machine), at most 8192 characters, without credentials or a fragment,
+ * and name a host whose every address is public, unless it names the configured Langfuse host or
+ * that host is on this machine. Langfuse chooses the link, so this keeps a hostile or compromised
+ * deployment from sending requests to this machine's network. The name's lookup gives up after a
+ * minute or once `signal` stops the import.
+ */
+export async function refusedDownload(url, langfuse, signal) {
+    if (url.href.length > MAX_LINK_LENGTH)
+        return "is too long";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname)))
+        return "does not use https";
+    if (url.username || url.password || url.hash)
+        return "carries credentials or a fragment";
+    if (isLoopbackHost(langfuse.hostname) || url.hostname === langfuse.hostname)
+        return undefined;
+    const host = url.hostname.replace(/^\[|\]$/gu, "");
+    const named = host === "localhost" || host.endsWith(".localhost");
+    // shortcut: the name is resolved apart from the request's own lookup, so a host that answers a
+    // second lookup differently (DNS rebinding) is not caught; pin the lookup if fetch gains a hook.
+    let addresses;
+    try {
+        addresses =
+            named || isIP(host)
+                ? [named ? "127.0.0.1" : host]
+                : await resolved(host, AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]));
+    }
+    catch {
+        return "names a host that could not be resolved";
+    }
+    if (addresses.length === 0 || addresses.some(isInternalAddress))
+        return "names an address on this machine or a private network";
+    return undefined;
+}
+/** Every address `host` resolves to; rejects once `signal` aborts, since a lookup cannot be
+ * cancelled. */
+function resolved(host, signal) {
+    return new Promise((resolve, reject) => {
+        const stop = () => reject(new Error("The lookup was abandoned"));
+        if (signal.aborted)
+            return stop();
+        signal.addEventListener("abort", stop, { once: true });
+        lookup(host, { all: true }).then((entries) => resolve(entries.map((entry) => entry.address)), reject);
+    });
+}
 // ---------------------------------------------------------------------------------------------
 // Conversion
 // ---------------------------------------------------------------------------------------------

package/dist/client.d.ts

@@ -51,8 +51,9 @@ export declare class HueClient {
     private ownedProviders?;
     private closed;
     private shutdownPromise?;
-    private flushPromise?;
-    private safeFlushPromise?;
+    /** The latest flush while it still sends its records (`sent`, which the next flush's send
+     * follows), and the safe result that joined it. */
+    private sending?;
     private safeShutdownPromise?;
     constructor(options: HueOptions | ExistingHueProviders);
     /**
@@ -166,10 +167,15 @@ export declare class HueClient {
     /**
      * Adds a `hue.file` event to the active (or given) span for a file the work read, received or
      * produced: `hue.file.sha256`, `hue.file.role`, `hue.file.media_type`, `hue.file.size` when known
-     * and, when `captureContent` is true, `hue.file.name`. `data` is hashed and measured locally and
-     * uploaded only with `upload: true`. The event is metadata, so it is recorded in both capture modes. An invalid
-     * record, or one without an active span, is omitted and counted, never thrown; an invalid name
-     * alone is omitted and counted while the rest is recorded.
+     * and, when `captureContent` is true, `hue.file.name`. `data` or the file at `path` is hashed and
+     * measured locally and uploaded only with `upload: true`: `data` and a file up to 25 MiB are
+     * held in memory until then, while a larger regular file, up to Hue's 1 GB upload limit, is
+     * hashed a slice at a time and read again from disk when it is uploaded, and is uploaded only if
+     * it still has the size and SHA-256 it was recorded with; a `path` that is no regular file, such
+     * as a named pipe, is refused without waiting on it. The event is metadata, so it is
+     * recorded in both capture modes. An invalid record, or one without an active span, is omitted
+     * and counted, never thrown; an invalid name alone is omitted and counted while the rest is
+     * recorded.
      */
     recordFile(file: FileRecord, explicitContext?: Context): void;
     /** The keys of each span's content values that were cut to Hue's value cap, for `hue.truncated`. */
@@ -201,22 +207,25 @@ export declare class HueClient {
     /**
      * Safe for finally blocks; preserves the application's result or original exception. When its
      * budget runs out while the client's own transport holds records for a receiver that limited
-     * the rate, the hold ends: those records are reported lost to the rate limit, and the hold no
-     * longer keeps the process running.
+     * the rate, or still uploads values its records listed, the hold and the uploads end: those
+     * records are reported lost to the rate limit, the uploads counted as failed (their records keep
+     * their entries), and neither keeps the process running.
      */
     shutdownSafe(options?: SafeLifecycleOptions): Promise<SafeLifecycleResult>;
     private safeLifecycle;
     /**
-     * Drains the trace and log providers and waits for Hue's acknowledgements. Each caller gets a
-     * fresh serialized drain that includes records emitted before its call.
+     * Drains the trace and log providers and waits for Hue's acknowledgements, then for the uploads
+     * queued so far. Each caller gets a fresh drain that includes records emitted before its call;
+     * its records are sent after an earlier drain's records, never after that drain's uploads.
      *
      * @throws HueExportError when this drain observed a new rejection, delivery failure, drop or
      * invalid record; its `issues` and `report` are sanitized counts, never server text.
      */
     flush(): Promise<ExportReport>;
-    private flushOnce;
+    private flushProviders;
     /**
      * Flushes, then shuts down the providers this client owns; borrowed providers are left running.
+     * Like {@link flush}, it waits for queued uploads after the records are sent.
      * Idempotent: later calls return the same promise, and later helper calls only run their callbacks.
      *
      * @throws HueExportError when the final flush observed new failures; owned providers are still released.

package/dist/client.js

@@ -13,8 +13,8 @@ import { hostedServerAddresses, hostedToolActivity, hostedToolProvider, provider
 import { toolCatalogSummary } from "./tool-definitions.js";
 import { contentLimitsOf, encodeBoundedContent, encodeContent, noopSpan, safeSpan, spanSource, } from "./safety.js";
 import { TRUNCATED_KEY, withTruncatedKeys } from "./privacy.js";
-import { countFallback, MAX_BLOB_BYTES, newTally } from "./blobs.js";
-import { attachmentPart, attachmentState, holdsAttachment, MAX_ATTACHMENT_DEPTH, } from "./attachment.js";
+import { countFallback, MAX_BLOB_BYTES, newTally, sizeOf } from "./blobs.js";
+import { attachmentPart, attachmentState, fileSource, holdsAttachment, MAX_ATTACHMENT_DEPTH, readPath, } from "./attachment.js";
 import { createHueTransport, exportBudgetMillis, HueExportError, } from "./transport.js";
 import { verifyTrace } from "./receipt.js";
 import { sdkVersion } from "./version.js";
@@ -219,8 +219,9 @@ export class HueClient {
     ownedProviders;
     closed = false;
     shutdownPromise;
-    flushPromise;
-    safeFlushPromise;
+    /** The latest flush while it still sends its records (`sent`, which the next flush's send
+     * follows), and the safe result that joined it. */
+    sending;
     safeShutdownPromise;
     constructor(options) {
         if ("transport" in options) {
@@ -611,21 +612,22 @@ export class HueClient {
         const files = [];
         const tally = newTally();
         for (const { state, part, depth } of placed) {
-            if (!part || !state.bytes || !state.sha256) {
+            if (!part || state.size === undefined || !state.sha256) {
                 this.instrumentationFailed(signal);
                 continue;
             }
             if (state.invalidName && captureContent)
                 this.instrumentationFailed(signal);
-            if (!this.transport.offloadsValues() || !state.bytes.byteLength)
+            if (!this.transport.offloadsValues() || !state.size)
                 continue;
             if (cut || depth > MAX_ATTACHMENT_DEPTH) {
                 countFallback(tally, "budget", traceId);
                 continue;
             }
             files.push({
-                bytes: state.bytes,
-                digest: { sha256: state.sha256, size: state.bytes.byteLength },
+                // A file given by path over 25 MiB is read again from disk when it is uploaded.
+                bytes: state.file ? fileSource(state.file) : state.bytes,
+                digest: { sha256: state.sha256, size: state.size },
                 contentType: state.contentType,
                 ...(state.name === undefined ? {} : { name: state.name }),
             });
@@ -788,10 +790,15 @@ export class HueClient {
     /**
      * Adds a `hue.file` event to the active (or given) span for a file the work read, received or
      * produced: `hue.file.sha256`, `hue.file.role`, `hue.file.media_type`, `hue.file.size` when known
-     * and, when `captureContent` is true, `hue.file.name`. `data` is hashed and measured locally and
-     * uploaded only with `upload: true`. The event is metadata, so it is recorded in both capture modes. An invalid
-     * record, or one without an active span, is omitted and counted, never thrown; an invalid name
-     * alone is omitted and counted while the rest is recorded.
+     * and, when `captureContent` is true, `hue.file.name`. `data` or the file at `path` is hashed and
+     * measured locally and uploaded only with `upload: true`: `data` and a file up to 25 MiB are
+     * held in memory until then, while a larger regular file, up to Hue's 1 GB upload limit, is
+     * hashed a slice at a time and read again from disk when it is uploaded, and is uploaded only if
+     * it still has the size and SHA-256 it was recorded with; a `path` that is no regular file, such
+     * as a named pipe, is refused without waiting on it. The event is metadata, so it is
+     * recorded in both capture modes. An invalid record, or one without an active span, is omitted
+     * and counted, never thrown; an invalid name alone is omitted and counted while the rest is
+     * recorded.
      */
     recordFile(file, explicitContext) {
         if (!this.enabled || this.closed)
@@ -800,7 +807,7 @@ export class HueClient {
             const span = trace.getSpan(explicitContext ?? this.storage.getStore()?.context ?? context.active());
             if (!span?.isRecording())
                 throw new Error("File records require an active span");
-            const { role, mediaType, data, name } = file;
+            const { role, mediaType, data, name, path } = file;
             if (role !== "input" && role !== "attachment" && role !== "output")
                 throw new TypeError("Invalid file role");
             if (!isLabel(mediaType))
@@ -808,7 +815,31 @@ export class HueClient {
             let sha256 = typeof file.sha256 === "string" ? file.sha256.toLowerCase() : file.sha256;
             let byteSize = file.byteSize;
             let bytes;
-            if (data !== undefined) {
+            // A file given by path over 25 MiB: hashed now and read again from disk when it is uploaded.
+            let onDisk;
+            let given = data;
+            if (path !== undefined) {
+                if (data !== undefined)
+                    throw new TypeError("A file takes data or a path, not both");
+                if (typeof path !== "string" || !path)
+                    throw new TypeError("Invalid file path");
+                const read = readPath(path);
+                if (!read)
+                    throw new RangeError("File must be a regular file within Hue's 1 GB upload limit");
+                if ("bytes" in read)
+                    given = read.bytes;
+                else {
+                    onDisk = read.file;
+                    // A caller-supplied digest or size must describe the same bytes.
+                    if ((sha256 !== undefined && sha256 !== onDisk.sha256) ||
+                        (byteSize !== undefined && byteSize !== onDisk.size))
+                        throw new TypeError("File digest or size does not match its data");
+                    sha256 = onDisk.sha256;
+                    byteSize = onDisk.size;
+                }
+            }
+            if (given !== undefined) {
+                const data = given;
                 bytes =
                     typeof data === "string"
                         ? (() => {
@@ -888,10 +919,11 @@ export class HueClient {
             if (eventTime)
                 this.fileEventTimes.set(source, eventTime);
             if (file.upload === true && this.transport.offloadsValues()) {
-                if (!this.transport.stageMedia(span, bytes && eventTime
+                const upload = bytes ?? (onDisk ? fileSource(onDisk) : undefined);
+                if (!this.transport.stageMedia(span, upload && eventTime
                     ? {
-                        bytes,
-                        digest: { sha256, size: bytes.byteLength },
+                        bytes: upload,
+                        digest: { sha256, size: sizeOf(upload) },
                         contentType: mediaType,
                         eventTime,
                         ...(isMediaName(name) ? { name } : {}),
@@ -1034,24 +1066,25 @@ export class HueClient {
     }
     /** Production lifecycle path: never rejects; timeouts do not cancel borrowed provider work. */
     flushSafe(options = {}) {
-        if (this.safeFlushPromise)
-            return this.safeFlushPromise;
-        const work = this.flushPromise ?? this.flush();
+        // A flush still sending its records is joined, so repeated timeouts do not accumulate
+        // promises against a hung borrowed provider. Once it sent them, a new flush sends the
+        // caller's own records instead of waiting on the earlier flush's uploads.
+        if (this.sending?.safe)
+            return this.sending.safe;
+        const work = this.sending?.work ?? this.flush();
+        // An invalid budget returns before the result awaits the flush: its failure is still handled.
+        void work.catch(() => { });
         const result = this.safeLifecycle(() => work, options);
-        this.safeFlushPromise = result;
-        const clear = () => {
-            this.safeFlushPromise = undefined;
-        };
-        // Retain the timed-out result until its underlying drain settles. Repeated
-        // timeouts must not accumulate promises against a hung borrowed provider.
-        void work.then(clear, clear);
+        if (this.sending?.work === work)
+            this.sending.safe = result;
         return result;
     }
     /**
      * Safe for finally blocks; preserves the application's result or original exception. When its
      * budget runs out while the client's own transport holds records for a receiver that limited
-     * the rate, the hold ends: those records are reported lost to the rate limit, and the hold no
-     * longer keeps the process running.
+     * the rate, or still uploads values its records listed, the hold and the uploads end: those
+     * records are reported lost to the rate limit, the uploads counted as failed (their records keep
+     * their entries), and neither keeps the process running.
      */
     shutdownSafe(options = {}) {
         if (this.safeShutdownPromise)
@@ -1099,8 +1132,9 @@ export class HueClient {
         }
     }
     /**
-     * Drains the trace and log providers and waits for Hue's acknowledgements. Each caller gets a
-     * fresh serialized drain that includes records emitted before its call.
+     * Drains the trace and log providers and waits for Hue's acknowledgements, then for the uploads
+     * queued so far. Each caller gets a fresh drain that includes records emitted before its call;
+     * its records are sent after an earlier drain's records, never after that drain's uploads.
      *
      * @throws HueExportError when this drain observed a new rejection, delivery failure, drop or
      * invalid record; its `issues` and `report` are sanitized counts, never server text.
@@ -1108,25 +1142,31 @@ export class HueClient {
     flush() {
         // Each caller needs a drain after its own preceding span/log emissions.
         // Joining an earlier drain can acknowledge records that were not in its batch.
+        // Only the sends are serialized: each flush then waits on its own for the uploads queued so
+        // far, so a later flush's records never wait behind an earlier flush's uploads.
         const from = this.transport.getFailureSequence();
-        const drain = async () => {
-            const report = await this.flushOnce();
+        const start = () => this.transport.flushRecords(() => this.flushProviders());
+        const flushing = (this.sending?.sent ?? Promise.resolve()).then(start, start);
+        const sent = flushing.then(({ sent }) => sent);
+        const next = flushing
+            .then(({ report }) => report)
+            .then((report) => {
             if (this.transport.getFailureSequence() !== from)
                 throw new HueExportError(this.transport
                     .getIssues()
                     .filter((issue) => issue.sequence > from && issue.kind !== "warning"), report);
             return report;
-        };
-        const next = (this.flushPromise ?? Promise.resolve()).then(drain, drain);
-        this.flushPromise = next;
+        });
+        const sending = { work: next, sent };
+        this.sending = sending;
         const clear = () => {
-            if (this.flushPromise === next)
-                this.flushPromise = undefined;
+            if (this.sending === sending)
+                this.sending = undefined;
         };
-        void next.then(clear, clear);
+        void sent.then(clear, clear);
         return next;
     }
-    async flushOnce() {
+    async flushProviders() {
         // Providers this client owns wait as long as an export may take, a rate-limit hold included,
         // instead of OpenTelemetry's 30 s; borrowed providers keep their own budget.
         const owned = this.ownedProviders;
@@ -1138,10 +1178,10 @@ export class HueClient {
         for (const [index, result] of results.entries())
             if (result.status === "rejected")
                 this.transport.issue(index === 0 ? "traces" : "logs", "failed", 0, "OpenTelemetry provider flush failed");
-        return this.transport.flush();
     }
     /**
      * Flushes, then shuts down the providers this client owns; borrowed providers are left running.
+     * Like {@link flush}, it waits for queued uploads after the records are sent.
      * Idempotent: later calls return the same promise, and later helper calls only run their callbacks.
      *
      * @throws HueExportError when the final flush observed new failures; owned providers are still released.

package/dist/inline-files.d.ts

@@ -137,20 +137,21 @@ 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 a found file has bytes to place: nonempty (`size` bytes), and a whole string's `data:`
+ * URL decodes. */
+export declare function placeable(file: InlineFilePart, decoded: Pick<InlineFileBytes, "decoded">, size: number): 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;
+export declare function keepsPrefix(file: InlineFilePart, textual: boolean, decoded: Pick<InlineFileBytes, "bareBase64">): 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 declare function mediaContentType(file: InlineFilePart, decoded: Pick<InlineFileBytes, "decoded" | "urlMediaType">): string;
 export interface FileDigest {
     sha256: string;
     size: number;

package/dist/inline-files.js

@@ -707,9 +707,10 @@ export function reencodeMedia(media) {
         });
     }
 }
-/** 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 a found file has bytes to place: nonempty (`size` bytes), and a whole string's `data:`
+ * URL decodes. */
+export function placeable(file, decoded, size) {
+    return size > 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
@@ -841,7 +842,7 @@ 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))
+        if (!placeable(file, decoded, decoded.bytes.byteLength))
             continue;
         if ((nested || isTextMediaType(mediaContentType(file, decoded))) &&
             decoded.bytes.byteLength <= INLINE_FILE_LIMIT)
@@ -875,7 +876,7 @@ export function digestFormBytes(value) {
             continue;
         inspected += units;
         const decoded = mediaBytes(file);
-        if (!placeable(file, decoded))
+        if (!placeable(file, decoded, decoded.bytes.byteLength))
             continue;
         if (isTextMediaType(mediaContentType(file, decoded)) &&
             decoded.bytes.byteLength <= INLINE_FILE_LIMIT)