@hue-run/sdk 0.6.0 → 0.7.0

package/CLI.md

@@ -42,8 +42,8 @@ project manifest are refused because managers can update ancestor locks; Python
 The generated `hue.setup.mjs` or `hue_setup.py` always selects `captureContent: false` /
 `capture_content=False`. For a supported application, setup installs the dependency and adds the
 managed import and middleware registration to the existing entrypoint; an unreferenced helper is
-not a completed integration. TypeScript uses `@hue-run/sdk@0.6.0`, `@opentelemetry/api@1.9.1` and
-`@opentelemetry/context-async-hooks@2.11.0`; Python uses published `hue-run==0.2.2`.
+not a completed integration. TypeScript uses `@hue-run/sdk@0.7.0`, `@opentelemetry/api@1.9.1` and
+`@opentelemetry/context-async-hooks@2.11.0`; Python setup uses its separately tested package pin.
 Content capture requires an ordinary account-managed key and a later explicit application decision.
 
 The generated bootstrap supplies standard active SERVER-span context across asynchronous/streaming
@@ -231,7 +231,8 @@ capability `setup_telemetry_write`.
 Normal project credentials and unknown token shapes are refused in setup responses and private
 managed state. These credentials authorize metadata-only OTLP at `/api/v1/otlp/v1/traces` and exact
 content-free receipt verification at `/api/v1/setup/traces/{traceId}/receipt`. They do not authorize
-generic project, receipt, evaluation, log or browsing APIs. Published Python `0.2.2` can export with the setup
+generic project, receipt, evaluation, log or browsing APIs. The Python package version
+pinned by setup can export with the setup
 credential; the CLI verifies the dedicated setup receipt instead of Python's generic receipt helper.
 
 Each command uses bounded timeouts and retries. Provisioning records at most five attempts per local
@@ -300,7 +301,7 @@ node packages/sdk-typescript/scripts/verify-package.mjs --artifacts-dir .artifac
 # Set project to an existing supported fixture; use the same directory on resume.
 project=/absolute/path/to/supported-fixture
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.6.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.7.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -311,7 +312,7 @@ the private local handoff and finish the real browser claim, then reconcile the
 
 ```sh
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.6.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.7.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json

package/README.md

@@ -329,7 +329,8 @@ const hue = createHue({
 
 ## Delivery behavior
 
-Exports use official OTel retry handling for temporary HTTP/network failures. Each
+Exports retry temporary HTTP/network failures (429, 502, 503, 504 and connection errors,
+honoring `Retry-After`) within the export timeout, by OpenTelemetry's OTLP/HTTP exporter rules. Each
 request is limited to 1 MiB before gzip (with space reserved for gzip overhead) and each content value to 256 KiB. Batches
 split at record boundaries. Each signal queues at most 2,048 records, including
 exports in flight; overflow is reported through the callback, counters and next
@@ -349,6 +350,36 @@ drain, including records emitted before its call. Stop request production
 before shutdown so late spans cannot race it. A client does not own instrumented
 operations still running in the application.
 
+## Live spans
+
+OpenTelemetry exports a span only when it ends, so a long streamed turn would otherwise stay
+invisible until it finishes. When a Hue or AI span is still open at the transport's next 500 ms
+tick, the transport queues a placeholder: an ordinary OTLP span whose parent is the running span,
+with its name, kind, start time and current attributes, an end time of 0,
+`hue.span_type = "pending_span"` and `hue.pending_parent_id` (the running span's own parent,
+omitted for a root). Hue shows the span as running and replaces the placeholder when the real span
+arrives. A placeholder whose span has ended by the time it is exported is not sent.
+
+- Only spans from the client's tracer (`withSpan`, `tool`, `model`, `hue.tracer` and the AI SDK
+  adapters) and spans with a `gen_ai.`, `ai.`, `llm.` or `traceloop.` attribute at start, or a
+  name starting with `ai.`, are announced. HTTP, database and other framework spans are not.
+- Placeholder attributes follow `captureContent` and `redact` like the real span. Tool
+  definitions, system instructions and any value over 64 KiB are left out.
+- Placeholders are advisory. They are queued only while the queue is under a quarter of its
+  record and byte budgets, and skipped silently otherwise. While queued they count in
+  `pendingSpans` and `pendingBytes`, but never as accepted, rejected, failed or dropped records.
+  Losing only placeholders records a warning and does not make `flush()` throw.
+- A Hue server that accepts placeholders sends `Hue-Pending-Spans: 1` on trace acknowledgements.
+  When a response to a request carrying placeholders lacks it, the receiver predates them: the
+  transport attributes up to one rejection per placeholder to them, records one warning and stops
+  sending placeholders for that client. Other rejections count against real spans as usual.
+- Opt out with `liveSpans: false`. Setup credentials never send placeholders.
+- With an existing provider, announcements start in `spanProcessor.onStart`. A wrapping processor
+  that forwards `onStart` should forward `onEnd` for the same spans: a span that ends without
+  reaching Hue is forgotten at the next tick, but a placeholder already sent keeps it showing as
+  running until Hue marks the trace stalled. The filtering wrapper above forwards no starts, so it
+  sends no placeholders.
+
 ## Verify a stored application trace
 
 After exercising a real application request and finishing its stream, flush the

package/dist/client.js

@@ -6,6 +6,7 @@ import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { LoggerProvider } from "@opentelemetry/sdk-logs";
 import { TracerProvider } from "@opentelemetry/sdk-trace";
 import { defaultResource, resourceFromAttributes } from "@opentelemetry/resources";
+import { HUE_SCOPE } from "./config.js";
 import { encodeContent, noopSpan, safeSpan } from "./safety.js";
 import { createHueTransport, HueExportError } from "./transport.js";
 import { verifyTrace } from "./receipt.js";
@@ -197,8 +198,8 @@ export class HueClient {
         }
         this.captureContent = this.transport.options.captureContent;
         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);
+        this.tracer = new ContextualTracer(this.tracerProvider.getTracer(HUE_SCOPE, sdkVersion), this.storage, () => this.enabled && !this.closed, () => this.transport.instrumentationFailure());
+        this.logger = this.loggerProvider.getLogger(HUE_SCOPE, sdkVersion);
     }
     /**
      * Verifies that Hue stored a trace by ID, optionally waiting for expected span IDs and normalized

package/dist/config.d.ts

@@ -1,11 +1,13 @@
 import type { HueOptions, SharedHueOptions } from "./types.js";
 export declare const MAX_BODY_BYTES: number;
 export declare const MAX_CONTENT_BYTES: number;
+/** Instrumentation scope of the client's own tracer and logger. */
+export declare const HUE_SCOPE = "@hue-run/sdk";
 /** Loopback hostnames that may use plain HTTP without opting in. */
 export declare function isLoopbackHost(hostname: string): boolean;
 /** True when a validated origin exports over plain HTTP to a host other than loopback. */
 export declare function isInsecureOrigin(baseUrl: string): boolean;
-export declare function validateOptions(options: HueOptions): HueOptions & Required<Pick<SharedHueOptions, "captureContent" | "baseUrl" | "timeoutMillis" | "maxQueueBytes">> & {
+export declare function validateOptions(options: HueOptions): HueOptions & Required<Pick<SharedHueOptions, "captureContent" | "baseUrl" | "timeoutMillis" | "maxQueueBytes" | "liveSpans">> & {
     /** Project key after validation; empty for a disabled client. */
     apiKey: string;
     /** Service name after validation; `hue-disabled` for a disabled client. */

package/dist/config.js

@@ -1,5 +1,7 @@
 export const MAX_BODY_BYTES = 1024 * 1024;
 export const MAX_CONTENT_BYTES = 256 * 1024;
+/** Instrumentation scope of the client's own tracer and logger. */
+export const HUE_SCOPE = "@hue-run/sdk";
 /** Loopback hostnames that may use plain HTTP without opting in. */
 export function isLoopbackHost(hostname) {
     return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
@@ -30,6 +32,7 @@ export function validateOptions(options) {
             baseUrl: "https://app.hue.run",
             timeoutMillis: 10000,
             maxQueueBytes: 8 * 1024 * 1024,
+            liveSpans: false,
         };
     }
     if (typeof options.captureContent !== "boolean")
@@ -74,5 +77,9 @@ export function validateOptions(options) {
         maxQueueBytes < 1024 ||
         maxQueueBytes > 64 * 1024 * 1024)
         throw new TypeError("maxQueueBytes must be 1024–67108864");
-    return { ...options, baseUrl: url.origin, timeoutMillis, maxQueueBytes };
+    if (options.liveSpans !== undefined && typeof options.liveSpans !== "boolean")
+        throw new TypeError("liveSpans must be a boolean");
+    // Setup credentials send installer telemetry only, never in-progress placeholders.
+    const liveSpans = options.liveSpans !== false && !options.apiKey.startsWith("hue_setup_");
+    return { ...options, baseUrl: url.origin, timeoutMillis, maxQueueBytes, liveSpans };
 }

package/dist/live-spans.d.ts

@@ -0,0 +1,25 @@
+import { type Attributes } from "@opentelemetry/api";
+import { type ReadableSpan } from "@opentelemetry/sdk-trace";
+/**
+ * A finished span never carries the placeholder markers, whatever an application set: Hue would
+ * read such a span as a malformed placeholder and reject it.
+ */
+export declare function withoutPlaceholderMarkers(attributes: Attributes): Attributes;
+/** Open spans tracked for announcement at once; later starts are not announced. */
+export declare const MAX_LIVE_SPANS = 1024;
+export declare const LIVE_SPAN_INTERVAL_MILLIS = 500;
+/**
+ * Response header on every trace acknowledgement from a Hue that accepts placeholders. Without
+ * it the receiver predates them and rejects each one by its zero end time.
+ */
+export declare const PLACEHOLDERS_HEADER = "hue-pending-spans";
+/** Hue's own spans and recognizable AI spans, judged from what is known when the span starts. */
+export declare function announcesLiveSpan(span: ReadableSpan): boolean;
+/**
+ * A normal OTLP span announcing `span` while it runs: a new identity whose parent is the real
+ * span, the real start time and an end time of 0. The markers are added after redaction.
+ */
+export declare function pendingPlaceholder(span: ReadableSpan): {
+    record: ReadableSpan;
+    markers: Attributes;
+};

package/dist/live-spans.js

@@ -0,0 +1,115 @@
+import { SpanStatusCode } from "@opentelemetry/api";
+import { RandomIdGenerator } from "@opentelemetry/sdk-trace";
+import { HUE_SCOPE } from "./config.js";
+/** Marks a placeholder for a span that has started but not ended. The value versions the shape. */
+const PENDING_SPAN_TYPE_KEY = "hue.span_type";
+const PENDING_SPAN_TYPE = "pending_span";
+/** The real span's own parent. Absent when the real span is a root. */
+const PENDING_PARENT_KEY = "hue.pending_parent_id";
+const markerKeys = [PENDING_SPAN_TYPE_KEY, PENDING_PARENT_KEY];
+/**
+ * A finished span never carries the placeholder markers, whatever an application set: Hue would
+ * read such a span as a malformed placeholder and reject it.
+ */
+export function withoutPlaceholderMarkers(attributes) {
+    if (!markerKeys.some((key) => Object.hasOwn(attributes, key)))
+        return attributes;
+    const kept = { ...attributes };
+    for (const key of markerKeys)
+        delete kept[key];
+    return kept;
+}
+/** Open spans tracked for announcement at once; later starts are not announced. */
+export const MAX_LIVE_SPANS = 1024;
+export const LIVE_SPAN_INTERVAL_MILLIS = 500;
+/**
+ * Response header on every trace acknowledgement from a Hue that accepts placeholders. Without
+ * it the receiver predates them and rejects each one by its zero end time.
+ */
+export const PLACEHOLDERS_HEADER = "hue-pending-spans";
+const MAX_PLACEHOLDER_VALUE_BYTES = 64 * 1024;
+// Kept narrow on purpose: common application processors export only these spans, and a
+// placeholder whose real span is filtered later would read as running until the trace stalls.
+const livePrefixes = ["gen_ai.", "ai.", "llm.", "traceloop."];
+// Definitions and instructions are large and rarely useful while a span runs; the real span
+// still carries them. Copied markers would misplace the placeholder.
+const omittedKeys = [
+    "gen_ai.tool.definitions",
+    "gen_ai.system_instructions",
+    PENDING_SPAN_TYPE_KEY,
+    PENDING_PARENT_KEY,
+];
+const ids = new RandomIdGenerator();
+/** Hue's own spans and recognizable AI spans, judged from what is known when the span starts. */
+export function announcesLiveSpan(span) {
+    if (span.instrumentationScope.name === HUE_SCOPE || span.name.startsWith("ai."))
+        return true;
+    for (const key in span.attributes)
+        if (livePrefixes.some((prefix) => key.startsWith(prefix)))
+            return true;
+    return false;
+}
+function valueBytes(value) {
+    if (typeof value === "string")
+        return Buffer.byteLength(value);
+    if (!Array.isArray(value))
+        return 8;
+    let bytes = 0;
+    for (const item of value)
+        bytes += typeof item === "string" ? Buffer.byteLength(item) : 8;
+    return bytes;
+}
+function placeholderAttributes(source) {
+    const attributes = {};
+    for (const key in source) {
+        if (!Object.hasOwn(source, key))
+            continue;
+        if (omittedKeys.some((omitted) => key === omitted || key.startsWith(`${omitted}.`)))
+            continue;
+        const value = source[key];
+        if (valueBytes(value) <= MAX_PLACEHOLDER_VALUE_BYTES)
+            attributes[key] = value;
+    }
+    return attributes;
+}
+/**
+ * A normal OTLP span announcing `span` while it runs: a new identity whose parent is the real
+ * span, the real start time and an end time of 0. The markers are added after redaction.
+ */
+export function pendingPlaceholder(span) {
+    const real = span.spanContext();
+    const own = {
+        traceId: real.traceId,
+        spanId: ids.generateSpanId(),
+        traceFlags: real.traceFlags,
+        ...(real.traceState ? { traceState: real.traceState } : {}),
+    };
+    const parent = span.parentSpanContext?.spanId;
+    const record = {
+        name: span.name,
+        kind: span.kind,
+        spanContext: () => own,
+        // Hue re-keys a placeholder as its real span, so the flags describe the real span's parent.
+        parentSpanContext: { ...real, isRemote: span.parentSpanContext?.isRemote === true },
+        startTime: span.startTime,
+        endTime: [0, 0],
+        duration: [0, 0],
+        ended: true,
+        status: { code: SpanStatusCode.UNSET },
+        attributes: placeholderAttributes(span.attributes),
+        links: [],
+        events: [],
+        resource: span.resource,
+        instrumentationScope: span.instrumentationScope,
+        droppedAttributesCount: 0,
+        droppedEventsCount: 0,
+        droppedLinksCount: 0,
+    };
+    return {
+        record,
+        markers: {
+            [PENDING_SPAN_TYPE_KEY]: PENDING_SPAN_TYPE,
+            ...(parent ? { [PENDING_PARENT_KEY]: parent } : {}),
+        },
+    };
+}

package/dist/transport.d.ts

@@ -50,8 +50,25 @@ export declare class HueTransport {
     private closed;
     private shutdownPromise?;
     private flushPromise?;
+    private live;
+    private liveTimer?;
+    private liveSpans;
+    private placeholdersRejected;
+    private placeholders;
+    private placeholderSources;
+    private batchSpans?;
     constructor(options: HueOptions);
+    /**
+     * Advisory records (placeholders) are admitted only while the queue is under a quarter of its
+     * record and byte budgets, so they never take more than a quarter from real records. They are
+     * skipped silently.
+     */
     private enqueue;
+    private track;
+    /** Placeholders are built lazily, so input set right after a span starts is included. */
+    private announceLiveSpans;
+    private stopLiveTimer;
+    private stopLiveSpans;
     /** Cumulative counters and current queue gauges. */
     getReport(): ExportReport;
     /** Copies of the latest 128 sanitized issues, oldest first. */

package/dist/transport.js

@@ -1,10 +1,12 @@
+import { gzip } from "node:zlib";
 import { ExportResultCode } from "@opentelemetry/core";
-import { CompressionAlgorithm, OTLPExporterBase, OTLPExporterError, } from "@opentelemetry/otlp-exporter-base";
-import { createOtlpHttpExportDelegate } from "@opentelemetry/otlp-exporter-base/node-http";
+import { createOtlpNetworkExportDelegate, OTLPExporterBase, OTLPExporterError, } from "@opentelemetry/otlp-exporter-base";
+import { createOtlpHttpExporterMetrics } 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 { isInsecureOrigin, MAX_BODY_BYTES, validateOptions } from "./config.js";
+import { announcesLiveSpan, LIVE_SPAN_INTERVAL_MILLIS, MAX_LIVE_SPANS, pendingPlaceholder, PLACEHOLDERS_HEADER, withoutPlaceholderMarkers, } from "./live-spans.js";
 import { estimateRecordBytes } from "./safety.js";
 import { snapshotLog, snapshotSpan } from "./snapshot.js";
 import { redactLog, redactSpan } from "./privacy.js";
@@ -83,9 +85,20 @@ export class HueTransport {
     closed = false;
     shutdownPromise;
     flushPromise;
+    // Open spans not yet announced. Each is considered once, at the next tick after it starts.
+    live = new Set();
+    liveTimer;
+    liveSpans;
+    placeholdersRejected = false;
+    // Admitted placeholder snapshots and the marker attributes added after redaction.
+    placeholders = new WeakMap();
+    // The running span each admitted placeholder announces, so one it has outlived is not sent.
+    placeholderSources = new WeakMap();
+    batchSpans;
     constructor(options) {
         this.options = validateOptions(options);
         Object.defineProperty(this, "options", { enumerable: false });
+        this.liveSpans = this.options.enabled !== false && this.options.liveSpans;
         this.traceExporter = new ReportingExporter(this, "traces", ProtobufTraceSerializer, TraceExporterMetricsHelper, (span, cache) => redactSpan(span, this.options, cache));
         this.logExporter = new ReportingExporter(this, "logs", ProtobufLogsSerializer, LogsExporterMetricsHelper, (log, cache) => redactLog(log, this.options, cache));
         if (this.options.enabled === false) {
@@ -103,6 +116,7 @@ export class HueTransport {
         };
         const spans = new BatchSpanProcessor({ exporter: this.traceExporter, ...batching });
         const logs = new BatchLogRecordProcessor({ exporter: this.logExporter, ...batching });
+        this.batchSpans = spans;
         this.spanProcessor = {
             onStart: (span, parent) => {
                 try {
@@ -111,8 +125,11 @@ export class HueTransport {
                 catch {
                     this.instrumentationFailure();
                 }
+                this.track(span);
             },
             onEnd: (span) => {
+                if (this.live.delete(span) && !this.live.size)
+                    this.stopLiveTimer();
                 let admitted;
                 try {
                     if (!(span.spanContext().traceFlags & 1))
@@ -130,7 +147,10 @@ export class HueTransport {
                 }
             },
             forceFlush: () => spans.forceFlush(),
-            shutdown: () => spans.shutdown(),
+            shutdown: () => {
+                this.stopLiveSpans();
+                return spans.shutdown();
+            },
         };
         this.logRecordProcessor = {
             onEmit: (log) => {
@@ -152,8 +172,15 @@ export class HueTransport {
             shutdown: () => logs.shutdown(),
         };
     }
-    enqueue(signal, record) {
+    /**
+     * Advisory records (placeholders) are admitted only while the queue is under a quarter of its
+     * record and byte budgets, so they never take more than a quarter from real records. They are
+     * skipped silently.
+     */
+    enqueue(signal, record, advisory = false) {
         const pending = signal === "traces" ? this.spans : this.logs;
+        if (advisory && (this.closed || pending.size >= 2048 / 4))
+            return undefined;
         if (this.closed || pending.size >= 2048) {
             this.issue(signal, "dropped", 1, this.closed
                 ? "Telemetry emitted after transport shutdown"
@@ -161,7 +188,8 @@ export class HueTransport {
             return undefined;
         }
         try {
-            const remaining = this.options.maxQueueBytes - this.pendingBytes;
+            const remaining = (advisory ? this.options.maxQueueBytes / 4 : this.options.maxQueueBytes) -
+                this.pendingBytes;
             const snapshot = signal === "traces"
                 ? snapshotSpan(record, remaining)
                 : snapshotLog(record, remaining);
@@ -170,15 +198,94 @@ export class HueTransport {
                 this.spans.set(snapshot.record, snapshot.bytes);
             else
                 this.logs.set(snapshot.record, snapshot.bytes);
-            if (snapshot.unresolvedResource)
+            if (snapshot.unresolvedResource && !advisory)
                 this.issue(signal, "warning", 0, "Unresolved resource attributes omitted from the telemetry snapshot");
             return snapshot.record;
         }
         catch {
+            if (advisory)
+                return undefined;
             this.issue(signal, "dropped", 1, "Telemetry snapshot exceeded its byte or complexity budget or contained unsupported data");
             return undefined;
         }
     }
+    track(span) {
+        try {
+            if (!this.liveSpans || this.live.size >= MAX_LIVE_SPANS)
+                return;
+            if (!(span.spanContext().traceFlags & 1) || !span.isRecording() || !announcesLiveSpan(span))
+                return;
+            this.live.add(span);
+            if (!this.liveTimer) {
+                const timer = setInterval(() => this.announceLiveSpans(), LIVE_SPAN_INTERVAL_MILLIS);
+                timer.unref();
+                this.liveTimer = timer;
+            }
+        }
+        catch {
+            // Live announcements are advisory. They never report failures or affect the span.
+        }
+    }
+    /** Placeholders are built lazily, so input set right after a span starts is included. */
+    announceLiveSpans() {
+        for (const span of this.live) {
+            this.live.delete(span);
+            try {
+                // Ended without reaching onEnd: a wrapping processor filtered it, so no real span follows.
+                if (!this.liveSpans || span.ended || !this.batchSpans)
+                    continue;
+                const { record, markers } = pendingPlaceholder(span);
+                const admitted = this.enqueue("traces", record, true);
+                if (!admitted)
+                    continue;
+                this.placeholders.set(admitted, markers);
+                this.placeholderSources.set(admitted, span);
+                try {
+                    this.batchSpans.onEnd(admitted);
+                }
+                catch {
+                    this.finish("traces", [admitted]);
+                }
+            }
+            catch {
+                // Skipped silently, like any placeholder the queue has no room for.
+            }
+        }
+        if (!this.live.size)
+            this.stopLiveTimer();
+    }
+    stopLiveTimer() {
+        clearInterval(this.liveTimer);
+        this.liveTimer = undefined;
+    }
+    stopLiveSpans() {
+        this.liveSpans = false;
+        this.live.clear();
+        this.stopLiveTimer();
+    }
+    /** @internal Exporter callback: marker attributes when `record` is an admitted placeholder. */
+    placeholderMarkers(record) {
+        return this.placeholders.get(record);
+    }
+    /** @internal Exporter callback: whether a placeholder's span has ended, so it announces nothing. */
+    placeholderSettled(record) {
+        return this.placeholderSources.get(record)?.ended === true;
+    }
+    /** @internal Exporter callback: false once the receiver refused placeholders; queued ones are then dropped. */
+    sendsPlaceholders() {
+        return !this.placeholdersRejected;
+    }
+    /**
+     * @internal Exporter callback: a receiver without placeholder support rejects each by its zero
+     * end time. Stops announcing for this transport and records one warning.
+     */
+    rejectPlaceholders(count) {
+        this.stopLiveSpans();
+        if (this.placeholdersRejected)
+            return;
+        this.placeholdersRejected = true;
+        this.issue("traces", "warning", count, "This Hue server does not accept in-progress span placeholders; live spans are disabled");
+    }
     /** @internal Exporter callback: releases queued records after an export attempt settles. */
     finish(signal, records) {
         for (const record of records) {
@@ -345,13 +452,52 @@ class ReportingExporter {
             .catch(() => { });
         this.pending.add(work);
     }
+    /** Real records first, then placeholders whose real span is not already in this batch. */
+    ordered(records) {
+        if (this.signal !== "traces")
+            return records.map((record) => ({ record }));
+        const real = [];
+        const placeholders = [];
+        for (const record of records) {
+            const markers = this.transport.placeholderMarkers(record);
+            if (markers)
+                placeholders.push({ record, markers });
+            else
+                real.push({ record });
+        }
+        if (!placeholders.length || !this.transport.sendsPlaceholders())
+            return real;
+        const ended = new Set(real.map(({ record }) => record.spanContext().spanId));
+        // A span that already ended, in this batch or not (even one a wrapping processor filtered),
+        // is no longer running, so its placeholder is not sent.
+        for (const placeholder of placeholders)
+            if (!ended.has(placeholder.record.parentSpanContext?.spanId ?? "") &&
+                !this.transport.placeholderSettled(placeholder.record))
+                real.push(placeholder);
+        return real;
+    }
     async exportRecords(records) {
         const accepted = [];
+        // Placeholders are advisory: losing one is a warning, never an export failure.
+        const placeholders = new Set();
         const cache = new WeakMap();
         let failed = false;
         let redactedBytes = 0;
+        const invalid = (placeholder, message) => {
+            if (placeholder)
+                this.transport.issue(this.signal, "warning", 1, `${message} (in-progress span placeholder)`);
+            else {
+                failed = true;
+                this.transport.issue(this.signal, "invalid", 1, message);
+            }
+        };
+        const send = async (batch) => {
+            const count = batch.filter((record) => placeholders.has(record)).length;
+            if (!(await this.send(batch, count)))
+                failed = true;
+        };
         const resourceDeadline = Date.now() + this.transport.options.timeoutMillis;
-        for (const record of records) {
+        for (const { record, markers } of this.ordered(records)) {
             try {
                 const ready = record.resource.waitForAsyncAttributes?.();
                 if (ready) {
@@ -368,17 +514,30 @@ class ReportingExporter {
                         clearTimeout(timer);
                     }
                 }
-                const redacted = this.redact(record, cache);
+                let redacted = this.redact(record, cache);
+                // Added after redaction, so a redactor cannot alter the markers or the parent identity.
+                if (markers)
+                    redacted = {
+                        ...redacted,
+                        attributes: { ...redacted.attributes, ...markers },
+                    };
+                else if (this.signal === "traces") {
+                    const attributes = redacted.attributes;
+                    const kept = withoutPlaceholderMarkers(attributes);
+                    if (kept !== attributes)
+                        redacted = { ...redacted, attributes: kept };
+                }
                 const bytes = 512 +
                     estimateRecordBytes(recordData(redacted, this.signal), this.transport.options.maxQueueBytes - redactedBytes);
                 if (redactedBytes + bytes > this.transport.options.maxQueueBytes)
                     throw new RangeError("Redacted batch exceeds byte budget");
                 redactedBytes += bytes;
                 accepted.push(redacted);
+                if (markers)
+                    placeholders.add(redacted);
             }
             catch {
-                failed = true;
-                this.transport.issue(this.signal, "invalid", 1, "Telemetry record could not be redacted or exceeds supported content limits");
+                invalid(markers !== undefined, "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.
@@ -394,37 +553,41 @@ class ReportingExporter {
                 recordBytes = this.serializer.serializeRequest([record])?.byteLength ?? Infinity;
             }
             catch {
-                failed = true;
-                this.transport.issue(this.signal, "invalid", 1, "Telemetry record could not be serialized");
+                invalid(placeholders.has(record), "Telemetry record could not be serialized");
                 continue;
             }
             const framedBytes = recordBytes + RECORD_FRAMING_BYTES;
             if (batch.length && batchBytes + framedBytes > limit) {
-                if (!(await this.send(batch)))
-                    failed = true;
+                await send(batch);
                 batch = [];
                 batchBytes = 0;
             }
             if (recordBytes > limit) {
-                failed = true;
-                this.transport.issue(this.signal, "invalid", 1, "Telemetry record exceeds the 1 MiB request limit");
+                invalid(placeholders.has(record), "Telemetry record exceeds the 1 MiB request limit");
                 continue;
             }
             batch.push(record);
             batchBytes += framedBytes;
         }
-        if (batch.length && !(await this.send(batch)))
-            failed = true;
+        if (batch.length)
+            await send(batch);
         if (failed)
             throw new Error("Hue telemetry export failed");
     }
-    async send(records) {
+    /** Sends one request; `placeholders` of `records` are advisory and never count as lost. */
+    async send(records, placeholders = 0) {
         const options = this.transport.options;
+        const real = records.length - placeholders;
+        // A loss involving only placeholders is a warning. Mixed losses count only real records.
+        const lose = (message, status) => {
+            this.transport.issue(this.signal, real ? "failed" : "warning", real || placeholders, real ? message : `${message} (in-progress span placeholders only)`, status);
+            return !real;
+        };
         let rejected = 0;
         let validResponse = true;
         let receivedResponse = false;
+        let acceptsPlaceholders = false;
         let expired = false;
-        const agents = new Set();
         const deadline = Date.now() + options.timeoutMillis;
         let timer;
         const serializer = {
@@ -439,17 +602,27 @@ class ReportingExporter {
                     const count = Number(partial?.[this.signal === "traces" ? "rejectedSpans" : "rejectedLogRecords"] ?? 0);
                     if (!Number.isSafeInteger(count) || count < 0 || count > records.length)
                         throw new Error("Invalid rejection count");
-                    rejected = count;
-                    if (count || partial?.errorMessage)
-                        this.transport.issue(this.signal, count ? "rejected" : "warning", count, count
+                    // A receiver that accepts placeholders never rejects them for being placeholders, so its
+                    // rejections count as before. One without the header predates them and rejects each.
+                    const downgrade = placeholders > 0 && !acceptsPlaceholders;
+                    const placeholderRejections = downgrade ? Math.min(count, placeholders) : 0;
+                    if (downgrade)
+                        this.transport.rejectPlaceholders(placeholderRejections);
+                    const remaining = count - placeholderRejections;
+                    // Rejections are not matched to records. Attribute them to real records first.
+                    rejected = Math.min(remaining, real);
+                    if (remaining || (partial?.errorMessage && !downgrade))
+                        this.transport.issue(this.signal, rejected ? "rejected" : "warning", rejected || remaining, rejected
                             ? "Hue rejected telemetry records; inspect the project ingestion settings and supported limits"
-                            : "Hue returned an ingestion warning");
+                            : remaining
+                                ? "Hue rejected in-progress span placeholders"
+                                : "Hue returned an ingestion warning");
                     // Do not pass backend error text or raw response bytes into the global OTel diagnostic logger.
                     return {};
                 }
                 catch {
                     validResponse = false;
-                    this.transport.issue(this.signal, "failed", records.length, "Hue returned an invalid OTLP acknowledgement; acceptance is uncertain");
+                    lose("Hue returned an invalid OTLP acknowledgement; acceptance is uncertain");
                     return {};
                 }
             },
@@ -457,64 +630,44 @@ class ReportingExporter {
         const endpoint = `${options.baseUrl}/api/v1/otlp/v1/${this.signal}`;
         // 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: 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,
-            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");
-                const agent = new Agent({ keepAlive: false });
-                agents.add(agent);
-                if (expired)
-                    agent.destroy();
-                return agent;
-            },
-        }, serializer, this.signal === "traces" ? "otlp_http_span_exporter" : "otlp_http_log_exporter", this.metrics, undefined);
+        const transport = new OtlpHttpTransport(endpoint, {
+            "Content-Type": "application/x-protobuf",
+            Authorization: `Bearer ${options.apiKey}`,
+            "User-Agent": `hue-sdk-typescript/${sdkVersion} ${OTEL_USER_AGENT}`,
+        }, (headers) => {
+            acceptsPlaceholders = headers[PLACEHOLDERS_HEADER] === "1";
+        });
+        const delegate = createOtlpNetworkExportDelegate({ timeoutMillis: options.timeoutMillis, concurrencyLimit: 1, compression: "gzip" }, serializer, createOtlpHttpExporterMetrics(this.signal === "traces" ? "otlp_http_span_exporter" : "otlp_http_log_exporter", this.metrics, endpoint, undefined), transport);
         const exporter = new OTLPExporterBase(delegate);
         try {
             const result = await new Promise((resolve) => {
                 timer = setTimeout(() => {
                     expired = true;
-                    for (const agent of agents)
-                        agent.destroy();
+                    transport.abort();
                     resolve({ code: ExportResultCode.FAILED });
                 }, Math.max(1, deadline - Date.now()));
                 exporter.export(records, resolve);
             });
             if (result.code === ExportResultCode.SUCCESS) {
-                if (!receivedResponse) {
-                    this.transport.issue(this.signal, "failed", records.length, "Hue response ended without a complete OTLP acknowledgement; acceptance is uncertain");
-                    return false;
-                }
+                if (!receivedResponse)
+                    return lose("Hue response ended without a complete OTLP acknowledgement; acceptance is uncertain");
                 if (validResponse)
-                    this.transport.acceptedRecords(this.signal, records.length - rejected);
-                return validResponse;
+                    this.transport.acceptedRecords(this.signal, real - rejected);
+                return validResponse || !real;
             }
             else {
                 const status = result.error instanceof OTLPExporterError && Number.isInteger(result.error.code)
                     ? result.error.code
                     : undefined;
-                this.transport.issue(this.signal, "failed", records.length, "Hue telemetry request failed", status);
-                return false;
+                return lose("Hue telemetry request failed", status);
             }
         }
         catch {
-            this.transport.issue(this.signal, "failed", records.length, "Hue telemetry request failed");
-            return false;
+            return lose("Hue telemetry request failed");
         }
         finally {
             clearTimeout(timer);
-            for (const agent of agents)
-                agent.destroy();
+            transport.abort();
             // Delegate cleanup cannot extend the hard request wait. Sockets are closed
             // and the cleanup promise is always observed, even after a caller timeout.
             void exporter.shutdown().catch(() => { });
@@ -527,6 +680,182 @@ class ReportingExporter {
         await this.forceFlush();
     }
 }
+// OpenTelemetry's OTLP/HTTP transport rules (otlp-exporter-base 0.222), restated because that
+// transport discards response headers, which Hue uses to announce features.
+const MAX_RETRIES = 5;
+const INITIAL_BACKOFF_MILLIS = 1000;
+const MAX_BACKOFF_MILLIS = 5000;
+const BACKOFF_MULTIPLIER = 1.5;
+const JITTER = 0.2;
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
+const RETRYABLE_NETWORK_ERRORS = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "EPIPE",
+    "ETIMEDOUT",
+    "EAI_AGAIN",
+    "ENOTFOUND",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+]);
+/** OpenTelemetry's exporter token, which follows Hue's in the User-Agent as it always has. */
+const OTEL_USER_AGENT = "OTel-OTLP-Exporter-JavaScript/0.222.0";
+function retryAfterMillis(value) {
+    if (value == null)
+        return undefined;
+    const seconds = Number.parseInt(value, 10);
+    if (Number.isInteger(seconds))
+        return seconds > 0 ? seconds * 1000 : -1;
+    const delay = new Date(value).getTime() - Date.now();
+    return delay >= 0 ? delay : 0;
+}
+function networkFailure(error) {
+    const code = error.code;
+    return typeof code === "string" && RETRYABLE_NETWORK_ERRORS.has(code)
+        ? { status: "retryable", error }
+        : { status: "failure", error };
+}
+function compress(data) {
+    return new Promise((resolve, reject) => gzip(data, (error, result) => (error ? reject(error) : resolve(result))));
+}
+/**
+ * Gzip-compressed OTLP/HTTP POSTs that never follow redirects, retried like OpenTelemetry's
+ * exporter within the request budget. `onSuccess` receives the headers of the 2xx response whose
+ * body becomes the acknowledgement, before that body is decoded. One instance serves a single
+ * export request: its connections are never reused, and `abort()` closes them at the export
+ * deadline.
+ */
+class OtlpHttpTransport {
+    url;
+    headers;
+    onSuccess;
+    // Requests in flight and how to settle each, so an abort never leaves an attempt pending.
+    requests = new Map();
+    agent;
+    aborted = false;
+    constructor(url, headers, onSuccess) {
+        this.url = url;
+        this.headers = headers;
+        this.onSuccess = onSuccess;
+    }
+    async send(data, timeoutMillis) {
+        const deadline = Date.now() + timeoutMillis;
+        let backoff = INITIAL_BACKOFF_MILLIS;
+        let result = await this.attempt(data, timeoutMillis);
+        for (let retries = MAX_RETRIES; result.status === "retryable" && retries > 0; retries--) {
+            const jitter = Math.random() * 2 * JITTER - JITTER;
+            const wait = result.retryInMillis ?? Math.max(Math.min(backoff * (1 + jitter), MAX_BACKOFF_MILLIS), 0);
+            backoff *= BACKOFF_MULTIPLIER;
+            // Return when the next attempt would start after the export deadline.
+            if (this.aborted || wait > deadline - Date.now())
+                return result;
+            await new Promise((resolve) => setTimeout(resolve, Math.max(0, wait)));
+            result = await this.attempt(data, Math.max(1, deadline - Date.now()));
+        }
+        return result;
+    }
+    async attempt(data, timeoutMillis) {
+        try {
+            if (this.aborted)
+                throw new Error("Hue export deadline exceeded");
+            const url = new URL(this.url);
+            const protocol = url.protocol;
+            // Loaded on first use, as OpenTelemetry's exporter does, so importing Hue never loads http
+            // before the application's http instrumentation can patch it.
+            const [{ Agent: ConnectionAgent, request }, body] = await Promise.all([
+                import(protocol === "https:" ? "node:https" : "node:http"),
+                compress(data),
+            ]);
+            if (this.aborted)
+                throw new Error("Hue export deadline exceeded");
+            // Never kept alive: each attempt's socket closes with its response or at the deadline.
+            this.agent ??= new ConnectionAgent({ keepAlive: false });
+            return await new Promise((resolve) => {
+                const req = request(url, {
+                    method: "POST",
+                    agent: this.agent,
+                    headers: {
+                        ...this.headers,
+                        "Content-Encoding": "gzip",
+                        "Content-Length": body.byteLength,
+                    },
+                }, (res) => {
+                    const chunks = [];
+                    let size = 0;
+                    const status = res.statusCode ?? 0;
+                    const success = status >= 200 && status <= 299;
+                    res.on("data", (chunk) => {
+                        size += chunk.length;
+                        if (size > MAX_RESPONSE_BYTES) {
+                            // Oversized responses fail regardless of status; resolve before tearing down.
+                            resolve({ status: "failure", error: new Error("OTLP response exceeded 4 MiB") });
+                            res.destroy();
+                            return;
+                        }
+                        chunks.push(chunk);
+                    });
+                    res.on("end", () => {
+                        if (success) {
+                            this.onSuccess(res.headers);
+                            resolve({ status: "success", data: Buffer.concat(chunks) });
+                        }
+                        else if (RETRYABLE_STATUS.has(status))
+                            resolve({
+                                status: "retryable",
+                                retryInMillis: retryAfterMillis(res.headers["retry-after"]),
+                            });
+                        else
+                            resolve({
+                                status: "failure",
+                                error: new OTLPExporterError(res.statusMessage, status, Buffer.concat(chunks).toString()),
+                            });
+                    });
+                    res.on("error", (error) => {
+                        // Sent, but the acknowledgement was not read: success without a body to decode.
+                        if (success)
+                            resolve({ status: "success" });
+                        else if (RETRYABLE_STATUS.has(status))
+                            resolve({
+                                status: "retryable",
+                                error,
+                                retryInMillis: retryAfterMillis(res.headers["retry-after"]),
+                            });
+                        else
+                            resolve({ status: "failure", error });
+                    });
+                });
+                this.requests.set(req, resolve);
+                req.on("close", () => this.requests.delete(req));
+                req.setTimeout(timeoutMillis, () => {
+                    req.destroy();
+                    resolve({ status: "retryable", error: new Error("Request timed out") });
+                });
+                req.on("error", (error) => resolve(networkFailure(error)));
+                req.end(body);
+            });
+        }
+        catch (error) {
+            return {
+                status: "failure",
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+        }
+    }
+    /** Fails and destroys requests in flight and their sockets, and every later attempt. */
+    abort() {
+        this.aborted = true;
+        for (const [req, settle] of this.requests) {
+            settle({ status: "failure", error: new Error("Hue export deadline exceeded") });
+            req.destroy();
+        }
+        this.requests.clear();
+        this.agent?.destroy();
+    }
+    shutdown() {
+        this.abort();
+    }
+}
 /**
  * Creates the export pipeline for attach mode; pass it with the application's providers to
  * {@link createHue}. Validates options like an owned client.

package/dist/types.d.ts

@@ -43,6 +43,12 @@ export interface SharedHueOptions {
     timeoutMillis?: number;
     /** Aggregate estimated retained telemetry bytes across both signals, including in-flight work. Default 8 MiB. */
     maxQueueBytes?: number;
+    /**
+     * Announces AI and Hue spans that are still running with in-progress placeholder spans, so Hue
+     * shows a trace while it runs. Default `true`; always off for setup credentials (`hue_setup_…`),
+     * and turned off for the client when its receiver does not accept placeholders.
+     */
+    liveSpans?: boolean;
 }
 /**
  * Options for a client that owns its OpenTelemetry providers. An enabled client needs a project
@@ -75,7 +81,7 @@ export interface ExportIssue {
     signal: Signal;
     /** `rejected` by Hue, `failed` to deliver, `dropped` from the queue, `invalid` record or capture, or a non-failing `warning`. */
     kind: "rejected" | "failed" | "dropped" | "invalid" | "warning";
-    /** Records affected; zero for warnings and capture failures. */
+    /** Records affected; zero for capture failures and for warnings other than lost in-progress span placeholders. */
     count: number;
     /** HTTP status when the issue came from a response. */
     status?: number;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.6.0";
+export declare const sdkVersion = "0.7.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/write-version.mjs from package.json; do not edit by hand.
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export const sdkVersion = "0.6.0";
+export const sdkVersion = "0.7.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": false,
   "license": "MIT",
   "publishConfig": {