@hue-run/sdk 0.15.2 → 0.17.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.15.2`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.17.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.15.2.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.17.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.15.2.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.17.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -510,7 +510,7 @@ and prints Hue's verdicts. It is the command-line form of `runSimulation()` (one
 process, Hue creates one isolated simulated world per case, and Hue-owned outcome checks grade
 the sealed world. Hue never executes the agent. `HUE_API_KEY` must be a **Read and
 write** project key (a **Read** or **Tracing only** key cannot read cases or create runs);
-the CLI never prints it. The optional `zod` peer of `@hue-run/sdk/evals` must be installed.
+the CLI never prints it.
 
 Run the agent's own start command with `--command`. `hue eval` spawns it once per case with the
 world's environment (below) and `{"inputs", "config"}` on stdin, and stores its stdout as the
@@ -519,19 +519,20 @@ committed helper described in [Make your agent eval-ready](https://docs.hue.run/
 reads `HUE_SIM_<SURFACE ID>_URL` and `HUE_WORLD_TOKEN` when `HUE_WORLD_TOKEN` is set, fails
 closed when a needed variable is missing, and returns the production URL and credential
 otherwise. Never hand the agent Hue-native tools (`context.tools`, `context.mcp`) or a tool its
-production agent lacks. Pin the SDK and bring its `zod` peer along, so the agent's repository
-gains no dependency:
+production agent lacks. Pin the SDK, so the agent's repository gains no dependency:
 
 ```sh
-npx --yes --package @hue-run/sdk@0.15.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.15.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.15.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.15.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 -y @hue-run/sdk@0.17.0 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.17.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.17.0 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.17.0 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
 ```
 
-Without the second `--package`, `hue eval` exits with `hue eval needs zod`, even for `--help`;
-installing zod in the project does not help when the SDK itself is not installed there. An
-unpinned `--package @hue-run/sdk` runs a local, possibly older, copy in a project that already
+One invocation creates one run holding every selected case; it prints the run URL
+(`https://app.hue.run/runs/<id>`) once the run exists. Add `--check` to confirm the key, the
+selection, the case kind and the agent first: it prints what the run would do and exits without
+creating a run, a world or a checkpoint. An
+unpinned `npx @hue-run/sdk` runs a local, possibly older, copy in a project that already
 depends on it.
 
 An adapter module is the in-process alternative for a TypeScript agent. It exports `default` or
@@ -562,7 +563,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx --yes --package @hue-run/sdk@0.15.2 --package "zod@^4.6.5" hue eval --case "Refund an eligible charge" ./hue-agent.ts --content --env-file .env.hue
+npx -y @hue-run/sdk@0.17.0 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.
@@ -593,7 +594,7 @@ 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
-with the version's first eight characters. `--baseline <experiment id|url>` adds improvement,
+with the version's first eight characters. `--baseline <run id|url>` adds improvement,
 regression and unchanged counts with per-case deltas. `--json` prints one JSON document
 (`experimentId`, `runId`, `runUrl`, `complete`, `cases`, `totals`, optional `baseline`) on stdout
 and sends progress to stderr; each case lists its not-applicable evaluator versions in
@@ -670,7 +671,8 @@ the sealed world at once and attaches the trace once its export is complete. The
 A Scenario or eval set whose dataset version is not saved cannot back an experiment: the command
 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`
+(default `https://app.hue.run`), loaded from `--env-file <path>` (or its alias `--env-path`) first when given, otherwise from
+`./.env.hue` when the shell has no `HUE_API_KEY` (a key in the shell keeps its own origin); `--origin`
 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
@@ -734,8 +736,8 @@ published version, beside or instead of explicit `--scorer-version` IDs.
 ```sh
 hue eval --set gia-d1-citation --scorer gia-d1-citation \
   --command "pnpm --filter @august/frontend run hue:gia-agent" \
-  --revision prompt-v10 --wait 1800 --content --json --env-file .env.hue
-hue eval --set gia-d1-citation --set-version 1 --scorer gia-d1-citation ./hue-agent.ts --content --baseline <experiment id>
+  --revision prompt-v10 --wait 1800 --content --json
+hue eval --set gia-d1-citation --set-version 1 --scorer gia-d1-citation ./hue-agent.ts --content --baseline <run id>
 ```
 
 For each case the command is spawned once **inside a private case directory** with
@@ -755,14 +757,21 @@ minutes, so a completion that cannot reach Hue takes that long to fail; a reserv
 that cannot reach Hue still fails at once.
 
 Every regular file the command leaves under `output/` is uploaded as a generated document
-(accepted: `.pdf .docx .pptx .xlsx .json .txt .csv .png .jpg .jpeg .webp`; another extension or an
-empty file is the case's error). Optional helpers: `manifest.json` (`{"primary": "<filename>",
-"output": <json>}`) names the primary document and the JSON output; `result.json` is the JSON
+(accepted: `.pdf .docx .pptx .xlsx .json .txt .csv .png .jpg .jpeg .webp .gif .avif .mp3 .mpeg
+.wav .ogg .m4a .flac .opus .aac .mp4 .webm`; another extension or an empty file is the case's
+error). Optional helpers: `manifest.json` (`{"primary": "<filename>", "output": <json>,
+"contentTypes": {"<path>": "<MIME>"}}`) names the primary document, the JSON output and declared
+content types; `result.json` is the JSON
 output; `summary.txt` or `summary.md` is recorded as `{"summary": "..."}`. When none is written,
 the command's stdout is the output (JSON when it parses). A single generated file is the primary
 document by default. Model and provider credentials stay in the command's own environment; the
 scoped case files are copies under `--checkpoint-dir` (default `.hue/eval/<agent-key>/<project>/direct/<experiment>`).
 
+For `.mp4` and `.webm` files, `manifest.json.contentTypes` must declare the matching audio or
+video MIME type: `audio/mp4` or `video/mp4`, and `audio/webm` or `video/webm`. Each key must match
+the actual relative path under `output/`, including case. For example,
+`{"contentTypes":{"nested/clip.MP4":"video/mp4"}}` declares `output/nested/clip.MP4`.
+
 The same collection serves world cases, and it does not trust paths the agent controls. `output/`
 must be a real directory, and a helper name, when present, a regular file; a symlink, FIFO or
 directory in either place is the case's error. Symlinks and other special files among the

package/EVALUATIONS.md

@@ -7,7 +7,7 @@ Install the optional runtime-contract peer with the SDK before importing
 npm install @hue-run/sdk zod
 ```
 
-The SDK executes targets and scorers on your machine. Hue stores pinned definitions, experiment progress and results. It does not execute uploaded source code. Follow the [installation guide](https://docs.hue.run/installation) to add `@hue-run/sdk` to your application.
+The SDK executes targets and scorers on your machine. Hue stores pinned definitions, experiment progress and results. It does not execute uploaded source code. Follow [Install the SDK](https://docs.hue.run/quickstart#2-install-the-sdk) to add `@hue-run/sdk` to your application.
 
 Create a **Read and write** project service key under **Settings → Integrations & API keys** and expose it to this server-side process as `HUE_API_KEY`. A **Tracing only** key cannot author datasets or evaluation runs.
 

package/README.md

@@ -205,26 +205,33 @@ while the callback result is returned unchanged.
 ## Files
 
 Record a file the work read, received or produced with `hue.recordFile`. It adds a `hue.file`
-event to the active span (or the span of an explicit context passed second), keyed by the file's
-SHA-256, so a trace can be linked to the same file elsewhere without exporting its bytes:
+event to the active span, or to the span of an explicit context passed second. The event identifies
+the file by SHA-256. Pass `upload: true` to store its bytes in Hue as well:
 
 ```ts
 import { readFile } from "node:fs/promises";
 
 await hue.withSpan("review contract", async () => {
   const pdf = await readFile("contract.pdf");
-  hue.recordFile({ role: "input", mediaType: "application/pdf", data: pdf, name: "contract.pdf" });
-  // ...
+  hue.recordFile({
+    role: "input", mediaType: "application/pdf", data: pdf, name: "contract.pdf", upload: true,
+  });
 });
 ```
 
-`data` up to 25 MiB is hashed and measured locally and never exported; larger data is omitted and
-counted as an instrumentation failure, so pass `sha256` (and `byteSize`) instead when you already
-have them. The event carries `hue.file.sha256`, `hue.file.role` (`input`,
-`attachment` or `output`), `hue.file.media_type` and `hue.file.size`. It is metadata, so it is
-recorded in both capture modes, while `hue.file.name` is recorded only when `captureContent` is
-true. An invalid record, or one without an active span, is omitted and counted as an
-instrumentation failure.
+`upload` defaults to `false`, which hashes and measures `data` locally without exporting bytes.
+`data` is limited to 25 MiB. Larger data is omitted and counted as an instrumentation failure;
+pass `sha256` and `byteSize` when you already have them. Upload requires supplied bytes, content
+capture and an ordinary project key. It runs during export and adds a `hue.blobs` entry to the
+same span, keyed `event:hue.file:<sha256>`, while preserving the event.
+
+The event carries `hue.file.sha256`, `hue.file.role` (`input`, `attachment` or `output`),
+`hue.file.media_type` and `hue.file.size` in both capture modes. `hue.file.name` requires
+`captureContent: true`. Names must be nonblank after trimming, contain at most 256 UTF-16 code
+units, be well-formed Unicode and contain no C0 characters (U+0000–U+001F) or DEL (U+007F).
+Tabs, newlines, DEL and lone surrogates make a name invalid. An invalid name is omitted and
+counted as an instrumentation failure; the otherwise valid event remains. Invalid records and
+records without an active span count as instrumentation failures.
 
 ## Vercel AI SDK 6
 
@@ -369,26 +376,34 @@ definition list. The digest is the same in both SDKs and does not change when a
 rotates. Only definitions another integration recorded can be summarized: `hueTelemetry(hue)` with
 `captureContent: false` records none, whereas an application whose AI SDK integration records
 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 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.
+Recorded messages can contain images, documents and audio. Hue inspects
+`gen_ai.input.messages`, `gen_ai.output.messages` and `ai.prompt.messages`, including `parts`
+and OpenAI `content` arrays. Supported byte shapes include GenAI `blob`, AI SDK `file` and
+`image`, OpenAI Chat and Responses image, file and audio parts, Anthropic base64 sources, Gemini
+`inlineData` and `inline_data`, Vertex `media`, and Bedrock image and document sources.
+Remote URLs, provider file IDs and S3 references stay unchanged. Hue never fetches them.
+
+Nonempty binary media in a span's own message attributes is eligible for upload at every size
+within the inspection limits. Empty byte fields stay recorded and do not upload. The byte field is
+removed and the part carries `sha256` and `size`; the span's `hue.blobs` entry points to the part,
+for example `gen_ai.input.messages#/0/parts/1`. Text media over 64 KiB of decoded bytes uploads
+with a UTF-8-safe 16 KiB prefix in its content field. Its entry points to that field, for example
+`gen_ai.input.messages#/0/parts/1/content`. Smaller text stays inline. Hue reads both these forms
+and earlier binary prefixes. If upload fails, the part keeps its digest with no blob entry.
+In resources, events, links and log records, inline media up to 64 KiB stays verbatim; larger
+inline media is replaced by its digest, as events, links and log records were in 0.16. These
+nested values never upload. Ordinary hold, cut or drop rules still apply to the resulting record.
+
+Entries use the recorded media type and, when valid, the filename, name or title. A valid name
+is nonblank after trimming, at most 256 UTF-16 code units and well-formed Unicode, with no C0
+characters (U+0000–U+001F) or DEL (U+007F). Invalid names are omitted
+from the entry without rewriting the original field. Data URLs and fields explicitly encoded as
+base64 by the provider contract are decoded before hashing. Other non-data strings with a valid
+declared textual media type remain raw UTF-8: `YWJj` hashes as those four characters. The digest
+matches `hue.recordFile`'s digest for the same bytes. Inspection is bounded to 8 Mi UTF-16
+code units of text per message attribute and 16 Mi per record. Longer attributes use the ordinary value limit.
+With `captureContent: false`, messages are removed without inspection or uploads. See
+[Values over the inline limit](#values-over-the-inline-limit).
 
 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
@@ -528,8 +543,7 @@ dropped event and link counts, rather than being dropped whole.
 
 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,
+`input.value`, `output.value` and tool results, or another instrumentation's attribute), and eligible media in a span's own recorded messages, are 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)
@@ -541,8 +555,9 @@ up to Hue's upload limit of 1,000,000,000 bytes:
    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:
+3. Whole string values and large text media keep a UTF-8-safe 16 KiB prefix. Binary media keeps
+   its digest on the part. The span lists stored values in `hue.blobs`, at most 64 compact JSON
+   strings with fields ordered `key`, `sha256`, `size`, `content_type` and optional `name`:
    `{"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.
 
@@ -555,17 +570,20 @@ 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
+existed: whole attributes keep a prefix up to the limit and are listed under `hue.truncated`;
+media parts keep their digest without a blob entry; failed opt-in `recordFile` uploads preserve
+the file event. The explicit helper limit is 25 MiB; whole attributes retain their 1 GB limit. 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
+`traceIds` their traces, and counts them in `report.uploadFallbacks`; successful uploads are counted
+in `report.uploadedValues`. Both counters include whole attributes, eligible media and opt-in
+`recordFile` uploads. 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
+eligible media 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
@@ -574,8 +592,9 @@ is held while nothing else is. While values can be uploaded, helpers encode cont
 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
+log records (Hue does not read a log record's uploaded values yet), links, resources
+or in-progress placeholders. Span events upload only through explicit `recordFile({ upload: true, ... })`;
+other event 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.
 
@@ -677,15 +696,12 @@ conditions only. Use Hue's UI to inspect captured values and redaction.
 
 ## Dependencies
 
-The tracing core depends only on official `@opentelemetry/*` packages. The optional
-`@hue-run/sdk/evals` entry point uses `zod` for its bounded runtime contracts; install that peer
-when you use evaluations or simulations. JSON Schema scoring also uses `ajv`, an optional peer
-loaded inside a worker only when `builtins.jsonSchema` scores a case; without it that scorer
+The tracing core depends only on official `@opentelemetry/*` packages and `zod`, which the
+`@hue-run/sdk/evals` entry point and `hue eval` use for their bounded runtime contracts and which
+installs with the SDK. JSON Schema scoring also uses `ajv`, an optional peer loaded inside a worker only when `builtins.jsonSchema` scores a case; without it that scorer
 reports `SchemaValidatorUnavailable`. Install it when you use that scorer:
 
 ```bash
-npm install zod
-# Add ajv too when using builtins.jsonSchema.
 npm install ajv
 ```
 
@@ -782,7 +798,13 @@ the [managed-run guide](https://docs.hue.run/evaluations/managed-runs).
 
 `runAgentForEvaluation` adapts your application result to `{ output, files? }`.
 Files contain `filename`, `contentType`, actual `Uint8Array` data and an optional
-`primary` flag. The helper verifies input bytes, claims the invocation, saves the
+`primary` flag. Generated files accept the same 22 content types as Python managed outputs:
+PDF, DOCX, PPTX, XLSX, `application/json`, `text/plain`, `text/csv`, `image/png`, `image/jpeg`,
+`image/webp`, `image/gif`, `image/avif`, `audio/mpeg`, `audio/wav`, `audio/ogg`, `audio/webm`,
+`audio/mp4`, `audio/flac`, `audio/opus`, `audio/aac`, `video/mp4` and `video/webm`.
+Declare `audio/mp4` or `video/mp4` for `.mp4` files, and `audio/webm` or `video/webm` for
+`.webm` files; the extension alone does not distinguish audio from video.
+The helper verifies input bytes, claims the invocation, saves the
 outcome and correlates its span with Hue. It never retries the agent automatically.
 Use a 120-second host request limit for the default 90-second execution and
 30-second finalization budget; your target must honor `signal`.
@@ -795,6 +817,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; `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).
+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 successful uploads and upload fallbacks for whole attributes, eligible binary or large text media, and opt-in `recordFile` uploads. Whole-attribute fallbacks keep a prefix; media fallbacks keep a digest; helper upload fallbacks keep the file event. 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).
 
 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

@@ -1,13 +1,13 @@
+import { type HrTime } from "@opentelemetry/api";
+import { type MediaDigestMemo, type FileDigest } from "./inline-files.js";
 /**
- * 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.
+ * Large values and binary media travel apart from their span through reservation, presigned PUT,
+ * and completion. Text keeps a 16 KiB prefix. Binary media keeps digest metadata on its part.
+ * Successful uploads are listed in `hue.blobs`; failures keep inline fallback or file metadata,
+ * are reported as warnings, and are 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. */
+ * object per value, `{"key", "sha256", "size", "content_type"}`, with an optional `name`. */
 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;
@@ -24,7 +24,7 @@ export declare const MAX_BLOB_ENTRIES = 64;
 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. */
+/** Why content kept its fallback instead of being 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>;
@@ -38,6 +38,18 @@ export interface OffloadCandidate {
 export interface OffloadCollector {
     candidates: OffloadCandidate[];
     cut: string[];
+    attachments?: MediaAttachment[];
+    /** The span's own message attributes admission inspected within the record's allowance:
+     * export inspects only these. Absent for a record admission did not copy, which export
+     * inspects within its own allowance. */
+    inspected?: ReadonlySet<string> | undefined;
+}
+export interface MediaAttachment {
+    bytes: Uint8Array;
+    digest: FileDigest;
+    contentType: string;
+    name?: string;
+    eventTime?: HrTime;
 }
 /** The outcome of one export's uploads, reported once the export's records are placed. */
 export interface OffloadTally {
@@ -48,6 +60,8 @@ export interface OffloadTally {
     }>;
 }
 export declare function newTally(): OffloadTally;
+export declare function countFallback(tally: OffloadTally, reason: FallbackReason, traceId: string): void;
+/** A media type accepted by the upload contract. */
 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. */
@@ -62,6 +76,8 @@ export declare function digestOf(value: string | Uint8Array): Promise<{
     sha256: string;
     size: number;
 }>;
+/** The `hue.blobs` element for one uploaded value. */
+export declare function blobEntry(key: string, sha256: string, size: number, contentType: string, name?: string): string;
 /** 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 {
@@ -100,6 +116,7 @@ export declare class BlobUploader {
     private running;
     private waiting;
     private requests;
+    private outcomes;
     constructor(options: UploaderOptions);
     /** Whether a value over the inline limit is worth holding whole for upload now. */
     available(): boolean;
@@ -114,12 +131,12 @@ export declare class BlobUploader {
     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.
+     * completed. Only a fresh upload takes a {@link limit} slot: another reference to bytes the
+     * trace is already storing shares that upload's outcome without one, so repeated files never
+     * hold the slots new files need. The caller must not hold a slot.
      */
-    store(traceId: string, key: string, value: string | Uint8Array, contentType: string, digest: {
-        sha256: string;
-        size: number;
-    }, upload: UploadContext): Promise<Outcome>;
+    store(traceId: string, key: string, value: string | Uint8Array, contentType: string, digest: FileDigest, upload: UploadContext): Promise<Outcome>;
+    private storeFresh;
     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. */
@@ -145,11 +162,12 @@ export interface OffloadOptions {
     valueBytes: number;
     upload: UploadContext;
     tally: OffloadTally;
+    memo?: MediaDigestMemo;
 }
 /**
- * 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
+ * A span's own attributes with each candidate placed: binary media becomes a digest, while
+ * text media over 64 KiB retains a 16 KiB prefix after upload or a digest on failure.
+ * A value still over the inline limit is 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.
  */
@@ -160,5 +178,5 @@ export declare function offloadAttributes(attributes: Record<string, unknown>, c
  * 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 declare function fallbackAttributes(attributes: Record<string, unknown>, collector: OffloadCollector, valueBytes: number, tally: OffloadTally, traceId: string, memo?: MediaDigestMemo): Record<string, unknown>;
 export {};