@hue-run/sdk 0.1.4 → 0.2.0

package/dist/managed.d.ts

@@ -1,65 +1,115 @@
 import { type Tracer } from "@opentelemetry/api";
 import type { JsonValue } from "./types.js";
+/** A declared input file the handler downloads and verifies before calling the target. */
 export interface ManagedInputFile {
+    /** Hue artifact ID. */
     artifactId: string;
+    /** File name without path separators. */
     filename: string;
+    /** MIME type. */
     contentType: string;
+    /** Exact size in bytes; verified after download. */
     byteSize: number;
+    /** Lowercase hex SHA-256 of the bytes; verified after download. */
     sha256: string;
+    /** Caller-defined role of the file in the case, up to 64 characters. */
     role: string;
 }
+/** The request body Hue POSTs to a managed target (protocol version 1). */
 export interface ManagedInvocation {
+    /** Always 1. */
     protocolVersion: 1;
+    /** Execution to claim and complete. */
     executionId: string;
+    /** Attempt number, starting at 1. */
     attempt: number;
+    /** Frozen case inputs. */
     input: JsonValue;
+    /** Experiment configuration. */
     config: JsonValue;
+    /** Up to 16 declared input files. */
     inputFiles: ManagedInputFile[];
+    /** RFC 3339 UTC deadline for the whole invocation. */
     deadline: string;
+    /** Sampled W3C `traceparent` the target span must continue. */
     traceparent: string;
 }
+/** What the target callback receives after the claim and file verification succeed. */
 export interface ManagedTargetContext {
+    /** Execution being run. */
     executionId: string;
+    /** Attempt number, starting at 1. */
     attempt: number;
+    /** Frozen case inputs. */
     input: JsonValue;
+    /** Experiment configuration. */
     config: JsonValue;
+    /** Verified input files with their bytes. */
     inputFiles: Array<ManagedInputFile & {
+        /** Verified file contents. */
         data: Uint8Array;
     }>;
+    /** Aborts at the execution deadline; the target must honor it. */
     signal: AbortSignal;
+    /** Trace ID of the `ai.managed_target` span the target runs under. */
     traceId: string;
 }
+/** A file the target returns for upload. */
 export interface ManagedOutputFile {
+    /** File name without path separators. */
     filename: string;
+    /** MIME type. */
     contentType: string;
+    /** Exact bytes to store, at most 25 MiB. */
     data: Uint8Array;
+    /** Marks the single primary artifact of the outcome. */
     primary?: boolean;
 }
+/** The target callback's return value. */
 export interface ManagedTargetResult {
+    /** Outcome state; `succeeded` by default. */
     state?: "succeeded" | "error" | "cancelled";
+    /** Output JSON; omitted means unavailable, `null` is a present output. */
     output?: JsonValue;
     /** Public, safe error summary. Never include provider errors, credentials or stacks. */
     error?: {
+        /** Stable lowercase type such as `target_error`. */
         type: string;
+        /** Bounded public message. */
         message?: string;
     };
+    /** Up to 16 files, 64 MiB in total. */
     files?: ManagedOutputFile[];
+    /** Provider-reported token usage, when known. */
     usage?: {
+        /** Prompt tokens. */
         inputTokens?: number;
+        /** Completion tokens. */
         outputTokens?: number;
     };
 }
+/** Options for {@link createManagedTargetHandler}. */
 export interface ManagedTargetOptions {
+    /** Dedicated shared secret Hue presents as a Bearer token; validated before any network access. */
     machineCredential: string;
+    /** Hue origin for invocation callbacks, `https://app.hue.run` by default; never taken from a request. */
     baseUrl?: string;
+    /** The application's existing agent function; called at most once per invocation. */
     target: (invocation: ManagedTargetContext) => Promise<ManagedTargetResult>;
     /** Flush the application's existing trace AND log pipelines; do not shut them down. */
     flushTelemetry: () => Promise<unknown>;
+    /** Tracer that records under the incoming trace context; defaults to the global tracer, which must be configured. */
     tracer?: Tracer;
     /** Reserve finalization time inside the host's request limit. Default 90 seconds. */
     maxExecutionMillis?: number;
     /** Upload/checkpoint/flush grace after execution deadline, at most 30 seconds. */
     finalizationMillis?: number;
 }
-/** A machine-authenticated, framework-neutral POST handler. Never retries the target. */
+/**
+ * Creates a machine-authenticated, framework-neutral POST handler that claims the invocation,
+ * verifies input files, runs `target` under the incoming trace context, uploads output files,
+ * saves the outcome and acknowledges telemetry. It never retries the target.
+ *
+ * @throws TypeError for an invalid credential, origin, budget or missing callbacks at construction.
+ */
 export declare function createManagedTargetHandler(options: ManagedTargetOptions): (request: Request) => Promise<Response>;

package/dist/managed.js

@@ -21,7 +21,13 @@ const STATES = new Set([
     "superseded",
 ]);
 const propagator = new W3CTraceContextPropagator();
-/** A machine-authenticated, framework-neutral POST handler. Never retries the target. */
+/**
+ * Creates a machine-authenticated, framework-neutral POST handler that claims the invocation,
+ * verifies input files, runs `target` under the incoming trace context, uploads output files,
+ * saves the outcome and acknowledges telemetry. It never retries the target.
+ *
+ * @throws TypeError for an invalid credential, origin, budget or missing callbacks at construction.
+ */
 export function createManagedTargetHandler(options) {
     token(options.machineCredential);
     const baseUrl = validateOptions({
@@ -343,6 +349,7 @@ function sha256(data) {
     return createHash("sha256").update(data).digest("hex");
 }
 function token(value) {
+    // eslint-disable-next-line no-control-regex -- control characters are rejected deliberately
     if (typeof value !== "string" || !value || value.length > 8192 || /[\s\u0000]/u.test(value))
         throw new TypeError("Invalid credential");
     return value;
@@ -364,6 +371,7 @@ function filename(value) {
     if (typeof value !== "string" ||
         !value.trim() ||
         value.length > 255 ||
+        // eslint-disable-next-line no-control-regex -- control characters are rejected deliberately
         /[\x00-\x1f\x7f/\\]/u.test(value) ||
         value === "." ||
         value === "..")
@@ -374,6 +382,7 @@ function shortString(value, maximum = 255) {
     if (typeof value !== "string" ||
         !value ||
         value.length > maximum ||
+        // eslint-disable-next-line no-control-regex -- control characters are rejected deliberately
         /[\x00-\x1f\x7f]/u.test(value))
         throw new TypeError("Invalid string");
     return value;
@@ -466,6 +475,7 @@ function validateResult(result) {
         throw new TypeError("Invalid output files");
 }
 function safeUploadUrl(value) {
+    // eslint-disable-next-line no-control-regex -- control characters are rejected deliberately
     if (typeof value !== "string" || value.length > 8192 || /[\x00-\x20\x7f]/u.test(value))
         throw new TypeError("Invalid upload URL");
     const url = new URL(value);

package/dist/privacy.d.ts

@@ -2,6 +2,8 @@ import type { ReadableSpan } from "@opentelemetry/sdk-trace";
 import type { ReadableLogRecord } from "@opentelemetry/sdk-logs";
 import { type Resource } from "@opentelemetry/resources";
 import type { HueOptions } from "./types.js";
+/** Attribute keys (and their dotted children) removed in metadata-only mode. */
+export declare const contentPrefixes: string[];
 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;

package/dist/privacy.js

@@ -1,6 +1,7 @@
 import { resourceFromAttributes } from "@opentelemetry/resources";
-import { MAX_CONTENT_BYTES } from "./config.js";
-const contentPrefixes = [
+import { MAX_BODY_BYTES, MAX_CONTENT_BYTES } from "./config.js";
+/** Attribute keys (and their dotted children) removed in metadata-only mode. */
+export const contentPrefixes = [
     "gen_ai.input.messages",
     "gen_ai.output.messages",
     "gen_ai.system_instructions",
@@ -15,11 +16,25 @@ const contentPrefixes = [
     "llm.prompts",
     "llm.completions",
     "llm.invocation_parameters",
+    "llm.prompt_template.template",
+    "llm.prompt_template.variables",
+    "llm.tools",
+    "llm.function_call",
+    "llm.choices",
     "input.value",
     "output.value",
+    "input.images",
+    "output.images",
+    "retrieval.documents",
+    "embedding.embeddings",
+    "reranker.query",
+    "reranker.input_documents",
+    "reranker.output_documents",
     "ai.prompt",
     "ai.response.text",
     "ai.response.object",
+    "ai.response.reasoning",
+    "ai.response.files",
     "ai.response.toolCalls",
     "ai.response.body",
     "ai.toolCall.args",
@@ -38,45 +53,62 @@ const contentPrefixes = [
 function isContentKey(key) {
     return contentPrefixes.some((prefix) => key === prefix || key.startsWith(`${prefix}.`));
 }
-function redactValue(value, path, options, depth = 0) {
-    if (depth > 32)
+function redactValue(value, path, options, budget, depth = 0) {
+    if (++budget.nodes > 16384 || depth > 32)
         throw new Error("Telemetry value exceeds the supported nesting limit");
     if (typeof value === "string") {
         const result = options.redact ? options.redact(value, path) : value;
-        if (typeof result !== "string" || !result.isWellFormed() || result.includes("\u0000"))
+        // 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(() => { });
+        if (typeof result !== "string" ||
+            result.length > MAX_CONTENT_BYTES ||
+            !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;
     }
-    if (Array.isArray(value))
-        return value.map((item, index) => redactValue(item, `${path}.${index}`, options, depth + 1));
+    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));
+    }
     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 !== null && typeof value === "object")
         return Object.fromEntries(Object.entries(value).map(([key, item]) => [
             key,
-            redactValue(item, `${path}.${key}`, options, depth + 1),
+            redactValue(item, `${path}.${key}`, options, budget, depth + 1),
         ]));
     return value;
 }
-function attributes(source, options, path) {
+function attributes(source, options, path, budget) {
     return Object.fromEntries(Object.entries(source).flatMap(([key, value]) => !options.captureContent && isContentKey(key)
         ? []
-        : [[key, redactValue(value, `${path}.${key}`, options)]]));
+        : [[key, redactValue(value, `${path}.${key}`, options, budget)]]));
 }
-function redactResource(resource, options, cache) {
+function redactResource(resource, options, cache, budget) {
     let result = cache.get(resource);
     if (!result) {
-        result = resourceFromAttributes(attributes(resource.attributes, options, "resource.attributes"), { schemaUrl: resource.schemaUrl });
+        result = resourceFromAttributes(attributes(resource.attributes, options, "resource.attributes", budget), { schemaUrl: resource.schemaUrl });
         cache.set(resource, result);
     }
     return result;
 }
 export function redactSpan(span, options, cache) {
+    const budget = { bytes: 0, nodes: 0 };
     return {
         name: span.name,
         kind: span.kind,
@@ -89,22 +121,22 @@ export function redactSpan(span, options, cache) {
         status: {
             code: span.status.code,
             ...(options.captureContent && span.status.message !== undefined
-                ? { message: String(redactValue(span.status.message, "status.message", options)) }
+                ? { message: String(redactValue(span.status.message, "status.message", options, budget)) }
                 : {}),
         },
-        attributes: attributes(span.attributes, options, "attributes"),
+        attributes: attributes(span.attributes, 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}`),
+            attributes: attributes(event.attributes ?? {}, options, `events.${event.name}`, budget),
         })),
         links: span.links.map((link) => ({
             ...link,
-            attributes: attributes(link.attributes ?? {}, options, "links.attributes"),
+            attributes: attributes(link.attributes ?? {}, options, "links.attributes", budget),
         })),
-        resource: redactResource(span.resource, options, cache),
+        resource: redactResource(span.resource, options, cache, budget),
         instrumentationScope: span.instrumentationScope,
         droppedAttributesCount: span.droppedAttributesCount,
         droppedEventsCount: span.droppedEventsCount,
@@ -112,7 +144,8 @@ export function redactSpan(span, options, cache) {
     };
 }
 export function redactLog(log, options, cache) {
-    const body = options.captureContent ? redactValue(log.body, "body", options) : undefined;
+    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");
     return {
@@ -123,13 +156,13 @@ export function redactLog(log, options, cache) {
         severityNumber: log.severityNumber,
         eventName: log.eventName,
         body: body,
-        attributes: attributes(log.attributes, options, "attributes"),
-        resource: redactResource(log.resource, options, cache),
+        attributes: attributes(log.attributes, options, "attributes", budget),
+        resource: redactResource(log.resource, options, cache, budget),
         instrumentationScope: {
             ...log.instrumentationScope,
             ...(log.instrumentationScope.attributes
                 ? {
-                    attributes: attributes(log.instrumentationScope.attributes, options, "scope.attributes"),
+                    attributes: attributes(log.instrumentationScope.attributes, options, "scope.attributes", budget),
                 }
                 : {}),
         },

package/dist/receipt.d.ts

@@ -1,8 +1,19 @@
 import type { HueOptions, TraceVerification, VerifyTraceOptions } from "./types.js";
+/**
+ * Thrown by {@link HueClient.verifyTrace} when verification cannot proceed: denied key, unsupported
+ * or refusing server, unreachable network or an invalid receipt. A timeout is not an error; it
+ * returns `verified: false`.
+ */
 export declare class HueTraceVerificationError extends Error {
+    /** Safe failure class for branching without parsing the message. */
     readonly code: "authentication" | "http" | "invalid_response" | "transport";
+    /** HTTP status when Hue answered. */
     readonly status?: number | undefined;
-    constructor(code: "authentication" | "http" | "invalid_response" | "transport", message: string, status?: number | undefined);
+    constructor(
+    /** Safe failure class for branching without parsing the message. */
+    code: "authentication" | "http" | "invalid_response" | "transport", message: string, 
+    /** HTTP status when Hue answered. */
+    status?: number | undefined);
 }
 /** Observe persisted evidence after the application and its exporter have finished. */
 export declare function verifyTrace(connection: Pick<HueOptions, "apiKey"> & {

package/dist/receipt.js

@@ -1,9 +1,18 @@
 const fields = ["input", "output", "model", "usage", "session"];
 const MAX_RESPONSE_BYTES = 64 * 1024;
+/**
+ * Thrown by {@link HueClient.verifyTrace} when verification cannot proceed: denied key, unsupported
+ * or refusing server, unreachable network or an invalid receipt. A timeout is not an error; it
+ * returns `verified: false`.
+ */
 export class HueTraceVerificationError extends Error {
     code;
     status;
-    constructor(code, message, status) {
+    constructor(
+    /** Safe failure class for branching without parsing the message. */
+    code, message, 
+    /** HTTP status when Hue answered. */
+    status) {
         super(message);
         this.code = code;
         this.status = status;

package/dist/safety.d.ts

@@ -0,0 +1,7 @@
+import { type Span } from "@opentelemetry/api";
+export declare function noopSpan(): Span;
+export declare function safeSpan(source: Span, failed: () => void): Span;
+/** Validate a bounded data tree without invoking toJSON or property getters. */
+export declare function encodeContent(value: unknown): 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

@@ -0,0 +1,179 @@
+import { INVALID_SPAN_CONTEXT, trace } from "@opentelemetry/api";
+import { types as utilTypes } from "node:util";
+import { MAX_CONTENT_BYTES } from "./config.js";
+export function noopSpan() {
+    return trace.wrapSpanContext(INVALID_SPAN_CONTEXT);
+}
+/** Isolate the public Span interface without changing its fluent method contract. */
+class SafeSpan {
+    source;
+    failed;
+    constructor(source, failed) {
+        this.source = source;
+        this.failed = failed;
+    }
+    write(work) {
+        try {
+            const result = work();
+            // Broken/custom providers can return rejected promises from synchronous
+            // OTel methods. Observe them without awaiting on application code paths.
+            if (result && typeof result.then === "function")
+                void Promise.resolve(result).catch(this.failed);
+        }
+        catch {
+            this.failed();
+        }
+    }
+    spanContext() {
+        try {
+            const ids = this.source.spanContext();
+            if (!ids || typeof ids.traceId !== "string" || typeof ids.spanId !== "string")
+                throw new TypeError("Invalid span context");
+            return {
+                traceId: ids.traceId,
+                spanId: ids.spanId,
+                traceFlags: ids.traceFlags,
+                isRemote: ids.isRemote,
+                traceState: ids.traceState,
+            };
+        }
+        catch {
+            this.failed();
+            return INVALID_SPAN_CONTEXT;
+        }
+    }
+    isRecording() {
+        try {
+            return this.source.isRecording() === true;
+        }
+        catch {
+            this.failed();
+            return false;
+        }
+    }
+    setAttribute(...args) {
+        this.write(() => this.source.setAttribute(...args));
+        return this;
+    }
+    setAttributes(...args) {
+        this.write(() => this.source.setAttributes(...args));
+        return this;
+    }
+    addEvent(...args) {
+        this.write(() => this.source.addEvent(...args));
+        return this;
+    }
+    addLink(...args) {
+        this.write(() => this.source.addLink(...args));
+        return this;
+    }
+    addLinks(...args) {
+        this.write(() => this.source.addLinks(...args));
+        return this;
+    }
+    setStatus(...args) {
+        this.write(() => this.source.setStatus(...args));
+        return this;
+    }
+    updateName(...args) {
+        this.write(() => this.source.updateName(...args));
+        return this;
+    }
+    end(...args) {
+        this.write(() => this.source.end(...args));
+    }
+    recordException(...args) {
+        this.write(() => this.source.recordException(...args));
+    }
+}
+export function safeSpan(source, failed) {
+    return new SafeSpan(source, failed);
+}
+/** Validate a bounded data tree without invoking toJSON or property getters. */
+export function encodeContent(value) {
+    let nodes = 0;
+    let bytes = 0;
+    const ancestors = new Set();
+    const charge = (amount) => {
+        bytes += amount;
+        if (bytes > MAX_CONTENT_BYTES)
+            throw new RangeError("Content limit exceeded");
+    };
+    const visit = (item, depth) => {
+        if (++nodes > 16384 || depth > 32)
+            throw new RangeError("Content complexity limit exceeded");
+        if (typeof item === "string") {
+            if (item.length > MAX_CONTENT_BYTES)
+                throw new RangeError("Content limit exceeded");
+            charge(Buffer.byteLength(JSON.stringify(item)));
+            return item;
+        }
+        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;
+        }
+        if (!item || typeof item !== "object" || ancestors.has(item))
+            throw new TypeError("Invalid JSON");
+        // Even descriptor/prototype reads can execute application code on a Proxy.
+        // The native check also handles revoked proxies without invoking their traps.
+        if (utilTypes.isProxy(item))
+            throw new TypeError("JSON proxies are unsupported");
+        const array = Array.isArray(item);
+        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);
+        // Own descriptors avoid executing application accessors during capture.
+        const keys = array
+            ? Array.from({ length: Math.min(item.length, 16385) }, (_, i) => String(i))
+            : Object.keys(item);
+        if (keys.length > 16384)
+            throw new RangeError("Content complexity limit exceeded");
+        for (const key of keys) {
+            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;
+        }
+        ancestors.delete(item);
+        return result;
+    };
+    const encoded = JSON.stringify(visit(value, 0));
+    if (Buffer.byteLength(encoded) > MAX_CONTENT_BYTES)
+        throw new RangeError("Content limit exceeded");
+    return encoded;
+}
+/** Bounded conservative accounting for the record data retained by our queue, not total process RSS. */
+export function estimateRecordBytes(value, limit) {
+    let bytes = 0;
+    let nodes = 0;
+    const seen = new Set();
+    const visit = (item, depth) => {
+        if (++nodes > 16384 || depth > 32)
+            throw new RangeError("Telemetry complexity limit exceeded");
+        bytes += 16;
+        if (typeof item === "string")
+            bytes += item.length * 2;
+        else if (item instanceof Uint8Array)
+            bytes += item.byteLength;
+        else if (item && typeof item === "object" && !seen.has(item)) {
+            seen.add(item);
+            for (const [key, child] of Object.entries(item)) {
+                bytes += key.length * 2 + 16;
+                visit(child, depth + 1);
+            }
+        }
+        if (bytes > limit)
+            throw new RangeError("Telemetry byte limit exceeded");
+    };
+    visit(value, 0);
+    return bytes;
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,12 @@
+import type { ReadableSpan } from "@opentelemetry/sdk-trace";
+import type { ReadableLogRecord, ReadWriteLogRecord } from "@opentelemetry/sdk-logs";
+export declare function snapshotSpan(source: ReadableSpan, limit: number): {
+    record: ReadableSpan;
+    bytes: number;
+    unresolvedResource: boolean;
+};
+export declare function snapshotLog(source: ReadableLogRecord, limit: number): {
+    record: ReadWriteLogRecord;
+    bytes: number;
+    unresolvedResource: boolean;
+};