@hue-run/sdk 0.20.1 → 0.20.2

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

@@ -0,0 +1,52 @@
+/**
+ * A bounded reader of ZIP archives for `hue traces import prepare`: the central directory is
+ * read from the end of the file, each member is read on demand at its own offset and inflated
+ * in memory with `node:zlib`, never with an external command and never onto disk. Only stored
+ * and deflated members are read; a member that is encrypted, uses another method, names an
+ * unsafe path or exceeds a bound is reported, not read. ZIP64 sizes and offsets are understood,
+ * so an archive over 4 GiB or with many members still lists.
+ */
+export declare const ZIP_LIMITS: {
+    /** Members one archive may list. */
+    readonly members: 20000;
+    /** One member, decoded. */
+    readonly memberBytes: number;
+    /** Every member of the archive, decoded, together. */
+    readonly totalBytes: number;
+    /** The central directory itself. */
+    readonly centralDirectoryBytes: number;
+    /** A member name or extra field. */
+    readonly fieldBytes: 65535;
+};
+export interface ZipMember {
+    /** The member's path as the archive names it. */
+    path: string;
+    /** Why the member cannot be read, when it cannot; a readable member has none. */
+    refused?: string;
+    size: number;
+    compressedSize: number;
+    method: number;
+    crc32: number;
+    localHeaderOffset: number;
+}
+export declare class ZipError extends Error {
+}
+/** Whether a file starts like a ZIP archive: a local header, or the end record of an empty one. */
+export declare function isZipSignature(head: Uint8Array): boolean;
+/**
+ * Why a member path must not be read: an absolute path, a drive or network path, a `..`
+ * segment, a backslash, a control character or an empty name. A directory entry (ending in
+ * `/`) is not a file and is skipped by the caller.
+ */
+export declare function unsafeZipPath(path: string): string | undefined;
+/** The archive's central directory, listed once; members are read on demand. */
+export declare class ZipArchive {
+    private readonly handle;
+    readonly members: readonly ZipMember[];
+    private constructor();
+    static open(path: string): Promise<ZipArchive>;
+    private static list;
+    /** The member's bytes, decoded and checked against its recorded size and CRC-32. */
+    read(member: ZipMember): Promise<Uint8Array>;
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,278 @@
+import { open } from "node:fs/promises";
+import { crc32, inflateRawSync } from "node:zlib";
+/**
+ * A bounded reader of ZIP archives for `hue traces import prepare`: the central directory is
+ * read from the end of the file, each member is read on demand at its own offset and inflated
+ * in memory with `node:zlib`, never with an external command and never onto disk. Only stored
+ * and deflated members are read; a member that is encrypted, uses another method, names an
+ * unsafe path or exceeds a bound is reported, not read. ZIP64 sizes and offsets are understood,
+ * so an archive over 4 GiB or with many members still lists.
+ */
+export const ZIP_LIMITS = {
+    /** Members one archive may list. */
+    members: 20_000,
+    /** One member, decoded. */
+    memberBytes: 64 * 1024 * 1024,
+    /** Every member of the archive, decoded, together. */
+    totalBytes: 1024 * 1024 * 1024,
+    /** The central directory itself. */
+    centralDirectoryBytes: 32 * 1024 * 1024,
+    /** A member name or extra field. */
+    fieldBytes: 65_535,
+};
+const LOCAL_HEADER = 0x04034b50;
+const CENTRAL_HEADER = 0x02014b50;
+const END_OF_CENTRAL_DIRECTORY = 0x06054b50;
+const ZIP64_END_OF_CENTRAL_DIRECTORY = 0x06064b50;
+const ZIP64_LOCATOR = 0x07064b50;
+const ZIP64_EXTRA = 0x0001;
+const END_RECORD_BYTES = 22;
+const MAX_COMMENT_BYTES = 65_535;
+const METHOD_STORED = 0;
+const METHOD_DEFLATE = 8;
+/** The most compressed bytes a deflated member of `size` decoded bytes can take: deflate grows
+ * an incompressible input by at most 5 bytes per 64 KiB block, well under a kilobyte per
+ * megabyte and a kilobyte of slack. A larger `compressedSize` is a malformed entry, refused
+ * before any of it is read. */
+const deflateBound = (size) => size + (size >>> 10) + 1024;
+const FLAG_ENCRYPTED = 0x0001;
+const FLAG_UTF8 = 0x0800;
+export class ZipError extends Error {
+}
+/** Whether a file starts like a ZIP archive: a local header, or the end record of an empty one. */
+export function isZipSignature(head) {
+    if (head.byteLength < 4)
+        return false;
+    const signature = head[0] | (head[1] << 8) | (head[2] << 16) | (head[3] << 24);
+    return signature === LOCAL_HEADER || signature === END_OF_CENTRAL_DIRECTORY;
+}
+/**
+ * Why a member path must not be read: an absolute path, a drive or network path, a `..`
+ * segment, a backslash, a control character or an empty name. A directory entry (ending in
+ * `/`) is not a file and is skipped by the caller.
+ */
+export function unsafeZipPath(path) {
+    if (!path)
+        return "an empty member name";
+    if (path.includes("\0") || /[\p{Cc}]/u.test(path))
+        return "a control character in the name";
+    if (path.includes("\\"))
+        return "a backslash in the name";
+    if (path.startsWith("/") || /^[A-Za-z]:/.test(path) || path.startsWith("//"))
+        return "an absolute path";
+    if (path.split("/").some((segment) => segment === ".." || segment === "."))
+        return "a relative path segment";
+    if (!path.isWellFormed())
+        return "an invalid name";
+    return undefined;
+}
+async function readAt(handle, position, length) {
+    const buffer = Buffer.allocUnsafe(length);
+    let offset = 0;
+    while (offset < length) {
+        const { bytesRead } = await handle.read(buffer, offset, length - offset, position + offset);
+        if (bytesRead === 0)
+            throw new ZipError("The archive ends before a record it names");
+        offset += bytesRead;
+    }
+    return buffer;
+}
+const readU64 = (buffer, offset) => {
+    const value = buffer.readBigUInt64LE(offset);
+    if (value > BigInt(Number.MAX_SAFE_INTEGER))
+        throw new ZipError("A ZIP64 field is out of range");
+    return Number(value);
+};
+/** The archive's central directory, listed once; members are read on demand. */
+export class ZipArchive {
+    handle;
+    members;
+    constructor(handle, members) {
+        this.handle = handle;
+        this.members = members;
+    }
+    static async open(path) {
+        const handle = await open(path, "r");
+        try {
+            const members = await ZipArchive.list(handle);
+            return new ZipArchive(handle, members);
+        }
+        catch (error) {
+            await handle.close();
+            throw error;
+        }
+    }
+    static async list(handle) {
+        const size = (await handle.stat()).size;
+        if (size < END_RECORD_BYTES)
+            throw new ZipError("The archive has no end record");
+        const tailLength = Math.min(size, END_RECORD_BYTES + MAX_COMMENT_BYTES);
+        const tail = await readAt(handle, size - tailLength, tailLength);
+        let endOffset = -1;
+        for (let at = tailLength - END_RECORD_BYTES; at >= 0; at--) {
+            if (tail.readUInt32LE(at) !== END_OF_CENTRAL_DIRECTORY)
+                continue;
+            // The record's comment length must reach the end of the file for it to be the end record.
+            if (at + END_RECORD_BYTES + tail.readUInt16LE(at + 20) === tailLength) {
+                endOffset = at;
+                break;
+            }
+        }
+        if (endOffset < 0)
+            throw new ZipError("The archive has no end record");
+        const end = tail.subarray(endOffset);
+        if (end.readUInt16LE(4) !== 0 || end.readUInt16LE(6) !== 0)
+            throw new ZipError("Multi-disk archives are not supported");
+        let count = end.readUInt16LE(10);
+        let directoryBytes = end.readUInt32LE(12);
+        let directoryOffset = end.readUInt32LE(16);
+        const endPosition = size - tailLength + endOffset;
+        if (count === 0xffff || directoryBytes === 0xffffffff || directoryOffset === 0xffffffff) {
+            if (endPosition < 20)
+                throw new ZipError("The ZIP64 locator is missing");
+            const locator = await readAt(handle, endPosition - 20, 20);
+            if (locator.readUInt32LE(0) !== ZIP64_LOCATOR)
+                throw new ZipError("The ZIP64 locator is missing");
+            const recordOffset = readU64(locator, 8);
+            if (recordOffset + 56 > size)
+                throw new ZipError("The ZIP64 end record is out of range");
+            const record = await readAt(handle, recordOffset, 56);
+            if (record.readUInt32LE(0) !== ZIP64_END_OF_CENTRAL_DIRECTORY)
+                throw new ZipError("The ZIP64 end record is missing");
+            if (record.readUInt32LE(16) !== 0 || record.readUInt32LE(20) !== 0)
+                throw new ZipError("Multi-disk archives are not supported");
+            count = readU64(record, 32);
+            directoryBytes = readU64(record, 40);
+            directoryOffset = readU64(record, 48);
+        }
+        if (count > ZIP_LIMITS.members)
+            throw new ZipError(`The archive lists more than ${ZIP_LIMITS.members} members`);
+        if (directoryBytes > ZIP_LIMITS.centralDirectoryBytes)
+            throw new ZipError("The archive's central directory is too large");
+        if (directoryOffset + directoryBytes > size)
+            throw new ZipError("The archive's central directory is out of range");
+        const directory = await readAt(handle, directoryOffset, directoryBytes);
+        const members = [];
+        let at = 0;
+        const utf8 = new TextDecoder("utf-8");
+        for (let index = 0; index < count; index++) {
+            if (at + 46 > directory.byteLength)
+                throw new ZipError("The archive's central directory is truncated");
+            if (directory.readUInt32LE(at) !== CENTRAL_HEADER)
+                throw new ZipError("The archive's central directory is malformed");
+            const flags = directory.readUInt16LE(at + 8);
+            const method = directory.readUInt16LE(at + 10);
+            const crc = directory.readUInt32LE(at + 16);
+            let compressedSize = directory.readUInt32LE(at + 20);
+            let uncompressedSize = directory.readUInt32LE(at + 24);
+            const nameLength = directory.readUInt16LE(at + 28);
+            const extraLength = directory.readUInt16LE(at + 30);
+            const commentLength = directory.readUInt16LE(at + 32);
+            const disk = directory.readUInt16LE(at + 34);
+            let localHeaderOffset = directory.readUInt32LE(at + 42);
+            const nameStart = at + 46;
+            const extraStart = nameStart + nameLength;
+            const next = extraStart + extraLength + commentLength;
+            if (next > directory.byteLength)
+                throw new ZipError("The archive's central directory is truncated");
+            const nameBytes = directory.subarray(nameStart, extraStart);
+            const extra = directory.subarray(extraStart, extraStart + extraLength);
+            // ZIP64 fields replace, in order, only the header fields that are at their maximum.
+            if (compressedSize === 0xffffffff ||
+                uncompressedSize === 0xffffffff ||
+                localHeaderOffset === 0xffffffff) {
+                let field = 0;
+                let found = false;
+                while (field + 4 <= extra.byteLength) {
+                    const id = extra.readUInt16LE(field);
+                    const length = extra.readUInt16LE(field + 2);
+                    if (id === ZIP64_EXTRA) {
+                        let cursor = field + 4;
+                        const take = () => {
+                            if (cursor + 8 > field + 4 + length)
+                                throw new ZipError("A ZIP64 extra field is truncated");
+                            const value = readU64(extra, cursor);
+                            cursor += 8;
+                            return value;
+                        };
+                        if (uncompressedSize === 0xffffffff)
+                            uncompressedSize = take();
+                        if (compressedSize === 0xffffffff)
+                            compressedSize = take();
+                        if (localHeaderOffset === 0xffffffff)
+                            localHeaderOffset = take();
+                        found = true;
+                        break;
+                    }
+                    field += 4 + length;
+                }
+                if (!found)
+                    throw new ZipError("A member needs a ZIP64 extra field it lacks");
+            }
+            const path = utf8.decode(nameBytes);
+            const member = {
+                path,
+                size: uncompressedSize,
+                compressedSize,
+                method,
+                crc32: crc,
+                localHeaderOffset,
+            };
+            const unsafe = unsafeZipPath(path);
+            if (!(flags & FLAG_UTF8) && nameBytes.some((byte) => byte >= 0x80))
+                member.refused = "a member name that is not UTF-8";
+            else if (unsafe)
+                member.refused = unsafe;
+            else if (disk !== 0)
+                member.refused = "a member on another disk";
+            else if (flags & FLAG_ENCRYPTED)
+                member.refused = "an encrypted member";
+            else if (method !== METHOD_STORED && method !== METHOD_DEFLATE)
+                member.refused = `compression method ${method} (only stored and deflate are read)`;
+            else if (uncompressedSize > ZIP_LIMITS.memberBytes)
+                member.refused = `a member over ${ZIP_LIMITS.memberBytes} bytes`;
+            else if (method === METHOD_STORED
+                ? compressedSize !== uncompressedSize
+                : compressedSize > deflateBound(uncompressedSize))
+                member.refused = "a member whose compressed size does not fit its recorded size";
+            else if (localHeaderOffset + 30 > size || compressedSize > size)
+                member.refused = "a member outside the archive";
+            members.push(member);
+            at = next;
+        }
+        return members;
+    }
+    /** The member's bytes, decoded and checked against its recorded size and CRC-32. */
+    async read(member) {
+        if (member.refused)
+            throw new ZipError(`The member cannot be read: ${member.refused}`);
+        const header = await readAt(this.handle, member.localHeaderOffset, 30);
+        if (header.readUInt32LE(0) !== LOCAL_HEADER)
+            throw new ZipError("A member's local header is malformed");
+        const dataOffset = member.localHeaderOffset + 30 + header.readUInt16LE(26) + header.readUInt16LE(28);
+        // The listing refused any member past this bound; a member built elsewhere is held to it
+        // before its compressed bytes are allocated.
+        if (member.compressedSize > deflateBound(Math.min(member.size, ZIP_LIMITS.memberBytes)))
+            throw new ZipError("A member's compressed data exceeds the archive bounds");
+        const compressed = await readAt(this.handle, dataOffset, member.compressedSize);
+        let bytes;
+        if (member.method === METHOD_STORED)
+            bytes = compressed;
+        else {
+            try {
+                bytes = inflateRawSync(compressed, { maxOutputLength: Math.max(1, member.size) });
+            }
+            catch {
+                throw new ZipError("A member's compressed data is invalid");
+            }
+        }
+        if (bytes.byteLength !== member.size)
+            throw new ZipError("A member's size differs from its recorded size");
+        if (crc32(bytes) !== member.crc32)
+            throw new ZipError("A member's CRC-32 does not match");
+        return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    }
+    async close() {
+        await this.handle.close();
+    }
+}

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

@@ -0,0 +1,18 @@
+import { type UploadIo } from "./traces-import-upload.js";
+/**
+ * `hue traces import`: imports a bundle of existing traces into Hue in two steps that keep the
+ * payloads on this machine until the agent has authorized their delivery. `prepare` converts a
+ * file, directory or ZIP archive of OTLP/JSON, Langfuse observation or ATIF exports into a
+ * bundle and prints its manifest digest and totals; `prepare_trace_import` (Hue MCP) takes
+ * those and answers an import authorization; `upload` delivers the bundle with it.
+ */
+/** Streams and seams for {@link runTracesCommand}; tests inject these. */
+export interface TracesCommandIo extends UploadIo {
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}
+export declare const TRACES_USAGE = "Usage: hue traces import prepare <path> [--out <directory>] [--json]\n       hue traces import upload <directory> --authorization-file <file> [--import-url <url>] [--json]\n\nImport a bundle of existing traces into Hue. Nothing leaves this machine until the upload step,\nand no project key is involved: a Hue MCP connection authorizes the delivery.\n\nprepare  Reads a file, a directory or a ZIP archive and recognizes each file by its content:\n         OTLP/JSON trace exports ({\"resourceSpans\": [\u2026]}, also one per line), complete Langfuse\n         observation exports (the data or observations envelope) and text ATIF v1.7/v1.8 exports.\n         Every trace becomes gzip OTLP/JSON batches written to --out (default <path>.hue-import)\n         with manifest.json. The report names the manifest_digest and totals that\n         prepare_trace_import takes, the files it could not read, invalid vendor ids it mapped\n         to OpenTelemetry ids, traces without a history owner and the origin each source\n         recorded.\n  --out <directory>   Where the bundle is written (created with mode 0700)\n  --json              Print the report as one JSON object\n\nupload   Registers the manifest, then sends each trace's values and batches in order, two\n         requests at a time, checks every span's receipt, reconciles and completes. Progress is\n         kept in <directory>/progress.json, so running the same command again resumes.\n  --authorization-file <file>  A private file holding what prepare_trace_import answered: its\n                               JSON (authorization and upload_url), or the authorization\n                               (hue_it_\u2026) alone on the first line, the upload_url on the second.\n                               The authorization is never taken from the command line or the\n                               environment, and never printed.\n  --import-url <url>  The upload_url prepare_trace_import returned (https://\u2026/api/v1/trace-imports/<id>),\n                      when the authorization file does not hold it\n  --origin <url>      Accept only an import URL on this Hue origin\n  --json              Print one JSON progress object per line on stderr and the report on stdout\n\nExit codes: 0 prepared or completed, 1 not completed (the report says what to do next),\n2 usage error, 130 stopped (run the same command again to resume).";
+/** Runs `hue traces import …`; resolves to the exit code. */
+export declare function runTracesCommand(argv: string[], io?: TracesCommandIo): Promise<number>;

package/dist/cli/traces-import.js

@@ -0,0 +1,231 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { parseHueOrigin } from "./login.js";
+import { PrepareError, prepareTraceBundle } from "./traces-import-prepare.js";
+import { parseAuthorizationFile, parseImportUrl, UploadStop, uploadTraceBundle, } from "./traces-import-upload.js";
+export const TRACES_USAGE = `Usage: hue traces import prepare <path> [--out <directory>] [--json]
+       hue traces import upload <directory> --authorization-file <file> [--import-url <url>] [--json]
+
+Import a bundle of existing traces into Hue. Nothing leaves this machine until the upload step,
+and no project key is involved: a Hue MCP connection authorizes the delivery.
+
+prepare  Reads a file, a directory or a ZIP archive and recognizes each file by its content:
+         OTLP/JSON trace exports ({"resourceSpans": […]}, also one per line), complete Langfuse
+         observation exports (the data or observations envelope) and text ATIF v1.7/v1.8 exports.
+         Every trace becomes gzip OTLP/JSON batches written to --out (default <path>.hue-import)
+         with manifest.json. The report names the manifest_digest and totals that
+         prepare_trace_import takes, the files it could not read, invalid vendor ids it mapped
+         to OpenTelemetry ids, traces without a history owner and the origin each source
+         recorded.
+  --out <directory>   Where the bundle is written (created with mode 0700)
+  --json              Print the report as one JSON object
+
+upload   Registers the manifest, then sends each trace's values and batches in order, two
+         requests at a time, checks every span's receipt, reconciles and completes. Progress is
+         kept in <directory>/progress.json, so running the same command again resumes.
+  --authorization-file <file>  A private file holding what prepare_trace_import answered: its
+                               JSON (authorization and upload_url), or the authorization
+                               (hue_it_…) alone on the first line, the upload_url on the second.
+                               The authorization is never taken from the command line or the
+                               environment, and never printed.
+  --import-url <url>  The upload_url prepare_trace_import returned (https://…/api/v1/trace-imports/<id>),
+                      when the authorization file does not hold it
+  --origin <url>      Accept only an import URL on this Hue origin
+  --json              Print one JSON progress object per line on stderr and the report on stdout
+
+Exit codes: 0 prepared or completed, 1 not completed (the report says what to do next),
+2 usage error, 130 stopped (run the same command again to resume).`;
+class UsageError extends Error {
+}
+const IMPORT_TOKEN = /hue_it_[A-Za-z0-9_-]{43}/g;
+function plural(count, one, many = `${one}s`) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+/** Runs `hue traces import …`; resolves to the exit code. */
+export async function runTracesCommand(argv, io = {}) {
+    const stdout = io.stdout ?? process.stdout;
+    const stderr = io.stderr ?? process.stderr;
+    const cwd = io.cwd ?? process.cwd();
+    // Every line loses import authorizations and control characters.
+    const clean = (line) => line.replace(IMPORT_TOKEN, "[redacted]").replace(/[^\P{Cc}\n\t]|\p{Cf}/gu, " ");
+    const out = (line) => void stdout.write(`${clean(line)}\n`);
+    const warn = (line) => void stderr.write(`${clean(line)}\n`);
+    try {
+        if (argv.includes("--help") || argv.includes("-h")) {
+            stdout.write(`${TRACES_USAGE}\n`);
+            return 0;
+        }
+        const [group, action, ...rest] = argv;
+        if (group !== "import")
+            throw new UsageError(`Unknown command: hue traces ${group ?? ""}`.trim());
+        if (action === "prepare")
+            return await prepare(rest, cwd, out, warn);
+        if (action === "upload")
+            return await upload(rest, cwd, io, out, warn);
+        throw new UsageError(action ? `Unknown command: hue traces import ${action}` : "Name the step: prepare or upload");
+    }
+    catch (error) {
+        if (!(error instanceof UsageError))
+            throw error;
+        warn(error.message);
+        stderr.write(`\n${TRACES_USAGE}\n`);
+        return 2;
+    }
+}
+function parsePrepareArguments(argv) {
+    try {
+        return parseArgs({
+            args: argv,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                out: { type: "string" },
+                json: { type: "boolean", default: false },
+            },
+        });
+    }
+    catch (error) {
+        throw new UsageError(error.message);
+    }
+}
+async function prepare(argv, cwd, out, warn) {
+    const { values, positionals } = parsePrepareArguments(argv);
+    if (positionals.length !== 1)
+        throw new UsageError(positionals.length
+            ? `Unexpected argument: ${positionals[1]}`
+            : "Name the file, directory or archive to prepare");
+    const input = resolve(cwd, positionals[0]);
+    let report;
+    try {
+        report = await prepareTraceBundle(input, {
+            ...(values.out !== undefined ? { out: resolve(cwd, values.out) } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof PrepareError) {
+            warn(error.message);
+            return 1;
+        }
+        if (error.code === "ENOENT") {
+            warn(`${input} does not exist`);
+            return 1;
+        }
+        throw error;
+    }
+    if (values.json) {
+        out(JSON.stringify(report));
+        return 0;
+    }
+    out(`Prepared ${plural(report.totals.traces, "trace")} (${plural(report.totals.spans, "span")}, ${plural(report.totals.batches, "batch", "batches")}, ${plural(report.totals.blobs, "large value")}) in ${report.output_directory}.`);
+    out(`Formats: ${Object.entries(report.formats)
+        .filter(([, count]) => count)
+        .map(([format, count]) => `${format} ${count}`)
+        .join(", ")}.`);
+    out(`Manifest digest: ${report.manifest_digest}`);
+    out(`Totals: ${JSON.stringify(report.totals)}`);
+    out(`Source: ${JSON.stringify(report.source)}`);
+    if (report.traces.without_identity)
+        out(`${plural(report.traces.without_identity, "trace names", "traces name")} no history owner.`);
+    const origins = Object.entries(report.traces.by_origin).filter(([, count]) => count);
+    out(`Origin: ${origins.map(([origin, count]) => `${origin} ${count}`).join(", ")}.`);
+    if (report.traces.remapped.traces)
+        out(`Mapped invalid vendor ids to OpenTelemetry ids in ${plural(report.traces.remapped.traces, "trace")} (${plural(report.traces.remapped.spans, "span")}).`);
+    for (const file of report.files.unsupported)
+        warn(`Not read: ${file.file}: ${file.reason}.`);
+    for (const refusal of report.traces.refused)
+        warn(`Not converted: ${[refusal.file, refusal.trace_id ? `trace ${refusal.trace_id}` : undefined].filter(Boolean).join(" ")}: ${refusal.reason}.`);
+    out("Next: call prepare_trace_import with manifest_digest, totals and source, write the authorization to a private file and run hue traces import upload.");
+    return 0;
+}
+function parseUploadArguments(argv) {
+    try {
+        return parseArgs({
+            args: argv,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                "authorization-file": { type: "string" },
+                "import-url": { type: "string" },
+                origin: { type: "string" },
+                json: { type: "boolean", default: false },
+            },
+        });
+    }
+    catch (error) {
+        throw new UsageError(error.message);
+    }
+}
+async function upload(argv, cwd, io, out, warn) {
+    const { values, positionals } = parseUploadArguments(argv);
+    if (positionals.length !== 1)
+        throw new UsageError(positionals.length
+            ? `Unexpected argument: ${positionals[1]}`
+            : "Name the prepared directory to upload");
+    if (!values["authorization-file"])
+        throw new UsageError("--authorization-file is required: the file holding the import authorization");
+    let origin;
+    if (values.origin !== undefined) {
+        const parsed = parseHueOrigin(values.origin);
+        if (!parsed)
+            throw new UsageError("--origin must be an HTTPS origin such as https://app.hue.run (plain HTTP is accepted for loopback test servers only)");
+        origin = parsed;
+    }
+    const directory = resolve(cwd, positionals[0]);
+    let token;
+    let importUrl = values["import-url"];
+    try {
+        const content = await readFile(resolve(cwd, values["authorization-file"]), "utf8").catch(() => {
+            throw new UploadStop(`${values["authorization-file"]} could not be read`, "authorization_invalid");
+        });
+        const parsed = parseAuthorizationFile(content);
+        token = parsed.token;
+        importUrl ??= parsed.importUrl;
+        if (!importUrl)
+            throw new UploadStop("Pass --import-url, or put the upload_url prepare_trace_import returned on the authorization file's second line", "url_invalid");
+        importUrl = parseImportUrl(importUrl, origin).href;
+    }
+    catch (error) {
+        if (!(error instanceof UploadStop))
+            throw error;
+        throw new UsageError(error.message);
+    }
+    const json = values.json;
+    const progress = (event) => {
+        if (json)
+            warn(JSON.stringify(event));
+        else if (event.event === "manifest.registered")
+            out(`Registered the manifest with import ${String(event.import_id)}.`);
+        else if (event.event === "trace.conflicted")
+            warn(`Trace ${String(event.trace_id)} conflicts with evidence Hue already holds.`);
+        else if (event.event === "trace.unverified")
+            warn(`Trace ${String(event.trace_id)}: ${String(event.missing_spans)} span(s) not yet confirmed.`);
+        else if (event.event === "trace.verified" && Number(event.index) % 100 === 0)
+            out(`Verified ${String(event.index)} of ${String(event.of)} traces.`);
+    };
+    let report;
+    try {
+        report = await uploadTraceBundle({ directory, token, importUrl }, { ...io, progress });
+    }
+    catch (error) {
+        if (!(error instanceof UploadStop))
+            throw error;
+        warn(error.message);
+        return 1;
+    }
+    if (json)
+        out(JSON.stringify(report));
+    else {
+        out(`${report.state === "completed" ? "Completed" : report.state === "stopped" ? "Stopped" : report.state === "failed" ? "Failed" : "Not completed"}: ${report.traces.verified} of ${plural(report.traces.declared, "trace")} verified, ${report.traces.conflicted} conflicted, ${report.batches.landed} of ${plural(report.batches.declared, "batch", "batches")} landed, ${report.blobs.stored} of ${plural(report.blobs.declared, "large value")} stored.`);
+        for (const conflict of report.conflicts.slice(0, 20))
+            warn(`  ${conflict.trace_id} ${conflict.sha256}: ${conflict.message}`);
+        if (report.conflicts.length > 20)
+            warn(`  … and ${report.conflicts.length - 20} more`);
+        if (report.error)
+            warn(`${report.error.message}`);
+        if (report.note)
+            out(report.note);
+        out(report.next_action);
+    }
+    return report.state === "completed" ? 0 : report.state === "stopped" ? 130 : 1;
+}

package/dist/setup/cli.js

@@ -32,6 +32,10 @@ const extensions = new Map([
         "listen",
         async () => (await loadCommand("listen", () => import("../cli/listen.js"))).runListenCommand(process.argv.slice(3)),
     ],
+    [
+        "traces",
+        async () => (await loadCommand("traces", () => import("../cli/traces-import.js"))).runTracesCommand(process.argv.slice(3)),
+    ],
 ]);
 function writeEvent(event, mode, width) {
     const line = mode === "jsonl"
@@ -74,7 +78,7 @@ async function main() {
     }
     catch {
         if (!agentRequested) {
-            process.stderr.write("Usage: hue <setup|resume|status|claim|login|eval|mcp|listen|import> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
+            process.stderr.write("Usage: hue <setup|resume|status|claim|login|eval|mcp|listen|import|traces> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
             return 2;
         }
         const event = {
@@ -105,7 +109,7 @@ async function main() {
             process.stdout.write(`${renderJsonlEvent(event)}\n`);
             return 2;
         }
-        process.stdout.write("Usage: hue <setup|resume|status|claim|login|eval|mcp|listen|import> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
+        process.stdout.write("Usage: hue <setup|resume|status|claim|login|eval|mcp|listen|import|traces> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
         return 0;
     }
     const command = parsed.positionals[0];
@@ -137,7 +141,7 @@ async function main() {
             process.stdout.write(`${renderJsonlEvent(event)}\n`);
         }
         else
-            process.stderr.write("Usage: hue <setup|resume|status|claim|login|eval|mcp|listen|import> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
+            process.stderr.write("Usage: hue <setup|resume|status|claim|login|eval|mcp|listen|import|traces> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
         return 2;
     }
     const mode = selectSetupOutputMode({

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

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

package/dist/world/world.d.ts

@@ -16,8 +16,9 @@ export declare function worldNow(source?: WorldHandoff | Record<string, string |
 /** Variables that authenticate against Hue's control plane rather than a simulated provider. */
 export declare const HUE_CONTROL_PLANE_VARIABLES: readonly string[];
 /** Prefixes of the Hue control-plane credentials the server issues: project and setup keys,
- * attempt grants, the project MCP key, invocation and installation tokens, and OAuth tokens and
- * secrets. World tokens (`hue_world_`) and MCP capabilities (`hue_sim_`) are what the agent holds. */
+ * attempt grants, the project MCP key, invocation and installation tokens, OAuth tokens, trace
+ * import authorizations and secrets. World tokens (`hue_world_`) and MCP capabilities
+ * (`hue_sim_`) are what the agent holds. */
 export declare const HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES: readonly string[];
 /** True for a control-plane variable by name, or for a value carrying a Hue control-plane
  * credential anywhere in it, including wrapped, percent-encoded or JSON-Unicode-escaped values. */

package/dist/world/world.js

@@ -53,8 +53,9 @@ export const HUE_CONTROL_PLANE_VARIABLES = [
     "HUE_SERVICE_KEY",
 ];
 /** Prefixes of the Hue control-plane credentials the server issues: project and setup keys,
- * attempt grants, the project MCP key, invocation and installation tokens, and OAuth tokens and
- * secrets. World tokens (`hue_world_`) and MCP capabilities (`hue_sim_`) are what the agent holds. */
+ * attempt grants, the project MCP key, invocation and installation tokens, OAuth tokens, trace
+ * import authorizations and secrets. World tokens (`hue_world_`) and MCP capabilities
+ * (`hue_sim_`) are what the agent holds. */
 export const HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES = [
     "hue_sk_",
     "hue_attempt_",
@@ -64,6 +65,7 @@ export const HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES = [
     "hue_install_",
     "hue_at_",
     "hue_rt_",
+    "hue_it_",
     "hue_oauth_",
 ];
 /** A Hue credential anywhere in a value, including JSON Unicode escapes, not inside a longer word. */