@hue-run/sdk 0.14.0 → 0.15.1

package/dist/inline-files.js

@@ -2,7 +2,8 @@ import { createHash } from "node:crypto";
 import { MAX_BODY_BYTES } from "./config.js";
 /** Inline file content larger than this many UTF-8 bytes is exported as its digest instead. */
 export const INLINE_FILE_LIMIT = 64 * 1024;
-const MAX_INLINE_FILE_TEXT = 8 * MAX_BODY_BYTES;
+/** The longest message text, in UTF-8 bytes, inspected for inline files. */
+export const MAX_INLINE_FILE_TEXT = 8 * MAX_BODY_BYTES;
 /** Message text one record inspects for inline files in all, in UTF-16 code units. */
 export const INLINE_FILE_TEXT_PER_RECORD = 2 * MAX_INLINE_FILE_TEXT;
 /** Message attributes whose JSON can inline files: GenAI blob parts and AI SDK 6 file parts. */
@@ -52,7 +53,7 @@ function percentDecoded(payload) {
  * the base64 alphabet decoded, and anything else, such as a text file's own text, as UTF-8. A
  * `data:` URL whose data does not decode is taken as UTF-8 too.
  */
-function fileBytes(content) {
+export function inlineFileBytes(content) {
     const url = dataUrl.exec(content);
     const payload = url ? content.slice(url[0].length) : content;
     const decoded = url && !base64Header(url[1])
@@ -60,10 +61,19 @@ function fileBytes(content) {
         : payload.length % 4 === 0 && base64.test(payload)
             ? Buffer.from(payload, "base64")
             : undefined;
-    return decoded ?? Buffer.from(content, "utf8");
+    const header = url?.[1];
+    const mediaType = header === undefined ? undefined : header.split(";")[0].trim();
+    return {
+        bytes: decoded ?? Buffer.from(content, "utf8"),
+        decoded: decoded !== undefined,
+        ...(mediaType ? { urlMediaType: mediaType } : {}),
+    };
+}
+function fileBytes(content) {
+    return inlineFileBytes(content).bytes;
 }
 /** The key holding a part's inline content: GenAI `blob` parts and AI SDK 6 `file` parts. */
-function contentKey(part) {
+export function contentKey(part) {
     return part.type === "blob" ? "content" : part.type === "file" ? "data" : undefined;
 }
 function hashNode(value, state, depth) {
@@ -81,6 +91,7 @@ function hashNode(value, state, depth) {
         if (bytes.byteLength > INLINE_FILE_LIMIT) {
             const { [key]: _omitted, ...rest } = part;
             state.changed = true;
+            state.files++;
             return {
                 ...rest,
                 sha256: createHash("sha256").update(bytes).digest("hex"),
@@ -97,7 +108,9 @@ function hashNode(value, state, depth) {
  * `mime_type`, `modality`, `mediaType`, …). Other attributes, shorter messages and values that
  * are not JSON are returned unchanged.
  */
-export function hashInlineFiles(key, value) {
+export function hashInlineFiles(key, value, 
+/** Counts the files replaced by their digest, when given. */
+count) {
     if (!messageKeys.has(key) ||
         typeof value !== "string" ||
         Buffer.byteLength(value, "utf8") <= INLINE_FILE_LIMIT ||
@@ -106,8 +119,10 @@ export function hashInlineFiles(key, value) {
         return value;
     try {
         const parsed = JSON.parse(value);
-        const state = { changed: false };
+        const state = { changed: false, files: 0 };
         const hashed = hashNode(parsed, state, 0);
+        if (count)
+            count.files += state.files;
         return state.changed ? JSON.stringify(hashed) : value;
     }
     catch {
@@ -115,3 +130,47 @@ export function hashInlineFiles(key, value) {
         return value;
     }
 }
+function pointerSegment(segment) {
+    return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+/**
+ * The inline file parts of a parsed message whose content text is longer than
+ * {@link INLINE_FILE_LIMIT} UTF-8 bytes, in document order: the caller decodes each and keeps the
+ * ones whose file bytes are over the limit. The parts are the parsed value's own objects, so the
+ * caller may replace their content in place.
+ */
+export function largeInlineFileParts(value) {
+    const found = [];
+    const visit = (node, pointer, depth) => {
+        if (depth > 256)
+            throw new Error("Message exceeds the supported nesting limit");
+        if (Array.isArray(node)) {
+            node.forEach((item, index) => visit(item, `${pointer}/${index}`, depth + 1));
+            return;
+        }
+        if (node === null || typeof node !== "object")
+            return;
+        const part = node;
+        const key = contentKey(part);
+        const inline = key === undefined ? undefined : part[key];
+        // Decoding only shrinks the text, so text of at most the limit holds no file over it.
+        if (key !== undefined &&
+            typeof inline === "string" &&
+            inline.length * 3 > INLINE_FILE_LIMIT &&
+            Buffer.byteLength(inline, "utf8") > INLINE_FILE_LIMIT) {
+            found.push({ part, key, content: inline, pointer: `${pointer}/${key}` });
+            return;
+        }
+        for (const [name, item] of Object.entries(part))
+            visit(item, `${pointer}/${pointerSegment(name)}`, depth + 1);
+    };
+    visit(value, "", 0);
+    return found;
+}
+/** The digest an inline file part is exported as when its bytes are not uploaded: the part's
+ * other fields with the file's SHA-256 and byte size, as {@link hashInlineFiles} writes it. */
+export function digestPart(part, key, digest) {
+    delete part[key];
+    part.sha256 = digest.sha256;
+    part.size = digest.size;
+}

package/dist/limits.d.ts

@@ -0,0 +1,32 @@
+import type { IncomingHttpHeaders } from "node:http";
+/**
+ * What a Hue receiver accepts. Every OTLP acknowledgement, whatever its status, advertises these
+ * (`Hue-Max-Request-Bytes`, `Hue-Max-Decoded-Bytes`, `Hue-Max-Value-Bytes`); until one arrives an
+ * exporter assumes the receiver's limits as of this release.
+ */
+export interface ReceiverLimits {
+    /** Bytes of one request on the wire, after gzip. */
+    readonly requestBytes: number;
+    /** Bytes of one request after decompression. */
+    readonly decodedBytes: number;
+    /** Bytes of one attribute value or log body the receiver keeps inline. */
+    readonly valueBytes: number;
+}
+/** The limits assumed before a receiver advertises its own. */
+export declare const DEFAULT_RECEIVER_LIMITS: ReceiverLimits;
+/**
+ * The ordinary size of one request before gzip. Advertised limits are ceilings, not targets: a
+ * receiver decodes a larger request more slowly, so batches stay at this size, or the advertised
+ * decoded limit when that is lower, and only a single record that needs more is sent alone in a
+ * larger request, up to the advertised ceilings.
+ */
+export declare const BATCH_TARGET_BYTES: number;
+/**
+ * `current` with every limit a response advertised adopted, clamped to its range; `current`
+ * itself when the response advertised none, or the same values. A lower advertised limit is
+ * adopted as readily as a higher one: the exporter never exceeds what the receiver last said.
+ */
+export declare function advertisedLimits(current: ReceiverLimits, headers: IncomingHttpHeaders): ReceiverLimits;
+/** Whether `bytes` before gzip are certain to stay within `limit` after it: deflate's worst case
+ * (stored blocks) adds a few bytes per 16 KiB, plus gzip's header and trailer. */
+export declare function fitsWithoutCompression(bytes: number, limit: number): boolean;

package/dist/limits.js

@@ -0,0 +1,54 @@
+import { MAX_BODY_BYTES, MAX_CONTENT_BYTES, MAX_DECODED_BYTES } from "./config.js";
+const KIB = 1024;
+const MIB = 1024 * KIB;
+/** The limits assumed before a receiver advertises its own. */
+export const DEFAULT_RECEIVER_LIMITS = Object.freeze({
+    requestBytes: MAX_BODY_BYTES,
+    decodedBytes: MAX_DECODED_BYTES,
+    valueBytes: MAX_CONTENT_BYTES,
+});
+/**
+ * The ordinary size of one request before gzip. Advertised limits are ceilings, not targets: a
+ * receiver decodes a larger request more slowly, so batches stay at this size, or the advertised
+ * decoded limit when that is lower, and only a single record that needs more is sent alone in a
+ * larger request, up to the advertised ceilings.
+ */
+export const BATCH_TARGET_BYTES = 4 * MIB;
+/** Each advertised limit's header and the range it is clamped to, so a faulty value cannot make
+ * requests unboundedly large or too small to carry a record. */
+const ADVERTISED = [
+    { field: "requestBytes", header: "hue-max-request-bytes", min: MIB, max: 64 * MIB },
+    { field: "decodedBytes", header: "hue-max-decoded-bytes", min: MIB, max: 64 * MIB },
+    { field: "valueBytes", header: "hue-max-value-bytes", min: 256 * KIB, max: 16 * MIB },
+];
+/** A decimal integer header value, else undefined. */
+function decimal(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const text = value.trim();
+    if (!/^[0-9]{1,20}$/.test(text))
+        return undefined;
+    return Number(text);
+}
+/**
+ * `current` with every limit a response advertised adopted, clamped to its range; `current`
+ * itself when the response advertised none, or the same values. A lower advertised limit is
+ * adopted as readily as a higher one: the exporter never exceeds what the receiver last said.
+ */
+export function advertisedLimits(current, headers) {
+    let next = current;
+    for (const { field, header, min, max } of ADVERTISED) {
+        const value = decimal(headers[header]);
+        if (value === undefined)
+            continue;
+        const clamped = Math.min(max, Math.max(min, value));
+        if (clamped !== next[field])
+            next = { ...next, [field]: clamped };
+    }
+    return next === current ? current : Object.freeze(next);
+}
+/** Whether `bytes` before gzip are certain to stay within `limit` after it: deflate's worst case
+ * (stored blocks) adds a few bytes per 16 KiB, plus gzip's header and trailer. */
+export function fitsWithoutCompression(bytes, limit) {
+    return bytes + Math.ceil(bytes / 1024) + 64 <= limit;
+}

package/dist/privacy.d.ts

@@ -3,13 +3,16 @@ import type { ReadableLogRecord } from "@opentelemetry/sdk-logs";
 import { type Resource } from "@opentelemetry/resources";
 import type { HueOptions } from "./types.js";
 import { truncateUtf8 } from "./safety.js";
+import type { OffloadCollector } from "./blobs.js";
+import type { DigestedMessage } from "./snapshot.js";
 export { truncateUtf8 };
 /** Attribute keys (and their dotted children) removed in metadata-only mode. */
 export declare const contentPrefixes: string[];
 export declare function isContentKey(key: string): boolean;
-/** 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. */
+/** The record attribute listing the keys whose values were cut to fit Hue's value cap (1 MiB
+ * unless the receiver advertises another): 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 declare const TRUNCATED_KEY = "hue.truncated";
 /** The size of a structured value the marker replaced. */
 export declare const TRUNCATED_BYTES_KEY = "hue.truncated_bytes";
@@ -20,8 +23,27 @@ export declare const DROPPED_RECORDS_KEY = "hue.sdk.dropped_records";
 /** 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 declare function truncatedMarker(bytes: number): Record<string, unknown>;
+/** Whether a value is the receiver's marker for a value that was shed or replaced. */
+export declare function isTruncatedMarker(value: unknown): boolean;
 /** `listed` with `keys` added, each once, in order. */
 export declare function withTruncatedKeys(listed: unknown, keys: readonly string[]): string[];
+/** How one record is redacted: the receiver's value cap, and the value strings the queue cut. */
+export interface RedactionLimits {
+    /** The value cap in UTF-8 bytes. Default 1 MiB, the receiver's limit before it advertises one. */
+    valueBytes?: number;
+    /** The record's value strings cut when it was queued. */
+    cut?: ReadonlySet<string>;
+    /** The span's own messages whose large inline files were shrunk to their digest when it was
+     * queued, with how many files each: reported as not uploaded when values may be. */
+    digested?: ReadonlyMap<string, DigestedMessage> | undefined;
+    /**
+     * Set when a span's values over the cap may be uploaded: each of its own string or byte
+     * attribute values still over the cap after the redactor, and each recorded message that may
+     * inline a large file, is left whole (uncut, unlisted) and collected here for the upload step
+     * to place; a value the queue cut when it was admitted is named in `cut`.
+     */
+    offload?: OffloadCollector;
+}
 export type ResourceCache = WeakMap<Resource, Resource>;
-export declare function redactSpan(span: ReadableSpan, options: HueOptions, cache: ResourceCache): ReadableSpan;
-export declare function redactLog(log: ReadableLogRecord, options: HueOptions, cache: ResourceCache): ReadableLogRecord;
+export declare function redactSpan(span: ReadableSpan, options: HueOptions, cache: ResourceCache, limits?: RedactionLimits): ReadableSpan;
+export declare function redactLog(log: ReadableLogRecord, options: HueOptions, cache: ResourceCache, limits?: RedactionLimits): ReadableLogRecord;

package/dist/privacy.js

@@ -1,8 +1,8 @@
 import { SpanStatusCode } from "@opentelemetry/api";
 import { resourceFromAttributes } from "@opentelemetry/resources";
-import { MAX_CONTENT_BYTES } from "./config.js";
+import { MAX_CONTENT_BYTES, MAX_RECORD_NODES, REDACTION_CONTEXT_UNITS } from "./config.js";
 import { scrubToolCredentials, withToolCatalogSummary } from "./tool-definitions.js";
-import { hashInlineFiles } from "./inline-files.js";
+import { hashInlineFiles, INLINE_FILE_LIMIT, isMessageKey } from "./inline-files.js";
 import { truncateUtf8 } from "./safety.js";
 export { truncateUtf8 };
 /** Attribute keys (and their dotted children) removed in metadata-only mode. */
@@ -65,9 +65,10 @@ export const contentPrefixes = [
 export function isContentKey(key) {
     return contentPrefixes.some((prefix) => key === prefix || key.startsWith(`${prefix}.`));
 }
-/** 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. */
+/** The record attribute listing the keys whose values were cut to fit Hue's value cap (1 MiB
+ * unless the receiver advertises another): 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";
@@ -89,6 +90,13 @@ function structuredBytes(value) {
 export function truncatedMarker(bytes) {
     return { [TRUNCATED_KEY]: true, [TRUNCATED_BYTES_KEY]: bytes };
 }
+/** Whether a value is the receiver's marker for a value that was shed or replaced. */
+export function isTruncatedMarker(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        value[TRUNCATED_KEY] === true);
+}
 /** `listed` with `keys` added, each once, in order. */
 export function withTruncatedKeys(listed, keys) {
     const result = Array.isArray(listed)
@@ -99,50 +107,135 @@ export function withTruncatedKeys(listed, keys) {
             result.push(key);
     return result;
 }
+function budgetOf(limits) {
+    return {
+        bytes: 0,
+        nodes: 0,
+        truncated: [],
+        valueBytes: limits.valueBytes ?? MAX_CONTENT_BYTES,
+        ...(limits.cut?.size ? { cut: limits.cut } : {}),
+        ...(limits.digested?.size ? { digested: limits.digested } : {}),
+        ...(limits.offload ? { offload: limits.offload } : {}),
+    };
+}
+/** `text` without its last `units` code units, never ending on the first half of a pair. */
+function withoutTail(text, units) {
+    let end = Math.max(0, text.length - units);
+    if (end > 0 && /[\uD800-\uDBFF]/.test(text[end - 1]))
+        end--;
+    return text.slice(0, end);
+}
+/** Text through the redactor, whole: the answer validated, not yet cut to the cap. */
+function redactedText(value, path, options, cap) {
+    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 > Math.max(cap, value.length) ||
+        !result.isWellFormed() ||
+        result.includes("\u0000"))
+        throw new Error("Redaction produced unsupported text");
+    return result;
+}
+/** Whether a recorded message's text may inline a file over the inline file limit. */
+function mayInlineFiles(key, text) {
+    return (isMessageKey(key) &&
+        text.length * 3 > INLINE_FILE_LIMIT &&
+        (text.includes('"blob"') || text.includes('"file"')));
+}
+/** Marks a value the upload step does not place. */
+const NOT_HELD = Symbol("not held");
+/**
+ * One of a span's own attribute values, when its values may be uploaded: text through the
+ * credential scrub and the redactor, whole, and collected when it is over the cap or may inline
+ * a large file; bytes over the cap collected as they are. {@link NOT_HELD} for any other value,
+ * and for text the queue cut when the record was admitted, which is never the whole value.
+ */
+function offloadValue(key, value, path, options, budget) {
+    const collector = budget.offload;
+    if (value instanceof Uint8Array) {
+        if (value.byteLength <= budget.valueBytes)
+            return NOT_HELD;
+        if (++budget.nodes > MAX_RECORD_NODES)
+            throw new Error("Telemetry value exceeds the supported nesting limit");
+        collector.candidates.push({ key, value });
+        return value;
+    }
+    if (typeof value !== "string")
+        return NOT_HELD;
+    // Each large inline file the queue shrank to its digest is reported as not uploaded; what is
+    // left of the message is placed like any other value, and reported too if it is cut.
+    const digested = budget.digested?.get(key);
+    const files = digested?.text === value ? digested.files : 0;
+    for (let file = 0; file < files; file++)
+        collector.cut.push(key);
+    if (budget.cut?.has(value)) {
+        collector.cut.push(key);
+        return NOT_HELD;
+    }
+    const scrubbed = scrubToolCredentials(key, value);
+    if (typeof scrubbed !== "string")
+        return NOT_HELD;
+    if (++budget.nodes > MAX_RECORD_NODES)
+        throw new Error("Telemetry value exceeds the supported nesting limit");
+    const result = redactedText(scrubbed, path, options, budget.valueBytes);
+    if (mayInlineFiles(key, result) ||
+        (result.length * 3 > budget.valueBytes && Buffer.byteLength(result) > budget.valueBytes))
+        collector.candidates.push({ key, value: result });
+    return result;
+}
 /**
- * One value through the redactor and Hue's value cap. Text over 256 KiB is cut to a UTF-8 prefix
+ * One value through the redactor and Hue's value cap. Text over the cap 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)
+    if (++budget.nodes > MAX_RECORD_NODES || 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 > Math.max(MAX_CONTENT_BYTES, value.length) ||
-            !result.isWellFormed() ||
-            result.includes("\u0000"))
-            throw new Error("Redaction produced unsupported text");
+        const cap = budget.valueBytes;
+        // The redactor sees the recorded text past the cap, so a secret that crosses the cap is still
+        // its to recognize; what it returns is cut to the cap afterwards. Text the queue cut when the
+        // record was admitted (far past the cap) reached the redactor without its continuation, so
+        // the end of the answer, which may hold the start of a secret it could not recognize, is
+        // never exported.
+        const cutWhenQueued = budget.cut?.has(value) === true;
+        let result = redactedText(value, path, options, cap);
+        if (cutWhenQueued && options.redact)
+            result = withoutTail(result, REDACTION_CONTEXT_UNITS);
         const bytes = Buffer.byteLength(result);
-        if (bytes <= MAX_CONTENT_BYTES) {
+        if (bytes <= cap && !cutWhenQueued) {
             budget.bytes += bytes;
             return result;
         }
-        // Within the cap's code units but over its bytes (multibyte text): cut to the bytes.
+        // Within the cap's code units but over its bytes (multibyte text), or cut when queued: cut to
+        // the bytes, and listed either way.
         if (!budget.truncated.includes(listAs))
             budget.truncated.push(listAs);
-        budget.bytes += MAX_CONTENT_BYTES;
-        return truncateUtf8(result, MAX_CONTENT_BYTES);
+        budget.bytes += cap;
+        return truncateUtf8(result, cap);
+    }
+    // A value the queue replaced by the receiver's marker (a tool definition or recorded request
+    // too long to scrub when it was queued) is listed as cut.
+    if (depth === 0 && isTruncatedMarker(value)) {
+        if (!budget.truncated.includes(listAs))
+            budget.truncated.push(listAs);
+        return value;
     }
     if (Array.isArray(value)) {
-        if (value.length > 16384)
+        if (value.length > MAX_RECORD_NODES)
             throw new Error("Telemetry array exceeds the complexity limit");
         return value.map((item, index) => redactValue(item, `${path}.${index}`, options, budget, depth + 1, listAs));
     }
     if (value instanceof Uint8Array) {
-        if (value.byteLength <= MAX_CONTENT_BYTES) {
+        if (value.byteLength <= budget.valueBytes) {
             budget.bytes += value.byteLength;
             return value;
         }
@@ -163,17 +256,25 @@ function redactValue(value, path, options, budget, depth = 0, listAs = path) {
  * 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 = "") {
+function attributes(source, options, path, budget, listPrefix = "", own = false) {
     // 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)
-        ? []
-        : [
+    return Object.fromEntries(Object.entries(summarized).flatMap(([key, value]) => {
+        if (!options.captureContent && isContentKey(key))
+            return [];
+        // A span's own value that may be uploaded is placed by the upload step.
+        if (own && budget.offload) {
+            const held = offloadValue(key, value, `${path}.${key}`, options, budget);
+            if (held !== NOT_HELD)
+                return [[key, held]];
+        }
+        return [
             [
                 key,
                 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. */
@@ -221,8 +322,8 @@ function hostedMcpCall(attributes) {
         serverLabel.isWellFormed();
     return { ...(valid ? { serverName: serverLabel } : {}), failed: error != null };
 }
-export function redactSpan(span, options, cache) {
-    const budget = { bytes: 0, nodes: 0, truncated: [] };
+export function redactSpan(span, options, cache, limits = {}) {
+    const budget = budgetOf(limits);
     // Derived before metadata-only stripping so the identity survives without the result itself.
     const hosted = hostedMcpCall(span.attributes);
     const source = {
@@ -253,7 +354,7 @@ export function redactSpan(span, options, cache) {
     }));
     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);
+    const redactedAttributes = withTruncated(attributes(source, options, "attributes", budget, "", true), budget);
     return {
         name: span.name,
         kind: span.kind,
@@ -274,13 +375,13 @@ export function redactSpan(span, options, cache) {
         droppedLinksCount: span.droppedLinksCount,
     };
 }
-export function redactLog(log, options, cache) {
-    const budget = { bytes: 0, nodes: 0, truncated: [] };
+export function redactLog(log, options, cache, limits = {}) {
+    const budget = budgetOf(limits);
     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) {
+        if (Buffer.byteLength(JSON.stringify(body)) > budget.valueBytes) {
             body = truncatedMarker(structuredBytes(log.body));
             if (!budget.truncated.includes("body"))
                 budget.truncated.push("body");

package/dist/provider-tools.js

@@ -1,6 +1,6 @@
 import { MAX_CONTENT_BYTES } from "./config.js";
 import { scrubCredentialText } from "./tool-definitions.js";
-const MAX_PROVIDER_ITEMS = 128;
+const MAX_PROVIDER_ITEMS = 1024;
 const MAX_PROVIDER_DEFINITIONS = 512;
 const MAX_PROVIDER_SERVERS = 512;
 function isItem(value) {

package/dist/safety.d.ts

@@ -7,6 +7,8 @@ export interface EncodeLimits {
     nodes: number;
     depth: number;
 }
+/** One content attribute's bounds under a receiver's value cap of `valueBytes`. */
+export declare function contentLimitsOf(valueBytes: number): EncodeLimits;
 /** Validate a bounded data tree without invoking toJSON or property getters. */
 export declare function encodeContent(value: unknown, limits?: EncodeLimits): string;
 /**

package/dist/safety.js

@@ -1,6 +1,6 @@
 import { INVALID_SPAN_CONTEXT, trace } from "@opentelemetry/api";
 import { types as utilTypes } from "node:util";
-import { MAX_CONTENT_BYTES } from "./config.js";
+import { MAX_CONTENT_BYTES, MAX_RECORD_NODES } from "./config.js";
 export function noopSpan() {
     return trace.wrapSpanContext(INVALID_SPAN_CONTEXT);
 }
@@ -99,8 +99,14 @@ class SafeSpan {
 export function safeSpan(source, failed) {
     return new SafeSpan(source, failed);
 }
-/** One content attribute's bounds. */
-const contentLimits = { bytes: MAX_CONTENT_BYTES, nodes: 16384, depth: 32 };
+/** One content attribute's bounds: the value cap, and as many values as the Python SDK's content
+ * snapshot allows, so a structured value of small members is cut at the cap rather than refused
+ * for its count before reaching it. */
+const contentLimits = { bytes: MAX_CONTENT_BYTES, nodes: 65_536, depth: 32 };
+/** One content attribute's bounds under a receiver's value cap of `valueBytes`. */
+export function contentLimitsOf(valueBytes) {
+    return { ...contentLimits, bytes: valueBytes };
+}
 /** Validate a bounded data tree without invoking toJSON or property getters. */
 export function encodeContent(value, limits = contentLimits) {
     const { text, truncated } = encodeBoundedContent(value, limits, false);
@@ -212,7 +218,7 @@ export function estimateRecordBytes(value, limit) {
     let nodes = 0;
     const seen = new Set();
     const visit = (item, depth) => {
-        if (++nodes > 16384 || depth > 32)
+        if (++nodes > MAX_RECORD_NODES || depth > 32)
             throw new RangeError("Telemetry complexity limit exceeded");
         bytes += 16;
         if (typeof item === "string")

package/dist/snapshot.d.ts

@@ -1,12 +1,34 @@
 import type { ReadableSpan } from "@opentelemetry/sdk-trace";
 import type { ReadableLogRecord, ReadWriteLogRecord } from "@opentelemetry/sdk-logs";
-export declare function snapshotSpan(source: ReadableSpan, limit: number, captureContent?: boolean): {
-    record: ReadableSpan;
+/**
+ * How a span's own values over the receiver's value cap are held whole for export to upload:
+ * the cap, the bytes the held-value budget has left, and whether nothing else is held (a single
+ * value larger than the whole budget is held then). A string is charged two bytes a code unit,
+ * bytes as themselves. The queue's byte budget is charged what the value would have cost cut
+ * when queued, so a value whose upload fails is exported cut exactly as before.
+ */
+export interface HoldLimits {
+    valueBytes: number;
+    budget: number;
+    first: boolean;
+}
+/** A span's own message whose large inline files shrank to their digest when it was queued: the
+ * text queued, and how many files it lost. */
+export interface DigestedMessage {
+    text: string;
+    files: number;
+}
+/** What admission keeps of a record: its copy, the bytes charged for it, whether resource
+ * attributes were still unresolved, the value strings it cut, the bytes of the values it held
+ * whole for upload, and the span's own messages whose large inline files it shrank to their
+ * digest (with how many files each). */
+export interface RecordSnapshot<T> {
+    record: T;
     bytes: number;
     unresolvedResource: boolean;
-};
-export declare function snapshotLog(source: ReadableLogRecord, limit: number, captureContent?: boolean): {
-    record: ReadWriteLogRecord;
-    bytes: number;
-    unresolvedResource: boolean;
-};
+    cut: ReadonlySet<string>;
+    held: number;
+    digested: ReadonlyMap<string, DigestedMessage>;
+}
+export declare function snapshotSpan(source: ReadableSpan, limit: number, captureContent?: boolean, valueUnits?: number, hold?: HoldLimits): RecordSnapshot<ReadableSpan>;
+export declare function snapshotLog(source: ReadableLogRecord, limit: number, captureContent?: boolean, valueUnits?: number): RecordSnapshot<ReadWriteLogRecord>;