@hue-run/sdk 0.18.2 → 0.19.1

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);
     /**
@@ -206,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

@@ -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) {
@@ -1065,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)
@@ -1130,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.
@@ -1139,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;
@@ -1169,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

@@ -21,6 +21,19 @@ 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;
+/**
+ * The canonical media type of raw 16-bit PCM whose type declares its format, as Hue's reader reads
+ * one and names it: `audio/pcm;rate=<Hz>;channels=<n>` for little-endian `audio/pcm` and
+ * `audio/x-pcm`, `audio/L16;rate=<Hz>;channels=<n>` for big-endian `audio/L16`, `rate` a whole
+ * 8000 to 192000 and `channels` 1 or 2 (1 when absent). Undefined for any other type, raw PCM
+ * without a rate or with any other parameter included: Hue plays raw PCM only in a format its
+ * type declares.
+ */
+export declare function pcmMediaType(mediaType: string): string | undefined;
+/** The media type a `data:` URL's header (between `data:` and its comma) gives its file: raw PCM
+ * whose parameters declare its format as its canonical type (`pcmMediaType`), any other type
+ * without its parameters. Empty when the header names no type. */
+export declare function headerMediaType(header: string): string;
 /** 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 {
@@ -124,10 +137,12 @@ export interface MediaValue {
 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.
+ * convention, text that does not parse as the text itself (a Langfuse SDK records a string input
+ * or output as it is, so a whole `data:` URL is a file); 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 metadata or parts JSON that does
+ * not parse.
  */
 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
@@ -151,6 +166,8 @@ export declare function keepsPrefix(file: InlineFilePart, textual: boolean, deco
  * `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;
+/** The type a file is reserved and listed under: the type its part declares, else its `data:`
+ * URL's, raw PCM whose type declares its format in its canonical form (`pcmMediaType`). */
 export declare function mediaContentType(file: InlineFilePart, decoded: Pick<InlineFileBytes, "decoded" | "urlMediaType">): string;
 export interface FileDigest {
     sha256: string;

package/dist/inline-files.js

@@ -102,6 +102,74 @@ function base64Header(header) {
     return semicolon !== -1 && `${header.slice(semicolon)};`.includes(";base64;");
 }
 const hexPair = /^[0-9A-Fa-f]{2}$/;
+/** Raw 16-bit PCM media types and the byte order of their samples, as Hue's reader names them. */
+const pcmEndian = new Map([
+    ["audio/l16", "big"],
+    ["audio/pcm", "little"],
+    ["audio/x-pcm", "little"],
+]);
+/** One media type parameter (`name=value`, the value a token or a quoted string) or an empty one,
+ * then the `;` that ends it or the end of the type (RFC 9110 section 8.3.1). */
+const pcmParameter = /[ \t]*(?:([!#$%&'*+.^_`|~0-9A-Za-z-]+)[ \t]*=[ \t]*([!#$%&'*+.^_`|~0-9A-Za-z-]+|"(?:[^"\\]|\\.)*")[ \t]*)?(;|$)/y;
+/** A whole number written in decimal digits alone, within `[min, max]`. */
+function wholeIn(value, min, max) {
+    if (value === undefined || !/^\d{1,7}$/.test(value))
+        return undefined;
+    const number = Number(value);
+    return number >= min && number <= max ? number : undefined;
+}
+/**
+ * The canonical media type of raw 16-bit PCM whose type declares its format, as Hue's reader reads
+ * one and names it: `audio/pcm;rate=<Hz>;channels=<n>` for little-endian `audio/pcm` and
+ * `audio/x-pcm`, `audio/L16;rate=<Hz>;channels=<n>` for big-endian `audio/L16`, `rate` a whole
+ * 8000 to 192000 and `channels` 1 or 2 (1 when absent). Undefined for any other type, raw PCM
+ * without a rate or with any other parameter included: Hue plays raw PCM only in a format its
+ * type declares.
+ */
+export function pcmMediaType(mediaType) {
+    if (mediaType.length > 255)
+        return undefined;
+    const endian = pcmEndian.get(mediaType.split(";", 1)[0].trim().toLowerCase());
+    if (!endian)
+        return undefined;
+    const parameters = new Map();
+    const start = mediaType.indexOf(";");
+    if (start !== -1) {
+        pcmParameter.lastIndex = start + 1;
+        for (;;) {
+            const match = pcmParameter.exec(mediaType);
+            if (!match)
+                return undefined;
+            if (match[1] !== undefined) {
+                const name = match[1].toLowerCase();
+                if (parameters.has(name))
+                    return undefined;
+                const value = match[2];
+                parameters.set(name, value.startsWith('"') ? value.slice(1, -1).replace(/\\(.)/g, "$1") : value);
+            }
+            if (match[3] === "")
+                break;
+        }
+    }
+    for (const name of parameters.keys())
+        if (name !== "rate" && name !== "channels")
+            return undefined;
+    const rate = wholeIn(parameters.get("rate"), 8_000, 192_000);
+    const channels = parameters.has("channels") ? wholeIn(parameters.get("channels"), 1, 2) : 1;
+    if (rate === undefined || channels === undefined)
+        return undefined;
+    return `${endian === "big" ? "audio/L16" : "audio/pcm"};rate=${rate};channels=${channels}`;
+}
+/** The media type a `data:` URL's header (between `data:` and its comma) gives its file: raw PCM
+ * whose parameters declare its format as its canonical type (`pcmMediaType`), any other type
+ * without its parameters. Empty when the header names no type. */
+export function headerMediaType(header) {
+    const type = header.split(";", 1)[0].trim();
+    if (!type)
+        return type;
+    const declared = header.endsWith(";base64") ? header.slice(0, -";base64".length) : header;
+    return pcmMediaType(declared) ?? type;
+}
 /** RFC 2397 data without `;base64`: percent-escaped octets, other characters as UTF-8. Undefined
  * when a `%` does not start an escape. */
 function percentDecoded(payload) {
@@ -135,7 +203,7 @@ export function inlineFileBytes(content) {
             ? Buffer.from(payload, "base64")
             : undefined;
     const header = url?.[1];
-    const mediaType = header === undefined ? undefined : header.split(";")[0].trim();
+    const mediaType = header === undefined ? undefined : headerMediaType(header);
     return {
         bytes: decoded ?? Buffer.from(content, "utf8"),
         decoded: decoded !== undefined,
@@ -143,6 +211,8 @@ export function inlineFileBytes(content) {
         ...(decoded !== undefined && !url ? { bareBase64: true } : {}),
     };
 }
+/** OpenAI's `pcm16` audio: raw 16-bit little-endian PCM, 24 kHz mono, as Hue's reader types it. */
+const PCM16 = "audio/pcm;rate=24000;channels=1";
 const audioTypes = {
     wav: "audio/wav",
     mp3: "audio/mpeg",
@@ -152,7 +222,7 @@ const audioTypes = {
     aac: "audio/aac",
     m4a: "audio/mp4",
     webm: "audio/webm",
-    pcm16: "audio/pcm",
+    pcm16: PCM16,
 };
 const documentTypes = {
     pdf: "application/pdf",
@@ -342,16 +412,18 @@ export function contentPath(part, pointer = "") {
 }
 /** A media type as a `data:` URL declares one: `type/subtype`, no parameters. */
 const declaredMediaType = /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9!#$&^_.+-]+$/;
-/** The media type a whole string that is a `data:` URL declares, when it declares one: such a
- * string is a file wherever it sits. A web URL, or any other text, is not. */
+/** The media type of a whole string that is a `data:` URL declaring one (`headerMediaType`): such
+ * a string is a file wherever it sits. A web URL, or any other text, is not. */
 function dataUrlType(text) {
     if (!text.startsWith("data:"))
         return undefined;
     const header = dataUrl.exec(text);
     if (!header)
         return undefined;
-    const type = header[1].split(";")[0].trim();
-    return declaredMediaType.test(type) && isMediaContentType(type) ? type : undefined;
+    const type = header[1].split(";", 1)[0].trim();
+    return declaredMediaType.test(type) && isMediaContentType(type)
+        ? headerMediaType(header[1])
+        : undefined;
 }
 /** The modality a media type implies, as Hue's reader names it. */
 export function modalityOf(mediaType) {
@@ -387,7 +459,7 @@ const audioFormats = {
     m4a: "audio/mp4",
     mp4: "audio/mp4",
     webm: "audio/webm",
-    pcm16: "audio/pcm",
+    pcm16: PCM16,
     pcm: "audio/pcm",
 };
 function audioFormatMediaType(format) {
@@ -654,17 +726,27 @@ export function mediaIn(value, source) {
 }
 /**
  * An attribute's recorded text read for files as Hue's reader reads that attribute: JSON by its
- * convention; metadata as JSON when it reads as an object or array, otherwise as the text itself;
- * an OpenLLMetry content as the parts list it encodes (any other content stays text); an
- * OpenInference image URL as the text itself. Undefined for text that reading finds nothing in.
- * Throws for JSON that does not parse or nests too deep.
+ * convention, text that does not parse as the text itself (a Langfuse SDK records a string input
+ * or output as it is, so a whole `data:` URL is a file); 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 metadata or parts JSON that does
+ * not parse.
  */
 export function readMediaText(key, text) {
     /** JSON text read as Hue's reader reads it: text it keeps as text holds no file. */
     const json = (parsed) => (readerParses(parsed) ? mediaIn(parsed, text) : undefined);
     switch (readingOf(key)) {
-        case "json":
-            return json(JSON.parse(text));
+        case "json": {
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                return mediaIn(text);
+            }
+            return json(parsed);
+        }
         case "metadata":
             return /^\s*[[{]/.test(text) ? json(JSON.parse(text)) : mediaIn(text);
         case "parts": {
@@ -729,8 +811,12 @@ export function mediaBytes(file) {
         return { bytes: Buffer.from(file.content, "base64"), decoded: true };
     return inlineFileBytes(file.content);
 }
+/** The type a file is reserved and listed under: the type its part declares, else its `data:`
+ * URL's, raw PCM whose type declares its format in its canonical form (`pcmMediaType`). */
 export function mediaContentType(file, decoded) {
-    return ((isMediaContentType(file.contentType) ? file.contentType : undefined) ??
+    return ((isMediaContentType(file.contentType)
+        ? (pcmMediaType(file.contentType) ?? file.contentType)
+        : undefined) ??
         (isMediaContentType(decoded.urlMediaType) ? decoded.urlMediaType : undefined) ??
         (decoded.decoded ? "application/octet-stream" : "text/plain; charset=utf-8"));
 }