@hue-run/sdk 0.1.4 → 0.2.0

package/dist/client.js

@@ -1,16 +1,26 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { context, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { context, isSpanContextValid, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { defaultTextMapGetter, defaultTextMapSetter } from "@opentelemetry/api";
 import { SeverityNumber } from "@opentelemetry/api-logs";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { LoggerProvider } from "@opentelemetry/sdk-logs";
 import { TracerProvider } from "@opentelemetry/sdk-trace";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import { MAX_CONTENT_BYTES } from "./config.js";
+import { defaultResource, resourceFromAttributes } from "@opentelemetry/resources";
+import { encodeContent, noopSpan, safeSpan } from "./safety.js";
 import { createHueTransport, HueExportError } from "./transport.js";
 import { verifyTrace } from "./receipt.js";
+import { sdkVersion } from "./version.js";
+/**
+ * Thrown by {@link HueClient.checkConnection} and {@link HueClient.verifyTrace} when Hue cannot be
+ * reached, rejects the project key or answers unexpectedly. The message is fixed and safe to log;
+ * the underlying network, timeout or parsing error, when there is one, is available as `cause`.
+ */
 export class HueConnectionError extends Error {
     status;
-    constructor(message, status) {
-        super(message);
+    constructor(message, 
+    /** HTTP status when Hue answered; absent for network, timeout and parsing failures. */
+    status, options) {
+        super(message, options);
         this.status = status;
         this.name = "HueConnectionError";
     }
@@ -26,24 +36,72 @@ function identifier(value) {
         throw new TypeError("Session/user identifiers must contain 1–4096 valid characters");
     return value;
 }
+/** A usable metadata label: a non-blank string of at most 256 characters. */
+function isLabel(value) {
+    return typeof value === "string" && value.trim() !== "" && value.length <= 256;
+}
+/**
+ * Runs `work` exactly once with `active` as OpenTelemetry's current context, so instrumentations
+ * that use the global API parent under the Hue span. Without a registered context manager
+ * `context.with` only calls `work`; a failing manager is counted and cannot skip or rerun `work`.
+ */
+function runInContext(active, work, failed) {
+    const slot = {};
+    const invoke = () => {
+        try {
+            return { value: work() };
+        }
+        catch (error) {
+            return { error };
+        }
+    };
+    try {
+        context.with(active, () => {
+            slot.outcome = invoke();
+        });
+    }
+    catch {
+        failed();
+    }
+    const settled = slot.outcome ?? invoke();
+    if ("error" in settled)
+        throw settled.error;
+    return settled.value;
+}
+/** Error class name for `error.type` and `exception.type`; never the message or stack. */
+function errorType(error) {
+    return error instanceof Error && error.name ? String(error.name) : "Error";
+}
 /** Local async context preserves nesting without registering or replacing global OTel providers. */
 class ContextualTracer {
     source;
     storage;
-    constructor(source, storage) {
+    enabled;
+    failed;
+    constructor(source, storage, enabled, failed) {
         this.source = source;
         this.storage = storage;
+        this.enabled = enabled;
+        this.failed = failed;
     }
     startSpan(name, options = {}, parent) {
-        const active = this.storage.getStore();
-        return this.source.startSpan(name, {
-            ...options,
-            attributes: {
-                ...options.attributes,
-                ...(active?.sessionId ? { "gen_ai.conversation.id": active.sessionId } : {}),
-                ...(active?.userId ? { "user.id": active.userId } : {}),
-            },
-        }, parent ?? active?.context ?? context.active());
+        if (!this.enabled())
+            return noopSpan();
+        try {
+            const active = this.storage.getStore();
+            return safeSpan(this.source.startSpan(name, {
+                ...options,
+                attributes: {
+                    ...options.attributes,
+                    ...(active?.sessionId ? { "gen_ai.conversation.id": active.sessionId } : {}),
+                    ...(active?.userId ? { "user.id": active.userId } : {}),
+                },
+            }, parent ?? active?.context ?? context.active()), this.failed);
+        }
+        catch {
+            this.failed();
+            return noopSpan();
+        }
     }
     startActiveSpan(name, optionsOrFn, contextOrFn, fn) {
         const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
@@ -54,17 +112,48 @@ class ContextualTracer {
                 : fn;
         if (!callback)
             throw new TypeError("A span callback is required");
-        const parent = typeof contextOrFn === "object"
-            ? contextOrFn
-            : (this.storage.getStore()?.context ?? context.active());
+        let parent = ROOT_CONTEXT;
+        try {
+            parent =
+                typeof contextOrFn === "object"
+                    ? contextOrFn
+                    : (this.storage.getStore()?.context ?? context.active());
+        }
+        catch {
+            this.failed();
+        }
         const span = this.startSpan(name, options, parent);
-        return this.storage.run({ ...this.storage.getStore(), context: trace.setSpan(parent, span) }, () => callback(span));
+        // A disabled client creates no span and leaves the application's active context untouched.
+        const created = isSpanContextValid(span.spanContext());
+        let active = parent;
+        if (created)
+            try {
+                active = trace.setSpan(parent, span);
+            }
+            catch {
+                this.failed();
+                active = trace.setSpan(ROOT_CONTEXT, span);
+            }
+        return this.storage.run({ ...this.storage.getStore(), context: active }, () => created
+            ? runInContext(active, () => callback(span), this.failed)
+            : callback(span));
     }
 }
+const propagator = new W3CTraceContextPropagator();
+/**
+ * Hue tracing client. Helpers create spans through a private tracer and local async context, never
+ * through global OpenTelemetry registration, and they fail open: capture problems are counted in
+ * the export report while application code runs and returns unchanged.
+ */
 export class HueClient {
+    /** Export pipeline: counters, issue history and the processors that feed Hue. */
     transport;
+    /** Hue's tracer for other instrumentations; spans parent under `withSpan` and inherit identifiers. */
     tracer;
+    /** Whether helpers record content, as configured. */
     captureContent;
+    /** False for `enabled: false` clients and for `createHueSafe` fallbacks; helpers then only run callbacks. */
+    enabled;
     logger;
     storage = new AsyncLocalStorage();
     tracerProvider;
@@ -73,135 +162,348 @@ export class HueClient {
     closed = false;
     shutdownPromise;
     flushPromise;
+    safeFlushPromise;
+    safeShutdownPromise;
     constructor(options) {
         if ("transport" in options) {
             this.transport = options.transport;
             this.tracerProvider = options.tracerProvider;
             this.loggerProvider = options.loggerProvider;
+            if (this.transport.options.resourceAttributes !== undefined)
+                this.transport.issue("traces", "warning", 0, "resourceAttributes are ignored in attach mode; configure the resource on the application's providers");
         }
         else {
             this.transport = createHueTransport(options);
-            const resource = resourceFromAttributes({
-                "service.name": options.serviceName,
+            // The OpenTelemetry default resource supplies the required telemetry.sdk.* attributes and
+            // Hue's service identity is merged on top of any caller-supplied resourceAttributes, so
+            // serviceName and serviceVersion take precedence over same-named keys. Nothing here reads
+            // environment variables.
+            const resource = defaultResource().merge(resourceFromAttributes({
+                ...options.resourceAttributes,
+                "service.name": this.transport.options.serviceName,
                 ...(options.serviceVersion ? { "service.version": options.serviceVersion } : {}),
-            });
+            }));
             const tracer = new TracerProvider({
                 resource,
-                spanProcessors: [this.transport.spanProcessor],
+                spanProcessors: this.transport.options.enabled === false ? [] : [this.transport.spanProcessor],
             });
             const logger = new LoggerProvider({
                 resource,
-                processors: [this.transport.logRecordProcessor],
+                processors: this.transport.options.enabled === false ? [] : [this.transport.logRecordProcessor],
             });
             this.ownedProviders = { tracer, logger };
             this.tracerProvider = tracer;
             this.loggerProvider = logger;
         }
         this.captureContent = this.transport.options.captureContent;
-        this.tracer = new ContextualTracer(this.tracerProvider.getTracer("@hue-run/sdk", "0.1.4"), this.storage);
-        this.logger = this.loggerProvider.getLogger("@hue-run/sdk", "0.1.4");
+        this.enabled = this.transport.options.enabled !== false;
+        this.tracer = new ContextualTracer(this.tracerProvider.getTracer("@hue-run/sdk", sdkVersion), this.storage, () => this.enabled && !this.closed, () => this.transport.instrumentationFailure());
+        this.logger = this.loggerProvider.getLogger("@hue-run/sdk", sdkVersion);
     }
+    /**
+     * Verifies that Hue stored a trace by ID, optionally waiting for expected span IDs and normalized
+     * fields within the budget. Read-only; it does not flush or inspect content.
+     *
+     * @throws HueConnectionError when the client is disabled.
+     * @throws HueTraceVerificationError for authentication, unsupported endpoint, transport or invalid response failures.
+     * @throws TypeError for an invalid trace ID or options.
+     */
     verifyTrace(traceId, options = {}) {
+        if (!this.enabled)
+            return Promise.reject(new HueConnectionError("Hue telemetry is disabled"));
         return verifyTrace(this.transport.options, traceId, options);
     }
+    /** The helper's current context: the innermost active Hue span, else the OpenTelemetry active context. */
     getContext() {
-        return this.storage.getStore()?.context ?? context.active();
+        try {
+            return this.storage.getStore()?.context ?? context.active();
+        }
+        catch {
+            this.transport.instrumentationFailure();
+            return ROOT_CONTEXT;
+        }
     }
+    /**
+     * Runs `callback` inside a new span that nests under the active Hue span. Application errors are
+     * recorded on the span and rethrown unchanged; the span always ends when the callback settles.
+     */
     async withSpan(name, callback, options = {}) {
-        if (this.closed)
-            throw new Error("Hue client is shut down");
-        const inherited = this.storage.getStore();
-        const sessionId = identifier(options.sessionId ?? inherited?.sessionId);
-        const userId = identifier(options.userId ?? inherited?.userId);
-        const parent = options.parentContext ?? inherited?.context ?? context.active();
-        const active = { context: parent, sessionId, userId };
-        return this.storage.run(active, async () => {
-            const span = this.tracer.startSpan(name, { kind: options.kind ?? SpanKind.INTERNAL, attributes: options.attributes }, parent);
-            const spanContext = trace.setSpan(parent, span);
-            const handle = {
-                span,
-                context: spanContext,
-                traceId: span.spanContext().traceId,
-                spanId: span.spanContext().spanId,
-                setInput: (value) => this.setContent(span, "input.value", value),
-                setOutput: (value) => this.setContent(span, "output.value", value),
-            };
-            return this.storage.run({ ...active, context: spanContext }, async () => {
-                try {
-                    if (options.input !== undefined)
-                        handle.setInput(options.input);
-                    return await callback(handle);
-                }
-                catch (error) {
-                    this.recordError(span, error);
-                    throw error;
-                }
-                finally {
-                    span.end();
-                }
-            });
-        });
+        let span = noopSpan();
+        let active = { context: this.getContext() };
+        if (this.enabled && !this.closed) {
+            try {
+                const inherited = this.storage.getStore();
+                active = {
+                    context: options.parentContext ?? inherited?.context ?? context.active(),
+                    sessionId: identifier(options.sessionId ?? inherited?.sessionId),
+                    userId: identifier(options.userId ?? inherited?.userId),
+                    model: inherited?.model,
+                };
+                span = this.storage.run(active, () => this.tracer.startSpan(name, { kind: options.kind ?? SpanKind.INTERNAL, attributes: options.attributes }, active.context));
+            }
+            catch {
+                this.transport.instrumentationFailure();
+            }
+        }
+        // A disabled or failed client creates no span; the application's own active span then stays
+        // visible through getContext(), inject() and HueSpan.context instead of an invalid one.
+        const created = isSpanContextValid(span.spanContext());
+        let spanContext = active.context;
+        if (created)
+            try {
+                spanContext = trace.setSpan(active.context, span);
+            }
+            catch {
+                this.transport.instrumentationFailure();
+                spanContext = trace.setSpan(ROOT_CONTEXT, span);
+            }
+        const handle = {
+            span,
+            context: spanContext,
+            traceId: span.spanContext().traceId,
+            spanId: span.spanContext().spanId,
+            setInput: (value) => this.setContent(span, "input.value", value),
+            setOutput: (value) => this.setContent(span, "output.value", value),
+            setUsage: (usage) => this.setUsage(span, usage),
+        };
+        const execute = async () => {
+            // Setup, capture and cleanup have separate failure boundaries from customer code.
+            try {
+                if (this.enabled && !this.closed && options.input !== undefined)
+                    handle.setInput(options.input);
+            }
+            catch {
+                this.transport.instrumentationFailure();
+            }
+            try {
+                return await callback(handle);
+            }
+            catch (error) {
+                this.recordError(span, error);
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        };
+        // The span is also OpenTelemetry's active span while the callback runs, so spans from other
+        // instrumentations (HTTP clients, provider SDKs) join this trace when the application has
+        // registered a context manager. Hue still registers none itself.
+        return this.storage.run({ ...active, context: spanContext }, () => created
+            ? runInContext(spanContext, execute, () => this.transport.instrumentationFailure())
+            : execute());
     }
-    async tool(name, input, execute) {
-        return this.withSpan(name, async ({ span }) => {
+    /**
+     * Runs `execute` inside an `execute_tool` span named after the tool. `input` and a defined result
+     * are recorded as `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result` when `captureContent`
+     * is true; values that are not JSON-encodable are omitted with an instrumentation failure.
+     * `options.callId` is recorded as `gen_ai.tool.call.id`, like the Python `call_id=` keyword.
+     */
+    async tool(name, input, execute, options = {}) {
+        const attributes = {
+            "gen_ai.operation.name": "execute_tool",
+            "gen_ai.tool.name": name,
+        };
+        const callId = options.callId;
+        if (callId !== undefined) {
+            // A blank or non-string id is omitted and counted; the tool call itself still runs.
+            if (isLabel(callId))
+                attributes["gen_ai.tool.call.id"] = callId;
+            else if (this.enabled && !this.closed)
+                this.transport.instrumentationFailure();
+        }
+        return this.withSpan(`execute_tool ${name}`, async ({ span }) => {
             this.setContent(span, "gen_ai.tool.call.arguments", input);
             const result = await execute();
             if (result !== undefined)
                 this.setContent(span, "gen_ai.tool.call.result", result);
             return result;
-        }, { attributes: { "gen_ai.operation.name": "execute_tool", "gen_ai.tool.name": name } });
-    }
-    recordError(span, error) {
-        const type = error instanceof Error ? error.name : "Error";
-        span.setStatus({
-            code: SpanStatusCode.ERROR,
-            ...(this.captureContent
-                ? { message: error instanceof Error ? error.message : "Operation failed" }
-                : {}),
+        }, {
+            attributes,
+            ...(options.parentContext ? { parentContext: options.parentContext } : {}),
         });
-        span.addEvent("exception", {
-            "exception.type": type,
-            ...(this.captureContent && error instanceof Error
-                ? {
-                    "exception.message": error.message,
-                    ...(error.stack ? { "exception.stacktrace": error.stack } : {}),
-                }
-                : {}),
+    }
+    /**
+     * Runs `callback` inside a GenAI client span for one direct provider call, named
+     * `{operation} {model}` unless `options.name` is given and carrying `gen_ai.operation.name`,
+     * `gen_ai.request.model` and `gen_ai.provider.name`. The argument order matches `withSpan`. The
+     * handle's `setInput`/`setOutput` record `gen_ai.input.messages` / `gen_ai.output.messages`,
+     * which should use the GenAI semantic-convention message shape; `recordMessages` inside the
+     * callback inherits the request metadata.
+     */
+    async model(model, callback, options) {
+        // A disabled or closed client creates no span, so invalid metadata is not an instrumentation
+        // failure either; only an active client records it (matching the other helpers).
+        const active = this.enabled && !this.closed;
+        const label = (value, fallback) => {
+            if (isLabel(value))
+                return value;
+            if (active)
+                this.transport.instrumentationFailure();
+            return fallback;
+        };
+        const requestModel = label(model, "unknown");
+        const operation = label(options?.operation ?? "chat", "chat");
+        const provider = label(options?.provider, "unknown");
+        const name = options?.name === undefined
+            ? `${operation} ${requestModel}`
+            : label(options.name, `${operation} ${requestModel}`);
+        const metadata = { operation, provider, requestModel };
+        const { sessionId, userId, parentContext, input } = options ?? {};
+        return this.withSpan(name, (span) => {
+            const handle = {
+                ...span,
+                setInput: (value) => this.setContent(span.span, "gen_ai.input.messages", value),
+                setOutput: (value) => this.setContent(span.span, "gen_ai.output.messages", value),
+            };
+            if (input !== undefined)
+                handle.setInput(input);
+            // recordMessages inside the callback copies this request metadata onto its log record.
+            const store = this.storage.getStore() ?? { context: span.context };
+            return this.storage.run({ ...store, model: metadata }, () => callback(handle));
+        }, {
+            sessionId,
+            userId,
+            parentContext,
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "gen_ai.operation.name": operation,
+                "gen_ai.request.model": requestModel,
+                "gen_ai.provider.name": provider,
+            },
         });
     }
+    setUsage(span, usage) {
+        if (!this.enabled || this.closed)
+            return;
+        for (const [key, value] of [
+            ["gen_ai.usage.input_tokens", usage?.inputTokens],
+            ["gen_ai.usage.output_tokens", usage?.outputTokens],
+        ]) {
+            if (value === undefined)
+                continue;
+            if (!Number.isInteger(value) || value < 0) {
+                this.transport.instrumentationFailure();
+                continue;
+            }
+            try {
+                span.setAttribute(key, value);
+            }
+            catch {
+                this.transport.instrumentationFailure();
+            }
+        }
+    }
+    /**
+     * Writes W3C `traceparent` for the active span into a carrier; never the API key or baggage.
+     * Propagation also runs for a disabled or closed client so downstream tracing stays connected.
+     */
+    inject(carrier, activeContext = this.getContext()) {
+        try {
+            propagator.inject(activeContext, carrier, defaultTextMapSetter);
+        }
+        catch {
+            this.transport.instrumentationFailure();
+        }
+    }
+    /** Reads W3C trace context from a carrier for use as `parentContext`. */
+    extract(carrier) {
+        try {
+            return propagator.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);
+        }
+        catch {
+            this.transport.instrumentationFailure();
+            return ROOT_CONTEXT;
+        }
+    }
+    /**
+     * Marks a span failed the same way in every helper: `error.type`, an ERROR status without a
+     * description and an `exception` event carrying only the type. Exception messages and stack
+     * traces are never recorded, whatever `captureContent` is, matching the Python SDK.
+     */
+    recordError(span, error) {
+        if (!this.enabled || this.closed)
+            return;
+        try {
+            const type = errorType(error);
+            span.setAttribute("error.type", type);
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            span.addEvent("exception", { "exception.type": type });
+        }
+        catch {
+            this.transport.instrumentationFailure();
+        }
+    }
+    /**
+     * Emits a `gen_ai.client.inference.operation.details` log record correlated with the active (or
+     * given) span, carrying the messages in its body. `gen_ai.operation.name`, `gen_ai.provider.name`
+     * and `gen_ai.request.model` are set as record attributes from the caller's values or the
+     * enclosing {@link model} span, and `gen_ai.conversation.id` from the active session. Nothing is
+     * emitted when `captureContent` is false; capture failures are counted, never thrown.
+     */
     recordMessages(messages, explicitContext) {
-        if (this.closed)
-            throw new Error("Hue client is shut down");
-        if (!this.captureContent)
+        if (!this.enabled || this.closed || !this.captureContent)
             return;
-        const active = explicitContext ?? this.getContext();
-        if (!trace.getSpanContext(active))
-            throw new Error("Message records require an active span or explicit span context");
-        const body = {};
-        if (messages.input !== undefined)
-            body["gen_ai.input.messages"] = messages.input;
-        if (messages.output !== undefined)
-            body["gen_ai.output.messages"] = messages.output;
-        this.logger.emit({
-            context: active,
-            severityNumber: SeverityNumber.INFO,
-            eventName: "gen_ai.client.inference.operation.details",
-            body,
-        });
+        try {
+            const store = this.storage.getStore();
+            const active = explicitContext ?? store?.context ?? context.active();
+            if (!trace.getSpanContext(active))
+                throw new Error("Message records require an active span or explicit span context");
+            const body = {};
+            if (messages.input !== undefined)
+                body["gen_ai.input.messages"] = messages.input;
+            if (messages.output !== undefined)
+                body["gen_ai.output.messages"] = messages.output;
+            // Request metadata is inherited only when the record correlates with the enclosing helper
+            // scope; an unrelated explicit context carries caller-supplied values alone.
+            const enclosing = explicitContext === undefined || explicitContext === store?.context ? store : undefined;
+            const attributes = {};
+            const stamp = (key, explicit, inherited) => {
+                if (explicit === undefined) {
+                    if (inherited !== undefined)
+                        attributes[key] = inherited;
+                }
+                else if (typeof explicit === "string" && explicit.trim() && explicit.length <= 256)
+                    attributes[key] = explicit;
+                else
+                    this.transport.instrumentationFailure("logs");
+            };
+            stamp("gen_ai.operation.name", messages.operation, enclosing?.model?.operation);
+            stamp("gen_ai.provider.name", messages.provider, enclosing?.model?.provider);
+            stamp("gen_ai.request.model", messages.model, enclosing?.model?.requestModel);
+            stamp("gen_ai.conversation.id", undefined, enclosing?.sessionId);
+            this.logger.emit({
+                context: active,
+                severityNumber: SeverityNumber.INFO,
+                eventName: "gen_ai.client.inference.operation.details",
+                attributes,
+                body: JSON.parse(encodeContent(body)),
+            });
+        }
+        catch {
+            this.transport.instrumentationFailure("logs");
+        }
     }
     setContent(span, key, value) {
-        if (!this.captureContent)
+        if (!this.enabled || this.closed || !this.captureContent)
             return;
-        const encoded = JSON.stringify(value, (_key, item) => {
-            if (typeof item === "number" && !Number.isFinite(item))
-                throw new TypeError("Captured JSON numbers must be finite");
-            return item;
-        });
-        if (encoded === undefined || Buffer.byteLength(encoded) > MAX_CONTENT_BYTES)
-            throw new RangeError("Captured content must be JSON and no more than 256 KiB");
-        span.setAttribute(key, encoded);
+        try {
+            span.setAttribute(key, encodeContent(value));
+        }
+        catch {
+            this.transport.instrumentationFailure();
+        }
     }
+    /**
+     * Confirms the key and origin by reading the current project; a setup and CI diagnostic, not a
+     * readiness gate. Redirects are refused and the response is bounded.
+     *
+     * @throws HueConnectionError when the client is disabled, Hue is unreachable (the network or
+     * timeout error is the `cause`), the key is rejected (`status` is set) or the response is invalid.
+     */
     async checkConnection() {
+        if (!this.enabled)
+            throw new HueConnectionError("Hue telemetry is disabled");
         const options = this.transport.options;
         let response;
         try {
@@ -211,8 +513,8 @@ export class HueClient {
                 signal: AbortSignal.timeout(options.timeoutMillis),
             });
         }
-        catch {
-            throw new HueConnectionError("Unable to connect to Hue; check the endpoint and network");
+        catch (error) {
+            throw new HueConnectionError("Unable to connect to Hue; check the endpoint and network", undefined, { cause: error });
         }
         if (!response.ok) {
             await response.body?.cancel();
@@ -254,10 +556,75 @@ export class HueClient {
                 slug: fields.slug,
             };
         }
+        catch (error) {
+            throw new HueConnectionError("Hue returned an invalid project response", undefined, {
+                cause: error,
+            });
+        }
+    }
+    /** Production lifecycle path: never rejects; timeouts do not cancel borrowed provider work. */
+    flushSafe(options = {}) {
+        if (this.safeFlushPromise)
+            return this.safeFlushPromise;
+        const work = this.flushPromise ?? this.flush();
+        const result = this.safeLifecycle(() => work, options);
+        this.safeFlushPromise = result;
+        const clear = () => {
+            this.safeFlushPromise = undefined;
+        };
+        // Retain the timed-out result until its underlying drain settles. Repeated
+        // timeouts must not accumulate promises against a hung borrowed provider.
+        void work.then(clear, clear);
+        return result;
+    }
+    /** Safe for finally blocks; preserves the application's result or original exception. */
+    shutdownSafe(options = {}) {
+        if (this.safeShutdownPromise)
+            return this.safeShutdownPromise;
+        const work = this.shutdown();
+        const result = this.safeLifecycle(() => work, options);
+        this.safeShutdownPromise = result;
+        const clear = () => {
+            this.safeShutdownPromise = undefined;
+        };
+        void work.then(clear, clear);
+        return result;
+    }
+    async safeLifecycle(work, options) {
+        let timer;
+        try {
+            const timeout = options.timeoutMillis ?? 1000;
+            if (!Number.isInteger(timeout) || timeout < 1 || timeout > 60000)
+                throw new TypeError("Invalid lifecycle budget");
+            const outcome = await Promise.race([
+                work().then(() => "complete"),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve("timeout"), timeout);
+                }),
+            ]);
+            const report = this.transport.getReport();
+            return {
+                ok: outcome === "complete" &&
+                    this.transport.getFailureSequence() === 0 &&
+                    report.pendingSpans + report.pendingLogs === 0,
+                timedOut: outcome === "timeout",
+                report,
+            };
+        }
         catch {
-            throw new HueConnectionError("Hue returned an invalid project response");
+            return { ok: false, timedOut: false, report: this.transport.getReport() };
+        }
+        finally {
+            clearTimeout(timer);
         }
     }
+    /**
+     * Drains the trace and log providers and waits for Hue's acknowledgements. Each caller gets a
+     * fresh serialized drain that includes records emitted before its call.
+     *
+     * @throws HueExportError when this drain observed a new rejection, delivery failure, drop or
+     * invalid record; its `issues` and `report` are sanitized counts, never server text.
+     */
     flush() {
         // Each caller needs a drain after its own preceding span/log emissions.
         // Joining an earlier drain can acknowledge records that were not in its batch.
@@ -281,14 +648,20 @@ export class HueClient {
     }
     async flushOnce() {
         const results = await Promise.allSettled([
-            this.tracerProvider.forceFlush(),
-            this.loggerProvider.forceFlush(),
+            Promise.resolve().then(() => this.tracerProvider.forceFlush()),
+            Promise.resolve().then(() => this.loggerProvider.forceFlush()),
         ]);
         for (const [index, result] of results.entries())
             if (result.status === "rejected")
                 this.transport.issue(index === 0 ? "traces" : "logs", "failed", 0, "OpenTelemetry provider flush failed");
         return this.transport.flush();
     }
+    /**
+     * Flushes, then shuts down the providers this client owns; borrowed providers are left running.
+     * Idempotent: later calls return the same promise, and later helper calls only run their callbacks.
+     *
+     * @throws HueExportError when the final flush observed new failures; owned providers are still released.
+     */
     shutdown() {
         this.shutdownPromise ??= (async () => {
             this.closed = true;
@@ -308,6 +681,41 @@ export class HueClient {
         return this.shutdownPromise;
     }
 }
+/**
+ * Creates a client that owns its providers ({@link HueOptions}) or attaches to the application's
+ * ({@link ExistingHueProviders}). Strict: use it for setup and CI, `createHueSafe` in serving code.
+ *
+ * @throws TypeError for invalid options, including a missing `captureContent` choice, an invalid
+ * key or `serviceName`, a non-origin or insecure `baseUrl`, or out-of-range budgets.
+ */
 export function createHue(options) {
     return new HueClient(options);
 }
+/**
+ * Fail-open initialization for production: invalid options return a disabled client with one
+ * instrumentation failure recorded instead of throwing. Strict {@link createHue} remains for setup/CI.
+ */
+export function createHueSafe(options) {
+    try {
+        return new HueClient(options);
+    }
+    catch (error) {
+        // The caller's diagnostics hook stays attached and hears why telemetry is off.
+        const disabled = new HueClient({ enabled: false, onExportIssue: issueCallback(options) });
+        const reason = error instanceof Error && error.message ? error.message : "unknown error";
+        disabled.transport.instrumentationFailure("traces", `Hue is disabled: ${reason.slice(0, 256)}`);
+        return disabled;
+    }
+}
+function issueCallback(options) {
+    try {
+        const source = options && typeof options === "object" && "transport" in options
+            ? options.transport?.options
+            : options;
+        const callback = source?.onExportIssue;
+        return typeof callback === "function" ? callback : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}