@hue-run/sdk 0.1.5 → 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_BODY_BYTES, MAX_CONTENT_BYTES } from "./config.js";
-const contentPrefixes = [
+/** 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",

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

@@ -1,8 +1,7 @@
 import { type Span } from "@opentelemetry/api";
-import type { JsonValue } from "./types.js";
 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: JsonValue): string;
+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/snapshot.js

@@ -1,7 +1,11 @@
 import { createTraceState } from "@opentelemetry/api";
 import { types as utilTypes } from "node:util";
 import { resourceFromAttributes } from "@opentelemetry/resources";
+// Intrinsic accessors are captured once and invoked with an explicit receiver so a
+// hostile object cannot override them; the unbound reference is the point.
+// eslint-disable-next-line @typescript-eslint/unbound-method
 const typedArrayByteLength = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), "byteLength").get;
+// eslint-disable-next-line @typescript-eslint/unbound-method
 const typedArraySet = Uint8Array.prototype.set;
 /** Copies only exported data, with the same finite budget used for admission. */
 class Snapshot {

package/dist/transport.d.ts

@@ -1,17 +1,35 @@
 import { type ReadableSpan, type SpanProcessor } from "@opentelemetry/sdk-trace";
 import { type LogRecordProcessor, type ReadableLogRecord } from "@opentelemetry/sdk-logs";
 import { validateOptions } from "./config.js";
-import type { ExportIssue, ExportReport, HueOptions, Signal } from "./types.js";
-type RecordValue = ReadableSpan | ReadableLogRecord;
+import type { ExportIssue, ExportReport, HueOptions } from "./types.js";
+/** A finished span or emitted log record as the OpenTelemetry SDK hands it to a processor. */
+export type RecordValue = ReadableSpan | ReadableLogRecord;
+/**
+ * Rejection of {@link HueClient.flush} and {@link HueClient.shutdown}: telemetry was not fully
+ * accepted. Carries sanitized counts only, never server response text or content.
+ */
 export declare class HueExportError extends Error {
+    /** Non-warning issues observed since the failing drain began. */
     readonly issues: ExportIssue[];
+    /** Cumulative counters and current gauges at the time of the failure. */
     readonly report: ExportReport;
-    constructor(issues: ExportIssue[], report: ExportReport);
+    constructor(
+    /** Non-warning issues observed since the failing drain began. */
+    issues: ExportIssue[], 
+    /** Cumulative counters and current gauges at the time of the failure. */
+    report: ExportReport);
 }
-/** Owned transport components; attach processors during provider construction. */
+/**
+ * Hue's export pipeline: OTLP/HTTP exporters behind bounded batch processors, with cumulative
+ * counters and a sanitized issue history. A client owns one; in attach mode the application attaches
+ * `spanProcessor` and `logRecordProcessor` to its own providers while constructing them.
+ */
 export declare class HueTransport {
+    /** Validated options with defaults applied; `baseUrl` is the origin. Not enumerable, so it does not leak the key when logged. */
     readonly options: ReturnType<typeof validateOptions>;
+    /** Span processor to attach to a tracer provider; a no-op when disabled. */
     readonly spanProcessor: SpanProcessor;
+    /** Log record processor to attach to a logger provider; a no-op when disabled. */
     readonly logRecordProcessor: LogRecordProcessor;
     private sequence;
     private observedSequence;
@@ -34,17 +52,31 @@ export declare class HueTransport {
     private flushPromise?;
     constructor(options: HueOptions);
     private enqueue;
-    finish(signal: Signal, records: RecordValue[]): void;
-    acceptedRecords(signal: Signal, count: number): void;
-    issue(signal: Signal, kind: ExportIssue["kind"], count: number, message: string, status?: number): void;
-    instrumentationFailure(signal?: Signal): void;
+    /** Cumulative counters and current queue gauges. */
     getReport(): ExportReport;
+    /** Copies of the latest 128 sanitized issues, oldest first. */
     getIssues(): ExportIssue[];
     /** Monotonic failure marker, retained even when the bounded issue history rolls over. */
     getFailureSequence(): number;
+    /**
+     * Waits for the processors' and exporters' in-flight work; drain the providers first.
+     *
+     * @throws HueExportError when a new non-warning issue was recorded since the previous observation.
+     */
     flush(): Promise<ExportReport>;
     private flushOnce;
+    /**
+     * Flushes and stops the processors; records emitted afterwards are dropped and counted. In attach
+     * mode call it after shutting down the application's providers.
+     *
+     * @throws HueExportError when the final flush observed new failures.
+     */
     shutdown(): Promise<ExportReport>;
 }
+/**
+ * Creates the export pipeline for attach mode; pass it with the application's providers to
+ * {@link createHue}. Validates options like an owned client.
+ *
+ * @throws TypeError for invalid options; see {@link createHue}.
+ */
 export declare function createHueTransport(options: HueOptions): HueTransport;
-export {};

package/dist/transport.js

@@ -1,13 +1,16 @@
 import { ExportResultCode } from "@opentelemetry/core";
 import { CompressionAlgorithm, OTLPExporterBase, OTLPExporterError, } from "@opentelemetry/otlp-exporter-base";
-import { convertLegacyHttpOptions, createOtlpHttpExportDelegate, } from "@opentelemetry/otlp-exporter-base/node-http";
+import { createOtlpHttpExportDelegate } from "@opentelemetry/otlp-exporter-base/node-http";
 import { LogsExporterMetricsHelper, ProtobufLogsSerializer, ProtobufTraceSerializer, TraceExporterMetricsHelper, } from "@opentelemetry/otlp-transformer";
 import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace";
 import { BatchLogRecordProcessor, } from "@opentelemetry/sdk-logs";
-import { MAX_BODY_BYTES, validateOptions } from "./config.js";
+import { isInsecureOrigin, MAX_BODY_BYTES, validateOptions } from "./config.js";
 import { estimateRecordBytes } from "./safety.js";
 import { snapshotLog, snapshotSpan } from "./snapshot.js";
 import { redactLog, redactSpan } from "./privacy.js";
+import { sdkVersion } from "./version.js";
+/** Per-record allowance for protobuf length prefixes that grow when records are grouped. */
+const RECORD_FRAMING_BYTES = 64;
 function recordData(record, signal) {
     if (signal === "traces") {
         const span = record;
@@ -31,20 +34,35 @@ function recordData(record, signal) {
         scope: log.instrumentationScope,
     };
 }
+/**
+ * Rejection of {@link HueClient.flush} and {@link HueClient.shutdown}: telemetry was not fully
+ * accepted. Carries sanitized counts only, never server response text or content.
+ */
 export class HueExportError extends Error {
     issues;
     report;
-    constructor(issues, report) {
+    constructor(
+    /** Non-warning issues observed since the failing drain began. */
+    issues, 
+    /** Cumulative counters and current gauges at the time of the failure. */
+    report) {
         super("Hue could not accept all telemetry. Inspect issues and report for sanitized counts.");
         this.issues = issues;
         this.report = report;
         this.name = "HueExportError";
     }
 }
-/** Owned transport components; attach processors during provider construction. */
+/**
+ * Hue's export pipeline: OTLP/HTTP exporters behind bounded batch processors, with cumulative
+ * counters and a sanitized issue history. A client owns one; in attach mode the application attaches
+ * `spanProcessor` and `logRecordProcessor` to its own providers while constructing them.
+ */
 export class HueTransport {
+    /** Validated options with defaults applied; `baseUrl` is the origin. Not enumerable, so it does not leak the key when logged. */
     options;
+    /** Span processor to attach to a tracer provider; a no-op when disabled. */
     spanProcessor;
+    /** Log record processor to attach to a logger provider; a no-op when disabled. */
     logRecordProcessor;
     sequence = 0;
     observedSequence = 0;
@@ -75,6 +93,8 @@ export class HueTransport {
             this.logRecordProcessor = { onEmit() { }, async forceFlush() { }, async shutdown() { } };
             return;
         }
+        if (isInsecureOrigin(this.options.baseUrl))
+            this.issue("traces", "warning", 0, "allowInsecureHttp is set: telemetry and the project key are sent over plain HTTP to a host that is not loopback");
         const batching = {
             maxQueueSize: 2048,
             maxExportBatchSize: 128,
@@ -159,6 +179,7 @@ export class HueTransport {
             return undefined;
         }
     }
+    /** @internal Exporter callback: releases queued records after an export attempt settles. */
     finish(signal, records) {
         for (const record of records) {
             const pending = signal === "traces" ? this.spans : this.logs;
@@ -166,9 +187,11 @@ export class HueTransport {
             pending.delete(record);
         }
     }
+    /** @internal Exporter callback: counts records the collector acknowledged. */
     acceptedRecords(signal, count) {
         this.accepted[signal] += count;
     }
+    /** @internal Records a sanitized issue, updates counters and rate-limits the diagnostic callback. */
     issue(signal, kind, count, message, status) {
         if (kind === "dropped")
             this.dropped[signal] += count;
@@ -195,7 +218,10 @@ export class HueTransport {
             !this.diagnosticPending &&
             Date.now() - this.lastDiagnosticAt >= 1000) {
             this.diagnosticPending = true;
-            this.lastDiagnosticAt = Date.now();
+            // Warnings (for example the allowInsecureHttp notice) do not consume the slot, so the first
+            // real failure still reaches the callback promptly.
+            if (kind !== "warning")
+                this.lastDiagnosticAt = Date.now();
             void Promise.resolve()
                 .then(() => this.options.onExportIssue?.({ ...issue }))
                 .then(() => {
@@ -205,10 +231,12 @@ export class HueTransport {
             });
         }
     }
-    instrumentationFailure(signal = "traces") {
+    /** @internal Counts a helper capture or instrumentation failure that preserved application execution. */
+    instrumentationFailure(signal = "traces", message = "Telemetry capture or instrumentation failed; application execution was preserved") {
         this.instrumentationFailures++;
-        this.issue(signal, "invalid", 0, "Telemetry capture or instrumentation failed; application execution was preserved");
+        this.issue(signal, "invalid", 0, message);
     }
+    /** Cumulative counters and current queue gauges. */
     getReport() {
         return {
             acceptedSpans: this.accepted.traces,
@@ -225,6 +253,7 @@ export class HueTransport {
             instrumentationFailures: this.instrumentationFailures,
         };
     }
+    /** Copies of the latest 128 sanitized issues, oldest first. */
     getIssues() {
         return this.issues.map((issue) => ({ ...issue }));
     }
@@ -232,6 +261,11 @@ export class HueTransport {
     getFailureSequence() {
         return this.failureSequence;
     }
+    /**
+     * Waits for the processors' and exporters' in-flight work; drain the providers first.
+     *
+     * @throws HueExportError when a new non-warning issue was recorded since the previous observation.
+     */
     flush() {
         const from = this.observedSequence;
         const next = (this.flushPromise ?? Promise.resolve()).then(() => this.flushOnce(from), () => this.flushOnce(from));
@@ -262,6 +296,12 @@ export class HueTransport {
             throw new HueExportError(issues, report);
         return report;
     }
+    /**
+     * Flushes and stops the processors; records emitted afterwards are dropped and counted. In attach
+     * mode call it after shutting down the application's providers.
+     *
+     * @throws HueExportError when the final flush observed new failures.
+     */
     shutdown() {
         this.shutdownPromise ??= (async () => {
             this.closed = true;
@@ -341,7 +381,13 @@ class ReportingExporter {
                 this.transport.issue(this.signal, "invalid", 1, "Telemetry record could not be redacted or exceeds supported content limits");
             }
         }
+        // Each record is encoded once to measure it; a request is encoded once more when it is sent.
+        // Records sharing a resource and scope are grouped on the wire, so the sum of the individual
+        // encodings plus a fixed framing margin bounds the request size. Room is left for gzip
+        // headers/blocks when otherwise incompressible data is near the wire cap.
+        const limit = MAX_BODY_BYTES - 1024;
         let batch = [];
+        let batchBytes = 0;
         for (const record of accepted) {
             let recordBytes;
             try {
@@ -352,21 +398,20 @@ class ReportingExporter {
                 this.transport.issue(this.signal, "invalid", 1, "Telemetry record could not be serialized");
                 continue;
             }
-            const candidate = [...batch, record];
-            // Leave room for gzip headers/blocks when otherwise incompressible data is near the wire cap.
-            if ((this.serializer.serializeRequest(candidate)?.byteLength ?? 0) <= MAX_BODY_BYTES - 1024) {
-                batch = candidate;
-                continue;
+            const framedBytes = recordBytes + RECORD_FRAMING_BYTES;
+            if (batch.length && batchBytes + framedBytes > limit) {
+                if (!(await this.send(batch)))
+                    failed = true;
+                batch = [];
+                batchBytes = 0;
             }
-            if (batch.length && !(await this.send(batch)))
-                failed = true;
-            batch = [];
-            if (recordBytes > MAX_BODY_BYTES - 1024) {
+            if (recordBytes > limit) {
                 failed = true;
                 this.transport.issue(this.signal, "invalid", 1, "Telemetry record exceeds the 1 MiB request limit");
+                continue;
             }
-            else
-                batch = [record];
+            batch.push(record);
+            batchBytes += framedBytes;
         }
         if (batch.length && !(await this.send(batch)))
             failed = true;
@@ -410,13 +455,20 @@ class ReportingExporter {
             },
         };
         const endpoint = `${options.baseUrl}/api/v1/otlp/v1/${this.signal}`;
-        const delegate = createOtlpHttpExportDelegate(convertLegacyHttpOptions({
+        // Explicit configuration only. OTEL_EXPORTER_OTLP_* environment variables are meant
+        // for generic exporters; merging them here could send another vendor's headers to Hue.
+        const delegate = createOtlpHttpExportDelegate({
             url: endpoint,
-            headers: { Authorization: `Bearer ${options.apiKey}` },
+            headers: async () => ({
+                "Content-Type": "application/x-protobuf",
+                Authorization: `Bearer ${options.apiKey}`,
+            }),
+            // The transport prefixes this to OpenTelemetry's own User-Agent token.
+            userAgent: `hue-sdk-typescript/${sdkVersion}`,
             timeoutMillis: options.timeoutMillis,
             concurrencyLimit: 1,
             compression: CompressionAlgorithm.GZIP,
-            httpAgentOptions: async (protocol) => {
+            agentFactory: async (protocol) => {
                 if (expired || Date.now() >= deadline)
                     throw new Error("Hue export deadline exceeded");
                 const { Agent } = await import(protocol === "https:" ? "node:https" : "node:http");
@@ -426,7 +478,7 @@ class ReportingExporter {
                     agent.destroy();
                 return agent;
             },
-        }, this.signal === "traces" ? "TRACES" : "LOGS", `v1/${this.signal}`, { "Content-Type": "application/x-protobuf" }), serializer, this.signal === "traces" ? "otlp_http_span_exporter" : "otlp_http_log_exporter", this.metrics, undefined);
+        }, serializer, this.signal === "traces" ? "otlp_http_span_exporter" : "otlp_http_log_exporter", this.metrics, undefined);
         const exporter = new OTLPExporterBase(delegate);
         try {
             const result = await new Promise((resolve) => {
@@ -475,6 +527,12 @@ class ReportingExporter {
         await this.forceFlush();
     }
 }
+/**
+ * Creates the export pipeline for attach mode; pass it with the application's providers to
+ * {@link createHue}. Validates options like an owned client.
+ *
+ * @throws TypeError for invalid options; see {@link createHue}.
+ */
 export function createHueTransport(options) {
     return new HueTransport(options);
 }