@hue-run/sdk 0.20.5 → 0.20.7

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.20.5`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.20.7`, `@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.20.5 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.5 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.20.7 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.20.7 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`
@@ -430,17 +430,25 @@ without a parent are its children, and it lasts from the earliest of its timesta
 to their last end. Spans carry `service.name` `langfuse` (`--service-name` sets another) and the
 instrumentation scope `@hue-run/sdk/import/langfuse`.
 
+**Environment and Worlds.** A span whose observation, or v1 trace, records an environment also
+carries it as recorded in `hue.import.source_environment`, which marks the trace as imported; one
+that records none carries neither attribute, and the resource never declares
+`deployment.environment.name`, since one import can mix environments. A trace adds to its user's
+World only when Langfuse recorded it in its `production` environment: Hue reads the root's
+`langfuse.environment` as the trace's deployment environment, and never takes an imported trace in
+which any span names another environment, such as Langfuse's `default`, as production history.
+
 **Ids and resuming.** A Langfuse id that already is an OpenTelemetry id (32 lowercase hex digits for
 a trace, 16 for an observation, as Langfuse's OpenTelemetry SDKs write them) is kept; any other id,
 such as an older SDK's UUID, becomes one derived from it with SHA-256. The original ids are kept as
 `langfuse.trace.id` and `langfuse.observation.id`. Running the same command again sends the same
 spans, and Hue keeps one copy of an exact replay of a completed span, so an interrupted or partly
 failed import is resumed by running it again. Hue refuses a different payload for a span it already
-holds: keep `--media`, `--no-content` and `--service-name` the same when resuming, and expect a span
-whose Langfuse data changed after it was imported to be refused. For the same reason the import
-sends nothing that depends on the run: a trace's root never carries `hue.sdk.dropped_records`, and
-files and large values are stored before their span is sent. Leave out of the window any traces that
-already reached Hue through OpenTelemetry.
+holds: keep `--media`, `--no-content`, `--service-name` and the SDK version the same when
+resuming, and expect a span whose Langfuse data changed after it was imported to be refused. For
+the same reason the import sends nothing that depends on the run: a trace's root never carries
+`hue.sdk.dropped_records`, and files and large values are stored before their span is sent. Leave
+out of the window any traces that already reached Hue through OpenTelemetry.
 
 **Export and content.** Spans go through the SDK's own exporter, as `createHue` sends them: batched,
 compressed, retried and within the limits Hue advertises. Before a span is sent, its content is
@@ -528,8 +536,9 @@ instrumentation scope `hue.import.atif`, and the run's agent span is named `invo
 <agent.name>` from the export's own agent. ATIF records instants, not durations, so model and tool
 spans are points in time, and a tool's result is kept as text with no error status of the
 importer's making. The same trace in two files is one trace when the copies agree and a refusal
-when they differ; a trace with more than 100,000 spans, 64 batches or 1,000 values is refused and
-named. Nothing about where a file sat or what it was called reaches a span: a renamed, reordered
+when they differ; a trace with more than 100,000 spans, 512 batches or 10,000 values is refused and
+named, and an input of more than 25,000 traces, or whose manifest would exceed 32 MiB (4 MiB
+compressed), is refused whole. Nothing about where a file sat or what it was called reaches a span: a renamed, reordered
 or re-zipped copy of the bundle prepares to byte-identical batches and the same manifest digest.
 
 The report (`--json` prints it as one object) names `manifest_digest`, `totals` (traces, batches,
@@ -545,7 +554,7 @@ no upload has started in it.
 
 **Authorize.** Call `prepare_trace_import` over the Hue MCP with the report's `manifest_digest`,
 `totals` and `source`. It answers the import id, `upload_url` and an `authorization` (`hue_it_` and
-43 characters) valid for an hour. Save its answer, or the authorization alone, in a private file
+43 characters) valid for a day. Save its answer, or the authorization alone, in a private file
 (mode 0600; never in a transcript, a message or a shell history). The same digest in the same
 project is the same import: calling again renews the authorization for an interrupted upload and
 revokes the earlier one.
@@ -689,7 +698,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.20.5.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.7.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -700,7 +709,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.20.5.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.7.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -742,10 +751,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.20.5 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.20.5 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.20.5 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.20.5 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
+npx -y @hue-run/sdk@0.20.7 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.20.7 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.20.7 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.20.7 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
@@ -783,7 +792,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.20.5 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.20.7 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

@@ -536,8 +536,8 @@ the Langfuse project's own keys (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, a
 `HUE_API_KEY`:
 
 ```sh
-npx -y @hue-run/sdk@0.20.5 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.5 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.20.7 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.20.7 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
@@ -547,6 +547,8 @@ npx -y @hue-run/sdk@0.20.5 import langfuse --env-path .env.langfuse --from 2026-
   `langfuse.observation.*` and `langfuse.trace.*` attributes Hue reads, the user, session, release
   and environment, and the model and token counts as GenAI attributes. Hex ids are kept and other
   ids derived from them, so running the same command again resumes an import without duplicates.
+- Langfuse's environment is also sent, as recorded, as `hue.import.source_environment`; only
+  traces Langfuse recorded in `production` add to a user's World.
 - Spans are exported by the SDK's transport with its content-capture default; `--no-content`
   sends metadata only.
 - With `--media`, files that Langfuse media references point to are downloaded and uploaded under

package/dist/cli/import.d.ts

@@ -26,7 +26,7 @@ export interface ImportCommandIo {
      * in flight do not hold it until their requests time out. */
     exit?: (code: number) => void;
 }
-export declare const IMPORT_USAGE = "Usage: hue import langfuse [options]\n\nCopy traces from a Langfuse project into Hue. The import runs on this machine with your own\nLangfuse keys, which are sent only to Langfuse. Each observation becomes a span with the\nlangfuse.* attributes Hue reads; ids are kept, so running the same command again resumes an\nimport without duplicating what was already sent.\n\nLangfuse (keys from the environment or --env-path; the secret key never from the command line):\n  LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY  The Langfuse project's API keys\n  LANGFUSE_BASE_URL or LANGFUSE_HOST        Langfuse host (default https://cloud.langfuse.com)\n  --langfuse-host URL                       Langfuse host, instead of the variables\n  --langfuse-public-key KEY                 Public key, instead of LANGFUSE_PUBLIC_KEY\n\nHue:\n  HUE_API_KEY            The Hue project key the traces are sent with (environment, --env-path\n                         or ./.env.hue); not needed with --dry-run\n  --origin URL           Hue origin (default HUE_BASE_URL, then https://app.hue.run)\n  --service-name NAME    service.name of the imported spans (default langfuse)\n\nSelection (newest first):\n  --from TIME            Traces that started at or after TIME: an ISO 8601 date (midnight UTC)\n                         or a date and time with a zone, such as 2026-01-01T09:00:00Z\n  --to TIME              Traces that started before TIME (default: an hour before the command\n                         starts, so traces still running are left for a later run)\n  --limit N              At most N traces\n  --trace-id ID          This Langfuse trace (repeatable); not with --from, --to or --limit\n\nContent:\n  --media                Download the files Langfuse media references (@@@langfuseMedia:\u2026@@@)\n                         point to and upload them to Hue; without it, references stay as text\n  --no-content           Send metadata only: no inputs, outputs, status messages or model\n                         parameters (content is sent by default, as the SDK records it)\n\nRun:\n  --dry-run              Read Langfuse and count what would be imported; send nothing to Hue\n  --yes                  Import without asking for confirmation (required without a terminal)\n  --env-path PATH        Load a dotenv file first (--env-file also works when it exists);\n                         ./.env.hue loads when HUE_API_KEY is not set. Variables already set win\n  -h, --help             Show this help\n\nExit codes: 0 every trace was imported, 1 a trace, span or file was not, 2 usage error,\n130 stopped (run the same command again to resume).";
+export declare const IMPORT_USAGE = "Usage: hue import langfuse [options]\n\nCopy traces from a Langfuse project into Hue. The import runs on this machine with your own\nLangfuse keys, which are sent only to Langfuse. Each observation becomes a span with the\nlangfuse.* attributes Hue reads; ids are kept, so running the same command again resumes an\nimport without duplicating what was already sent. Langfuse's environment is also sent, as\nrecorded, as hue.import.source_environment; only traces Langfuse recorded in production add to\na user's World.\n\nLangfuse (keys from the environment or --env-path; the secret key never from the command line):\n  LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY  The Langfuse project's API keys\n  LANGFUSE_BASE_URL or LANGFUSE_HOST        Langfuse host (default https://cloud.langfuse.com)\n  --langfuse-host URL                       Langfuse host, instead of the variables\n  --langfuse-public-key KEY                 Public key, instead of LANGFUSE_PUBLIC_KEY\n\nHue:\n  HUE_API_KEY            The Hue project key the traces are sent with (environment, --env-path\n                         or ./.env.hue); not needed with --dry-run\n  --origin URL           Hue origin (default HUE_BASE_URL, then https://app.hue.run)\n  --service-name NAME    service.name of the imported spans (default langfuse)\n\nSelection (newest first):\n  --from TIME            Traces that started at or after TIME: an ISO 8601 date (midnight UTC)\n                         or a date and time with a zone, such as 2026-01-01T09:00:00Z\n  --to TIME              Traces that started before TIME (default: an hour before the command\n                         starts, so traces still running are left for a later run)\n  --limit N              At most N traces\n  --trace-id ID          This Langfuse trace (repeatable); not with --from, --to or --limit\n\nContent:\n  --media                Download the files Langfuse media references (@@@langfuseMedia:\u2026@@@)\n                         point to and upload them to Hue; without it, references stay as text\n  --no-content           Send metadata only: no inputs, outputs, status messages or model\n                         parameters (content is sent by default, as the SDK records it)\n\nRun:\n  --dry-run              Read Langfuse and count what would be imported; send nothing to Hue\n  --yes                  Import without asking for confirmation (required without a terminal)\n  --env-path PATH        Load a dotenv file first (--env-file also works when it exists);\n                         ./.env.hue loads when HUE_API_KEY is not set. Variables already set win\n  -h, --help             Show this help\n\nExit codes: 0 every trace was imported, 1 a trace, span or file was not, 2 usage error,\n130 stopped (run the same command again to resume).";
 /** An instant of the window: an ISO 8601 date (midnight UTC) or a date and time with a zone. */
 export declare function parseInstant(option: string, value: string): string;
 /** The Langfuse host as a base URL without a trailing slash, or why it is refused. */

package/dist/cli/import.js

@@ -44,7 +44,9 @@ export const IMPORT_USAGE = `Usage: hue import langfuse [options]
 Copy traces from a Langfuse project into Hue. The import runs on this machine with your own
 Langfuse keys, which are sent only to Langfuse. Each observation becomes a span with the
 langfuse.* attributes Hue reads; ids are kept, so running the same command again resumes an
-import without duplicating what was already sent.
+import without duplicating what was already sent. Langfuse's environment is also sent, as
+recorded, as hue.import.source_environment; only traces Langfuse recorded in production add to
+a user's World.
 
 Langfuse (keys from the environment or --env-path; the secret key never from the command line):
   LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY  The Langfuse project's API keys

package/dist/cli/langfuse.d.ts

@@ -201,7 +201,8 @@ export interface TraceContext {
  * `langfuse.session.id`, `langfuse.release`, `langfuse.version` and `langfuse.environment`, with
  * `gen_ai.request.model` and the input and output token counts as GenAI attributes. The
  * observation's and trace's own ids are kept as `langfuse.observation.id` and
- * `langfuse.trace.id`. Throws for a start time that is no ISO 8601 instant.
+ * `langfuse.trace.id`, and its environment also as `hue.import.source_environment`. Throws for a
+ * start time that is no ISO 8601 instant.
  */
 export declare function observationSpan(observation: LangfuseObservation, context: TraceContext): ImportSpan;
 /** The context a v1 trace gives its observations. */
@@ -209,9 +210,9 @@ export declare function traceContext(trace: LangfuseTrace): TraceContext;
 /**
  * The span that stands for a v1 trace, the parent of its observations without one, as the trace
  * Langfuse shows above them: `langfuse.trace.*` (name, input, output, one `metadata.<key>`
- * attribute per key, tags, public), the user, session, release, version and environment. It
- * covers the trace's timestamp and its observations, `observed`. Throws for a timestamp that is
- * no ISO 8601 instant.
+ * attribute per key, tags, public), the user, session, release, version and environment (also as
+ * `hue.import.source_environment`). It covers the trace's timestamp and its observations,
+ * `observed`. Throws for a timestamp that is no ISO 8601 instant.
  */
 export declare function traceSpan(trace: LangfuseTrace, observed: TimeBounds | undefined): ImportSpan;
 /** A converted span as the OpenTelemetry SDK hands a finished span to a processor. */

package/dist/cli/langfuse.js

@@ -719,6 +719,16 @@ function setText(into, key, value) {
     if (value !== undefined && value !== "")
         into[key] = value;
 }
+/** Hue's import provenance: the source's own environment, as Langfuse recorded it. Hue's World
+ * capture treats a trace carrying `hue.import.*` attributes as imported, and never takes one in
+ * which a span names an environment other than exactly `production` as production history. */
+const IMPORT_SOURCE_ENVIRONMENT = "hue.import.source_environment";
+/** Langfuse's environment, verbatim, as `langfuse.environment` and as Hue's import provenance;
+ * an absent environment stays absent, never defaulted. */
+function setEnvironment(into, environment) {
+    setText(into, "langfuse.environment", environment);
+    setText(into, IMPORT_SOURCE_ENVIRONMENT, environment);
+}
 /**
  * A Langfuse observation as the span the Langfuse OpenTelemetry SDKs would have recorded:
  * `langfuse.observation.*` (type in lower case, input, output, one `metadata.<key>` attribute per
@@ -727,7 +737,8 @@ function setText(into, key, value) {
  * `langfuse.session.id`, `langfuse.release`, `langfuse.version` and `langfuse.environment`, with
  * `gen_ai.request.model` and the input and output token counts as GenAI attributes. The
  * observation's and trace's own ids are kept as `langfuse.observation.id` and
- * `langfuse.trace.id`. Throws for a start time that is no ISO 8601 instant.
+ * `langfuse.trace.id`, and its environment also as `hue.import.source_environment`. Throws for a
+ * start time that is no ISO 8601 instant.
  */
 export function observationSpan(observation, context) {
     const start = hrTimeOf(observation.startTime);
@@ -774,7 +785,7 @@ export function observationSpan(observation, context) {
     setText(attributes, "langfuse.session.id", observation.sessionId ?? context.sessionId);
     setText(attributes, "langfuse.release", observation.release ?? context.release);
     setText(attributes, "langfuse.version", observation.version);
-    setText(attributes, "langfuse.environment", observation.environment);
+    setEnvironment(attributes, observation.environment);
     attributes["langfuse.trace.id"] = context.langfuseTraceId;
     attributes["langfuse.observation.id"] = observation.id;
     const parent = observation.parentObservationId
@@ -806,9 +817,9 @@ export function traceContext(trace) {
 /**
  * The span that stands for a v1 trace, the parent of its observations without one, as the trace
  * Langfuse shows above them: `langfuse.trace.*` (name, input, output, one `metadata.<key>`
- * attribute per key, tags, public), the user, session, release, version and environment. It
- * covers the trace's timestamp and its observations, `observed`. Throws for a timestamp that is
- * no ISO 8601 instant.
+ * attribute per key, tags, public), the user, session, release, version and environment (also as
+ * `hue.import.source_environment`). It covers the trace's timestamp and its observations,
+ * `observed`. Throws for a timestamp that is no ISO 8601 instant.
  */
 export function traceSpan(trace, observed) {
     const timestamp = hrTimeOf(trace.timestamp);
@@ -829,7 +840,7 @@ export function traceSpan(trace, observed) {
     setText(attributes, "langfuse.session.id", trace.sessionId);
     setText(attributes, "langfuse.release", trace.release);
     setText(attributes, "langfuse.version", trace.version);
-    setText(attributes, "langfuse.environment", trace.environment);
+    setEnvironment(attributes, trace.environment);
     attributes["langfuse.trace.id"] = trace.id;
     return {
         traceId: hueTraceId(trace.id),

package/dist/cli/traces-import-convert.d.ts

@@ -12,11 +12,14 @@ export declare const traceImportOrigins: readonly ["production", "evaluation", "
 export type TraceImportOrigin = (typeof traceImportOrigins)[number];
 /** The bounds the import routes hold a manifest to. */
 export declare const traceImportLimits: {
-    readonly traces: 10000;
-    readonly batchesPerTrace: 64;
-    readonly blobsPerTrace: 1000;
+    readonly traces: 25000;
+    readonly batchesPerTrace: 512;
+    readonly blobsPerTrace: 10000;
     readonly spansPerTrace: 100000;
+    /** The manifest decoded. */
     readonly manifestBytes: number;
+    /** The manifest as registration takes it, gzip. */
+    readonly manifestWireBytes: number;
     readonly batchBytes: number;
     readonly blobBytes: 1000000000;
 };

package/dist/cli/traces-import-convert.js

@@ -17,11 +17,14 @@ export const traceImportFormats = ["otlp_json", "langfuse_observations", "atif"]
 export const traceImportOrigins = ["production", "evaluation", "simulation", "unknown"];
 /** The bounds the import routes hold a manifest to. */
 export const traceImportLimits = {
-    traces: 10_000,
-    batchesPerTrace: 64,
-    blobsPerTrace: 1_000,
+    traces: 25_000,
+    batchesPerTrace: 512,
+    blobsPerTrace: 10_000,
     spansPerTrace: 100_000,
-    manifestBytes: 8 * 1024 * 1024,
+    /** The manifest decoded. */
+    manifestBytes: 32 * 1024 * 1024,
+    /** The manifest as registration takes it, gzip. */
+    manifestWireBytes: 4 * 1024 * 1024,
     batchBytes: 4 * 1024 * 1024,
     blobBytes: 1_000_000_000,
 };

package/dist/cli/traces-import-prepare.d.ts

@@ -57,6 +57,9 @@ export declare class PrepareError extends Error {
 }
 /** The default output directory: `<input>.hue-import` beside the input. */
 export declare function defaultOutputDirectory(input: string): string;
+/** Why a manifest cannot be registered, or undefined: Hue reads at most 32 MiB decoded and takes
+ * at most 4 MiB on the wire, gzip as the upload sends it. Checked here, before any upload. */
+export declare function manifestTooLarge(bytes: Uint8Array): string | undefined;
 export interface PrepareOptions {
     out?: string;
 }

package/dist/cli/traces-import-prepare.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { mkdir, open, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, join, relative, resolve, sep } from "node:path";
+import { gzipSync } from "node:zlib";
 import { sdkVersion } from "../version.js";
 import { batchEntries, ConversionError, convertAtifExport, detectFormat, LangfuseTraceCollector, manifestTotals, manifestTraceHasIdentity, OtlpTraceCollector, sha256Hex, traceImportFormats, traceImportLimits, validateManifest, } from "./traces-import-convert.js";
 import { isZipSignature, ZipArchive, ZipError } from "./traces-import-zip.js";
@@ -193,6 +194,18 @@ async function prepareOutputDirectory(directory) {
         await rm(path, { force: true });
     }
 }
+/** Why a manifest cannot be registered, or undefined: Hue reads at most 32 MiB decoded and takes
+ * at most 4 MiB on the wire, gzip as the upload sends it. Checked here, before any upload. */
+export function manifestTooLarge(bytes) {
+    // No division by a name: the published package's import-boundary check reads one as a regex.
+    const mebibytes = (value) => `${Math.ceil(value * 2 ** -20)} MiB`;
+    if (bytes.byteLength > traceImportLimits.manifestBytes)
+        return `The manifest is ${mebibytes(bytes.byteLength)}, over the ${mebibytes(traceImportLimits.manifestBytes)} Hue reads; prepare the input in smaller parts`;
+    const wire = gzipSync(bytes, { level: 6 }).byteLength;
+    if (wire > traceImportLimits.manifestWireBytes)
+        return `The manifest is ${mebibytes(wire)} compressed, over the ${mebibytes(traceImportLimits.manifestWireBytes)} a registration takes; prepare the input in smaller parts`;
+    return undefined;
+}
 async function writePrivate(path, bytes) {
     const temporary = `${path}.tmp`;
     await writeFile(temporary, bytes, { mode: 0o600, flag: "w" });
@@ -422,8 +435,9 @@ export async function prepareTraceBundle(input, options = {}) {
     if (invalid)
         throw new PrepareError(`The prepared manifest is not valid: ${invalid}`);
     const bytes = Buffer.from(JSON.stringify(manifest), "utf8");
-    if (bytes.byteLength > traceImportLimits.manifestBytes)
-        throw new PrepareError("The manifest exceeds 8 MiB; prepare the input in smaller parts");
+    const tooLarge = manifestTooLarge(bytes);
+    if (tooLarge)
+        throw new PrepareError(tooLarge);
     await writePrivate(join(outputDirectory, MANIFEST_FILE), bytes);
     return {
         manifest_digest: createHash("sha256").update(bytes).digest("hex"),

package/dist/cli/traces-import-upload.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
 import { sdkVersion } from "../version.js";
 import { manifestTotals, sha256Hex, validateManifest, } from "./traces-import-convert.js";
-import { MANIFEST_FILE, PROGRESS_FILE } from "./traces-import-prepare.js";
+import { MANIFEST_FILE, manifestTooLarge, PROGRESS_FILE } from "./traces-import-prepare.js";
 /**
  * `hue traces import upload`: delivers a prepared bundle to Hue's import routes with the
  * short-lived import authorization `prepare_trace_import` minted. The manifest's exact bytes
@@ -229,6 +229,10 @@ export async function uploadTraceBundle(options, io = {}) {
     const invalid = validateManifest(manifest);
     if (invalid)
         throw new UploadStop(`${MANIFEST_FILE} is not valid: ${invalid}`, "bundle_invalid");
+    // A manifest registration would refuse (413) is refused here, before anything is sent.
+    const tooLarge = manifestTooLarge(manifestBytes);
+    if (tooLarge)
+        throw new UploadStop(tooLarge, "bundle_invalid");
     const manifestDigest = sha256Hex(manifestBytes);
     const totals = manifestTotals(manifest);
     // Every declared file must be present before the first request: a bundle missing a batch

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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