@hue-run/sdk 0.22.0 → 0.23.0

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.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.
 
@@ -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.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.23.0 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.0.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.0.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.0 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.23.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.23.0 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.23.0 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.0 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.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.23.0 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.

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.0";
 /** 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.0";
 /** 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.0",
   "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": {