@hue-run/sdk 0.12.0 → 0.13.0

package/dist/privacy.js

@@ -1,8 +1,10 @@
 import { SpanStatusCode } from "@opentelemetry/api";
 import { resourceFromAttributes } from "@opentelemetry/resources";
-import { MAX_BODY_BYTES, MAX_CONTENT_BYTES } from "./config.js";
+import { MAX_CONTENT_BYTES } from "./config.js";
 import { scrubToolCredentials, withToolCatalogSummary } from "./tool-definitions.js";
 import { hashInlineFiles } from "./inline-files.js";
+import { truncateUtf8 } from "./safety.js";
+export { truncateUtf8 };
 /** Attribute keys (and their dotted children) removed in metadata-only mode. */
 export const contentPrefixes = [
     "gen_ai.input.messages",
@@ -48,56 +50,120 @@ export const contentPrefixes = [
     "ai.embeddings",
     "traceloop.entity.input",
     "traceloop.entity.output",
+    // Langfuse content; its model name, usage, cost, type, session, user and metadata keys stay.
+    "langfuse.observation.input",
+    "langfuse.observation.output",
+    "langfuse.observation.status_message",
+    "langfuse.observation.model.parameters",
+    "langfuse.trace.input",
+    "langfuse.trace.output",
     "tool.parameters",
     "exception.message",
     "exception.stacktrace",
 ];
 // Kept as a function so metadata-only filtering is applied consistently to every exporter location.
-function isContentKey(key) {
+export function isContentKey(key) {
     return contentPrefixes.some((prefix) => key === prefix || key.startsWith(`${prefix}.`));
 }
-function redactValue(value, path, options, budget, depth = 0) {
+/** The record attribute listing the keys whose values were cut to fit Hue's 256 KiB value cap:
+ * Hue's receiver writes it for the values it cuts, and the SDK writes it for the values it cuts
+ * before export, under the same name, so a reader learns of a cut value from one place. */
+export const TRUNCATED_KEY = "hue.truncated";
+/** The size of a structured value the marker replaced. */
+export const TRUNCATED_BYTES_KEY = "hue.truncated_bytes";
+/** The root span attribute counting this trace's records the SDK could not export at all (a
+ * record over the request limit even with every content value shed, or one its queue had no
+ * room for): what Hue stores of the trace is incomplete by that many records. */
+export const DROPPED_RECORDS_KEY = "hue.sdk.dropped_records";
+/** The serialized size of a structured value as recorded, 0 for one JSON cannot serialize. */
+function structuredBytes(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value) ?? "");
+    }
+    catch {
+        return 0;
+    }
+}
+/** Hue's receiver's own marker for a structured value it replaced: nothing of the value, its
+ * size, and the flag a reader tests. */
+export function truncatedMarker(bytes) {
+    return { [TRUNCATED_KEY]: true, [TRUNCATED_BYTES_KEY]: bytes };
+}
+/** `listed` with `keys` added, each once, in order. */
+export function withTruncatedKeys(listed, keys) {
+    const result = Array.isArray(listed)
+        ? listed.filter((item) => typeof item === "string")
+        : [];
+    for (const key of keys)
+        if (!result.includes(key))
+            result.push(key);
+    return result;
+}
+/**
+ * One value through the redactor and Hue's value cap. Text over 256 KiB is cut to a UTF-8 prefix
+ * and bytes over it are replaced by the receiver's marker, as the receiver itself does to a
+ * value over its cap, and the value's key (`listAs`) is listed under `hue.truncated`: the span
+ * is exported whole with the rest of its evidence, and a reader knows the one value is partial.
+ * Dropping the record for a large value lost every call, result and reply it recorded.
+ */
+function redactValue(value, path, options, budget, depth = 0, listAs = path) {
     if (++budget.nodes > 16384 || depth > 32)
         throw new Error("Telemetry value exceeds the supported nesting limit");
     if (typeof value === "string") {
+        // The redactor sees the whole recorded text, so a secret that crosses the cap is still its
+        // to recognize; what it returns is cut to the cap afterwards.
         const result = options.redact ? options.redact(value, path) : value;
         // JavaScript can supply an async redactor despite the synchronous contract.
         // Observe its rejection before dropping the invalid record.
         if (result && typeof result === "object")
             void Promise.resolve(result).catch(() => { });
+        // A redactor may shorten or keep its text, never grow it past the cap: an answer longer than
+        // both the cap and the text it was given is the redactor's own, refused by its length before
+        // anything scans it, since scanning would materialize text the record never held.
         if (typeof result !== "string" ||
-            result.length > MAX_CONTENT_BYTES ||
+            result.length > Math.max(MAX_CONTENT_BYTES, value.length) ||
             !result.isWellFormed() ||
             result.includes("\u0000"))
             throw new Error("Redaction produced unsupported text");
-        if (Buffer.byteLength(result) > MAX_CONTENT_BYTES)
-            throw new Error("Telemetry text exceeds 256 KiB");
-        budget.bytes += Buffer.byteLength(result);
-        if (budget.bytes > MAX_BODY_BYTES)
-            throw new Error("Redacted record exceeds the content budget");
-        return result;
+        const bytes = Buffer.byteLength(result);
+        if (bytes <= MAX_CONTENT_BYTES) {
+            budget.bytes += bytes;
+            return result;
+        }
+        // Within the cap's code units but over its bytes (multibyte text): cut to the bytes.
+        if (!budget.truncated.includes(listAs))
+            budget.truncated.push(listAs);
+        budget.bytes += MAX_CONTENT_BYTES;
+        return truncateUtf8(result, MAX_CONTENT_BYTES);
     }
     if (Array.isArray(value)) {
         if (value.length > 16384)
             throw new Error("Telemetry array exceeds the complexity limit");
-        return value.map((item, index) => redactValue(item, `${path}.${index}`, options, budget, depth + 1));
+        return value.map((item, index) => redactValue(item, `${path}.${index}`, options, budget, depth + 1, listAs));
     }
     if (value instanceof Uint8Array) {
-        if (value.byteLength > MAX_CONTENT_BYTES)
-            throw new Error("Telemetry bytes exceed 256 KiB");
-        budget.bytes += value.byteLength;
-        if (budget.bytes > MAX_BODY_BYTES)
-            throw new Error("Redacted record exceeds the content budget");
-        return value;
+        if (value.byteLength <= MAX_CONTENT_BYTES) {
+            budget.bytes += value.byteLength;
+            return value;
+        }
+        // Bytes are never cut: a shortened encoding is a different value.
+        if (!budget.truncated.includes(listAs))
+            budget.truncated.push(listAs);
+        return truncatedMarker(value.byteLength);
     }
     if (value !== null && typeof value === "object")
         return Object.fromEntries(Object.entries(value).map(([key, item]) => [
             key,
-            redactValue(item, `${path}.${key}`, options, budget, depth + 1),
+            redactValue(item, `${path}.${key}`, options, budget, depth + 1, listAs),
         ]));
     return value;
 }
-function attributes(source, options, path, budget) {
+/**
+ * A record's attributes through the redactor. `listPrefix` is how a cut value of these
+ * attributes is listed under the record's `hue.truncated`: the key alone for the record's own
+ * attributes, `event:<name>:<key>` for an event's, as Hue's receiver lists the values it cuts.
+ */
+function attributes(source, options, path, budget, listPrefix = "") {
     // Metadata-only export summarizes the tool definitions it removes by name and digest.
     const summarized = options.captureContent ? source : withToolCatalogSummary(source);
     return Object.fromEntries(Object.entries(summarized).flatMap(([key, value]) => !options.captureContent && isContentKey(key)
@@ -105,15 +171,25 @@ function attributes(source, options, path, budget) {
         : [
             [
                 key,
-                redactValue(scrubToolCredentials(key, hashInlineFiles(key, value)), `${path}.${key}`, options, budget),
+                redactValue(scrubToolCredentials(key, hashInlineFiles(key, value)), `${path}.${key}`, options, budget, 0, `${listPrefix}${key}`),
             ],
         ]));
 }
+/** The record's attributes with the keys the redaction cut listed under `hue.truncated`, merged
+ * with any the application listed itself; unchanged when nothing was cut. */
+function withTruncated(source, budget) {
+    if (!budget.truncated.length)
+        return source;
+    return { ...source, [TRUNCATED_KEY]: withTruncatedKeys(source[TRUNCATED_KEY], budget.truncated) };
+}
 function redactResource(resource, options, cache, budget) {
     let result = cache.get(resource);
     if (!result) {
-        result = resourceFromAttributes(attributes(resource.attributes, options, "resource.attributes", budget), { schemaUrl: resource.schemaUrl });
-        cache.set(resource, result);
+        const cutsBefore = budget.truncated.length;
+        result = resourceFromAttributes(attributes(resource.attributes, options, "resource.attributes", budget, "resource."), { schemaUrl: resource.schemaUrl });
+        // A resource whose value was cut is redacted for every record, so each lists the cut.
+        if (budget.truncated.length === cutsBefore)
+            cache.set(resource, result);
     }
     return result;
 }
@@ -146,7 +222,7 @@ function hostedMcpCall(attributes) {
     return { ...(valid ? { serverName: serverLabel } : {}), failed: error != null };
 }
 export function redactSpan(span, options, cache) {
-    const budget = { bytes: 0, nodes: 0 };
+    const budget = { bytes: 0, nodes: 0, truncated: [] };
     // Derived before metadata-only stripping so the identity survives without the result itself.
     const hosted = hostedMcpCall(span.attributes);
     const source = {
@@ -154,6 +230,30 @@ export function redactSpan(span, options, cache) {
         ...(hosted.failed ? { "error.type": "mcp_error" } : {}),
         ...span.attributes,
     };
+    const status = {
+        code: hosted.failed && span.status.code === SpanStatusCode.UNSET
+            ? SpanStatusCode.ERROR
+            : span.status.code,
+        ...(options.captureContent &&
+            span.status.message !== undefined &&
+            !(hosted.failed && span.status.code === SpanStatusCode.UNSET)
+            ? { message: String(redactValue(span.status.message, "status.message", options, budget)) }
+            : {}),
+    };
+    const events = span.events
+        .filter((event) => options.captureContent ||
+        !/^gen_ai\.(?:system|user|assistant|tool|choice)/.test(event.name))
+        .map((event) => ({
+        ...event,
+        attributes: attributes(event.attributes ?? {}, options, `events.${event.name}`, budget, `event:${event.name}:`),
+    }));
+    const links = span.links.map((link) => ({
+        ...link,
+        attributes: attributes(link.attributes ?? {}, options, "links.attributes", budget, "link:"),
+    }));
+    const resource = redactResource(span.resource, options, cache, budget);
+    // Last, so every cut of the record, its events', links' and resource's included, is listed.
+    const redactedAttributes = withTruncated(attributes(source, options, "attributes", budget), budget);
     return {
         name: span.name,
         kind: span.kind,
@@ -163,29 +263,11 @@ export function redactSpan(span, options, cache) {
         endTime: span.endTime,
         duration: span.duration,
         ended: span.ended,
-        status: {
-            code: hosted.failed && span.status.code === SpanStatusCode.UNSET
-                ? SpanStatusCode.ERROR
-                : span.status.code,
-            ...(options.captureContent &&
-                span.status.message !== undefined &&
-                !(hosted.failed && span.status.code === SpanStatusCode.UNSET)
-                ? { message: String(redactValue(span.status.message, "status.message", options, budget)) }
-                : {}),
-        },
-        attributes: attributes(source, options, "attributes", budget),
-        events: span.events
-            .filter((event) => options.captureContent ||
-            !/^gen_ai\.(?:system|user|assistant|tool|choice)/.test(event.name))
-            .map((event) => ({
-            ...event,
-            attributes: attributes(event.attributes ?? {}, options, `events.${event.name}`, budget),
-        })),
-        links: span.links.map((link) => ({
-            ...link,
-            attributes: attributes(link.attributes ?? {}, options, "links.attributes", budget),
-        })),
-        resource: redactResource(span.resource, options, cache, budget),
+        status,
+        attributes: redactedAttributes,
+        events,
+        links,
+        resource,
         instrumentationScope: span.instrumentationScope,
         droppedAttributesCount: span.droppedAttributesCount,
         droppedEventsCount: span.droppedEventsCount,
@@ -193,10 +275,22 @@ export function redactSpan(span, options, cache) {
     };
 }
 export function redactLog(log, options, cache) {
-    const budget = { bytes: 0, nodes: 0 };
-    const body = options.captureContent ? redactValue(log.body, "body", options, budget) : undefined;
-    if (body !== undefined && Buffer.byteLength(JSON.stringify(body)) > MAX_CONTENT_BYTES)
-        throw new Error("Telemetry log body exceeds 256 KiB");
+    const budget = { bytes: 0, nodes: 0, truncated: [] };
+    let body = options.captureContent ? redactValue(log.body, "body", options, budget) : undefined;
+    if (body !== undefined && typeof body !== "string") {
+        // A structured body over the cap is replaced by the receiver's marker, as the receiver would
+        // replace it; the marker names the body's size as recorded, before any text part was cut.
+        if (Buffer.byteLength(JSON.stringify(body)) > MAX_CONTENT_BYTES) {
+            body = truncatedMarker(structuredBytes(log.body));
+            if (!budget.truncated.includes("body"))
+                budget.truncated.push("body");
+        }
+    }
+    const redactedAttributes = attributes(log.attributes, options, "attributes", budget);
+    const resource = redactResource(log.resource, options, cache, budget);
+    const scopeAttributes = log.instrumentationScope.attributes
+        ? attributes(log.instrumentationScope.attributes, options, "scope.attributes", budget, "scope.")
+        : undefined;
     return {
         hrTime: log.hrTime,
         hrTimeObserved: log.hrTimeObserved,
@@ -205,15 +299,11 @@ export function redactLog(log, options, cache) {
         severityNumber: log.severityNumber,
         eventName: log.eventName,
         body: body,
-        attributes: attributes(log.attributes, options, "attributes", budget),
-        resource: redactResource(log.resource, options, cache, budget),
+        attributes: withTruncated(redactedAttributes, budget),
+        resource,
         instrumentationScope: {
             ...log.instrumentationScope,
-            ...(log.instrumentationScope.attributes
-                ? {
-                    attributes: attributes(log.instrumentationScope.attributes, options, "scope.attributes", budget),
-                }
-                : {}),
+            ...(scopeAttributes ? { attributes: scopeAttributes } : {}),
         },
         droppedAttributesCount: log.droppedAttributesCount,
     };

package/dist/safety.d.ts

@@ -9,5 +9,23 @@ export interface EncodeLimits {
 }
 /** Validate a bounded data tree without invoking toJSON or property getters. */
 export declare function encodeContent(value: unknown, limits?: EncodeLimits): string;
+/**
+ * The value as JSON text within `limits.bytes`, and whether it was cut to fit. A value over the
+ * cap is cut to a UTF-8 prefix of its JSON text at the cap, as Hue's receiver cuts a value over
+ * its own cap and as it recognizes a cut (a text at one of its limits), so a span still carries
+ * the call, the recorded part of its result and the rest of its evidence; the caller lists the
+ * key under `hue.truncated`. The text is written as the value is walked and the walk stops once
+ * it is past the budget, so no more than the budget and one value is ever held, and a value cut
+ * among its members is never a shorter document that reads whole: the prefix ends at the cap,
+ * inside whatever member the cap fell in.
+ */
+export declare function encodeBoundedContent(value: unknown, limits?: EncodeLimits, cut?: boolean): {
+    text: string;
+    truncated: boolean;
+};
+/** `value` cut to at most `max` UTF-8 bytes, ending on a character boundary. The copy is bounded
+ * before the cut: `max` code units hold at least `max` bytes, so a gigabyte of text is never
+ * encoded whole to be cut to a quarter megabyte. */
+export declare function truncateUtf8(value: string, max: number): string;
 /** Bounded conservative accounting for the record data retained by our queue, not total process RSS. */
 export declare function estimateRecordBytes(value: unknown, limit: number): number;

package/dist/safety.js

@@ -12,6 +12,16 @@ class SafeSpan {
         this.source = source;
         this.failed = failed;
     }
+    /** The SDK span's attributes as they stand (the API alone shows none); undefined for a span
+     * that carries none, such as a non-recording span. */
+    get attributes() {
+        try {
+            return this.source.attributes;
+        }
+        catch {
+            return undefined;
+        }
+    }
     write(work) {
         try {
             const result = work();
@@ -93,28 +103,56 @@ export function safeSpan(source, failed) {
 const contentLimits = { bytes: MAX_CONTENT_BYTES, nodes: 16384, depth: 32 };
 /** Validate a bounded data tree without invoking toJSON or property getters. */
 export function encodeContent(value, limits = contentLimits) {
+    const { text, truncated } = encodeBoundedContent(value, limits, false);
+    if (truncated)
+        throw new RangeError("Content limit exceeded");
+    return text;
+}
+/**
+ * The value as JSON text within `limits.bytes`, and whether it was cut to fit. A value over the
+ * cap is cut to a UTF-8 prefix of its JSON text at the cap, as Hue's receiver cuts a value over
+ * its own cap and as it recognizes a cut (a text at one of its limits), so a span still carries
+ * the call, the recorded part of its result and the rest of its evidence; the caller lists the
+ * key under `hue.truncated`. The text is written as the value is walked and the walk stops once
+ * it is past the budget, so no more than the budget and one value is ever held, and a value cut
+ * among its members is never a shorter document that reads whole: the prefix ends at the cap,
+ * inside whatever member the cap fell in.
+ */
+export function encodeBoundedContent(value, limits = contentLimits, cut = true) {
     let nodes = 0;
     let bytes = 0;
+    let truncated = false;
+    const parts = [];
     const ancestors = new Set();
-    const charge = (amount) => {
-        bytes += amount;
-        if (bytes > limits.bytes)
-            throw new RangeError("Content limit exceeded");
+    const write = (text) => {
+        parts.push(text);
+        bytes += Buffer.byteLength(text);
+        if (bytes > limits.bytes) {
+            if (!cut)
+                throw new RangeError("Content limit exceeded");
+            truncated = true;
+        }
     };
     const visit = (item, depth) => {
         if (++nodes > limits.nodes || depth > limits.depth)
             throw new RangeError("Content complexity limit exceeded");
         if (typeof item === "string") {
-            if (item.length > limits.bytes)
-                throw new RangeError("Content limit exceeded");
-            charge(Buffer.byteLength(JSON.stringify(item)));
-            return item;
+            let text = item;
+            if (text.length > limits.bytes || Buffer.byteLength(text) > limits.bytes) {
+                if (!cut)
+                    throw new RangeError("Content limit exceeded");
+                // The copy itself is bounded in bytes: a longer string is cut before it is escaped.
+                truncated = true;
+                text = truncateUtf8(text.slice(0, limits.bytes), limits.bytes);
+            }
+            write(JSON.stringify(text));
+            return;
         }
         if (item === null || typeof item === "boolean" || typeof item === "number") {
             if (typeof item === "number" && !Number.isFinite(item))
                 throw new TypeError("Invalid number");
-            charge(JSON.stringify(item).length);
-            return item;
+            write(JSON.stringify(item));
+            return;
         }
         if (!item || typeof item !== "object" || ancestors.has(item))
             throw new TypeError("Invalid JSON");
@@ -126,32 +164,47 @@ export function encodeContent(value, limits = contentLimits) {
         if (!array && ![Object.prototype, null].includes(Object.getPrototypeOf(item)))
             throw new TypeError("Expected JSON data");
         ancestors.add(item);
-        charge(2);
-        const result = array ? [] : Object.create(null);
+        write(array ? "[" : "{");
         // Own descriptors avoid executing application accessors during capture.
         const keys = array
             ? Array.from({ length: Math.min(item.length, limits.nodes + 1) }, (_, i) => String(i))
             : Object.keys(item);
         if (keys.length > limits.nodes)
             throw new RangeError("Content complexity limit exceeded");
+        let first = true;
         for (const key of keys) {
+            // Past the budget, the rest is cut anyway: nothing more is copied.
+            if (truncated)
+                break;
             const descriptor = Object.getOwnPropertyDescriptor(item, key);
             if (!descriptor || !("value" in descriptor))
                 throw new TypeError("Expected JSON data property");
-            charge(1 + (array ? 0 : Buffer.byteLength(JSON.stringify(key)) + 1));
-            const child = visit(descriptor.value, depth + 1);
-            if (array)
-                result.push(child);
-            else
-                result[key] = child;
+            write(`${first ? "" : ","}${array ? "" : `${JSON.stringify(key)}:`}`);
+            first = false;
+            visit(descriptor.value, depth + 1);
         }
+        write(array ? "]" : "}");
         ancestors.delete(item);
-        return result;
     };
-    const encoded = JSON.stringify(visit(value, 0));
-    if (Buffer.byteLength(encoded) > limits.bytes)
-        throw new RangeError("Content limit exceeded");
-    return encoded;
+    visit(value, 0);
+    const encoded = parts.join("");
+    if (!truncated)
+        return { text: encoded, truncated: false };
+    // A cut value is past the cap as written (a cut text alone, with its quotes, is over it), so
+    // the prefix ends at the cap, where the receiver recognizes Hue's cut.
+    return { text: truncateUtf8(encoded, limits.bytes), truncated: true };
+}
+/** `value` cut to at most `max` UTF-8 bytes, ending on a character boundary. The copy is bounded
+ * before the cut: `max` code units hold at least `max` bytes, so a gigabyte of text is never
+ * encoded whole to be cut to a quarter megabyte. */
+export function truncateUtf8(value, max) {
+    if (Buffer.byteLength(value, "utf8") <= max)
+        return value;
+    const bytes = Buffer.from(value.slice(0, max), "utf8");
+    let end = Math.min(max, bytes.byteLength);
+    while (end > 0 && end < bytes.byteLength && (bytes[end] & 0xc0) === 0x80)
+        end--;
+    return bytes.toString("utf8", 0, end);
 }
 /** Bounded conservative accounting for the record data retained by our queue, not total process RSS. */
 export function estimateRecordBytes(value, limit) {

package/dist/transport.d.ts

@@ -42,6 +42,10 @@ export declare class HueTransport {
     private logs;
     private pendingBytes;
     private dropped;
+    /** Records of each trace the SDK never sent (dropped from the queue, refused as invalid or
+     * over the request limit), reported on the trace's root span as `hue.sdk.dropped_records` when
+     * the root is exported, so Hue reads the trace as incomplete by that many records. */
+    private droppedByTrace;
     private instrumentationFailures;
     private diagnosticPending;
     private lastDiagnosticAt;
@@ -53,6 +57,7 @@ export declare class HueTransport {
     private live;
     private liveTimer?;
     private liveSpans;
+    private readonly announcesLiveSpans;
     private placeholdersRejected;
     private placeholders;
     private placeholderSources;