@hue-run/sdk 0.7.0 → 0.8.1

package/dist/tool-definitions.js

@@ -0,0 +1,274 @@
+import { createHash } from "node:crypto";
+import { MAX_BODY_BYTES } from "./config.js";
+/** Replaces a hosted-tool credential found in an exported tool definition. */
+const REDACTED = "[redacted]";
+/**
+ * Credential keys, compared case-insensitively and ignoring `-` and `_`: OpenAI hosted MCP
+ * `authorization` and `headers`, Anthropic MCP `authorization_token`, and common API key fields.
+ * Keep this list deliberately broad: provider tool schemas are untrusted input and providers use
+ * generic names such as `token`, `secret`, and `password` for hosted credentials.
+ */
+const credentialKeys = new Set([
+    "authorization",
+    "authorizationtoken",
+    "headers",
+    "apikey",
+    "accesstoken",
+    "xapikey",
+    "token",
+    "refreshtoken",
+    "clientsecret",
+    "password",
+    "secret",
+    "credential",
+    "credentials",
+]);
+/** URL-valued fields in hosted tool and MCP-server definitions can carry credentials in userinfo
+ * or query parameters. Query values are all replaced because a provider may use an arbitrary key
+ * for its credential and guessing which names are sensitive would leave a leak. */
+function isUrlKey(key) {
+    const normalized = key.toLowerCase().replace(/[-_]/g, "");
+    return normalized === "serverurl" || normalized === "url";
+}
+function scrubUrl(value, state) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        // A malformed URL may still contain a credential. Do not export an opaque URL-valued
+        // string when it cannot be parsed safely.
+        state.changed = true;
+        return REDACTED;
+    }
+    let changed = false;
+    if (url.username || url.password) {
+        url.username = "";
+        url.password = "";
+        changed = true;
+    }
+    if (url.search) {
+        const keys = Array.from(url.searchParams.keys());
+        const scrubbed = new URLSearchParams();
+        for (const key of keys)
+            scrubbed.append(key, REDACTED);
+        url.search = scrubbed.toString();
+        changed = true;
+    }
+    if (url.hash) {
+        url.hash = "";
+        changed = true;
+    }
+    if (changed)
+        state.changed = true;
+    return changed ? url.toString() : value;
+}
+function isCredentialKey(key) {
+    const normalized = key.toLowerCase().replace(/[-_]/g, "");
+    return (credentialKeys.has(normalized) ||
+        normalized.endsWith("token") ||
+        normalized.endsWith("secret") ||
+        normalized.endsWith("password") ||
+        normalized.endsWith("apikey") ||
+        normalized.endsWith("credential"));
+}
+/** OpenInference records each tool as `llm.tools.{index}.tool.json_schema`. */
+const openInferenceTool = /^llm\.tools\.(\d+)\.tool\.json_schema$/;
+/**
+ * Replaces the value of every credential key at any depth. Keys directly inside a JSON Schema
+ * `properties` object name tool parameters (a tool may take a `headers` argument), so their
+ * schemas are kept and scrubbed like any other value.
+ */
+function scrubNode(value, state, depth, parameters, credentialParameter = false) {
+    if (depth > 256)
+        throw new Error("Tool definition exceeds the supported nesting limit");
+    if (Array.isArray(value))
+        return value.map((item) => scrubNode(item, state, depth + 1, false, credentialParameter));
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => {
+        if (credentialParameter && ["examples", "enum"].includes(key)) {
+            state.changed = true;
+            return [key, Array.isArray(item) ? item.map(() => REDACTED) : REDACTED];
+        }
+        if (credentialParameter && ["default", "const"].includes(key)) {
+            state.changed = true;
+            return [key, REDACTED];
+        }
+        if (!parameters && item !== null && isCredentialKey(key)) {
+            state.changed = true;
+            return [key, REDACTED];
+        }
+        if (!parameters && typeof item === "string" && isUrlKey(key))
+            return [key, scrubUrl(item, state)];
+        return [
+            key,
+            scrubNode(item, state, depth + 1, key === "properties", key === "properties"
+                ? false
+                : credentialParameter || (parameters && isCredentialKey(key))),
+        ];
+    }));
+}
+/**
+ * Parses JSON text, returning `undefined` for text that is not JSON. Oversized text is parsed too:
+ * the caller's `redact` runs afterwards and may shorten it enough to export.
+ */
+function parse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return undefined;
+        throw error;
+    }
+}
+/** A JSON-encoded tool definition, or list of them, with its credentials replaced. */
+function scrubDefinitionText(text) {
+    const parsed = parse(text);
+    if (parsed === null || typeof parsed !== "object")
+        return text;
+    const state = { changed: false };
+    const scrubbed = scrubNode(parsed, state, 0, false);
+    return state.changed ? JSON.stringify(scrubbed) : text;
+}
+/**
+ * A raw provider request or response recorded as JSON (OpenInference `input.value`,
+ * `output.value` and `llm.invocation_parameters`), with credentials replaced in its `tools` and
+ * `mcp_servers` entries only; nothing else in the value changes.
+ */
+function scrubRequestText(text) {
+    if (!text.includes('"tools"') && !text.includes('"mcp_servers"'))
+        return text;
+    const parsed = parse(text);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return text;
+    const state = { changed: false };
+    const request = { ...parsed };
+    for (const field of ["tools", "mcp_servers"])
+        if (request[field] !== null && typeof request[field] === "object")
+            request[field] = scrubNode(request[field], state, 0, false);
+    return state.changed ? JSON.stringify(request) : text;
+}
+/**
+ * Removes hosted-tool credentials from an exported attribute value, before the caller's `redact`.
+ * Tool definitions come from OpenTelemetry GenAI (`gen_ai.tool.definitions`), AI SDK 6
+ * (`ai.prompt.tools`, one JSON string per tool) and OpenInference (`llm.tools.{i}.tool.json_schema`,
+ * plus the raw request in `input.value`). Other attributes, and values that are not JSON, are
+ * returned unchanged. Metadata-only export removes all of these attributes anyway.
+ *
+ * @throws Error when a tool definition is nested too deeply to inspect; the record is then
+ * rejected rather than exported with credentials.
+ */
+export function scrubToolCredentials(key, value) {
+    const scrub = key === "gen_ai.tool.definitions" || key === "ai.prompt.tools" || openInferenceTool.test(key)
+        ? scrubDefinitionText
+        : key === "input.value" || key === "output.value" || key === "llm.invocation_parameters"
+            ? scrubRequestText
+            : undefined;
+    if (!scrub)
+        return value;
+    if (typeof value === "string")
+        return scrub(value);
+    if (Array.isArray(value))
+        return value.map((item) => (typeof item === "string" ? scrub(item) : item));
+    return value;
+}
+/** A usable tool name: non-blank, at most 256 characters, well-formed and free of NUL. */
+function isName(value) {
+    return (typeof value === "string" &&
+        value.trim() !== "" &&
+        value.length <= 256 &&
+        !value.includes("\u0000") &&
+        value.isWellFormed());
+}
+/**
+ * A definition's name: `name` (GenAI, AI SDK, Responses and Anthropic tools), else Chat
+ * Completions' `function.name`, else the `type` of an unnamed built-in tool such as `mcp`.
+ */
+function toolName(definition) {
+    if (definition === null || typeof definition !== "object" || Array.isArray(definition))
+        return undefined;
+    const { name, function: fn, type } = definition;
+    const nested = fn !== null && typeof fn === "object" ? fn.name : undefined;
+    return [name, nested, type].find(isName);
+}
+/**
+ * Parses JSON-encoded definitions; `undefined` unless every element is a JSON object or array.
+ * Like the Python SDK, which parses on the application thread, definitions longer than one
+ * export request are not parsed, so both SDKs summarize the same records.
+ */
+function parseDefinitions(texts) {
+    const length = texts.reduce((total, text) => total + (typeof text === "string" ? Buffer.byteLength(text, "utf8") : 0), 0);
+    if (length > MAX_BODY_BYTES)
+        return undefined;
+    const parsed = texts.map((text) => (typeof text === "string" ? parse(text) : undefined));
+    return parsed.every((item) => item !== null && typeof item === "object") ? parsed : undefined;
+}
+/**
+ * The tool definitions a record carries, in order: `gen_ai.tool.definitions` (one JSON list),
+ * else AI SDK 6 `ai.prompt.tools` (one JSON string per tool), else OpenInference
+ * `llm.tools.{i}.tool.json_schema` ordered by index.
+ */
+function definitionsOf(source) {
+    const definitions = source["gen_ai.tool.definitions"];
+    if (definitions !== undefined) {
+        const parsed = parseDefinitions([definitions])?.[0];
+        return parsed === undefined ? undefined : Array.isArray(parsed) ? parsed : [parsed];
+    }
+    const promptTools = source["ai.prompt.tools"];
+    if (promptTools !== undefined)
+        return parseDefinitions(Array.isArray(promptTools) ? promptTools : [promptTools]);
+    const indexed = Object.entries(source)
+        .flatMap(([key, value]) => {
+        const match = openInferenceTool.exec(key);
+        return match ? [[Number(match[1]), value]] : [];
+    })
+        .sort(([left], [right]) => left - right);
+    return indexed.length ? parseDefinitions(indexed.map(([, value]) => value)) : undefined;
+}
+/**
+ * RFC 8785 (JCS) canonical JSON: object keys sorted by UTF-16 code units, no whitespace, and
+ * ECMAScript number and string serialization. The Python SDK produces the same text.
+ */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        const members = Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`);
+        return `{${members.join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+/**
+ * Metadata-only summary of the tool definitions a record carries, which export then removes:
+ * `hue.tool.names` lists each definition's name in order, and `hue.tool.definitions.sha256` is
+ * the lowercase hex SHA-256 of the RFC 8785 canonical JSON of the credential-scrubbed definition
+ * list, so the same catalog has the same digest in both SDKs and across credential rotation.
+ * Returns the source unchanged when it has no parseable definitions; attributes the source
+ * already sets are kept.
+ */
+export function withToolCatalogSummary(source) {
+    let summary;
+    try {
+        const definitions = definitionsOf(source);
+        if (definitions === undefined)
+            return source;
+        const scrubbed = scrubNode(definitions, { changed: false }, 0, false);
+        const names = definitions.map(toolName).filter((name) => name !== undefined);
+        summary = {
+            ...(names.length ? { "hue.tool.names": names } : {}),
+            "hue.tool.definitions.sha256": createHash("sha256")
+                .update(canonicalJson(scrubbed), "utf8")
+                .digest("hex"),
+        };
+    }
+    catch {
+        // Metadata-only export removes the definitions whether or not they can be summarized.
+        return source;
+    }
+    return { ...summary, ...source };
+}

package/dist/transport.js

@@ -339,8 +339,10 @@ export class HueTransport {
         }
     }
     /** @internal Counts a helper capture or instrumentation failure that preserved application execution. */
-    instrumentationFailure(signal = "traces", message = "Telemetry capture or instrumentation failed; application execution was preserved") {
-        this.instrumentationFailures++;
+    instrumentationFailure(signal = "traces", message = "Telemetry capture or instrumentation failed; application execution was preserved", count = 1) {
+        if (!Number.isSafeInteger(count) || count < 1)
+            return;
+        this.instrumentationFailures += count;
         this.issue(signal, "invalid", 0, message);
     }
     /** Cumulative counters and current queue gauges. */

package/dist/types.d.ts

@@ -139,20 +139,30 @@ export interface SpanOptions {
     sessionId?: string;
     /** Recorded as `user.id` on this span and inherited by nested helper spans. */
     userId?: string;
+    /**
+     * The application workspace or tenant the work runs in, recorded as `hue.workspace.id` on this
+     * span and inherited by nested helper spans.
+     */
+    workspaceId?: string;
     /** Recorded as `input.value` when `captureContent` is true; any JSON-encodable value. */
     input?: unknown;
     /** Explicit parent context, for example from {@link HueClient.extract}. */
     parentContext?: Context;
 }
 /**
- * MCP `initialize` `serverInfo` for {@link HueClient.tool}. Pass
- * `client.getServerVersion()` after connect; any MCP server works.
+ * MCP `initialize` `serverInfo` for {@link HueClient.tool}, plus the Hue provider and surface
+ * when the tool came from one. Pass `client.getServerVersion()` after connect; any MCP server
+ * works.
  */
 export interface McpServerInfo {
     /** `serverInfo.name` from MCP initialize, recorded as `mcp.server.name`. */
     name?: string;
     /** `serverInfo.version` from MCP initialize, recorded as `mcp.server.version`. */
     version?: string;
+    /** Hue provider id such as `google.gmail`, recorded as `hue.mcp.provider`. */
+    provider?: string;
+    /** Hue surface such as `google.gmail/mcp`, recorded as `hue.mcp.surface`. */
+    surface?: string;
 }
 /**
  * Options for {@link HueClient.tool}. `callId` is the provider-issued tool-call
@@ -168,6 +178,57 @@ export interface ToolOptions extends Pick<SpanOptions, "parentContext"> {
      */
     mcp?: McpServerInfo;
 }
+/** Providers whose hosted tool calls {@link HueClient.recordProviderToolCalls} can read. */
+export type HostedToolProvider = "openai" | "anthropic";
+/** Identity of a hosted MCP server, keyed by the label the provider uses for it. */
+export interface HostedServerInfo {
+    /** Server name recorded as `mcp.server.name`; defaults to the provider's label. */
+    name?: string;
+    /** Server version recorded as `mcp.server.version`. */
+    version?: string;
+    /** Hue provider id such as `google.gmail`, recorded as `hue.mcp.provider`. */
+    provider?: string;
+    /** Hue surface such as `google.gmail/mcp`, recorded as `hue.mcp.surface`. */
+    surface?: string;
+}
+/** Options for {@link HueClient.recordProviderToolCalls}. */
+export interface ProviderToolCallOptions extends Pick<SpanOptions, "parentContext"> {
+    /**
+     * `openai` (Responses API) or `anthropic` (Messages API). Defaults to the enclosing `model()`
+     * call's `provider` when it is one of these.
+     */
+    provider?: HostedToolProvider;
+    /**
+     * The request the response answers. Only hosted MCP server URLs are read from it (OpenAI
+     * `tools[].server_url` by `server_label`, Anthropic `mcp_servers[].url` by `name`), to record
+     * each server's host as `server.address`.
+     */
+    request?: unknown;
+    /** Identity of each hosted MCP server, by the label the provider uses for it. */
+    servers?: Record<string, HostedServerInfo>;
+}
+/**
+ * A file the traced work read, received or produced, for {@link HueClient.recordFile}. Files are
+ * linked by content hash; their bytes are never exported.
+ */
+export interface FileRecord {
+    /**
+     * `input` was given to the agent, `attachment` arrived from a tool or message, and `output` was
+     * produced by the agent.
+     */
+    role: "input" | "attachment" | "output";
+    /** Media type, for example `application/pdf`. */
+    mediaType: string;
+    /** Hex SHA-256 of the file's bytes; computed from `data` when omitted. */
+    sha256?: string;
+    /** The file's bytes, only hashed and measured, never exported; a string is hashed as UTF-8.
+     * Data larger than 25 MiB is omitted and counted as an instrumentation failure. */
+    data?: Uint8Array | string;
+    /** Size in bytes; computed from `data` when omitted. */
+    byteSize?: number;
+    /** File name, recorded as `hue.file.name` only when `captureContent` is true. */
+    name?: string;
+}
 /** Provider-reported token counts for {@link HueSpan.setUsage}. */
 export interface TokenUsage {
     /** Provider-reported prompt tokens (`gen_ai.usage.input_tokens`). */
@@ -179,13 +240,25 @@ export interface TokenUsage {
  * Options for {@link HueClient.model}: GenAI request metadata plus the {@link SpanOptions} that
  * apply to a client span. `input` is recorded as `gen_ai.input.messages`.
  */
-export interface ModelOptions extends Pick<SpanOptions, "sessionId" | "userId" | "input" | "parentContext"> {
+export interface ModelOptions extends Pick<SpanOptions, "sessionId" | "userId" | "workspaceId" | "input" | "parentContext"> {
     /** Provider identifier recorded as `gen_ai.provider.name`, for example "openai". */
     provider: string;
     /** Recorded as `gen_ai.operation.name`; defaults to "chat". */
     operation?: string;
     /** Span name; defaults to "{operation} {model}". */
     name?: string;
+    /**
+     * System instructions sent separately from the chat history, recorded as
+     * `gen_ai.system_instructions` when `captureContent` is true. Any JSON-encodable value, ideally
+     * GenAI semantic-convention parts such as `[{ type: "text", content: "..." }]`.
+     */
+    systemInstructions?: unknown;
+    /**
+     * Tool definitions offered to the model, recorded as `gen_ai.tool.definitions` when
+     * `captureContent` is true. Any JSON-encodable value, ideally the GenAI shape
+     * `[{ type: "function", name, description, parameters }]`.
+     */
+    tools?: unknown;
 }
 /** Value for AI SDK 6's `experimental_telemetry` option; AI SDK 7 uses `hueTelemetry` instead. */
 export interface ExperimentalTelemetrySettings {

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

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

package/package.json

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