@hue-run/sdk 0.18.0 → 0.18.2

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.18.0`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.18.2`, `@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.
 
@@ -114,6 +114,7 @@ hue setup --origin http://127.0.0.1:PORT # isolated loopback tests only
 hue login                 # validate keys created in Hue and store them in ./.env.hue
 hue mcp install --client claude-code # write the Hue MCP configuration for a coding agent
 hue listen --subscription <id> --forward-to http://localhost:3000/slack/events # deliver events to a local bot
+hue import langfuse --from 2026-01-01 --dry-run # count a Langfuse project's traces, then import them
 ```
 
 Hosted setup accepts HTTPS origins only. HTTP is accepted solely for `localhost`, `127.0.0.1` and
@@ -365,6 +366,127 @@ codes: `0` stopped, `1` Hue refused the credential, the subscription (unknown, r
 delivers to a request URL) or the pull itself (a redirect, another refusal or an answer without
 deliveries), `2` usage error, `130` interrupted twice.
 
+## Import traces from Langfuse
+
+`hue import langfuse` copies a Langfuse project's traces into Hue, for a team moving from Langfuse.
+It runs on your machine: it reads Langfuse's public API with the project's own keys and sends the
+spans with your Hue project key through the SDK's exporter, so the Langfuse keys go only to Langfuse
+and Hue never receives or stores them. The command is part of the `hue` executable and runs with
+`npx` whatever language the application is written in; the Python SDK has no counterpart.
+
+```sh
+# .env.langfuse, kept out of version control:
+#   LANGFUSE_PUBLIC_KEY=pk-lf-...
+#   LANGFUSE_SECRET_KEY=sk-lf-...
+#   LANGFUSE_BASE_URL=https://cloud.langfuse.com
+npx -y @hue-run/sdk@0.18.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.18.2 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`
+(`--env-file` also works when the file exists), loaded first; a variable already set keeps its
+value. `--langfuse-public-key` replaces the public key on the command line, but the secret key is
+never taken from it, where other local processes and shell history can read it. The host is
+`--langfuse-host`, then `LANGFUSE_BASE_URL`, then `LANGFUSE_HOST`, then `https://cloud.langfuse.com`:
+use your region's host or your self-hosted URL, over HTTPS (plain HTTP only on this machine). A
+request carrying the keys follows no redirect. `HUE_API_KEY` is the Hue project key the spans are
+sent with, from the environment, the env file, or `./.env.hue` (where `hue login` stores it) when
+neither sets it (a dry run, which needs no Hue key, reads no `./.env.hue` beside a named file); `--origin` (default `HUE_BASE_URL`, then `https://app.hue.run`) is checked with
+`GET /api/v1/projects/current` before Langfuse is read. Keys are never printed.
+
+**What is read.** The command first asks for `GET /api/public/v2/observations`, which Langfuse Cloud
+and self-hosted Langfuse v4 answer. The traces are then the root observations
+(`isRootObservation=true`) that started in the window, listed newest first in cursor pages, and each
+trace's observations are read 100 a page with the field groups
+`core,basic,time,io,metadata,model,usage,prompt,trace_context`; a page whose metadata values Langfuse
+cut at 200 characters is read again with those keys expanded. A deployment that answers `404` there
+(self-hosted Langfuse v3) is read through `GET /api/public/traces` (`fromTimestamp`, `toTimestamp`,
+`orderBy=timestamp.desc`, `fields=core,io`) and `GET /api/public/observations?traceId=…`, in numbered
+pages. An answer over 32 MiB, or a `413`, is asked for again in smaller pages.
+
+**Selection.** `--from` and `--to` take an ISO 8601 date (midnight UTC) or a date and time with a time
+zone. A trace is selected by when it started, its root observation's start time or a v1 trace's
+timestamp, `--from` inclusive and `--to` exclusive. Without `--to` the window ends an hour before the
+command starts, so a trace still running, or still arriving in Langfuse, is left for a later run
+rather than sent half recorded. `--limit N` imports the N
+newest traces; `--trace-id ID` (repeatable, up to 1,000) imports those traces only and is not combined
+with the window or the limit.
+
+**What Hue receives.** Each observation becomes a completed span as a Langfuse OpenTelemetry SDK
+records it: its name, start, end (an observation without an end lasts no time) and parent, with
+`langfuse.observation.type` (lower case), `langfuse.observation.input` and `.output` (a string as
+recorded, any other value as its JSON), one `langfuse.observation.metadata.<key>` per metadata key,
+`.level`, `.status_message`, `.model.name`, `.model.parameters`, `.usage_details`, `.cost_details`,
+`.completion_start_time`, `.prompt.name` and `.prompt.version`, and the trace's
+`langfuse.trace.name`, `langfuse.trace.tags`, `langfuse.user.id`, `langfuse.session.id`,
+`langfuse.release`, `langfuse.version` and `langfuse.environment`. The model is also
+`gen_ai.request.model`, and Langfuse's `input` and `output` usage counts are
+`gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. An observation at level `ERROR` is an
+error span with its status message. A v1 trace is also a span of its own, named as the trace and
+carrying `langfuse.trace.input`, `.output`, `.metadata.<key>`, `.tags` and `.public`; its observations
+without a parent are its children, and it lasts from the earliest of its timestamp and their starts
+to their last end. Spans carry `service.name` `langfuse` (`--service-name` sets another) and the
+instrumentation scope `@hue-run/sdk/import/langfuse`.
+
+**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.
+
+**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
+stored as that exporter stores it, with the exporter's own placement: a file inline in an attribute
+Hue reads files from (a `data:` URL, or the bytes of a provider part, that Langfuse kept in place) is
+uploaded and placed in its digest form, and a text value still over Hue's inline limit (1 MiB) is
+uploaded whole and replaced by its first 16 KiB, each listed in `hue.blobs` (a whole value also in
+`hue.truncated`). Doing this first means a file or value that cannot be stored right now holds its
+span back for the next run instead of being kept inline or cut; one over a limit (Hue's size limit,
+or a span's 64 entries) is placed the same way on every run and counted in the summary. Content is
+captured, the SDK's default; `--no-content` sends metadata only, as `captureContent: false` does (no
+inputs, outputs, status messages or model parameters; metadata, model names and usage stay, and
+nothing is uploaded). The import waits for its queue to be sent every 1,024 spans or 32 MiB, so its
+memory stays bounded whatever the project's size.
+
+**Media.** Langfuse's SDKs replace a file in an input, output or metadata value with a reference,
+`@@@langfuseMedia:type=<media type>|id=<id>|source=<source>@@@`. Without `--media`, references are
+sent as recorded, and Hue shows them as files held in Langfuse. With `--media`, each reference where
+Hue reads a file (a whole string, or the content of a provider part such as an OpenAI `image_url` or
+`input_audio`, an Anthropic `source` or a GenAI `blob`, no deeper than ten levels) is looked up with
+`GET /api/public/media/{id}`. The file is downloaded from the link Langfuse answers (following its
+store's redirects, without the Langfuse keys), uploaded under the span's trace through Hue's upload route (reservation, presigned
+`PUT`, completion), and placed in the digest form the SDK writes for media it records: a whole string
+becomes `{"type":"blob","mime_type":…,"modality":…,"sha256":…,"size":…}` and a provider part loses its
+bytes and gains `sha256` and `size`, every other byte of the value's text kept, each file listed in
+`hue.blobs` under `<attribute>#<JSON pointer>`. Each file is downloaded once per trace. A reference
+stays as recorded when Langfuse holds no bytes for it, its file is over 25 MiB, it sits inside longer
+text, or its span already lists 64 files. A file that cannot be downloaded or stored right now holds
+its span back: the trace is reported, and the next run sends it.
+
+**Rate limits and failures.** A `429` from Langfuse is waited out for as long as its `Retry-After`
+asks, up to 15 minutes and ten times in a row; connection failures, timeouts and `5xx` answers are
+retried after 1, 2, 4, 8 and 16 seconds. Langfuse Cloud limits each organization's requests per
+minute by plan, so a large project imports at that pace: a request per page of traces and per page
+of each trace's observations, and one per media file. A refusal of the Langfuse keys (`401` or `403`)
+or of `HUE_API_KEY` stops the import before anything is sent; a trace Langfuse cannot answer for is
+reported and the import goes on.
+
+**Output and exit codes.** `--dry-run` reads and counts traces, spans and media references, needs no
+Hue key and sends nothing. Without `--yes` the command asks for confirmation in a terminal (declining
+exits `1`) and refuses to start without one. Progress is printed every 100 traces or 10 seconds, then
+a summary of the traces imported, the spans sent and accepted, and the media files uploaded and left
+in Langfuse; each trace not fully imported is named with the reason. Ctrl+C or `SIGTERM` stops
+reading, sends what was read and exits `130`; a second Ctrl+C a second or more later exits `130` at
+once, abandoning exports still in flight for the next run to send. Exit codes: `0` every selected
+trace was imported, `1` a trace, span or file was not (or a key was refused), `2` usage error, `130`
+stopped.
+
 ## Local state and conflicts
 
 Before its first network write, setup creates a lowercase UUIDv4 and a 32-byte random installation
@@ -469,7 +591,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.18.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.18.2.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -480,7 +602,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.18.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.18.2.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -522,10 +644,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.18.0 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.18.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.18.0 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.18.0 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
+npx -y @hue-run/sdk@0.18.2 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.18.2 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.18.2 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.18.2 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
@@ -563,7 +685,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.18.0 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.18.2 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.

package/EVALUATIONS.md

@@ -317,10 +317,13 @@ An uploaded file needs one of `outputContentTypes`, a well-formed name of 1–25
 (as JavaScript counts a string's `length`) without path separators or control characters, and 1
 byte to 25 MiB. Every file, and the case itself as it will be sent (its revision, key, values and
 size), is checked before the first upload; a file outside that policy, a `path` that cannot be
-read, or a case Hue would refuse throws `TypeError` or `RangeError` without a request. The
-reservation key names the version, the case's `externalKey`, the role, the bytes, the name and the
-content type, so sending the same case again reuses its artifacts and a corrected name or type
-reserves a new one; a reference to the artifact a file uploads as pins it once. `source`, `attached_template`, `attached_reference` and `original` files reach
+read, or a case Hue would refuse throws `TypeError` or `RangeError` without a request. A `path`
+is hashed a slice at a time when it is checked and read again when it is uploaded, one file at a
+time, so the write holds at most one file in memory and sends only the bytes its check hashed. A
+file that changed in between, or can no longer be read, sends nothing: the write throws `TypeError`
+and the case is not written. The reservation key names the version, the case's
+`externalKey`, the role, the bytes, the name and the content type, so sending the same case again
+reuses its artifacts and a corrected name or type reserves a new one; a reference to the artifact a file uploads as pins it once. `source`, `attached_template`, `attached_reference` and `original` files reach
 the target as `context.files`; `org_template` and `evaluator_reference` files reach only scorers.
 
 Recorded messages copied into a case's inputs keep their large files as digest parts. Pin each file

package/README.md

@@ -274,7 +274,8 @@ Each uploaded file is listed in the record's `hue.blobs`, keyed `<attribute>#<JS
   through the string, which no JSON pointer can address, so Hue matches it by its digest.
 - Text media over 64 KiB of decoded bytes in a provider part keeps a UTF-8-safe 16 KiB prefix in
   its content field instead, and its key names that field
-  (`gen_ai.input.messages#/0/parts/1/content`). Smaller text and empty fields stay inline.
+  (`gen_ai.input.messages#/0/parts/1/content`). Smaller text and empty fields stay inline. A text
+  file a GenAI `blob`, Vertex `media` or AI SDK part holds as bare base64 takes the digest form.
 
 Only the file's own value, or the members of the part that held it, change: every other byte of the
 recorded text, its key order, number spellings, escapes and spacing included, is kept, in an encoded
@@ -286,9 +287,11 @@ Entries use the recorded media type and, when valid, the filename, name or title
 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.
+contract are decoded before hashing. Other content is read as Hue's reader reads it, whatever its
+media type: content that reads as base64 (a length divisible by four, base64 characters only, as
+the GenAI conventions and `client.media.resolve` write a `blob` or `media` part's content) is the
+file's base64 and is decoded, so `YWJj` hashes as `abc`; anything else is the file's own UTF-8
+text. The digest matches `hue.recordFile`'s digest for the same bytes.
 
 A file that is not uploaded (the upload failed, the receiver has no upload route, or a budget ran
 out) keeps its digest without an entry in the recorded messages (`gen_ai.input.messages`,
@@ -309,13 +312,23 @@ listed under `hue.truncated`. While uploads are available, `recordMessages` reco
 the value limit when it fits the limit with its files as their digest.
 
 Inspection is bounded to 8 Mi UTF-16 code units of text per attribute and 16 Mi per record, a log
-body's file contents included; a longer value uses the ordinary value limit. Inspection parses the
-value and decodes each file while the record is queued and again when it is exported, holding
-several copies of the value at once; larger files belong in an `Attachment` or in
-`hue.recordFile` with `upload` set, whose bytes are not parsed out of text. Resources, links and
-span events never upload inline media: in their recorded messages, media up to 64 KiB stays
-verbatim and larger media is replaced by its digest, as in 0.16, and log records that cannot
-upload (not correlated with a span, or while uploads are unavailable) keep the same rule. With
+body's file contents included. Within those bounds, inspection parses the value and decodes each
+file while the record is queued and again when it is exported. A span's own attribute past either
+bound that is held whole for upload (it is over the value limit) has its media read in place when
+it is exported, as a voice agent's audio usually needs: each string in it longer than 16 Ki code
+units and written without escapes as strict base64 or a base64 `data:` URL is decoded, hashed and
+uploaded a 1 MiB window at a time from the recorded text, never parsed or copied out of it, and a
+file may be up to Hue's 1 GB upload limit. The scan that finds those strings also reads the value
+a window at a time, between turns of the event loop, so no step of it stalls the application for
+long; a percent-escaped `data:` URL is parsed with the JSON around it. The value is placed exactly as one within the bounds: the same
+digest form, entries and fallbacks. The JSON around those strings, a file written with escapes or
+inside a JSON-encoded string included, is parsed within the 8 Mi bound; a value past it uses the
+ordinary value limit (it uploads whole). Each such value is read within that bound on its own, apart
+from the record's 16 Mi allowance, while it stays held within the 128 MiB for values awaiting
+upload. Log records keep the bounds. Resources, links and span
+events never upload inline media: in their recorded messages, media up to 64 KiB stays verbatim
+and larger media is replaced by its digest, as in 0.16, and log records that cannot upload (not
+correlated with a span, or while uploads are unavailable) keep the same rule. With
 `captureContent: false`, nothing is inspected or uploaded.
 
 ### Attach a file anywhere
@@ -342,10 +355,19 @@ await hue.withSpan(
 ```
 
 Give exactly one of `data` (a `Buffer`, typed array, `ArrayBuffer`, or a base64 string or `data:`
-URL) and `path` (read from the file system when the attachment is created), a `contentType` and
-optionally a `name`. The bytes are read and hashed when the attachment is created and are limited
-to 25 MiB, the `recordFile` limit: they are held in memory from then until export, within the
-128 MiB budget that queued spans share for values awaiting upload.
+URL) and `path` (a file on the file system), a `contentType` and optionally a `name`. `data` is
+read and hashed when the attachment is created and is limited to 25 MiB, the `recordFile` limit:
+it is held in memory from then until export, within the 128 MiB budget that queued spans share for
+values awaiting upload. A `path` names a regular file: anything else, such as a named pipe, is
+refused without waiting on it. A `path` up to 25 MiB is read the same way. A larger regular file, up to
+Hue's 1 GB upload limit, is not held: it is hashed a 1 MiB slice at a time when the attachment is
+created and read again from disk when it is uploaded, each slice hashed as it is sent and the last
+sent only once the file ended at the size and SHA-256 it was recorded with. Keep such a file in
+place and unchanged until the client flushes: one that changed, is gone or is no longer a regular
+file is not uploaded (the
+request ends before its body is complete, and Hue's upload URL signs the size and SHA-256, so the
+store refuses other bytes), and it counts in `report.uploadFallbacks`, its part keeping the digest
+it was recorded with.
 
 At its position the attachment is recorded as a GenAI `blob` part that names the file by digest,
 `{"type":"blob","mime_type":"application/pdf","modality":"document","sha256":"<64 hex>","size":48213,"name":"contract.pdf"}`,
@@ -362,7 +384,11 @@ With `captureContent: false` or a setup credential no bytes leave the process: a
 attribute still records the part, without its name, and content values are not recorded at all. A
 part the redactor removes or rewrites is not uploaded. A part that cannot be uploaded keeps its
 digest and is counted in `report.uploadFallbacks`, as is one nested more than 10 levels deep in its
-value, where Hue does not read parts, or one in a value cut to the value limit. Creating an
+value, where Hue does not read parts, or one in a value cut to the value limit. An attachment in a
+value that is still over the value limit with its files as digest parts is uploaded and listed as
+usual, and `client.media.fetch({ traceId, sha256 })` and Hue's span read reach it by digest; the
+value itself uploads whole and keeps only its first 16 KiB inline, so readers do not place the file
+at its position in the value. Creating an
 attachment never throws: one without exactly one of `data` and `path`, with unreadable or larger
 data or an invalid content type is recorded as `null` and counted as an instrumentation failure;
 an invalid name alone is omitted and counted.
@@ -385,9 +411,14 @@ await hue.withSpan("review contract", async () => {
 ```
 
 `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
+`data` is limited to 25 MiB, as it is held in memory until it is uploaded. Larger data is omitted
+and counted as an instrumentation failure; pass `sha256` and `byteSize` when you already have them.
+Give `path` instead of `data` for a file on disk: up to 25 MiB it is read as `data` is, and a larger
+regular file, up to Hue's 1 GB upload limit, is hashed a slice at a time now and, with `upload`,
+read again from disk when it is uploaded, as an [`Attachment`](#attach-a-file-anywhere) given by
+path is: it uploads only if it still has the size and SHA-256 it was recorded with. A file over
+1 GB, a path that is no regular file, or `data` and `path` together, is omitted and counted. Upload requires supplied bytes or a
+path, 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. An export fits every
 span's events and entries before it uploads any of these files, then uploads the files of all its
 spans together, four at a time; a file whose event was redacted or shed is not uploaded.
@@ -480,7 +511,37 @@ the recorded model call again with the real image, document or audio. See
 | `LangfuseMedia` | `Attachment` | [`Attachment`](#attach-a-file-anywhere), at the same position |
 | `resolveMediaReferences({ obj, resolveWith: "base64DataUri" })` | | `client.media.resolve(obj, { traceId })` |
 | `GET /api/public/media/{mediaId}` | `ReadonlyAttachment.data()` | `client.media.fetch({ traceId, sha256 })` |
-| Media tokens (`@@@langfuseMedia:…@@@`) | `ExternalAttachment` | Left as recorded: Hue never fetches a remote URL or a file another service holds |
+| Media tokens (`@@@langfuseMedia:…@@@`) | `ExternalAttachment` | Left as recorded: Hue never fetches a remote URL or a file another service holds. [`hue import langfuse --media`](#import-from-langfuse) copies Langfuse's files with your keys |
+
+## Import from Langfuse
+
+`hue import langfuse` copies a Langfuse project's history into Hue. It runs on your machine with
+the Langfuse project's own keys (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, and
+`LANGFUSE_BASE_URL` or `LANGFUSE_HOST`), which go only to Langfuse, and sends the spans with your
+`HUE_API_KEY`:
+
+```sh
+npx -y @hue-run/sdk@0.18.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.18.2 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
+  through the v1 traces and observations API, newest first; `--from`, `--to`, `--limit` and
+  `--trace-id` select traces, and `--dry-run` counts them without sending anything.
+- Each observation becomes the span a Langfuse OpenTelemetry SDK records, with the
+  `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.
+- 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
+  the trace in the [digest form](#automatically-captured-media) the SDK writes, listed in
+  `hue.blobs`; a reference Langfuse holds no bytes for stays as recorded.
+- Langfuse's rate limits are waited out for as long as `Retry-After` asks.
+
+The command has no Python counterpart; it runs with `npx` for an application in any language. See
+[Import traces from Langfuse](CLI.md#import-traces-from-langfuse) for every option, the attribute
+mapping, media handling, limits and exit codes.
 
 ## Vercel AI SDK 6
 
@@ -787,7 +848,9 @@ apart from their record, up to Hue's upload limit of 1,000,000,000 bytes:
 
 Hue stores the value under the trace, so the trace's retention, deletion and erasure cover it.
 Uploads run in the export, never on the application's thread: at most four at a time, each request
-within the export timeout, and all of one export's uploads within six export timeouts; a
+within the export timeout, and all of one export's uploads within six export timeouts (60 seconds
+at the default `timeoutMillis` of 10000), so a 1 GB file needs about 17 MB/s at the defaults;
+raise `timeoutMillis` (up to 60000) for slower links. A
 transient failure is retried once. A rate-limited reservation (429) waits out its `Retry-After`
 within the export's 60-second hold. `flush()` and `shutdown()` wait for uploads like any export
 work, and a `shutdownSafe()` whose budget runs out ends the uploads in flight.
@@ -796,7 +859,8 @@ A value that cannot be uploaded (Hue or the store refused it or failed, the netw
 did, the receiver has no upload route, or the value is over 1 GB) is exported as before uploads
 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
+the file event. Bytes given in memory to `recordFile` or an `Attachment` are limited to 25 MiB; a
+file given by path, a file read in place from a value and a whole attribute to 1 GB. 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`; successful uploads are counted
 in `report.uploadedValues`. Both counters include whole attributes, eligible media, attachments

package/dist/attachment.d.ts

@@ -1,12 +1,15 @@
+import type { ByteSource } from "./large-media.js";
 /** How deep in a value an attachment's part may sit and still be uploaded: Hue reads media parts
  * within ten levels of the value's root. */
 export declare const MAX_ATTACHMENT_DEPTH = 10;
 /** Options for {@link Attachment}. Give exactly one of `data` and `path`. */
 export interface AttachmentOptions {
     /** The file's bytes (a `Buffer`, typed array or `ArrayBuffer`), or a string holding them as
-     * base64 or a `data:` URL. */
+     * base64 or a `data:` URL; up to 25 MiB. */
     data?: ArrayBufferView | ArrayBuffer | string;
-    /** A file to read when the attachment is created (Node.js file system). */
+    /** A file to read (Node.js file system): up to 25 MiB it is read when the attachment is created;
+     * a larger regular file, up to Hue's 1 GB upload limit, is hashed then and read again from disk
+     * when it is uploaded. */
     path?: string;
     /** The file's media type, such as `image/png` or `application/pdf`. */
     contentType: string;
@@ -15,15 +18,50 @@ export interface AttachmentOptions {
 }
 /** What an attachment holds, read by the client and transport only. */
 export interface AttachmentState {
-    /** The file's bytes; undefined for an attachment that could not be read or is invalid. */
+    /** The file's bytes; undefined for a file read from disk when it is uploaded, and for an
+     * attachment that could not be read or is invalid. */
     bytes?: Uint8Array;
+    /** A file given by path over 25 MiB, read again from disk when it is uploaded. */
+    file?: PathFile;
     sha256?: string;
+    /** The file's size; undefined for an invalid attachment. */
+    size?: number;
     contentType: string;
     /** The name, when it is a valid media name. */
     name?: string;
     /** A name was given and is not a valid media name: it is omitted and counted. */
     invalidName: boolean;
 }
+/** A regular file given by path over the in-memory limit, as it was hashed when it was recorded:
+ * its absolute path, size and SHA-256. Its bytes are read again from disk when it is uploaded. */
+export interface PathFile {
+    path: string;
+    size: number;
+    sha256: string;
+}
+/**
+ * A regular file given by path: its bytes when it is no larger than 25 MiB, and otherwise, up to
+ * Hue's 1 GB upload limit, its size and SHA-256 from one reading pass a slice at a time, never
+ * holding it whole. Undefined for a file over its limit and for anything that is no regular file
+ * (a named pipe, a device), which is opened without waiting and never read; throws for one that
+ * cannot be opened.
+ */
+export declare function readPath(path: string): {
+    bytes: Uint8Array;
+} | {
+    file: PathFile;
+} | undefined;
+/**
+ * A file given by path as an upload body, read from disk a slice at a time. Each slice is hashed as
+ * it is read and sent once the next one is read; the last is sent only once the file ended at its
+ * recorded size with its recorded SHA-256. A file that changed since it was recorded, or can no
+ * longer be read, ends the read with an error before its body is complete and sets `changed`, so
+ * the upload is abandoned and the value is counted as not uploaded; so does a path that is no
+ * longer a regular file, which is opened without waiting (a named pipe in its place would wait for
+ * a writer) and never read. Hue's presigned PUT also signs the size and SHA-256, so the store
+ * refuses a body that differs.
+ */
+export declare function fileSource(file: PathFile): ByteSource;
 /**
  * A file placed in a recorded value, the equivalent of Langfuse's `LangfuseMedia` and
  * Braintrust's `Attachment`. Put it anywhere in a `withSpan()` input or output, in `model()`
@@ -32,10 +70,16 @@ export interface AttachmentState {
  * names the file by digest (`{ type: "blob", mime_type, modality, sha256, size, name }`) and
  * uploads its bytes during export, listed under the record's `hue.blobs`.
  *
- * The bytes are read and hashed when the attachment is created; `data` and `path` are limited to
- * 25 MiB. Creating one never throws: an attachment without exactly one of `data` and `path`, with
- * unreadable data, larger data or an invalid `contentType` records `null` where it is placed and
- * counts an instrumentation failure; an invalid `name` alone is omitted and counted.
+ * The bytes are read and hashed when the attachment is created; `data` is limited to 25 MiB, as
+ * the bytes are held in memory until they are uploaded. A `path` names a regular file, opened
+ * without waiting: anything else, such as a named pipe, is invalid. One up to 25 MiB is read then
+ * too; a larger regular file, up to Hue's 1 GB upload limit, is hashed then a slice at a time and read
+ * again from disk when it is uploaded, so it must stay in place and unchanged until the client
+ * flushes: a file whose size or SHA-256 then differs is not uploaded and counts as an upload
+ * fallback, its part keeping the digest it was recorded with. Creating one never throws: an
+ * attachment without exactly one of `data` and `path`, with unreadable data, larger data or an
+ * invalid `contentType` records `null` where it is placed and counts an instrumentation failure;
+ * an invalid `name` alone is omitted and counted.
  */
 export declare class Attachment {
     /** The media type given. */