@hue-run/sdk 0.20.4 → 0.20.6

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.4`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.20.6`, `@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.4 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.4 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+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
 ```
 
 `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
@@ -523,7 +531,9 @@ attributes Hue reads; an id that is no OpenTelemetry id is mapped as `hue import
 so an export and a live import of the same trace agree. An ATIF export becomes one trace: an agent
 span for the run, a model span per agent step with the conversation so far, a tool span per call,
 each embedded subagent as its own agent span under the call that spawned it, and the export's
-`extra.user_id` as the trace's `user.id`. ATIF records instants, not durations, so model and tool
+`extra.user_id` as the trace's `user.id`; its spans carry `hue.import.format` `atif` under the
+instrumentation scope `hue.import.atif`, and the run's agent span is named `invoke_agent
+<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
@@ -687,7 +697,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.4.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.6.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -698,7 +708,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.4.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.6.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -740,10 +750,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.4 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.20.4 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.4 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.20.4 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
+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>
 ```
 
 One invocation creates one run holding every selected case; it prints the run URL
@@ -781,7 +791,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.20.4 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.20.6 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.4 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.4 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+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
 ```
 
 - 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.4 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.js

@@ -992,10 +992,21 @@ function convertLangfuseTrace(draft, traceId) {
 /** The ATIF reader's bounds: a text export of at most 4 MiB and 2,000 spans. */
 export const MAX_ATIF_FILE_BYTES = 4 * 1024 * 1024;
 export const MAX_ATIF_SPANS = 2000;
-const ATIF_IMPORT_VERSION = "2";
-/** The format and scope names Hue reads ATIF-imported spans by (their recorded step order). */
-const ATIF_FORMAT = "auctor.atif";
-const ATIF_SCOPE = "hue.auctor.atif-import";
+/** The conversion's generation, part of every derived trace and span id: raised when the ids'
+ * seed or the spans' shape changes, so a bundle prepared by an earlier generation is prepared
+ * again rather than mixed with this one. 3 names the format generically; 2 carried one
+ * producer's name in the label, the scope and the seed. */
+const ATIF_IMPORT_VERSION = "3";
+/** The format label (`hue.import.format`) and instrumentation scope of a trace converted from
+ * ATIF, the Agent Trajectory Interchange Format: the format's own name, whoever exported it. */
+const ATIF_FORMAT = "atif";
+const ATIF_SCOPE = "hue.import.atif";
+/** The agent span's name, from the export's own agent: `invoke_agent <agent.name>`, or
+ * `invoke_agent` alone when the export names none. */
+function agentSpanName(t) {
+    const name = typeof t.agent.name === "string" ? t.agent.name.trim() : "";
+    return name ? `invoke_agent ${name}` : "invoke_agent";
+}
 const optionalText = z.string().nullable().optional();
 const identity = z.string().min(1).max(512);
 const count = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).nullable().optional();
@@ -1339,8 +1350,10 @@ export function convertAtifExport(source, rawBytes) {
             for (const sub of spawned.get(requested.tool_call_id) ?? [])
                 order.set(sub, sub.steps.map(() => ordinal++));
     }
+    // The trace's identity is run scoped: the scope name, the conversion's generation, the
+    // export's session and trajectory ids. Never a path, a file digest or a producer's name.
     const identityParts = [
-        ATIF_FORMAT === "auctor.atif" ? "hue.auctor.atif" : ATIF_FORMAT,
+        ATIF_SCOPE,
         ATIF_IMPORT_VERSION,
         document.session_id,
         document.trajectory_id ?? null,
@@ -1404,7 +1417,7 @@ export function convertAtifExport(source, rawBytes) {
     addUsage(rootAttributes, finalUsage(document));
     addSpan({
         spanId: rootId,
-        name: "invoke_agent auctor",
+        name: agentSpanName(document),
         startTimeUnixNano: main.start,
         endTimeUnixNano: lastInstant,
         attributes: rootAttributes.finish(),
@@ -1543,7 +1556,7 @@ export function convertAtifExport(source, rawBytes) {
         addSpan({
             spanId: agentId,
             parentSpanId,
-            name: `invoke_agent ${sub.agent.name}`,
+            name: agentSpanName(sub),
             startTimeUnixNano: found.checked.start,
             endTimeUnixNano: found.checked.times.at(-1),
             attributes: attributes.finish(),

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.4";
+export declare const sdkVersion = "0.20.6";

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

package/package.json

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