@hue-run/sdk 0.16.0 → 0.18.0

package/dist/attachment.d.ts

@@ -0,0 +1,82 @@
+/** How deep in a value an attachment's part may sit and still be uploaded: Hue reads media parts
+ * within ten levels of the value's root. */
+export declare const MAX_ATTACHMENT_DEPTH = 10;
+/** Options for {@link Attachment}. Give exactly one of `data` and `path`. */
+export interface AttachmentOptions {
+    /** The file's bytes (a `Buffer`, typed array or `ArrayBuffer`), or a string holding them as
+     * base64 or a `data:` URL. */
+    data?: ArrayBufferView | ArrayBuffer | string;
+    /** A file to read when the attachment is created (Node.js file system). */
+    path?: string;
+    /** The file's media type, such as `image/png` or `application/pdf`. */
+    contentType: string;
+    /** The file name, recorded when `captureContent` is true. */
+    name?: string;
+}
+/** What an attachment holds, read by the client and transport only. */
+export interface AttachmentState {
+    /** The file's bytes; undefined for an attachment that could not be read or is invalid. */
+    bytes?: Uint8Array;
+    sha256?: string;
+    contentType: string;
+    /** The name, when it is a valid media name. */
+    name?: string;
+    /** A name was given and is not a valid media name: it is omitted and counted. */
+    invalidName: boolean;
+}
+/**
+ * A file placed in a recorded value, the equivalent of Langfuse's `LangfuseMedia` and
+ * Braintrust's `Attachment`. Put it anywhere in a `withSpan()` input or output, in `model()`
+ * messages, in a tool's arguments or result, in `recordMessages()` messages or in a span
+ * attribute passed to `withSpan()`. Hue records it at that position as a GenAI `blob` part that
+ * names the file by digest (`{ type: "blob", mime_type, modality, sha256, size, name }`) and
+ * uploads its bytes during export, listed under the record's `hue.blobs`.
+ *
+ * The bytes are read and hashed when the attachment is created; `data` and `path` are limited to
+ * 25 MiB. Creating one never throws: an attachment without exactly one of `data` and `path`, with
+ * unreadable data, larger data or an invalid `contentType` records `null` where it is placed and
+ * counts an instrumentation failure; an invalid `name` alone is omitted and counted.
+ */
+export declare class Attachment {
+    /** The media type given. */
+    readonly contentType: string;
+    /** The name given, when it is a valid media name. */
+    readonly name: string | undefined;
+    /** Lowercase hex SHA-256 of the bytes; undefined for an invalid attachment. */
+    readonly sha256: string | undefined;
+    /** Size of the bytes; undefined for an invalid attachment. */
+    readonly size: number | undefined;
+    constructor(options: AttachmentOptions);
+}
+/** The modality a media type implies, as Hue reads a part's media type. */
+export declare function modalityOf(contentType: string): string;
+/** An attachment's digest-form GenAI part, the name only with content capture; undefined for an
+ * invalid attachment. */
+export declare function attachmentPart(state: AttachmentState, captureContent: boolean): Record<string, unknown> | undefined;
+/** One attachment as a value is encoded: its state, its part (undefined when invalid), and the
+ * JSON pointer and depth of its position. */
+export interface PlacedAttachment {
+    state: AttachmentState;
+    part?: Record<string, unknown>;
+    pointer: string;
+    depth: number;
+}
+/** Whether a value holds an attachment anywhere, within the encoder's bounds. */
+export declare function holdsAttachment(value: unknown): boolean;
+/** A JSON pointer's reference token. */
+export declare function pointerSegment(segment: string): string;
+/** The digest parts in `value` (within {@link MAX_ATTACHMENT_DEPTH}) that are the `files`' own
+ * parts: an object with `type` `blob`, no `content`, and the file's `sha256`, `size` and
+ * `mime_type`. Each found part takes one file of that digest, in the value's order; a part's
+ * `name`, when valid, is the one it carries. */
+export declare function locateParts<T extends {
+    digest: {
+        sha256: string;
+        size: number;
+    };
+    contentType: string;
+}>(value: unknown, files: readonly T[]): {
+    file: T;
+    pointer: string;
+    name?: string;
+}[];

package/dist/attachment.js

@@ -0,0 +1,225 @@
+import { createHash } from "node:crypto";
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { types as utilTypes } from "node:util";
+import { MAX_FILE_DATA_BYTES } from "./config.js";
+import { inlineFileBytes, isMediaContentType, isMediaName } from "./inline-files.js";
+/** How deep in a value an attachment's part may sit and still be uploaded: Hue reads media parts
+ * within ten levels of the value's root. */
+export const MAX_ATTACHMENT_DEPTH = 10;
+const states = new WeakMap();
+/** A strict base64 string: alphabet characters only, padded to a multiple of four. */
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+/** The bytes of a string attachment: a `data:` URL by its own encoding, else strict base64. */
+function stringBytes(text) {
+    if (text.startsWith("data:")) {
+        const decoded = inlineFileBytes(text);
+        return decoded.decoded ? decoded.bytes : undefined;
+    }
+    if (text.length % 4 !== 0 || !BASE64.test(text))
+        return undefined;
+    return Buffer.from(text, "base64");
+}
+/** A file's bytes, read through one descriptor and never past the limit. */
+function fileBytes(path) {
+    const descriptor = openSync(path, "r");
+    try {
+        if (fstatSync(descriptor).size > MAX_FILE_DATA_BYTES)
+            return undefined;
+        // Read to its end, which may lie past its size as stated (a file that grew, a pipe), but
+        // never more than one byte past the limit.
+        const parts = [];
+        let total = 0;
+        for (;;) {
+            const room = Math.min(1 << 20, MAX_FILE_DATA_BYTES + 1 - total);
+            if (room <= 0)
+                return undefined;
+            const buffer = Buffer.alloc(room);
+            const read = readSync(descriptor, buffer, 0, room, null);
+            if (read === 0)
+                break;
+            parts.push(buffer.subarray(0, read));
+            total += read;
+        }
+        return Buffer.concat(parts, total);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function attachmentBytes(options) {
+    const { data, path } = options;
+    if ((data === undefined) === (path === undefined))
+        return undefined;
+    let bytes;
+    if (typeof path === "string")
+        bytes = path ? fileBytes(path) : undefined;
+    else if (typeof data === "string") {
+        if (data.length > 4 * MAX_FILE_DATA_BYTES)
+            return undefined;
+        bytes = stringBytes(data);
+    }
+    // A copy, so a later change to the caller's buffer cannot change what the digest describes;
+    // bytes over the limit are refused before anything is copied.
+    else if (ArrayBuffer.isView(data)) {
+        if (data.byteLength > MAX_FILE_DATA_BYTES)
+            return undefined;
+        bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice();
+    }
+    else if (data instanceof ArrayBuffer) {
+        if (data.byteLength > MAX_FILE_DATA_BYTES)
+            return undefined;
+        bytes = new Uint8Array(data.slice(0));
+    }
+    return bytes && bytes.byteLength <= MAX_FILE_DATA_BYTES ? bytes : undefined;
+}
+/**
+ * A file placed in a recorded value, the equivalent of Langfuse's `LangfuseMedia` and
+ * Braintrust's `Attachment`. Put it anywhere in a `withSpan()` input or output, in `model()`
+ * messages, in a tool's arguments or result, in `recordMessages()` messages or in a span
+ * attribute passed to `withSpan()`. Hue records it at that position as a GenAI `blob` part that
+ * names the file by digest (`{ type: "blob", mime_type, modality, sha256, size, name }`) and
+ * uploads its bytes during export, listed under the record's `hue.blobs`.
+ *
+ * The bytes are read and hashed when the attachment is created; `data` and `path` are limited to
+ * 25 MiB. Creating one never throws: an attachment without exactly one of `data` and `path`, with
+ * unreadable data, larger data or an invalid `contentType` records `null` where it is placed and
+ * counts an instrumentation failure; an invalid `name` alone is omitted and counted.
+ */
+export class Attachment {
+    /** The media type given. */
+    contentType;
+    /** The name given, when it is a valid media name. */
+    name;
+    /** Lowercase hex SHA-256 of the bytes; undefined for an invalid attachment. */
+    sha256;
+    /** Size of the bytes; undefined for an invalid attachment. */
+    size;
+    constructor(options) {
+        const contentType = options?.contentType;
+        const name = options?.name;
+        let bytes;
+        try {
+            bytes = isMediaContentType(contentType) ? attachmentBytes(options) : undefined;
+        }
+        catch {
+            // An unreadable path, or data that is not bytes: the attachment is invalid.
+            bytes = undefined;
+        }
+        const sha256 = bytes ? createHash("sha256").update(bytes).digest("hex") : undefined;
+        this.contentType = typeof contentType === "string" ? contentType : "";
+        this.name = isMediaName(name) ? name : undefined;
+        this.sha256 = sha256;
+        this.size = bytes?.byteLength;
+        states.set(this, {
+            ...(bytes ? { bytes, sha256 } : {}),
+            contentType: this.contentType,
+            ...(this.name === undefined ? {} : { name: this.name }),
+            invalidName: name !== undefined && name !== null && this.name === undefined,
+        });
+    }
+}
+/** @internal The attachment's bytes and validated fields; undefined for anything else. */
+export function attachmentState(value) {
+    return value instanceof Attachment ? states.get(value) : undefined;
+}
+/** The modality a media type implies, as Hue reads a part's media type. */
+export function modalityOf(contentType) {
+    const type = contentType.split(";", 1)[0].trim().toLowerCase();
+    if (type.startsWith("image/"))
+        return "image";
+    if (type.startsWith("audio/"))
+        return "audio";
+    if (type.startsWith("video/"))
+        return "video";
+    if (type.startsWith("text/") ||
+        type === "application/pdf" ||
+        type === "application/rtf" ||
+        type === "application/msword" ||
+        type === "application/vnd.ms-excel" ||
+        type === "application/vnd.ms-powerpoint" ||
+        type.startsWith("application/vnd.openxmlformats-officedocument."))
+        return "document";
+    return "file";
+}
+/** An attachment's digest-form GenAI part, the name only with content capture; undefined for an
+ * invalid attachment. */
+export function attachmentPart(state, captureContent) {
+    if (!state.bytes || !state.sha256)
+        return undefined;
+    return {
+        type: "blob",
+        mime_type: state.contentType,
+        modality: modalityOf(state.contentType),
+        sha256: state.sha256,
+        size: state.bytes.byteLength,
+        ...(captureContent && state.name !== undefined ? { name: state.name } : {}),
+    };
+}
+/** Whether a value holds an attachment anywhere, within the encoder's bounds. */
+export function holdsAttachment(value) {
+    let nodes = 0;
+    const visit = (item, depth) => {
+        // Proxies and accessors are never touched: reading them could run application code.
+        if (item === null || typeof item !== "object" || utilTypes.isProxy(item))
+            return false;
+        if (item instanceof Attachment)
+            return true;
+        if (depth > 32 || ++nodes > 65_536)
+            return false;
+        const prototype = Object.getPrototypeOf(item);
+        if (!Array.isArray(item) && prototype !== Object.prototype && prototype !== null)
+            return false;
+        return Object.keys(item).some((key) => {
+            const descriptor = Object.getOwnPropertyDescriptor(item, key);
+            return (descriptor !== undefined && "value" in descriptor && visit(descriptor.value, depth + 1));
+        });
+    };
+    try {
+        return visit(value, 0);
+    }
+    catch {
+        return false;
+    }
+}
+/** A JSON pointer's reference token. */
+export function pointerSegment(segment) {
+    return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+/** The digest parts in `value` (within {@link MAX_ATTACHMENT_DEPTH}) that are the `files`' own
+ * parts: an object with `type` `blob`, no `content`, and the file's `sha256`, `size` and
+ * `mime_type`. Each found part takes one file of that digest, in the value's order; a part's
+ * `name`, when valid, is the one it carries. */
+export function locateParts(value, files) {
+    const pending = [...files];
+    const found = [];
+    let nodes = 0;
+    const visit = (node, pointer, depth) => {
+        if (!pending.length || depth > MAX_ATTACHMENT_DEPTH || ++nodes > 1_048_576)
+            return;
+        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;
+        if (part.type === "blob" && !Object.hasOwn(part, "content")) {
+            const index = pending.findIndex((file) => part.sha256 === file.digest.sha256 &&
+                part.size === file.digest.size &&
+                part.mime_type === file.contentType);
+            if (index !== -1) {
+                const [file] = pending.splice(index, 1);
+                found.push({
+                    file: file,
+                    pointer,
+                    ...(isMediaName(part.name) ? { name: part.name } : {}),
+                });
+                return;
+            }
+        }
+        for (const [key, item] of Object.entries(part))
+            visit(item, `${pointer}/${pointerSegment(key)}`, depth + 1);
+    };
+    visit(value, "", 0);
+    return found;
+}

package/dist/blobs.d.ts

@@ -1,13 +1,13 @@
+import { type HrTime } from "@opentelemetry/api";
+import { type MediaDigestMemo, type FileDigest } from "./inline-files.js";
 /**
- * Values larger than Hue's inline limit travel apart from their span: the SDK uploads the value's
- * bytes straight to the project's evidence store through a presigned PUT that Hue answers at
- * `POST /api/v1/otlp/blobs`, keeps the value's first 16 KiB in the attribute it replaced, and
- * lists the value in the span attribute `hue.blobs`. A value that cannot be uploaded is exported
- * as it was before uploads existed: cut to the inline limit and listed under `hue.truncated` (an
- * inline file as its digest), reported as a warning and counted.
+ * Large values and binary media travel apart from their span through reservation, presigned PUT,
+ * and completion. Text keeps a 16 KiB prefix. Binary media keeps digest metadata on its part.
+ * Successful uploads are listed in `hue.blobs`; failures keep inline fallback or file metadata,
+ * are reported as warnings, and are counted.
  */
 /** The span attribute listing the values the SDK uploaded apart from the span: one compact JSON
- * object per value, `{"key", "sha256", "size", "content_type"}`, as Hue reads it. */
+ * object per value, `{"key", "sha256", "size", "content_type"}`, with an optional `name`. */
 export declare const BLOBS_KEY = "hue.blobs";
 /** The largest value one upload may hold (`Hue-Max-Blob-Bytes`): a larger value is cut inline. */
 export declare const MAX_BLOB_BYTES = 1000000000;
@@ -24,7 +24,7 @@ export declare const MAX_BLOB_ENTRIES = 64;
 export declare const MAX_HELD_BLOB_BYTES: number;
 /** How long one export may spend uploading its values, on top of its requests. */
 export declare function uploadBudgetMillis(timeoutMillis: number): number;
-/** Why a value over the inline limit was exported cut instead of uploaded. */
+/** Why content kept its fallback instead of being uploaded. */
 export type FallbackReason = "unsupported" | "failed" | "tooLarge" | "budget";
 /** The fixed description of each fallback, as an export issue reports it. */
 export declare const FALLBACK_MESSAGES: Record<FallbackReason, string>;
@@ -38,7 +38,37 @@ export interface OffloadCandidate {
 export interface OffloadCollector {
     candidates: OffloadCandidate[];
     cut: string[];
+    attachments?: MediaAttachment[];
+    /** The span's own attributes admission inspected for media within the record's allowance:
+     * export inspects only these. Absent for a record admission did not copy, and for a log record,
+     * which export inspects within its own allowance. */
+    inspected?: ReadonlySet<string> | undefined;
+    /** Set for a log record: its values over the inline limit are cut, never uploaded whole; only
+     * the media in its inspected attributes and its body upload, with the attachments placed in
+     * its body (`attachments`, keyed `body#<pointer>`). */
+    log?: boolean;
+    /** A log record's structured body, redacted whole, whose media upload under `body#<pointer>`. */
+    body?: {
+        value: unknown;
+    };
+    /** The strings of a log record's body the queue cut when the record was admitted: never read
+     * as files, since their bytes are not the file's. */
+    bodyCut?: Set<string>;
 }
+export interface MediaAttachment {
+    bytes: Uint8Array;
+    digest: FileDigest;
+    contentType: string;
+    name?: string;
+    eventTime?: HrTime;
+    /** For an attachment placed in a value: the record's attribute (or `body`) that holds its part. */
+    attribute?: string;
+    /** For a placed attachment found in its value: its `hue.blobs` key, `<attribute>#<pointer>`. */
+    key?: string;
+}
+/** The `hue.blobs` key of a staged file: its part's for an attachment placed in a value, else
+ * its `hue.file` event's. */
+export declare function mediaKey(file: MediaAttachment): string;
 /** The outcome of one export's uploads, reported once the export's records are placed. */
 export interface OffloadTally {
     uploaded: number;
@@ -48,6 +78,8 @@ export interface OffloadTally {
     }>;
 }
 export declare function newTally(): OffloadTally;
+export declare function countFallback(tally: OffloadTally, reason: FallbackReason, traceId: string): void;
+/** A media type accepted by the upload contract. */
 export declare function isBlobContentType(value: unknown): value is string;
 /** The media type an uploaded text is stored under: JSON when it reads as a JSON object or array
  * (a structured value's text), plain UTF-8 text otherwise. Both are previewed as text. */
@@ -62,6 +94,8 @@ export declare function digestOf(value: string | Uint8Array): Promise<{
     sha256: string;
     size: number;
 }>;
+/** The `hue.blobs` element for one uploaded value. */
+export declare function blobEntry(key: string, sha256: string, size: number, contentType: string, name?: string): string;
 /** What one export's uploads share: their deadline, and the export's hold for a receiver that
  * limited the rate (`wait` resolves false when the hold may not take `millis` more). */
 export interface UploadContext {
@@ -100,6 +134,7 @@ export declare class BlobUploader {
     private running;
     private waiting;
     private requests;
+    private outcomes;
     constructor(options: UploaderOptions);
     /** Whether a value over the inline limit is worth holding whole for upload now. */
     available(): boolean;
@@ -114,12 +149,12 @@ export declare class BlobUploader {
     private pause;
     /**
      * Stores `value` under `key` of the trace: reserved, uploaded unless Hue already holds it, and
-     * completed. The caller holds a {@link limit} slot.
+     * completed. Only a fresh upload takes a {@link limit} slot: another reference to bytes the
+     * trace is already storing shares that upload's outcome without one, so repeated files never
+     * hold the slots new files need. The caller must not hold a slot.
      */
-    store(traceId: string, key: string, value: string | Uint8Array, contentType: string, digest: {
-        sha256: string;
-        size: number;
-    }, upload: UploadContext): Promise<Outcome>;
+    store(traceId: string, key: string, value: string | Uint8Array, contentType: string, digest: FileDigest, upload: UploadContext): Promise<Outcome>;
+    private storeFresh;
     private jsonHeaders;
     /** Reserves the value: Hue answers that it holds it already, or a presigned PUT. A rate limit
      * is waited out within the export's hold, a transient refusal retried once. */
@@ -145,20 +180,41 @@ export interface OffloadOptions {
     valueBytes: number;
     upload: UploadContext;
     tally: OffloadTally;
+    memo?: MediaDigestMemo;
 }
 /**
- * A span's own attributes with each candidate placed: an inline file part over 64 KiB in a
- * recorded message uploaded and replaced by its first 16 KiB (or by its digest, as before, when
- * it could not be), and a value still over the inline limit uploaded and replaced by its first
+ * A span's own attributes with each candidate placed: binary media becomes a digest, while
+ * text media over 64 KiB retains a 16 KiB prefix after upload or a digest on failure.
+ * A value still over the inline limit is uploaded and replaced by its first
  * 16 KiB (or cut to the limit), each upload listed under `hue.blobs`, each whole value cut or
  * uploaded listed under `hue.truncated`. Every fallback is counted in the tally.
  */
 export declare function offloadAttributes(attributes: Record<string, unknown>, collector: OffloadCollector, options: OffloadOptions): Promise<Record<string, unknown>>;
+/**
+ * A record's own attributes, and a log record's body, with each candidate placed (see
+ * {@link offloadAttributes}). A file is uploaded and placed in its digest form (a text file in a
+ * provider part keeps a 16 KiB prefix), its `hue.blobs` entry keyed `<attribute>#<pointer>` or, in
+ * a log record's body, `body#<pointer>`. A file that is not uploaded keeps its bytes inline, except
+ * in a span's own recorded messages, where it keeps its digest as before. A log record's values
+ * over the inline limit are cut, never uploaded whole, and a body still over it is replaced by the
+ * receiver's marker, as before.
+ */
+export declare function offloadRecord(attributes: Record<string, unknown>, collector: OffloadCollector, options: OffloadOptions): Promise<{
+    attributes: Record<string, unknown>;
+    body?: unknown;
+}>;
 /**
  * The span's own attributes with every candidate placed as it was before uploads existed, for an
  * upload step that failed unexpectedly: a message's large inline files as their digest, a value
  * over the inline limit cut to it (bytes replaced by the receiver's marker) and listed under
  * `hue.truncated`.
  */
-export declare function fallbackAttributes(attributes: Record<string, unknown>, collector: OffloadCollector, valueBytes: number, tally: OffloadTally, traceId: string): Record<string, unknown>;
+export declare function fallbackAttributes(attributes: Record<string, unknown>, collector: OffloadCollector, valueBytes: number, tally: OffloadTally, traceId: string, memo?: MediaDigestMemo): Record<string, unknown>;
+/** A record's attributes, and a log record's body, placed as {@link fallbackAttributes} places
+ * them: a log record's files keep their bytes inline, and its body over the inline limit is
+ * replaced by the receiver's marker, as before. */
+export declare function fallbackRecord(attributes: Record<string, unknown>, collector: OffloadCollector, valueBytes: number, tally: OffloadTally, traceId: string, memo?: MediaDigestMemo): {
+    attributes: Record<string, unknown>;
+    body?: unknown;
+};
 export {};