@hue-run/sdk 0.21.0 → 0.22.0

package/dist/ai-sdk.d.ts

@@ -1,12 +1,34 @@
 import type { TelemetryOptions } from "ai";
 import type { HueClient } from "./client.js";
+/** Options for {@link hueTelemetry}. */
+export interface HueTelemetryOptions {
+    /**
+     * The runtime-context key whose value names the end user, recorded as `user.id` on the call's
+     * spans. `"userId"` by default; `false` records no user from runtime context.
+     */
+    userKey?: string | false;
+    /**
+     * The runtime-context keys whose value names the conversation, recorded as
+     * `gen_ai.conversation.id` on the call's spans; the first key with a value wins.
+     * `["sessionId", "threadId"]` by default; `false` records no conversation from runtime context.
+     */
+    sessionKey?: string | readonly string[] | false;
+}
 /**
  * Per-call telemetry for AI SDK 7: pass as an agent's or generation call's `telemetry` option.
  * Spans come from Hue's tracer, so they parent under `withSpan` and inherit session, user and
  * workspace identifiers; prompt and response recording follow `captureContent`. It does not
  * change global AI SDK integrations.
  *
+ * The end user and conversation can also come from the call's AI SDK runtime context: the value
+ * under `userKey` (`userId` by default) is recorded as `user.id`, and the first value under
+ * `sessionKey` (`sessionId`, then `threadId`) as `gen_ai.conversation.id`, on every span of the
+ * call. The returned `includeRuntimeContext` names those keys, which AI SDK otherwise withholds
+ * from telemetry; no other runtime-context value is recorded. An enclosing `withSpan`'s
+ * `userId` or `sessionId` takes precedence.
+ *
  * @throws TypeError when the client is enabled and the installed `ai` major version is below 7;
  * AI SDK 6 applications use `hueExperimentalTelemetry` from `@hue-run/sdk` instead.
+ * @throws TypeError when `userKey` or `sessionKey` names an empty key.
  */
-export declare function hueTelemetry(hue: HueClient): TelemetryOptions;
+export declare function hueTelemetry(hue: HueClient, options?: HueTelemetryOptions): TelemetryOptions;

package/dist/ai-sdk.js

@@ -19,16 +19,51 @@ function aiMajor() {
     }
     return Number.isNaN(installedAiMajor) ? undefined : installedAiMajor;
 }
+const runtimeKeys = (value, option) => {
+    const keys = value === false ? [] : typeof value === "string" ? [value] : [...value];
+    if (keys.some((key) => typeof key !== "string" || !key))
+        throw new TypeError(`hueTelemetry ${option} must be a non-empty runtime-context key or false`);
+    return keys;
+};
+/** A runtime-context value usable as an identifier: a string or finite number, 1–4096 valid
+ * characters with no NUL, as `withSpan` accepts for `userId` and `sessionId`. */
+function identifierFrom(value) {
+    const text = typeof value === "string"
+        ? value
+        : typeof value === "number" && Number.isFinite(value)
+            ? String(value)
+            : undefined;
+    return text && text.length <= 4096 && !text.includes("\u0000") && text.isWellFormed()
+        ? text
+        : undefined;
+}
+/** The identifier under the first of `keys` that holds a usable one. */
+function firstIdentifier(context, keys) {
+    for (const key of keys) {
+        const value = identifierFrom(context?.[key]);
+        if (value)
+            return value;
+    }
+    return undefined;
+}
 /**
  * Per-call telemetry for AI SDK 7: pass as an agent's or generation call's `telemetry` option.
  * Spans come from Hue's tracer, so they parent under `withSpan` and inherit session, user and
  * workspace identifiers; prompt and response recording follow `captureContent`. It does not
  * change global AI SDK integrations.
  *
+ * The end user and conversation can also come from the call's AI SDK runtime context: the value
+ * under `userKey` (`userId` by default) is recorded as `user.id`, and the first value under
+ * `sessionKey` (`sessionId`, then `threadId`) as `gen_ai.conversation.id`, on every span of the
+ * call. The returned `includeRuntimeContext` names those keys, which AI SDK otherwise withholds
+ * from telemetry; no other runtime-context value is recorded. An enclosing `withSpan`'s
+ * `userId` or `sessionId` takes precedence.
+ *
  * @throws TypeError when the client is enabled and the installed `ai` major version is below 7;
  * AI SDK 6 applications use `hueExperimentalTelemetry` from `@hue-run/sdk` instead.
+ * @throws TypeError when `userKey` or `sessionKey` names an empty key.
  */
-export function hueTelemetry(hue) {
+export function hueTelemetry(hue, options = {}) {
     // Core tracing also installs beside AI SDK 6. This adapter needs the v7 per-call
     // integration API, so fail explicitly during configuration instead of silently on v6.
     if (hue.enabled) {
@@ -36,10 +71,33 @@ export function hueTelemetry(hue) {
         if (major !== undefined && major < 7)
             throw new TypeError("hueTelemetry requires ai@7 or later; AI SDK 6 applications pass hueExperimentalTelemetry(hue) from @hue-run/sdk as experimental_telemetry");
     }
+    const userKeys = runtimeKeys(options.userKey ?? "userId", "userKey");
+    const sessionKeys = runtimeKeys(options.sessionKey ?? ["sessionId", "threadId"], "sessionKey");
+    const keys = [...new Set([...userKeys, ...sessionKeys])];
     return {
         isEnabled: hue.enabled,
         recordInputs: hue.captureContent,
         recordOutputs: hue.captureContent,
-        integrations: [new OpenTelemetry({ tracer: hue.tracer, usage: true })],
+        ...(keys.length
+            ? { includeRuntimeContext: Object.fromEntries(keys.map((key) => [key, true])) }
+            : {}),
+        integrations: [
+            new OpenTelemetry({
+                tracer: hue.tracer,
+                usage: true,
+                ...(keys.length
+                    ? {
+                        enrichSpan: ({ runtimeContext }) => {
+                            const user = firstIdentifier(runtimeContext, userKeys);
+                            const session = firstIdentifier(runtimeContext, sessionKeys);
+                            return {
+                                ...(user ? { "user.id": user } : {}),
+                                ...(session ? { "gen_ai.conversation.id": session } : {}),
+                            };
+                        },
+                    }
+                    : {}),
+            }),
+        ],
     };
 }

package/dist/cli/import-formats/adapter.d.ts

@@ -0,0 +1,80 @@
+import type { ConvertedTrace, Refusal, TraceImportFormat } from "../traces-import-convert.js";
+import type { IdentityKeys } from "./identity.js";
+import type { EventRow, SpanRow } from "./rows.js";
+/**
+ * The contract every import format implements; see `registry.ts` for how the formats are tried
+ * and how to add one.
+ */
+/** A source format `hue traces import prepare` reads. */
+export interface ImportAdapter {
+    /** The format's id: `hue.import.format` on every span it emits, the report's name for it and
+     * the namespace of the ids it derives. Lowercase, `[a-z0-9_]`. */
+    readonly id: string;
+    /** The format Hue's import registration knows the traces under (`source.formats` of the
+     * manifest). A format that emits canonical rows declares `otlp_json`, the encoding of the
+     * batches it writes, until Hue lists its own id. */
+    readonly manifestFormat: TraceImportFormat;
+    /** Whether a parsed JSON value is this format's: a whole document, one record of a JSON array,
+     * or one line of JSON Lines. Decided by distinctive top-level keys alone, never by a file name,
+     * and never claiming another format's value. */
+    detect(value: unknown): boolean;
+    /** Reads one value `detect` claimed. Rows, events and traces go to the context; a record that
+     * cannot be read is reported with `context.refuse` and the rest of the value is still read.
+     * Throwing a `ConversionError` reports the whole value as unreadable, with its message. */
+    convert(value: unknown, context: ConvertContext): void;
+}
+/** Where a record was read, for the report: never written to a span. */
+export interface Location {
+    file: string;
+    /** 1-based line of JSON Lines. */
+    line?: number;
+    /** 1-based position in a JSON array. */
+    record?: number;
+}
+/** Where a value was read, for the report: never written to a span. */
+export interface ValueSource {
+    /** The SHA-256 of the file's decoded content: the same for a renamed or recompressed copy. */
+    readonly digest: string;
+    /** The JSON text the value was parsed from: the document or the line (an array record has
+     * its re-serialized text). */
+    readonly text: string;
+    /** The UTF-8 size of `text`. */
+    readonly bytes: number;
+    /** Whether the text held an integer JavaScript cannot represent exactly; such an integer is
+     * kept as its decimal text in the parsed value. */
+    readonly unsafeIntegers: boolean;
+    /** The value's 1-based line, for JSON Lines. */
+    readonly line?: number;
+    /** The value's 0-based position, for a record of a JSON array. */
+    readonly index?: number;
+}
+/** Run-wide state a format gathers across files and lines; `finish` runs once all are read. */
+export interface TraceCollector {
+    finish(): {
+        traces: ConvertedTrace[];
+        refused: Refusal[];
+    };
+    /** Whether the traces it emits already carry `--user-key` and `--session-key`, as the shared
+     * row emitter writes them; otherwise the reader applies the keys to its traces. */
+    readonly appliesKeys?: boolean;
+}
+/** What a format's `convert` hands its results to. */
+export interface ConvertContext {
+    readonly source: ValueSource;
+    /** `--user-key` and `--session-key`, for a collector that emits rows itself. */
+    readonly keys: IdentityKeys;
+    /** Adds one canonical span row; rows are grouped into traces by `traceKey` across every file
+     * and line, and emitted as OTLP spans by the shared emitter (`rows.ts`). */
+    row(row: SpanRow): void;
+    /** Attaches an event (a log line, a message) to a span row by its trace and span keys. */
+    event(event: EventRow): void;
+    /** Adds a trace the format converted whole. */
+    trace(trace: ConvertedTrace): void;
+    /** Reports a record that could not be read. With the record's `traceKey`, that trace is
+     * refused whole and named; without one, the record alone is reported. */
+    refuse(reason: string, traceKey?: string): void;
+    /** This format's run-wide collector, created on first use by `create`. Formats that name the
+     * same `shared` key share one collector, so a trace whose spans they split between files is
+     * gathered as one; a shared collector names each trace's format itself. */
+    collector<T extends TraceCollector>(create: () => T, shared?: string): T;
+}

package/dist/cli/import-formats/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/import-formats/agent-events.d.ts

@@ -0,0 +1,5 @@
+import type { ImportAdapter } from "./adapter.js";
+/** Agent runtimes, event logs and plain chat transcripts: OpenAI Agents SDK traces, Raindrop
+ * events and span rows, Helicone request logs, and OpenAI chat, OpenAI Responses and Anthropic Messages
+ * transcripts. No two claim the same value, so their order here is free. */
+export declare const agentEventAdapters: readonly ImportAdapter[];

package/dist/cli/import-formats/agent-events.js

@@ -0,0 +1,16 @@
+import { helicone } from "./helicone.js";
+import { openaiAgents } from "./openai-agents.js";
+import { raindrop, raindropSpans } from "./raindrop.js";
+import { anthropicMessages, openaiChat, openaiResponses } from "./transcripts.js";
+/** Agent runtimes, event logs and plain chat transcripts: OpenAI Agents SDK traces, Raindrop
+ * events and span rows, Helicone request logs, and OpenAI chat, OpenAI Responses and Anthropic Messages
+ * transcripts. No two claim the same value, so their order here is free. */
+export const agentEventAdapters = [
+    openaiAgents,
+    raindrop,
+    raindropSpans,
+    helicone,
+    openaiChat,
+    openaiResponses,
+    anthropicMessages,
+];

package/dist/cli/import-formats/atif.d.ts

@@ -0,0 +1,3 @@
+import type { ImportAdapter } from "./adapter.js";
+/** Text ATIF v1.7 and v1.8 exports, one standalone document each, converted whole. */
+export declare const atif: ImportAdapter;

package/dist/cli/import-formats/atif.js

@@ -0,0 +1,15 @@
+import { ConversionError, convertAtifExport, isObject } from "../traces-import-convert.js";
+/** Text ATIF v1.7 and v1.8 exports, one standalone document each, converted whole. */
+export const atif = {
+    id: "atif",
+    manifestFormat: "atif",
+    detect: (value) => isObject(value) &&
+        typeof value.schema_version === "string" &&
+        value.schema_version.startsWith("ATIF-"),
+    convert(value, context) {
+        if (!isObject(value) || !Array.isArray(value.steps))
+            throw new ConversionError("an ATIF document without steps");
+        const { text, unsafeIntegers, bytes } = context.source;
+        context.trace(convertAtifExport({ text, document: value, unsafeIntegers }, bytes));
+    },
+};

package/dist/cli/import-formats/braintrust.d.ts

@@ -0,0 +1,2 @@
+import type { ImportAdapter } from "./adapter.js";
+export declare const braintrust: ImportAdapter;

package/dist/cli/import-formats/braintrust.js

@@ -0,0 +1,222 @@
+import { ConversionError, isObject, parseNestedJsonText, unixNano, } from "../traces-import-convert.js";
+import { identityText } from "./identity.js";
+import { metadataUser } from "./row-platform-fields.js";
+import { nanosFrom, readRecords } from "./rows.js";
+const isRow = (value) => isObject(value) && typeof value.span_id === "string" && typeof value.root_span_id === "string";
+/** The rows an envelope (`events` of a fetch, `data` of a query) holds, when it holds any. */
+function envelopeRows(value) {
+    if (!isObject(value))
+        return undefined;
+    for (const key of ["events", "data"])
+        if (Array.isArray(value[key]) && value[key].some(isRow))
+            return value[key];
+    return undefined;
+}
+const object = (value) => isObject(value) ? value : undefined;
+const text = (value) => typeof value === "string" && value ? value : undefined;
+const first = (fields, names) => {
+    for (const name of names) {
+        const value = identityText(fields?.[name]);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+};
+const SESSION_FIELDS = [
+    "session_id",
+    "sessionId",
+    "thread_id",
+    "threadId",
+    "conversation_id",
+    "conversationId",
+    "gen_ai.conversation.id",
+    "langgraph.thread_id",
+];
+const KINDS = { llm: "llm", tool: "tool" };
+/** Braintrust's own activity inside a trace (`SpanType` in its OpenAPI): scoring, not the
+ * agent's work. */
+const SCORING_TYPES = new Set([
+    "score",
+    "automation",
+    "facet",
+    "classifier",
+    "preprocessor",
+    "review",
+]);
+/** A token count Braintrust recorded, when it is a nonnegative integer. */
+const count = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+/** A Mastra tool span's input is the assistant message that requested it; its arguments are
+ * that call's. Any other input is the arguments as recorded. */
+function toolArguments(input) {
+    const message = Array.isArray(input) && input.length === 1 ? object(input[0]) : undefined;
+    const calls = message?.tool_calls;
+    const requested = Array.isArray(calls) && calls.length === 1 ? object(calls[0]) : undefined;
+    const fn = object(requested?.function);
+    if (!requested || !fn)
+        return input === undefined ? {} : { arguments: input };
+    let args = fn.arguments ?? null;
+    if (typeof args === "string")
+        try {
+            args = parseNestedJsonText(args).value;
+        }
+        catch {
+            // Arguments that are not JSON stay the text recorded.
+        }
+    return { arguments: args, ...(text(requested.id) ? { callId: text(requested.id) } : {}) };
+}
+/** A tool span's output as a tool message (`{role: "tool", content, tool_call_id}`) is read as
+ * its content. */
+function toolResult(output) {
+    const message = object(output);
+    if (message?.role === "tool" && "content" in message)
+        return {
+            result: message.content,
+            ...(text(message.tool_call_id) ? { callId: text(message.tool_call_id) } : {}),
+        };
+    return output === undefined ? {} : { result: output };
+}
+function readRow(record, context) {
+    const traceKey = text(record.root_span_id);
+    const spanKey = text(record.span_id);
+    if (!traceKey || !spanKey)
+        throw new ConversionError("a row without a span_id or root_span_id");
+    const parents = record.span_parents ?? [];
+    if (!Array.isArray(parents) || !parents.every((parent) => typeof parent === "string" && parent))
+        throw new ConversionError("span_parents is not a list of span ids");
+    const attributes = object(record.span_attributes);
+    if (record.span_attributes != null && !attributes)
+        throw new ConversionError("span_attributes is not an object");
+    const metadata = object(record.metadata);
+    if (record.metadata != null && !metadata)
+        throw new ConversionError("metadata is not an object");
+    const metrics = object(record.metrics);
+    if (record.metrics != null && !metrics)
+        throw new ConversionError("metrics is not an object");
+    const instant = (value) => value == null ? undefined : nanosFrom(value, "s");
+    let start = instant(metrics?.start);
+    const end = instant(metrics?.end);
+    let timing;
+    if (start === undefined && typeof record.created === "string") {
+        start = BigInt(unixNano(record.created));
+        timing = "start_from_created";
+    }
+    const type = text(attributes?.type);
+    const name = text(attributes?.name) ?? "span";
+    if (type === "log") {
+        context.event({
+            traceKey,
+            spanKey,
+            name: text(record.output) ?? name,
+            ...(start !== undefined ? { time: start } : {}),
+            ...(metadata ? { attributes: { "braintrust.metadata": JSON.stringify(metadata) } } : {}),
+            record,
+        });
+        return;
+    }
+    const context_ = object(record.context);
+    const origin = object(context_?.span_origin);
+    const instrumentation = text(object(origin?.instrumentation)?.name);
+    const environment = object(origin?.environment);
+    const mastra = instrumentation === "mastra" ||
+        metadata?.spanType !== undefined ||
+        metadata?.["mastra-trace-id"] !== undefined;
+    const openaiAgents = instrumentation === "openai-agents" || traceKey.startsWith("trace_");
+    const kind = type && Object.hasOwn(KINDS, type)
+        ? KINDS[type]
+        : mastra && metadata?.spanType === "agent_run"
+            ? "agent"
+            : undefined;
+    const error = record.error;
+    const scoring = attributes?.purpose === "scorer" || (type !== undefined && SCORING_TYPES.has(type));
+    const row = {
+        traceKey,
+        spanKey,
+        ...(scoring ? { scoring } : {}),
+        ...(parents[0] !== undefined ? { parentKey: parents[0] } : {}),
+        ...(parents.length > 1 ? { linkKeys: parents.slice(1) } : {}),
+        name,
+        ...(kind ? { kind } : {}),
+        ...(start !== undefined ? { start } : {}),
+        ...(end !== undefined ? { end } : {}),
+        ...(timing ? { timing } : {}),
+        ...(record.input !== undefined ? { input: record.input } : {}),
+        ...(record.output !== undefined ? { output: record.output } : {}),
+        record,
+        ...(metadata ? { metadata } : {}),
+        ...(text(record._xact_id) ? { revision: text(record._xact_id) } : {}),
+        attributes: {
+            ...(attributes ? { "braintrust.span_attributes": JSON.stringify(attributes) } : {}),
+            ...(metadata && Object.keys(metadata).length
+                ? { "braintrust.metadata": JSON.stringify(metadata) }
+                : {}),
+            ...(object(record.scores) ? { "braintrust.scores": JSON.stringify(record.scores) } : {}),
+            ...(Array.isArray(record.tags) && record.tags.every((tag) => typeof tag === "string")
+                ? { "braintrust.tags": record.tags }
+                : {}),
+        },
+    };
+    if (error !== undefined && error !== null && error !== false && error !== "")
+        row.error = {
+            message: typeof error === "string" ? error : (text(object(error)?.message) ?? JSON.stringify(error)),
+            ...(text(object(error)?.name) ? { type: text(object(error)?.name) } : {}),
+        };
+    if (kind === "llm") {
+        const model = text(metadata?.model);
+        const provider = text(metadata?.provider);
+        if (model)
+            row.model = model;
+        if (provider)
+            row.provider = provider;
+        row.usage = {
+            input: count(metrics?.prompt_tokens),
+            output: count(metrics?.completion_tokens),
+            cacheRead: count(metrics?.prompt_cached_tokens),
+            cacheWrite: count(metrics?.prompt_cache_creation_tokens),
+            reasoning: count(metrics?.completion_reasoning_tokens),
+        };
+    }
+    if (kind === "tool") {
+        const requested = toolArguments(record.input);
+        const returned = toolResult(record.output);
+        const quoted = /'([^']+)'\s*$/.exec(name)?.[1];
+        row.tool = {
+            name: text(metadata?.toolName) ?? text(metadata?.tool_name) ?? quoted ?? name,
+            ...(requested.arguments !== undefined ? { arguments: requested.arguments } : {}),
+            ...(returned.result !== undefined ? { result: returned.result } : {}),
+        };
+        const callId = text(metadata?.toolCallId) ??
+            text(metadata?.tool_call_id) ??
+            requested.callId ??
+            returned.callId;
+        if (callId)
+            row.tool.callId = callId;
+    }
+    else {
+        const user = metadataUser(metadata) ?? (mastra ? first(metadata, ["resourceId"]) : undefined);
+        const session = first(metadata, SESSION_FIELDS) ?? (openaiAgents ? first(metadata, ["group_id"]) : undefined);
+        if (user !== undefined)
+            row.user = user;
+        if (session !== undefined)
+            row.session = session;
+    }
+    if (text(record.experiment_id) || text(record.dataset_id))
+        row.origin = "evaluation";
+    // `vercel` and other platform names are where the code ran, not a deployment environment.
+    const environmentName = text(environment?.name);
+    if (environmentName === "production" || environmentName === "staging")
+        row.environment = environmentName;
+    context.row(row);
+}
+export const braintrust = {
+    id: "braintrust",
+    manifestFormat: "otlp_json",
+    detect: (value) => isRow(value) || envelopeRows(value) !== undefined,
+    convert(value, context) {
+        const records = isRow(value) ? [value] : (envelopeRows(value) ?? []);
+        readRecords(context, records, (record) => (isRow(record) ? text(record.root_span_id) : undefined), (record) => {
+            if (!isRow(record))
+                throw new ConversionError("a record that is not a Braintrust span row");
+            readRow(record, context);
+        });
+    },
+};

package/dist/cli/import-formats/containers.d.ts

@@ -0,0 +1,32 @@
+/** The file's content with its compression undone, and what of it could not be read; or why
+ * none of it can be. */
+export type Decoded = {
+    bytes: Uint8Array;
+    note?: string;
+} | {
+    unsupported: string;
+};
+/** The file's content with its compression undone, or why it cannot be read. `maxBytes` bounds
+ * the decompressed size. */
+export declare function decodeContainer(bytes: Uint8Array, maxBytes: number): Decoded;
+/** One JSON value read from a file: the whole document, or one line of JSON Lines. */
+export interface ParsedValue {
+    value: unknown;
+    /** The text it was parsed from. */
+    text: string;
+    unsafeIntegers: boolean;
+    /** Its 1-based line, for JSON Lines. */
+    line?: number;
+    /** A repair the value was read with, for the report. */
+    note?: string;
+}
+/** The JSON values of decoded content, the lines that are not JSON, or why none can be read. */
+export declare function parseValues(bytes: Uint8Array): {
+    values: ParsedValue[];
+    problems: {
+        line: number;
+        reason: string;
+    }[];
+} | {
+    unsupported: string;
+};