@hue-run/sdk 0.22.0 → 0.23.1

package/CLI.md

@@ -42,7 +42,7 @@ 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.22.0`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.23.1`, `@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.
 
@@ -381,8 +381,8 @@ and Hue never receives or stores them. The command is part of the `hue` executab
 #   LANGFUSE_PUBLIC_KEY=pk-lf-...
 #   LANGFUSE_SECRET_KEY=sk-lf-...
 #   LANGFUSE_BASE_URL=https://cloud.langfuse.com
-npx -y @hue-run/sdk@0.22.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.22.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.23.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.23.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
 ```
 
 `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` come from the environment or `--env-path`
@@ -892,7 +892,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.22.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.23.1.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -903,7 +903,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.22.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.23.1.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -945,10 +945,10 @@ otherwise. Never hand the agent Hue-native tools (`context.tools`, `context.mcp`
 production agent lacks. Pin the SDK, so the agent's repository gains no dependency:
 
 ```sh
-npx -y @hue-run/sdk@0.22.0 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.22.0 eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <run id>
-npx -y @hue-run/sdk@0.22.0 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.22.0 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
+npx -y @hue-run/sdk@0.23.1 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.23.1 eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <run id>
+npx -y @hue-run/sdk@0.23.1 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.23.1 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
 ```
 
 One invocation creates one run holding every selected case; it prints the run URL
@@ -986,7 +986,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.22.0 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.23.1 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.

package/README.md

@@ -552,8 +552,8 @@ the Langfuse project's own keys (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, a
 `HUE_API_KEY`:
 
 ```sh
-npx -y @hue-run/sdk@0.22.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.22.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.23.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.23.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
 ```
 
 - It reads Langfuse Cloud and self-hosted v4 through the Observations API v2, and self-hosted v3
@@ -1106,6 +1106,16 @@ own. Stop request production
 before shutdown so late spans cannot race it. A client does not own instrumented
 operations still running in the application.
 
+In Vercel Functions, the TypeScript SDK automatically registers admitted spans and logs with
+[`waitUntil`](https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package#waituntil).
+The response or Workflow step can return while the existing batches and their media uploads finish
+in the background, within the function's lifetime limit. You can remove a per-step
+`await hue.flushSafe()` when its purpose is to prevent the function freezing before delivery.
+Keep an explicit flush when you need its acknowledgement report before continuing. Background
+delivery preserves capture, redaction, batching and failure reports; it never flushes or shuts down
+application-owned providers. In other hosts, keep the host's lifetime hook or await a flush before
+a short-lived process exits.
+
 ## Live spans
 
 OpenTelemetry exports a span only when it ends, so a long streamed turn would otherwise stay
@@ -1119,7 +1129,11 @@ arrives.
 The placeholder then waits for the next batch export like any queued span: up to 500 ms until the
 next tick, then the 1 s batch delay when nothing else is queued, so it usually reaches Hue within
 about 1.5 s of its span starting. It goes out sooner when a batch is already scheduled, for example
-because another span has just ended, and at once for a full batch or `flush()`. It goes out later
+because another span has just ended, and at once for a full batch or a flush with no completed
+spans. When a flush has completed spans to deliver, it defers queued placeholders to the next
+normal announcement after the drain and its uploads finish. This avoids an extra acknowledgement
+for a still-open parent while preserving delivery of its completed children. A parent that ends
+before that announcement sends only its completed span. A placeholder goes out later
 while an earlier export is still in flight, because the next batch is scheduled only after that
 export finishes. A placeholder whose span has ended by the time it is exported is not sent, so a
 short span may send none and appear in Hue only when it finishes.
@@ -1311,7 +1325,7 @@ existing-provider flush callbacks and recovery. Local/CI runners remain availabl
 
 ## Serving safely
 
-Use `createHueSafe(options)` for best-effort startup. Invalid initialization returns a disabled client that keeps your `onExportIssue` hook and records the reason as an instrumentation failure. Pass `enabled: false` to disable Hue without a key or a `captureContent` choice; disabled helpers still execute the application callback, and `inject()` keeps propagating the application's own trace context. `flushSafe({ timeoutMillis: 1000 })` and `shutdownSafe({ timeoutMillis: 1000 })` return `{ ok, timedOut, report }` without rejecting. Strict initialization, connection checks and `flush()` remain available for diagnostics; do not gate application readiness or responses on them.
+Use `createHueSafe(options)` for best-effort startup. Invalid initialization returns a disabled client that keeps your `onExportIssue` hook and records a fixed initialization-failure diagnostic without inspecting or exposing the original error. Pass `enabled: false` to disable Hue without a key or a `captureContent` choice; disabled helpers still execute the application callback, and `inject()` keeps propagating the application's own trace context. `flushSafe({ timeoutMillis: 1000 })` and `shutdownSafe({ timeoutMillis: 1000 })` return `{ ok, timedOut, report }` without rejecting. Strict initialization, connection checks and `flush()` remain available for diagnostics; do not gate application readiness or responses on them.
 
 Capture/serialization/redaction/provider failures omit unsafe telemetry, record failures, and preserve the original business result/error. Async diagnostic rejections are contained; diagnostics are rate-limited. The default `maxQueueBytes` is 8 MiB across traces/logs including in-flight work, alongside the existing record cap. `pendingBytes` is a current queue gauge; `droppedSpans`, `droppedLogs` and `instrumentationFailures` are cumulative failure counters; `uploadedValues` and `uploadFallbacks` count completed uploads and upload fallbacks for whole attributes, eligible binary or large text media, and opt-in `recordFile` uploads. Whole-attribute fallbacks refused at export keep a prefix; media fallbacks keep a digest; helper upload fallbacks keep the file event; a value whose upload failed after export keeps its entry as well. This is a telemetry budget, not a total process memory ceiling. A timeout bounds the caller and does not cancel a borrowed provider. Never retry the business operation to recover telemetry. See [production setup](https://docs.hue.run/sdks/typescript#production-setup).
 

package/dist/client.js

@@ -370,6 +370,8 @@ export class HueClient {
      * provider and surface as `hue.mcp.provider` / `hue.mcp.surface`.
      */
     async tool(name, input, execute, options = {}) {
+        if (!this.enabled || this.closed)
+            return this.withSpan("execute_tool", () => execute());
         const attributes = {
             "gen_ai.operation.name": "execute_tool",
             "gen_ai.tool.name": name,
@@ -380,22 +382,25 @@ export class HueClient {
             // A blank or non-string label is omitted and counted; the tool call itself still runs.
             if (isLabel(value))
                 attributes[key] = value;
-            else if (this.enabled && !this.closed)
+            else
                 this.instrumentationFailed();
         };
-        stamp("gen_ai.tool.call.id", options.callId);
-        stamp("mcp.server.name", options.mcp?.name);
-        stamp("mcp.server.version", options.mcp?.version);
-        stamp("hue.mcp.provider", options.mcp?.provider);
-        stamp("hue.mcp.surface", options.mcp?.surface);
-        if (this.enabled && !this.closed && this.captureContent) {
-            try {
-                if (options.endpoint !== undefined)
-                    Object.assign(attributes, toolEndpointAttributes(options.endpoint));
-            }
-            catch {
-                this.instrumentationFailed();
-            }
+        let spanOptions = { attributes };
+        try {
+            stamp("gen_ai.tool.call.id", options.callId);
+            stamp("mcp.server.name", options.mcp?.name);
+            stamp("mcp.server.version", options.mcp?.version);
+            stamp("hue.mcp.provider", options.mcp?.provider);
+            stamp("hue.mcp.surface", options.mcp?.surface);
+            if (this.captureContent && options.endpoint !== undefined)
+                Object.assign(attributes, toolEndpointAttributes(options.endpoint));
+            spanOptions = {
+                attributes,
+                ...(options.parentContext ? { parentContext: options.parentContext } : {}),
+            };
+        }
+        catch {
+            this.instrumentationFailed();
         }
         return this.withSpan(`execute_tool ${name}`, async ({ span }) => {
             this.setContent(span, "gen_ai.tool.call.arguments", input);
@@ -403,10 +408,7 @@ export class HueClient {
             if (result !== undefined)
                 this.setContent(span, "gen_ai.tool.call.result", result);
             return result;
-        }, {
-            attributes,
-            ...(options.parentContext ? { parentContext: options.parentContext } : {}),
-        });
+        }, spanOptions);
     }
     /**
      * Runs `callback` as a sub-agent: inside an `invoke_agent {name}` span carrying
@@ -420,11 +422,27 @@ export class HueClient {
      * in `withSpan`. A blank or non-string name is recorded as `unknown` and counted.
      */
     async subagent(name, callback, options = {}) {
+        if (!this.enabled || this.closed)
+            return this.withSpan("invoke_agent", callback);
         let agent = name;
         if (!isLabel(name)) {
             agent = "unknown";
-            if (this.enabled && !this.closed)
-                this.instrumentationFailed();
+            this.instrumentationFailed();
+        }
+        let spanOptions = {};
+        try {
+            spanOptions = {
+                ...options,
+                attributes: {
+                    ...options.attributes,
+                    "gen_ai.operation.name": "invoke_agent",
+                    "gen_ai.agent.name": agent,
+                    "hue.agent.role": "subagent",
+                },
+            };
+        }
+        catch {
+            this.instrumentationFailed();
         }
         return this.withSpan(`invoke_agent ${agent}`, async (span) => {
             let outputSet = false;
@@ -438,15 +456,7 @@ export class HueClient {
             if (result !== undefined && !outputSet)
                 span.setOutput(result);
             return result;
-        }, {
-            ...options,
-            attributes: {
-                ...options.attributes,
-                "gen_ai.operation.name": "invoke_agent",
-                "gen_ai.agent.name": agent,
-                "hue.agent.role": "subagent",
-            },
-        });
+        }, spanOptions);
     }
     /**
      * Runs `callback` inside a GenAI client span for one direct provider call, named
@@ -458,24 +468,44 @@ export class HueClient {
      * recorded as `gen_ai.system_instructions` and `gen_ai.tool.definitions`, content like `input`.
      */
     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;
+        if (!this.enabled || this.closed)
+            return this.withSpan("model", callback);
+        let prepared = { provider: "unknown" };
+        try {
+            prepared = {
+                operation: options?.operation,
+                provider: options?.provider,
+                name: options?.name,
+                sessionId: options?.sessionId,
+                userId: options?.userId,
+                workspaceId: options?.workspaceId,
+                parentContext: options?.parentContext,
+                ...(this.captureContent
+                    ? {
+                        input: options?.input,
+                        systemInstructions: options?.systemInstructions,
+                        tools: options?.tools,
+                    }
+                    : {}),
+            };
+        }
+        catch {
+            this.instrumentationFailed();
+        }
         const label = (value, fallback) => {
             if (isLabel(value))
                 return value;
-            if (active)
-                this.instrumentationFailed();
+            this.instrumentationFailed();
             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
+        const operation = label(prepared.operation ?? "chat", "chat");
+        const provider = label(prepared.provider, "unknown");
+        const name = prepared.name === undefined
             ? `${operation} ${requestModel}`
-            : label(options.name, `${operation} ${requestModel}`);
+            : label(prepared.name, `${operation} ${requestModel}`);
         const metadata = { operation, provider, requestModel };
-        const { sessionId, userId, workspaceId, parentContext, input, systemInstructions, tools, } = options ?? {};
+        const { sessionId, userId, workspaceId, parentContext, input, systemInstructions, tools } = prepared;
         return this.withSpan(name, (span) => {
             const handle = {
                 ...span,
@@ -507,22 +537,22 @@ export class HueClient {
     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.instrumentationFailed();
-                continue;
-            }
-            try {
+        try {
+            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.instrumentationFailed();
+                    continue;
+                }
                 span.setAttribute(key, value);
             }
-            catch {
-                this.instrumentationFailed();
-            }
+        }
+        catch {
+            this.instrumentationFailed();
         }
     }
     /**
@@ -1275,11 +1305,10 @@ export function createHueSafe(options) {
     try {
         return new HueClient(options);
     }
-    catch (error) {
-        // The caller's diagnostics hook stays attached and hears why telemetry is off.
+    catch {
+        // Provider errors can contain credentials or expose throwing message accessors.
         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)}`);
+        disabled.transport.instrumentationFailure("traces", "Hue is disabled: initialization failed");
         return disabled;
     }
 }

package/dist/transport.d.ts

@@ -53,6 +53,9 @@ export declare class HueTransport {
     private failed;
     private spans;
     private logs;
+    private deliveryCohort?;
+    private deliveries;
+    private deliveryUploads;
     private pendingBytes;
     private dropped;
     /** Records of each trace the SDK never sent (dropped from the queue, refused as invalid or
@@ -81,6 +84,8 @@ export declare class HueTransport {
     private placeholdersRejected;
     private placeholders;
     private placeholderSources;
+    private forcedSpanDrains;
+    private completedSpanDrains;
     private batchSpans?;
     private limits;
     /** The rate-limit holds in progress, each ended early by calling it. */
@@ -120,11 +125,16 @@ export declare class HueTransport {
      * skipped silently.
      */
     private enqueue;
+    /** Register in the caller's request before it can return; outside Vercel this is a no-op. */
+    private protectDelivery;
+    private holdDelivery;
+    private finishDelivery;
     private track;
     /** Placeholders are built lazily, so input set right after a span starts is included. */
     private announceLiveSpans;
     private stopLiveTimer;
     private stopLiveSpans;
+    private beginSpanDrain;
     /** Holds the staged attachments of a log record being admitted with the queued record, within
      * the held-value budget; those the budget refuses are counted as not uploaded. */
     private admitLogParts;
@@ -144,6 +154,8 @@ export declare class HueTransport {
     private protectMedia;
     private releaseMediaIdentity;
     private sweepMedia;
+    /** Keep an export's warning aggregation within each cohort's upload ownership. */
+    private collectDeliveryUploads;
     /** Bounded: a trace whose root never arrives (an abandoned run) gives way to newer ones. */
     private countDropped;
     /** Cumulative counters and current queue gauges. */

package/dist/transport.js

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { gzip } from "node:zlib";
+import { waitUntil } from "@vercel/functions";
 import { ExportResultCode } from "@opentelemetry/core";
 import { createOtlpNetworkExportDelegate, OTLPExporterBase, OTLPExporterError, } from "@opentelemetry/otlp-exporter-base";
 import { createOtlpHttpExporterMetrics } from "@opentelemetry/otlp-exporter-base/node-http";
@@ -182,6 +183,10 @@ export class HueTransport {
     failed = { traces: 0, logs: 0 };
     spans = new Map();
     logs = new Map();
+    // A cohort closes when export starts, so later requests cannot extend its lifetime.
+    deliveryCohort;
+    deliveries = new WeakMap();
+    deliveryUploads = new WeakMap();
     pendingBytes = 0;
     dropped = { traces: 0, logs: 0 };
     /** Records of each trace the SDK never sent (dropped from the queue, refused as invalid or
@@ -214,6 +219,8 @@ export class HueTransport {
     placeholders = new WeakMap();
     // The running span each admitted placeholder announces, so one it has outlived is not sent.
     placeholderSources = new WeakMap();
+    forcedSpanDrains = 0;
+    completedSpanDrains = 0;
     batchSpans;
     // What the receiver accepts, as it last advertised; the limits of this release until it does.
     limits = DEFAULT_RECEIVER_LIMITS;
@@ -340,6 +347,7 @@ export class HueTransport {
                     this.protectMedia(admitted);
                     this.countEnded(admitted);
                     spans.onEnd(admitted);
+                    this.protectDelivery(admitted);
                 }
                 catch {
                     if (admitted)
@@ -352,12 +360,18 @@ export class HueTransport {
             // The spans are sent first, then the uploads queued so far are waited for, unless a
             // flush sends them: that flush waits for the uploads after its send.
             forceFlush: async () => {
+                const finish = this.beginSpanDrain();
                 try {
                     await spans.forceFlush();
                 }
                 finally {
-                    if (!this.sendingRecords.getStore())
-                        await this.drainUploads();
+                    try {
+                        if (!this.sendingRecords.getStore())
+                            await this.drainUploads();
+                    }
+                    finally {
+                        finish();
+                    }
                 }
             },
             shutdown: async () => {
@@ -391,6 +405,7 @@ export class HueTransport {
                     admitted = queued;
                     this.admitLogParts(log, queued);
                     logs.onEmit(queued);
+                    this.protectDelivery(admitted);
                 }
                 catch {
                     if (admitted)
@@ -399,12 +414,18 @@ export class HueTransport {
                 }
             },
             forceFlush: async () => {
+                const finish = this.beginSpanDrain();
                 try {
                     await logs.forceFlush();
                 }
                 finally {
-                    if (!this.sendingRecords.getStore())
-                        await this.drainUploads();
+                    try {
+                        if (!this.sendingRecords.getStore())
+                            await this.drainUploads();
+                    }
+                    finally {
+                        finish();
+                    }
                 }
             },
             shutdown: async () => {
@@ -472,6 +493,14 @@ export class HueTransport {
                 this.logs.set(snapshot.record, snapshot.bytes);
             if (snapshot.unresolvedResource && !advisory)
                 this.issue(signal, "warning", 0, "Unresolved resource attributes omitted from the telemetry snapshot");
+            if (!advisory) {
+                const cohort = (this.deliveryCohort ??= {
+                    pending: 0,
+                    ...Promise.withResolvers(),
+                });
+                cohort.pending++;
+                this.deliveries.set(snapshot.record, cohort);
+            }
             return snapshot.record;
         }
         catch {
@@ -481,11 +510,42 @@ export class HueTransport {
             return undefined;
         }
     }
+    /** Register in the caller's request before it can return; outside Vercel this is a no-op. */
+    protectDelivery(record) {
+        const cohort = this.deliveries.get(record);
+        if (!cohort)
+            return;
+        try {
+            waitUntil(cohort.promise);
+        }
+        catch {
+            // A host hook must never undo admission or change the application's result.
+        }
+    }
+    /** @internal Seal the batch's cohort before export can yield to another request. */
+    exporting(records) {
+        if (records.some((record) => this.deliveries.get(record) === this.deliveryCohort))
+            this.deliveryCohort = undefined;
+    }
+    holdDelivery(cohort, work) {
+        if (!cohort)
+            return;
+        cohort.pending++;
+        const finish = () => this.finishDelivery(cohort);
+        void work.then(finish, finish);
+    }
+    finishDelivery(cohort) {
+        if (--cohort.pending !== 0)
+            return;
+        if (this.deliveryCohort === cohort)
+            this.deliveryCohort = undefined;
+        cohort.resolve();
+    }
     track(span) {
         try {
             if (!this.liveSpans || this.live.size >= MAX_LIVE_SPANS)
                 return;
-            if (!(span.spanContext().traceFlags & 1) || !span.isRecording() || !announcesLiveSpan(span))
+            if (!(span.spanContext().traceFlags & 1) || span.ended || !announcesLiveSpan(span))
                 return;
             this.live.add(span);
             if (!this.liveTimer) {
@@ -500,6 +560,8 @@ export class HueTransport {
     }
     /** Placeholders are built lazily, so input set right after a span starts is included. */
     announceLiveSpans() {
+        if (this.forcedSpanDrains)
+            return;
         for (const span of this.live) {
             this.live.delete(span);
             try {
@@ -547,6 +609,28 @@ export class HueTransport {
     placeholderSettled(record) {
         return this.placeholderSources.get(record)?.ended === true;
     }
+    beginSpanDrain() {
+        const completed = [...this.spans.keys()].some((span) => !this.placeholders.has(span));
+        this.forcedSpanDrains++;
+        if (completed)
+            this.completedSpanDrains++;
+        return () => {
+            this.forcedSpanDrains--;
+            if (completed)
+                this.completedSpanDrains--;
+        };
+    }
+    /** @internal A forced drain sends completed spans without another advisory round trip. */
+    deferPlaceholders(records) {
+        if (!this.completedSpanDrains)
+            return false;
+        for (const record of records) {
+            const source = this.placeholderSources.get(record);
+            if (!this.closed && source)
+                this.track(source);
+        }
+        return true;
+    }
     /** @internal Exporter callback: false once the receiver refused placeholders; queued ones are then dropped. */
     sendsPlaceholders() {
         return !this.placeholdersRejected;
@@ -570,6 +654,11 @@ export class HueTransport {
     /** @internal Exporter callback: releases queued records after an export attempt settles. */
     finish(signal, records) {
         for (const record of records) {
+            const cohort = this.deliveries.get(record);
+            if (cohort) {
+                this.deliveries.delete(record);
+                this.finishDelivery(cohort);
+            }
             this.releaseMedia(record);
             this.logMedia.delete(record);
             const pending = signal === "traces" ? this.spans : this.logs;
@@ -737,6 +826,7 @@ export class HueTransport {
      * them. */
     uploadQueued(record, settled, shared, released) {
         this.awaitUploads(settled);
+        this.holdDelivery(this.deliveries.get(record), settled);
         const identity = this.mediaIdentity(record);
         const staged = identity
             ? (this.media.get(identity) ?? []).reduce((total, file) => total + heldBytesOf(file.bytes), 0)
@@ -853,8 +943,8 @@ export class HueTransport {
         return this.offloadsValues() && this.uploader?.available() === true;
     }
     /** @internal Exporter callback: a redacted span with the values its redaction left to the
-     * upload step placed: listed under `hue.blobs` with their uploads queued (each added to `late`
-     * once it settles, and charged in place of the `queued` record it came from), or cut as before.
+     * upload step placed: listed under `hue.blobs` with their uploads queued (reported once settled,
+     * and charged in place of the `queued` record they came from), or cut as before.
      * Never rejects. */
     async offloadSpan(span, collector, upload, tally, late, queued) {
         // A record without a readable context cannot name its trace: its values are cut.
@@ -878,8 +968,7 @@ export class HueTransport {
                 memo: this.mediaMemo,
                 background: own,
             });
-            if (own.settled.length)
-                late.settled.push(mergeWhenSettled(late.tally, own.tally, own.settled));
+            this.collectDeliveryUploads(queued, own, late);
             return { ...span, attributes: attributes };
         }
         catch {
@@ -919,14 +1008,37 @@ export class HueTransport {
                 memo: this.mediaMemo,
                 background: own,
             });
-            if (own.settled.length)
-                late.settled.push(mergeWhenSettled(late.tally, own.tally, own.settled));
+            this.collectDeliveryUploads(queued, own, late);
             return placed(result);
         }
         catch {
             return placed(fallbackRecord(log.attributes, collector, valueBytes, tally, traceId, this.mediaMemo));
         }
     }
+    /** Keep an export's warning aggregation within each cohort's upload ownership. */
+    collectDeliveryUploads(record, uploads, late) {
+        const { settled, tally } = uploads;
+        if (!settled.length)
+            return;
+        let groups = this.deliveryUploads.get(late);
+        if (!groups)
+            this.deliveryUploads.set(late, (groups = new Map()));
+        const cohort = this.deliveries.get(record);
+        let group = groups.get(cohort);
+        if (!group)
+            groups.set(cohort, (group = { tally: newTally(), settled: [] }));
+        group.settled.push(mergeWhenSettled(group.tally, tally, settled));
+    }
+    /** @internal Report only the uploads each cohort owns, without retaining their records. */
+    reportUploads(late, signal) {
+        const groups = this.deliveryUploads.get(late);
+        this.deliveryUploads.delete(late);
+        for (const [cohort, { settled, tally }] of groups ?? []) {
+            const report = Promise.all(settled).then(() => this.reportOffload(tally, signal, true));
+            this.awaitUploads(report);
+            this.holdDelivery(cohort, report);
+        }
+    }
     /** @internal Exporter callback: counts an export's uploads and reports each kind of fallback
      * once, as a warning naming its traces: the values were exported cut as before, or, `late`,
      * their uploads failed after their records listed them. */
@@ -1147,13 +1259,19 @@ export class HueTransport {
      */
     flushRecords(providers) {
         const from = this.observedSequence;
-        const join = () => this.sendRecords();
+        let finish;
+        const join = () => {
+            finish = this.beginSpanDrain();
+            return this.sendRecords();
+        };
         const sent = providers ? this.sendingRecords.run(true, providers).then(join, join) : join();
-        const report = sent.then(async (processors) => {
+        const report = sent
+            .then(async (processors) => {
             // Exports the processors did not start (a timer's, still in flight) queued uploads too.
             await this.drainUploads();
             return this.flushReport(from, processors);
-        });
+        })
+            .finally(() => finish?.());
         return { sent, report };
     }
     /** Sends what the processors and exporters hold, once the previous flush's send ended. */
@@ -1387,6 +1505,7 @@ class ReportingExporter {
         this.redact = redact;
     }
     export(records, callback) {
+        this.transport.exporting(records);
         const work = this.exportRecords(records)
             .then(() => callback({ code: ExportResultCode.SUCCESS }), () => callback({
             code: ExportResultCode.FAILED,
@@ -1423,23 +1542,16 @@ class ReportingExporter {
                 real.push(placeholder);
         return real;
     }
-    /** Places and sends the records; the uploads their placement queued are reported once they
-     * settle, after the records were sent, never awaited here. */
+    /** Queue final upload reports before releasing the records that own their cohorts. */
     async exportRecords(records) {
         const late = { tally: newTally(), settled: [] };
         try {
             await this.placeAndSend(records, late);
         }
         finally {
-            if (late.settled.length)
-                this.reportWhenSettled(late);
+            this.transport.reportUploads(late, this.signal);
         }
     }
-    /** Reports an export's uploads once they all settle. Built apart from the export, so a pending
-     * upload never keeps the export's records alive. */
-    reportWhenSettled(late) {
-        this.transport.awaitUploads(Promise.all(late.settled).then(() => this.transport.reportOffload(late.tally, this.signal, true)));
-    }
     async placeAndSend(records, late) {
         // Completed records and placeholders travel in separate requests, completed records first,
         // so a rejection count is always one kind of record's. Placeholders are advisory: losing one
@@ -1850,7 +1962,10 @@ class ReportingExporter {
         // records' acknowledgements may have just shown, nor after this export's completed records were
         // refused or unanswered: a receiver that just refused or timed out gets no second request with
         // its own retries. A record this side could not send keeps the placeholders going out.
-        if (pending.length && !refused && this.transport.sendsPlaceholders())
+        if (pending.length &&
+            !refused &&
+            this.transport.sendsPlaceholders() &&
+            !this.transport.deferPlaceholders(records))
             await pack(pending, true);
         if (failed)
             throw new Error("Hue telemetry export failed");

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.22.0";
+export declare const sdkVersion = "0.23.1";
 /** OTLP dependency version sent in the export User-Agent. */
 export declare const otlpExporterVersion = "0.223.0";

package/dist/version.js

@@ -1,5 +1,5 @@
 // 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.22.0";
+export const sdkVersion = "0.23.1";
 /** OTLP dependency version sent in the export User-Agent. */
 export const otlpExporterVersion = "0.223.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "private": false,
   "license": "MIT",
   "publishConfig": {
@@ -98,6 +98,7 @@
     "@opentelemetry/resources": "2.12.0",
     "@opentelemetry/sdk-logs": "0.223.0",
     "@opentelemetry/sdk-trace": "2.12.0",
+    "@vercel/functions": "3.9.7",
     "zod": "^3.25.76 || ^4.6.5"
   },
   "devDependencies": {