@hue-run/sdk 0.20.6 → 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.6`, `@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.6 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.6 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`
@@ -536,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,
@@ -553,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.
@@ -697,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.6.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
@@ -708,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.6.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
@@ -750,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.6 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.20.6 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.6 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.20.6 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
@@ -791,7 +792,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.20.6 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.6 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.6 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

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.6";
+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.6";
+export const sdkVersion = "0.20.7";

package/package.json

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