@hue-run/sdk 0.17.0 → 0.18.0

package/dist/json-edits.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Edits to recorded JSON text that keep every byte they do not change. Placing a file in a value
+ * read from JSON text (an attribute, or a tool call's JSON-encoded arguments) replaces only the
+ * file's own value, or the members of the part that held it; the rest of the text, its key order,
+ * number spellings and whitespace included, is kept as it was recorded. Mirrors the Python SDK's
+ * `_json_edits.py`, so both SDKs write the same bytes.
+ */
+/** One change at a JSON pointer of a document: its value replaced by `value` (JSON text), or,
+ * for an object, the member `remove` dropped and each `set` member's value replaced in place or
+ * appended. */
+export type JsonEdit = {
+    pointer: string;
+    value: string;
+} | {
+    pointer: string;
+    remove?: string;
+    set?: readonly [string, string][];
+};
+/**
+ * `text` with `edits` applied, every byte outside the changed values kept. Each object edit
+ * keeps the object's other members, the separators between them and its whitespace; appended
+ * members are written compactly (`,"key":value`) before the closing brace.
+ */
+export declare function applyJsonEdits(text: string, edits: readonly JsonEdit[]): string;

package/dist/json-edits.js

@@ -0,0 +1,187 @@
+/**
+ * Edits to recorded JSON text that keep every byte they do not change. Placing a file in a value
+ * read from JSON text (an attribute, or a tool call's JSON-encoded arguments) replaces only the
+ * file's own value, or the members of the part that held it; the rest of the text, its key order,
+ * number spellings and whitespace included, is kept as it was recorded. Mirrors the Python SDK's
+ * `_json_edits.py`, so both SDKs write the same bytes.
+ */
+const segment = (key) => key.replaceAll("~", "~0").replaceAll("/", "~1");
+/** The spans of the values at `wanted` pointers of valid JSON `text`, with the members of each
+ * object among them. A duplicate key's last member is the one a pointer names. */
+function locate(text, wanted) {
+    const prefixes = new Set();
+    for (const pointer of wanted)
+        for (let at = pointer.length; at >= 0; at = pointer.lastIndexOf("/", at - 1)) {
+            prefixes.add(pointer.slice(0, at));
+            if (at === 0)
+                break;
+        }
+    const found = new Map();
+    const space = (index) => {
+        let at = index;
+        for (;;) {
+            const code = text.charCodeAt(at);
+            if (code === 0x20 || code === 0x09 || code === 0x0a || code === 0x0d)
+                at++;
+            else
+                return at;
+        }
+    };
+    const stringEnd = (index) => {
+        let at = index + 1;
+        for (;;) {
+            const code = text.charCodeAt(at);
+            if (code === 0x22)
+                return at + 1;
+            at += code === 0x5c ? 2 : 1;
+        }
+    };
+    /** The end of the value starting at `index`, and an object's members when asked. */
+    const valueEnd = (index, members) => {
+        const code = text.charCodeAt(index);
+        if (code === 0x22)
+            return stringEnd(index);
+        if (code === 0x7b || code === 0x5b) {
+            const object = code === 0x7b;
+            let at = space(index + 1);
+            if (text.charCodeAt(at) === (object ? 0x7d : 0x5d))
+                return at + 1;
+            for (;;) {
+                let key = "";
+                let start = at;
+                if (object) {
+                    const keyEnd = stringEnd(at);
+                    if (members)
+                        key = JSON.parse(text.slice(at, keyEnd));
+                    at = space(space(keyEnd) + 1);
+                }
+                const valueStart = at;
+                const end = valueEnd(at);
+                if (members)
+                    members.push({ key, start, valueStart, end });
+                at = space(end);
+                if (text.charCodeAt(at) === 0x2c) {
+                    at = space(at + 1);
+                    start = at;
+                    continue;
+                }
+                return at + 1;
+            }
+        }
+        let at = index;
+        for (;;) {
+            const code = text.charCodeAt(at);
+            // A number's characters, or a literal's letters.
+            if ((code >= 0x30 && code <= 0x39) ||
+                code === 0x2d ||
+                code === 0x2b ||
+                code === 0x2e ||
+                (code >= 0x61 && code <= 0x7a) ||
+                code === 0x45)
+                at++;
+            else
+                return at;
+        }
+    };
+    const visit = (index, pointer) => {
+        const code = text.charCodeAt(index);
+        const descend = code === 0x7b || code === 0x5b;
+        const members = descend ? [] : undefined;
+        const end = valueEnd(index, members);
+        if (wanted.has(pointer))
+            found.set(pointer, code === 0x7b ? { start: index, end, members } : { start: index, end });
+        if (!members)
+            return;
+        const last = new Map();
+        members.forEach((member, position) => last.set(code === 0x7b ? member.key : String(position), member));
+        for (const [key, member] of last) {
+            const child = `${pointer}/${segment(key)}`;
+            if (prefixes.has(child))
+                visit(member.valueStart, child);
+        }
+    };
+    visit(space(0), "");
+    return found;
+}
+/**
+ * `text` with `edits` applied, every byte outside the changed values kept. Each object edit
+ * keeps the object's other members, the separators between them and its whitespace; appended
+ * members are written compactly (`,"key":value`) before the closing brace.
+ */
+export function applyJsonEdits(text, edits) {
+    if (!edits.length)
+        return text;
+    const values = new Map();
+    const objects = new Map();
+    for (const edit of edits) {
+        if ("value" in edit)
+            values.set(edit.pointer, edit.value);
+        else {
+            const object = objects.get(edit.pointer) ?? { remove: new Set(), set: new Map() };
+            if (edit.remove !== undefined)
+                object.remove.add(edit.remove);
+            for (const [key, value] of edit.set ?? [])
+                object.set.set(key, value);
+            objects.set(edit.pointer, object);
+        }
+    }
+    const located = locate(text, new Set([...values.keys(), ...objects.keys()]));
+    const pieces = [];
+    for (const [pointer, value] of values) {
+        const span = located.get(pointer);
+        if (span)
+            pieces.push({ start: span.start, end: span.end, render: () => value });
+    }
+    for (const [pointer, edit] of objects) {
+        const span = located.get(pointer);
+        if (!span?.members)
+            continue;
+        const members = span.members;
+        // The last member of each key set in place keeps its position; the others are appended.
+        const lastOf = new Map();
+        for (const member of members)
+            lastOf.set(member.key, member);
+        for (const [key, value] of edit.set) {
+            const member = lastOf.get(key);
+            if (member && !edit.remove.has(key))
+                pieces.push({ start: member.valueStart, end: member.end, render: () => value });
+        }
+        pieces.push({
+            start: span.start,
+            end: span.end,
+            render: () => {
+                const kept = members.filter((member) => !edit.remove.has(member.key));
+                const first = members[0]?.start ?? span.end - 1;
+                const close = members.length ? members.at(-1).end : span.end - 1;
+                let out = text.slice(span.start, first);
+                kept.forEach((member, position) => {
+                    const index = members.indexOf(member);
+                    // The separator that preceded this member, comma included, unless it now comes first.
+                    if (position > 0)
+                        out += text.slice(members[index - 1].end, member.start);
+                    out += render(member.start, member.end);
+                });
+                let appended = "";
+                for (const [key, value] of edit.set)
+                    if (!lastOf.has(key) || edit.remove.has(key))
+                        appended += `${kept.length || appended ? "," : ""}${JSON.stringify(key)}:${value}`;
+                return out + appended + text.slice(close, span.end);
+            },
+        });
+    }
+    pieces.sort((a, b) => a.start - b.start || b.end - a.end);
+    /** The text from `start` to `end` with the pieces within it rendered; a piece inside another
+     * is rendered by the outer one. */
+    const render = (start, end) => {
+        let out = "";
+        let at = start;
+        for (const piece of pieces) {
+            if (piece.start < at || piece.end > end)
+                continue;
+            out += text.slice(at, piece.start) + piece.render();
+            at = piece.end;
+        }
+        return out + text.slice(at, end);
+    };
+    return render(0, text.length);
+}

package/dist/privacy.d.ts

@@ -44,6 +44,19 @@ export interface RedactionLimits {
      */
     offload?: OffloadCollector;
 }
+/**
+ * A log record's body, placed by the upload step, cut as {@link redactLog} cuts one: each string
+ * over the cap cut to it and bytes over it replaced by the receiver's marker, and a structured
+ * body still over the cap replaced by the marker. Whether anything was cut, for `hue.truncated`.
+ */
+export declare function capLogBody(body: unknown, valueBytes: number): {
+    body: unknown;
+    cut: boolean;
+};
+/** Whether a log record is a GenAI event, whose structured body carries messages. */
+export declare function isGenAiLog(log: ReadableLogRecord): boolean;
+/** Whether a log body is structured (an object or array), so a pointer can address inside it. */
+export declare function isStructuredBody(body: unknown): boolean;
 export type ResourceCache = WeakMap<Resource, Resource>;
 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

@@ -2,7 +2,7 @@ import { SpanStatusCode } from "@opentelemetry/api";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { MAX_CONTENT_BYTES, MAX_RECORD_NODES, REDACTION_CONTEXT_UNITS } from "./config.js";
 import { scrubToolCredentials, withToolCatalogSummary } from "./tool-definitions.js";
-import { hashInlineFiles, mayInlineFiles } from "./inline-files.js";
+import { hashInlineFiles, isMediaKey, mayInlineFiles } from "./inline-files.js";
 import { truncateUtf8 } from "./safety.js";
 export { truncateUtf8 };
 /** Attribute keys (and their dotted children) removed in metadata-only mode. */
@@ -152,6 +152,10 @@ const NOT_HELD = Symbol("not held");
  */
 function offloadValue(key, value, path, options, budget) {
     const collector = budget.offload;
+    // A log record uploads only the media in its inspected attributes: anything else is redacted
+    // and cut as before.
+    if (collector.log && (typeof value !== "string" || !isMediaKey(key) || budget.cut?.has(value)))
+        return NOT_HELD;
     if (value instanceof Uint8Array) {
         if (value.byteLength <= budget.valueBytes)
             return NOT_HELD;
@@ -178,6 +182,13 @@ function offloadValue(key, value, path, options, budget) {
     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 (collector.log && !mayInlineFiles(key, result)) {
+        if (Buffer.byteLength(result) <= budget.valueBytes)
+            return result;
+        if (!budget.truncated.includes(key))
+            budget.truncated.push(key);
+        return truncateUtf8(result, budget.valueBytes);
+    }
     if (mayInlineFiles(key, result) ||
         (result.length * 3 > budget.valueBytes && Buffer.byteLength(result) > budget.valueBytes))
         collector.candidates.push({ key, value: result });
@@ -190,18 +201,19 @@ function offloadValue(key, value, path, options, budget) {
  * 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) {
+function redactValue(value, path, options, budget, depth = 0, listAs = path, whole = false) {
     if (++budget.nodes > MAX_RECORD_NODES || depth > 32)
         throw new Error("Telemetry value exceeds the supported nesting limit");
     if (typeof value === "string") {
-        const cap = budget.valueBytes;
+        // `whole`: a log record's body left for the upload step, which cuts what it does not upload.
+        const cap = whole && budget.cut?.has(value) !== true ? Infinity : 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);
+        let result = redactedText(value, path, options, Math.min(cap, budget.valueBytes));
         if (cutWhenQueued && options.redact)
             result = withoutTail(result, REDACTION_CONTEXT_UNITS);
         const bytes = Buffer.byteLength(result);
@@ -214,7 +226,11 @@ function redactValue(value, path, options, budget, depth = 0, listAs = path) {
         if (!budget.truncated.includes(listAs))
             budget.truncated.push(listAs);
         budget.bytes += cap;
-        return truncateUtf8(result, cap);
+        const cut = truncateUtf8(result, cap);
+        // A log body's string the queue cut is no whole file: the upload step leaves it as cut.
+        if (whole && cutWhenQueued && budget.offload)
+            (budget.offload.bodyCut ??= new Set()).add(cut);
+        return cut;
     }
     // 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.
@@ -226,7 +242,7 @@ function redactValue(value, path, options, budget, depth = 0, listAs = path) {
     if (Array.isArray(value)) {
         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));
+        return value.map((item, index) => redactValue(item, `${path}.${index}`, options, budget, depth + 1, listAs, whole));
     }
     if (value instanceof Uint8Array) {
         if (value.byteLength <= budget.valueBytes) {
@@ -241,10 +257,51 @@ function redactValue(value, path, options, budget, depth = 0, listAs = path) {
     if (value !== null && typeof value === "object")
         return Object.fromEntries(Object.entries(value).map(([key, item]) => [
             key,
-            redactValue(item, `${path}.${key}`, options, budget, depth + 1, listAs),
+            redactValue(item, `${path}.${key}`, options, budget, depth + 1, listAs, whole),
         ]));
     return value;
 }
+/**
+ * A log record's body, placed by the upload step, cut as {@link redactLog} cuts one: each string
+ * over the cap cut to it and bytes over it replaced by the receiver's marker, and a structured
+ * body still over the cap replaced by the marker. Whether anything was cut, for `hue.truncated`.
+ */
+export function capLogBody(body, valueBytes) {
+    let cut = false;
+    const visit = (value) => {
+        if (typeof value === "string") {
+            if (Buffer.byteLength(value) <= valueBytes)
+                return value;
+            cut = true;
+            return truncateUtf8(value, valueBytes);
+        }
+        if (value instanceof Uint8Array) {
+            if (value.byteLength <= valueBytes)
+                return value;
+            cut = true;
+            return truncatedMarker(value.byteLength);
+        }
+        if (Array.isArray(value))
+            return value.map(visit);
+        if (value !== null && typeof value === "object")
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, visit(item)]));
+        return value;
+    };
+    const size = structuredBytes(body);
+    const result = visit(body);
+    if (result !== null && typeof result === "object" && structuredBytes(result) > valueBytes)
+        return { body: truncatedMarker(size), cut: true };
+    return { body: result, cut };
+}
+/** Whether a log record is a GenAI event, whose structured body carries messages. */
+export function isGenAiLog(log) {
+    const name = log.eventName ?? log.attributes["event.name"];
+    return typeof name === "string" && name.startsWith("gen_ai.");
+}
+/** Whether a log body is structured (an object or array), so a pointer can address inside it. */
+export function isStructuredBody(body) {
+    return body !== null && typeof body === "object" && !(body instanceof Uint8Array);
+}
 /**
  * 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
@@ -265,7 +322,7 @@ function attributes(source, options, path, budget, listPrefix = "", own = false)
         return [
             [
                 key,
-                redactValue(scrubToolCredentials(key, own ? hashInlineFiles(key, value) : value), `${path}.${key}`, options, budget, 0, `${listPrefix}${key}`),
+                redactValue(scrubToolCredentials(key, own === true ? hashInlineFiles(key, value) : value), `${path}.${key}`, options, budget, 0, `${listPrefix}${key}`),
             ],
         ];
     }));
@@ -371,17 +428,27 @@ export function redactSpan(span, options, cache, limits = {}) {
 }
 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)) > budget.valueBytes) {
-            body = truncatedMarker(structuredBytes(log.body));
-            if (!budget.truncated.includes("body"))
-                budget.truncated.push("body");
+    const offload = limits.offload;
+    let body;
+    if (offload && options.captureContent && isGenAiLog(log) && isStructuredBody(log.body)) {
+        // Left whole for the upload step, which uploads its media and cuts what is left over the cap.
+        body = redactValue(log.body, "body", options, budget, 0, "body", true);
+        offload.body = { value: body };
+    }
+    else {
+        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)) > budget.valueBytes) {
+                body = truncatedMarker(structuredBytes(log.body));
+                if (!budget.truncated.includes("body"))
+                    budget.truncated.push("body");
+            }
         }
     }
-    const redactedAttributes = attributes(log.attributes, options, "attributes", budget);
+    const redactedAttributes = attributes(log.attributes, options, "attributes", budget, "", offload ? "log" : false);
     const resource = redactResource(log.resource, options, cache, budget);
     const scopeAttributes = log.instrumentationScope.attributes
         ? attributes(log.instrumentationScope.attributes, options, "scope.attributes", budget, "scope.")

package/dist/safety.d.ts

@@ -1,4 +1,5 @@
 import { type Span } from "@opentelemetry/api";
+import { Attachment } from "./attachment.js";
 export declare function noopSpan(): Span;
 export declare function safeSpan(source: Span, failed: () => void): Span;
 export declare function spanSource(span: Span): Span;
@@ -10,8 +11,11 @@ export interface EncodeLimits {
 }
 /** One content attribute's bounds under a receiver's value cap of `valueBytes`. */
 export declare function contentLimitsOf(valueBytes: number): EncodeLimits;
+/** Writes an {@link Attachment} met at `pointer`, `depth` levels deep: the JSON value written in
+ * its place. Without one, an attachment is no JSON data. */
+export type PlaceAttachment = (attachment: Attachment, pointer: string, depth: number) => unknown;
 /** Validate a bounded data tree without invoking toJSON or property getters. */
-export declare function encodeContent(value: unknown, limits?: EncodeLimits): string;
+export declare function encodeContent(value: unknown, limits?: EncodeLimits, place?: PlaceAttachment): 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
@@ -22,7 +26,7 @@ export declare function encodeContent(value: unknown, limits?: EncodeLimits): st
  * 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): {
+export declare function encodeBoundedContent(value: unknown, limits?: EncodeLimits, cut?: boolean, place?: PlaceAttachment): {
     text: string;
     truncated: boolean;
 };

package/dist/safety.js

@@ -1,5 +1,6 @@
 import { INVALID_SPAN_CONTEXT, trace } from "@opentelemetry/api";
 import { types as utilTypes } from "node:util";
+import { Attachment, pointerSegment } from "./attachment.js";
 import { MAX_CONTENT_BYTES, MAX_RECORD_NODES } from "./config.js";
 export function noopSpan() {
     return trace.wrapSpanContext(INVALID_SPAN_CONTEXT);
@@ -114,8 +115,8 @@ 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);
+export function encodeContent(value, limits = contentLimits, place) {
+    const { text, truncated } = encodeBoundedContent(value, limits, false, place);
     if (truncated)
         throw new RangeError("Content limit exceeded");
     return text;
@@ -130,12 +131,14 @@ export function encodeContent(value, limits = contentLimits) {
  * 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) {
+export function encodeBoundedContent(value, limits = contentLimits, cut = true, place) {
     let nodes = 0;
     let bytes = 0;
     let truncated = false;
     const parts = [];
     const ancestors = new Set();
+    // The keys from the root to the value being written, kept only to place attachments.
+    const path = [];
     const write = (text) => {
         parts.push(text);
         bytes += Buffer.byteLength(text);
@@ -172,6 +175,11 @@ export function encodeBoundedContent(value, limits = contentLimits, cut = true)
         // The native check also handles revoked proxies without invoking their traps.
         if (utilTypes.isProxy(item))
             throw new TypeError("JSON proxies are unsupported");
+        if (place && item instanceof Attachment) {
+            const pointer = path.length ? `/${path.map(pointerSegment).join("/")}` : "";
+            write(JSON.stringify(place(item, pointer, depth) ?? null));
+            return;
+        }
         const array = Array.isArray(item);
         if (!array && ![Object.prototype, null].includes(Object.getPrototypeOf(item)))
             throw new TypeError("Expected JSON data");
@@ -193,7 +201,11 @@ export function encodeBoundedContent(value, limits = contentLimits, cut = true)
                 throw new TypeError("Expected JSON data property");
             write(`${first ? "" : ","}${array ? "" : `${JSON.stringify(key)}:`}`);
             first = false;
+            if (place)
+                path.push(key);
             visit(descriptor.value, depth + 1);
+            if (place)
+                path.pop();
         }
         write(array ? "]" : "}");
         ancestors.delete(item);

package/dist/snapshot.d.ts

@@ -34,4 +34,4 @@ export interface RecordSnapshot<T> {
     inspected: ReadonlySet<string>;
 }
 export declare function snapshotSpan(source: ReadableSpan, limit: number, captureContent?: boolean, valueUnits?: number, hold?: HoldLimits, memo?: MediaDigestMemo): RecordSnapshot<ReadableSpan>;
-export declare function snapshotLog(source: ReadableLogRecord, limit: number, captureContent?: boolean, valueUnits?: number): RecordSnapshot<ReadWriteLogRecord>;
+export declare function snapshotLog(source: ReadableLogRecord, limit: number, captureContent?: boolean, valueUnits?: number, hold?: HoldLimits, memo?: MediaDigestMemo): RecordSnapshot<ReadWriteLogRecord>;