@hue-run/sdk 0.13.2 → 0.15.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.13.2`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.15.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.
 
@@ -469,7 +469,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.13.2.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.15.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -480,7 +480,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.13.2.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.15.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -523,10 +523,10 @@ production agent lacks. Pin the SDK and bring its `zod` peer along, so the agent
 gains no dependency:
 
 ```sh
-npx --yes --package @hue-run/sdk@0.13.2 --package "zod@^4.6.5" hue eval --case "Refund an eligible charge" --command "node agent.js" --env-file .env.hue
-npx --yes --package @hue-run/sdk@0.13.2 --package "zod@^4.6.5" hue eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <experiment id>
-npx --yes --package @hue-run/sdk@0.13.2 --package "zod@^4.6.5" hue eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx --yes --package @hue-run/sdk@0.13.2 --package "zod@^4.6.5" hue eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision> --env-file .env.hue
+npx --yes --package @hue-run/sdk@0.15.0 --package "zod@^4.6.5" hue eval --case "Refund an eligible charge" --command "node agent.js" --env-file .env.hue
+npx --yes --package @hue-run/sdk@0.15.0 --package "zod@^4.6.5" hue eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <experiment id>
+npx --yes --package @hue-run/sdk@0.15.0 --package "zod@^4.6.5" hue eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx --yes --package @hue-run/sdk@0.15.0 --package "zod@^4.6.5" hue eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision> --env-file .env.hue
 ```
 
 Without the second `--package`, `hue eval` exits with `hue eval needs zod`, even for `--help`;
@@ -562,7 +562,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx --yes --package @hue-run/sdk@0.13.2 --package "zod@^4.6.5" hue eval --case "Refund an eligible charge" ./hue-agent.ts --content --env-file .env.hue
+npx --yes --package @hue-run/sdk@0.15.0 --package "zod@^4.6.5" hue eval --case "Refund an eligible charge" ./hue-agent.ts --content --env-file .env.hue
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.
@@ -581,11 +581,15 @@ Failing cases print the scorer explanation. An evaluator Hue records as not appl
 that case's columns and neither passes nor fails it, so in a mixed eval set a case is decided by
 the evaluators that apply to it; the pass line counts the not-applicable results. A case that no
 pinned evaluator applies to is an error that names what they need. A result of a pinned Hue judge
-(an evaluator of kind `world_judge`) that Hue marks advisory is
+(an evaluator of kind `world_judge`) whose immutable version does not set `config.required: true`
+and that Hue marks advisory is
 shown in its column, marked `(advisory)`, but never decides a case or the exit code; the pass line
 counts advisory failures as not counted, and a case only advisory results ran for is an error.
-The Answer outcome evaluator uses its required judge to decide answer-only cases; if that judge
-cannot run, the case is inconclusive. Any
+Applicable outcome evaluators and judge versions pinned with `config.required: true` need a
+decision before a case can pass. A required result skipped without a decision is inconclusive;
+missing results remain pending and evaluator errors remain errors. A recorded failure takes
+precedence over an unavailable required evaluator. The Answer outcome evaluator uses its
+required judge to decide answer-only cases. Any
 other evaluator's result, an error, or a metric that carries `passed` is never advisory, whatever
 its evidence says. A metric name that
 several evaluators report, such as two judges' `verdict`, gets a column per evaluator, labelled
@@ -667,21 +671,21 @@ A Scenario or eval set whose dataset version is not saved cannot back an experim
 exits 1 and asks for **Save eval-set version** in Hue or `--save-version`, which freezes that
 version at its current revision. Connection settings are `HUE_API_KEY` and `HUE_BASE_URL`
 (default `https://app.hue.run`), loaded from `--env-file <path>` (or its alias `--env-path`) first when given; `--origin`
-overrides the origin. Telemetry content capture stays off unless `--content` is passed; the
-examples pass it so the run's case spans carry content. Model and tool spans inside the agent come
+overrides the origin. Since TypeScript 0.14.0, telemetry content capture defaults on; `--no-content` opts out.
+Earlier releases require `--content`; the examples include it for compatibility. Model and tool spans inside the agent come
 only from the agent's own instrumentation. Case outputs, error messages and explanations are
-stored in Hue whether or not `--content` is passed, so a case's answer can be graded and read on
+stored in Hue independently of the telemetry capture setting, so a case's answer can be graded and read on
 its run page. A `--command`'s stdout is its answer unless it writes a result file, and is stored,
 so it must not print credentials or debug logs there; before storing, `hue eval` replaces the
 credentials it handed the case (the world token and MCP headers, a legacy MCP token, attempt
 bearers) and every Hue control-plane credential in its environment with `[redacted]`, in the
 answer, an adapter's thrown message and name, generated file names and the local checkpoint.
 `--no-output` keeps outputs, error messages and explanations out of a one-shot run's stored
-results; with `--content` the case span still carries the output. `--worker` always stores them, because a run launched from Hue is read
+results; captured telemetry still carries the output. Pass `--no-output --no-content` to omit both. `--worker` always stores them, because a run launched from Hue is read
 on its run page (that is `runLocalAgent()`'s contract), and refuses `--no-output`. An interrupted
 one-shot run keeps the choice it started with, so one run never mixes stored and unstored outputs:
-rerunning it with other `--no-output` or `--content` flags is refused with the flags it started
-with. Resume a run that an earlier SDK started without `--content` by passing `--no-output`.
+rerunning it with another output or telemetry capture policy is refused with the flags that resume it.
+To resume a metadata-only trace from an earlier release, add `--no-content` and keep its original `--no-output` choice.
 
 Files the agent writes to `output/` are uploaded as generated documents with or without
 `--no-output`, and they are not redacted the way the answer is: `hue eval` replaces the same
@@ -696,8 +700,11 @@ case is completed as failed (error `TelemetryNotAccepted`, evidence omitted as
 `telemetry_not_accepted`, no output or generated files attached) instead of being left started,
 and the run goes on. Each export of the CLI's own telemetry may take 30 seconds, retries
 included: a slow acknowledgement is waited for, and a 429, 502, 503, 504 or network error is
-retried within that time, honouring `Retry-After`; any other response, or rejected records, fails
-the case at once. Stderr names the case as it completes, with the export
+retried within that time, honouring `Retry-After`. A 429 whose `Retry-After` is longer than that
+holds the case's records and sends them again once it has passed, for at most 60 seconds of holds
+per export, so such a case can take that much longer; a longer wait fails the case as
+`telemetry_not_accepted`. Any other response, or rejected records, fails the case at once. Stderr
+names the case as it completes, with the export
 issue counts, for example
 `[refund] telemetry not accepted, case failed: telemetry_not_accepted: traces failed 1 (HTTP 400)`;
 the case counts as an error in the table and JSON whatever its scores, and the command exits 1.

package/EVALUATIONS.md

@@ -303,7 +303,7 @@ and require a Hue deployment that serves case `inputFiles` on experiment
 items, subject `files`, and the artifact reservation, upload, completion and download APIs. The
 Python SDK has no equivalent.
 
-The TypeScript 0.13.2 `hue eval --worker --command "…"` wrapper supplies both callbacks, so one
+Since TypeScript 0.13.2, the `hue eval --worker --command "…"` wrapper supplies both callbacks, so one
 command worker accepts direct and world cases, including mixed eval sets. It keeps the launch
 directory for relative application entry points; private case inputs/output still use
 `HUE_CASE_*`. An adapter-file worker opts into the direct callback with `--capability direct:v1`

package/README.md

@@ -35,7 +35,7 @@ import { createHue, HueExportError } from "@hue-run/sdk";
 const hue = createHue({
   apiKey: process.env.HUE_API_KEY!, // a project service key, on the server only
   serviceName: "my-agent",
-  captureContent: true, // required: true records content; false sends metadata only
+  captureContent: true, // Also works with older releases; false sends metadata only
   onExportIssue: (issue) => console.error(issue), // sanitized counts, never server bodies
 });
 
@@ -57,7 +57,7 @@ try {
 await hue.shutdown(); // flushes and releases providers owned by this client
 ```
 
-`captureContent` is required. The example sets `true`, the recommended choice: trace inspection,
+Starting with TypeScript 0.14.0, `captureContent` defaults to `true`. Earlier releases require an explicit choice. The example sets `true`: trace inspection,
 evaluations and judges read the prompts, responses and tool inputs/outputs it records. Choose
 `false` for metadata only when a policy forbids sending that content; see
 [Privacy and content](#privacy-and-content).
@@ -324,11 +324,21 @@ there is no SDK retention timer or automatic content expiry. To redact strings
 before export, supply `redact(value, path)`; it applies to supported strings in
 attributes, resources, event/link attributes and log bodies. Return a string.
 Invalid helper content is omitted with an instrumentation failure; the span can still be delivered.
-A content value over Hue's 256 KiB value cap is not omitted: text is cut to a UTF-8 prefix and
+A content value over Hue's 1 MiB value cap (or the value limit Hue's receiver advertises) is not
+omitted. A span's own string attribute over the cap is uploaded to Hue whole and replaced by its
+first 16 KiB (see [Values over the inline limit](#values-over-the-inline-limit)); `redact` sees
+the whole value first, and its answer is what is uploaded. Any other value over the cap, and one
+that could not be uploaded, is cut: text to a UTF-8 prefix, and
 bytes or a structured log body are replaced by the receiver's own marker
 (`{ "hue.truncated": true, "hue.truncated_bytes": <size> }`), and the value's key is listed in
 the record's `hue.truncated` attribute, where Hue's receiver lists the values it cuts itself,
 so the span still carries the call, the recorded part of its value and the rest of its evidence.
+`redact` sees text past the cap, so it can recognize a secret that crosses it. A string longer
+than the cap and 64 Ki code units that is not held whole for upload is cut to that length when
+its record is queued, so a value of millions of characters cannot drop its record for the queue
+budget; for such a text the last 64 Ki code units of the redactor's answer are never exported,
+and tool definitions and recorded requests have their credentials removed from the whole value
+before that cut.
 Export-time redactor failures reject the affected record and are reported by flush. Shared resources are redacted once per
 export batch. Do not put user content or secrets in span names or scope names.
 
@@ -361,18 +371,24 @@ rotates. Only definitions another integration recorded can be summarized: `hueTe
 inputs and exports through Hue's attached processors gets the summary.
 Recorded messages can inline files: GenAI `blob` parts in `gen_ai.input.messages` /
 `gen_ai.output.messages` (what the AI SDK 7 adapter records for a file part) and AI SDK 6 `file`
-parts in `ai.prompt.messages`. A span whose messages exceed 256 KiB would be cut, so when a
-record is queued Hue replaces the `content`/`data` of any such part longer than 64 KiB with the
-file's `sha256` and `size`, both of the file's own bytes whatever its media type (base64 content
-and `;base64` `data:` URLs decoded, other `data:` URLs percent-decoded, anything else as UTF-8 text), keeping the part's other fields such as `type`, `mime_type` and `mediaType`. Smaller inline
-files are exported as recorded. The digest matches `hue.recordFile`'s `hue.file.sha256` for the same
-bytes, so a file can be recognized wherever it appears. The replacement happens before the record is
-charged to the queue budget, so a large file does not drop its span. It is bounded: a message
-attribute longer than 8 MiB of text is left unchanged, and the default 8 MiB `maxQueueBytes` then
-drops the span. Base64 grows a file by a third, so that ceiling is an inline file of about 6 MiB.
-The same message text is hashed once per record, and a record inspects at most 16 MiB of message
-text in all; messages past that are charged as recorded. With `captureContent: false` the messages,
-which export removes, are neither hashed nor charged.
+parts in `ai.prompt.messages`. A file is measured by its own bytes whatever its media type (base64
+content and `;base64` `data:` URLs decoded, other `data:` URLs percent-decoded, anything else as
+UTF-8 text). When a span's own message attribute inlines a file larger than 64 KiB, export uploads
+the file's bytes to Hue under the part's media type (`mime_type` or `mediaType`, else its `data:`
+URL's) and keeps the first 16 KiB of the part's `content`/`data` in place, listing the file in the
+span's `hue.blobs` as `<attribute>#<JSON pointer>`, for example
+`gen_ai.input.messages#/0/parts/1/content` (see
+[Values over the inline limit](#values-over-the-inline-limit)). A file that is not uploaded, and a
+large inline file in a log record or a span event, keeps the earlier behavior: the part's
+`content`/`data` is replaced by the file's `sha256` and `size`, keeping its other fields such as
+`type`, `mime_type` and `mediaType`, when the record is queued (or, for a span's own messages, at
+export). Smaller inline files are exported as recorded. The digest matches `hue.recordFile`'s
+`hue.file.sha256` for the same bytes, so a file can be recognized wherever it appears. It is bounded:
+a message attribute longer than 8 MiB of text is not inspected for files, and is uploaded or cut
+like any value over the cap. Base64 grows a file by a third, so that ceiling is an inline file of
+about 6 MiB. The same message text is inspected once per record, and a record inspects at most
+16 MiB of message text in all. With `captureContent: false` the messages, which export removes,
+are neither inspected nor charged.
 
 Manual helpers encode JSON values without converting null into absence. Unknown
 outputs and usage remain absent. This SDK does not estimate tokens or cost. A thrown
@@ -476,15 +492,92 @@ const hue = createHue({
 ## Delivery behavior
 
 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. A record over the request limit on its own sheds its content values,
+honoring `Retry-After`) within the export timeout, by OpenTelemetry's OTLP/HTTP exporter rules. A
+429 whose `Retry-After` outlasts the export timeout keeps its records queued, within the queue's
+bounds, and sends them again once the wait has passed; an export holds its records this way for at
+most 60 seconds in all, and a longer wait loses them, reported as a `failed` issue with status 429.
+`flush()` and `shutdown()` wait for a held export, and a held export keeps the process running
+until it is sent. When `shutdownSafe()`'s budget runs out first, a client that owns its providers
+ends the hold: its records are reported lost to the rate limit and the process can exit. In attach
+mode the application's providers drain with their own timeout (OpenTelemetry's default is 30
+seconds), so a flush during a longer hold can report a provider flush failure while the held
+export continues.
+
+Requests are measured as Hue's receiver measures them: after gzip against its request limit and
+after decompression against its decoded limit. Until a response advertises its own limits
+(`Hue-Max-Request-Bytes`, `Hue-Max-Decoded-Bytes` and `Hue-Max-Value-Bytes`, on every
+acknowledgement and refusal) these are 1 MiB on the wire, 4 MiB decoded and 1 MiB per value;
+advertised limits are adopted, clamped to 1–64 MiB, 1–64 MiB and 256 KiB–16 MiB, and never
+exceeded: a request that limits lowered while it was retried or held no longer fit is split and
+shed again before it is sent. Batches are packed to 4 MiB before gzip (or the decoded limit, when lower) and split at
+record boundaries; a batch that compresses worse than the limit allows is sent in halves. A record
+over a limit on its own sheds its content values,
 largest first, each replaced by the receiver's marker and listed under `hue.truncated`, until it
 fits; only a record too large without any content value is lost, reported as an `invalid` issue,
 and counted on its trace's root span as `hue.sdk.dropped_records` when the root is exported, so
-Hue reads the trace as incomplete by that many records. Each signal queues at most 2,048 records, including
+Hue reads the trace as incomplete by that many records; so are records lost to a rate limit
+longer than the hold. Each signal queues at most 2,048 records, including
 exports in flight; overflow is reported through the callback, counters and next
-flush. This is an in-memory queue, not durable storage.
+flush. This is an in-memory queue, not durable storage. A client's own providers keep 2,000
+attributes, events and links per span and 2,000 attributes per log record (OpenTelemetry's default
+is 128); providers an application attaches Hue to keep their own limits. A span whose events or
+links do not all fit the queue's byte budget keeps its newest ones and counts the rest in its
+dropped event and link counts, rather than being dropped whole.
+
+### Values over the inline limit
+
+Hue keeps a value inline up to its value limit (1 MiB unless the receiver advertises another in
+`Hue-Max-Value-Bytes`). A span's own string attribute larger than that (helper content such as
+`input.value`, `output.value` and tool results, or another instrumentation's attribute), and an
+inline file over 64 KiB in a span's own recorded messages, is uploaded to Hue apart from the span,
+up to Hue's upload limit of 1,000,000,000 bytes:
+
+1. Export computes the SHA-256 of the value's bytes (a string as UTF-8, a file as its own bytes)
+   and reserves it with `POST /api/v1/otlp/blobs`, authenticated with the project key. Hue answers
+   that it already stores the value under the trace, and nothing is uploaded, or with a presigned
+   URL.
+2. The bytes go straight to the project's evidence store in one `PUT` to that URL, with exactly the
+   headers Hue signed and never the project key (over HTTPS, or plain HTTP to a loopback store or
+   with `allowInsecureHttp`), and
+   the upload is confirmed with `POST /api/v1/otlp/blobs/complete`. A PUT the store answers with
+   412 (the same value uploaded at the same time by another span) counts as stored.
+3. The span keeps the value's first 16 KiB in the attribute it replaced and lists the value in its
+   `hue.blobs` attribute, one compact JSON object per value:
+   `{"key":"output.value","sha256":"<64 hex>","size":5242880,"content_type":"application/json"}`.
+   A whole value is listed under `hue.truncated` as well, since its inline text is a prefix.
+
+Hue stores the value under the trace, so the trace's retention, deletion and erasure cover it.
+Uploads run in the export, never on the application's thread: at most four at a time, each request
+within the export timeout, and all of one export's uploads within six export timeouts; a
+transient failure is retried once. A rate-limited reservation (429) waits out its `Retry-After`
+within the export's 60-second hold. `flush()` and `shutdown()` wait for uploads like any export
+work, and a `shutdownSafe()` whose budget runs out ends the uploads in flight.
+
+A value that cannot be uploaded (Hue or the store refused it or failed, the network or a deadline
+did, the receiver has no upload route, or the value is over 1 GB) is exported as before uploads
+existed: cut to the limit and listed under `hue.truncated`, an inline file as its digest. Each
+export reports such values in a `warning` issue per cause, whose `count` is the values and
+`traceIds` their traces, and counts them in `report.uploadFallbacks`; uploaded values are counted
+in `report.uploadedValues`. A warning never makes `flush()` throw. After a transient failure, or
+a refusal that is not about the value alone, uploads pause for 30 seconds, and a receiver without
+the upload route (a 404 that is not Hue's, a 405 or 501, or a 200 that is no reservation) is not
+asked again for 10 minutes, so an unavailable store or another OTLP receiver meets no retry storm.
+
+To upload a value whole, the queue holds it until export apart from `maxQueueBytes`, within a
+128 MiB budget of held values (a string charged two bytes a code unit); a recorded message holding
+an inline file over 64 KiB is held the same way. `maxQueueBytes` is still charged what the value
+would cost cut (a message, its copy with the files as their digest), so one that cannot be
+uploaded is exported exactly as it was before. A value the budget cannot hold, or one queued while
+the receiver is known to lack the upload route, is cut (its files digested) when it is queued, as
+before, and reported as not uploaded, once per file; a single value larger than the whole budget
+is held while nothing else is. While values can be uploaded, helpers encode content whole, up to the
+upload limit and 1,048,576 values, rather than cutting it to the value limit as they record it.
+
+Nothing is uploaded with `captureContent: false` or a setup credential (`hue_setup_…`), nor from
+log records (Hue does not read a log record's uploaded values yet), span events, links, resources
+or in-progress placeholders: those values are cut as before. `redact` and the credential scrub of
+tool definitions and recorded requests run on the whole value before it is hashed, so a value they
+rewrite is uploaded as rewritten.
 
 `flush()` waits for the current trace and log export work. A partial rejection,
 invalid acknowledgement, queue drop or failure throws `HueExportError`; its
@@ -649,11 +742,11 @@ before), wraps `runSimulation()` and `runLocalAgent()` for an adapter file or a
 `hue eval --case "<name>" ./hue-agent.ts --content` creates a fresh run from a published case's
 immutable pins, runs the agent with an isolated world when the case pins one, waits
 for Hue's outcome checks and prints the run URL and per-case PASS/FAIL verdicts with an exit code;
-`--worker` registers the same adapter for runs launched from Hue. In TypeScript 0.13.2, a
+`--worker` registers the same adapter for runs launched from Hue. Since TypeScript 0.13.2, a
 command worker handles both world and answer-only cases; adapter workers opt into direct cases
 with `--capability direct:v1`. Upgrade an existing command registration under a new `--revision`.
-It needs a Read and write key in `HUE_API_KEY` (never printed). Content capture stays off unless `--content` is
-passed; the example passes it so case spans carry content. Case outputs, error messages and
+It needs a Read and write key in `HUE_API_KEY` (never printed). Content capture defaults on; `--no-content` opts out. The example passes `--content` explicitly
+for compatibility with older releases. Case outputs, error messages and
 explanations are stored in Hue either way (`--no-output` keeps them out of a one-shot run's
 results); a command's stdout is its stored answer, with the credentials `hue eval` handed the case
 replaced by `[redacted]`.
@@ -702,6 +795,6 @@ existing-provider flush callbacks and recovery. Local/CI runners remain availabl
 
 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.
 
-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. 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 safety](https://docs.hue.run/guides/production-safety).
+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 the values over the inline limit uploaded apart from their spans and exported cut instead. 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 safety](https://docs.hue.run/guides/production-safety).
 
 Queued records snapshot supported telemetry values when a span ends or a log is emitted; later caller mutations cannot change queued data. Resource attributes still awaiting detection are omitted with a sanitized warning. Later records include them after detection finishes; await resource detection before instrumentation when those attributes are required.

package/dist/blobs.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Values larger than Hue's inline limit travel apart from their span: the SDK uploads the value's
+ * bytes straight to the project's evidence store through a presigned PUT that Hue answers at
+ * `POST /api/v1/otlp/blobs`, keeps the value's first 16 KiB in the attribute it replaced, and
+ * lists the value in the span attribute `hue.blobs`. A value that cannot be uploaded is exported
+ * as it was before uploads existed: cut to the inline limit and listed under `hue.truncated` (an
+ * inline file as its digest), reported as a warning and counted.
+ */
+/** The span attribute listing the values the SDK uploaded apart from the span: one compact JSON
+ * object per value, `{"key", "sha256", "size", "content_type"}`, as Hue reads it. */
+export declare const BLOBS_KEY = "hue.blobs";
+/** The largest value one upload may hold (`Hue-Max-Blob-Bytes`): a larger value is cut inline. */
+export declare const MAX_BLOB_BYTES = 1000000000;
+/** What an uploaded value keeps inline: its first 16 KiB, the receiver's search excerpt. */
+export declare const BLOB_PREFIX_BYTES: number;
+/** The entries one record's `hue.blobs` may list; Hue reads no more. */
+export declare const MAX_BLOB_ENTRIES = 64;
+/**
+ * The values over the inline limit that queued spans may hold whole for upload at once, charged
+ * apart from `maxQueueBytes` (a string as two bytes a code unit, bytes as themselves). A value
+ * the budget cannot hold is cut when it is queued, as before uploads existed; a single value
+ * larger than the whole budget is held while nothing else is.
+ */
+export declare const MAX_HELD_BLOB_BYTES: number;
+/** How long one export may spend uploading its values, on top of its requests. */
+export declare function uploadBudgetMillis(timeoutMillis: number): number;
+/** Why a value over the inline limit was exported cut instead of uploaded. */
+export type FallbackReason = "unsupported" | "failed" | "tooLarge" | "budget";
+/** The fixed description of each fallback, as an export issue reports it. */
+export declare const FALLBACK_MESSAGES: Record<FallbackReason, string>;
+/** A span's own attribute value the redaction left whole for the upload step to place. */
+export interface OffloadCandidate {
+    key: string;
+    value: string | Uint8Array;
+}
+/** What redaction leaves to the upload step: the candidates, and the keys of the values over the
+ * inline limit the queue cut when the span was admitted (they cannot be uploaded whole). */
+export interface OffloadCollector {
+    candidates: OffloadCandidate[];
+    cut: string[];
+}
+/** The outcome of one export's uploads, reported once the export's records are placed. */
+export interface OffloadTally {
+    uploaded: number;
+    fallbacks: Map<FallbackReason, {
+        count: number;
+        traceIds: Set<string>;
+    }>;
+}
+export declare function newTally(): OffloadTally;
+export declare function isBlobContentType(value: unknown): value is string;
+/** The media type an uploaded text is stored under: JSON when it reads as a JSON object or array
+ * (a structured value's text), plain UTF-8 text otherwise. Both are previewed as text. */
+export declare function textContentType(text: string): string;
+/** What an uploaded value keeps inline: its first 16 KiB (text cut back to a character), held
+ * as its own copy so the whole value is not kept alive by it. */
+export declare function blobPrefix(value: string): string;
+export declare function blobPrefix(value: Uint8Array): Uint8Array;
+/** The SHA-256 (lowercase hex) and byte size of what an upload of `value` carries, yielding to
+ * the event loop between slices so a large value does not stall the application. */
+export declare function digestOf(value: string | Uint8Array): Promise<{
+    sha256: string;
+    size: number;
+}>;
+/** What one export's uploads share: their deadline, and the export's hold for a receiver that
+ * limited the rate (`wait` resolves false when the hold may not take `millis` more). */
+export interface UploadContext {
+    deadline: number;
+    wait(millis: number): Promise<boolean>;
+}
+type Outcome = {
+    ok: true;
+    contentType: string;
+} | {
+    ok: false;
+    reason: FallbackReason;
+};
+/** The upload route's options, from the transport's validated options. */
+export interface UploaderOptions {
+    baseUrl: string;
+    apiKey: string;
+    timeoutMillis: number;
+    allowInsecureHttp: boolean;
+    userAgent: string;
+}
+/**
+ * Uploads values to Hue: reserves each with `POST /api/v1/otlp/blobs`, PUTs its bytes to the
+ * presigned URL Hue answers (skipped when Hue already stores the value), and completes it. At
+ * most {@link UPLOAD_CONCURRENCY} uploads run at once; every request has a deadline and none
+ * follows a redirect. A receiver without the route (a 404 without Hue's JSON error, a 405 or
+ * 501, or a 200 that is no reservation) is remembered for {@link UNSUPPORTED_PAUSE_MILLIS}, and a
+ * transient failure or a refusal that is not about the value alone pauses uploads for
+ * {@link FAILURE_PAUSE_MILLIS}, so values fall back to the inline cut instead of retrying.
+ */
+export declare class BlobUploader {
+    private readonly options;
+    private unsupportedUntil;
+    private pausedUntil;
+    private closed;
+    private running;
+    private waiting;
+    private requests;
+    constructor(options: UploaderOptions);
+    /** Whether a value over the inline limit is worth holding whole for upload now. */
+    available(): boolean;
+    /** Whether the receiver lacks the upload route, as it last answered. */
+    unsupported(): boolean;
+    /** Ends uploads in flight and refuses new ones: their values fall back to the inline cut. */
+    close(): void;
+    /** Runs `work` once fewer than {@link UPLOAD_CONCURRENCY} uploads are in flight. */
+    limit<R>(work: () => Promise<R>): Promise<R>;
+    /** Why a value cannot be uploaded right now without trying, if it cannot. */
+    refusal(): FallbackReason | undefined;
+    private pause;
+    /**
+     * Stores `value` under `key` of the trace: reserved, uploaded unless Hue already holds it, and
+     * completed. The caller holds a {@link limit} slot.
+     */
+    store(traceId: string, key: string, value: string | Uint8Array, contentType: string, digest: {
+        sha256: string;
+        size: number;
+    }, upload: UploadContext): Promise<Outcome>;
+    private jsonHeaders;
+    /** Reserves the value: Hue answers that it holds it already, or a presigned PUT. A rate limit
+     * is waited out within the export's hold, a transient refusal retried once. */
+    private reserve;
+    private delay;
+    /** A 200 answer read: `exists`, or an upload whose URL and headers are usable as given. */
+    private reservation;
+    /** The PUT of the value's bytes, with exactly the headers Hue signed. */
+    private put;
+    /**
+     * One HTTP request with a deadline and an idle timeout, never following a redirect, its
+     * response body bounded. Undefined for a network error, a timeout or a closed uploader. A text
+     * or byte body larger than one slice is written a slice at a time with backpressure; `length`
+     * is then its byte size.
+     */
+    private request;
+}
+/** Where one export's values are uploaded, and what it learned of them. */
+export interface OffloadOptions {
+    uploader: BlobUploader;
+    traceId: string;
+    /** The receiver's inline value limit. */
+    valueBytes: number;
+    upload: UploadContext;
+    tally: OffloadTally;
+}
+/**
+ * A span's own attributes with each candidate placed: an inline file part over 64 KiB in a
+ * recorded message uploaded and replaced by its first 16 KiB (or by its digest, as before, when
+ * it could not be), and a value still over the inline limit uploaded and replaced by its first
+ * 16 KiB (or cut to the limit), each upload listed under `hue.blobs`, each whole value cut or
+ * uploaded listed under `hue.truncated`. Every fallback is counted in the tally.
+ */
+export declare function offloadAttributes(attributes: Record<string, unknown>, collector: OffloadCollector, options: OffloadOptions): Promise<Record<string, unknown>>;
+/**
+ * The span's own attributes with every candidate placed as it was before uploads existed, for an
+ * upload step that failed unexpectedly: a message's large inline files as their digest, a value
+ * over the inline limit cut to it (bytes replaced by the receiver's marker) and listed under
+ * `hue.truncated`.
+ */
+export declare function fallbackAttributes(attributes: Record<string, unknown>, collector: OffloadCollector, valueBytes: number, tally: OffloadTally, traceId: string): Record<string, unknown>;
+export {};