@hue-run/sdk 0.8.0 → 0.8.1

package/dist/client.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
 import { context, isSpanContextValid, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
 import { defaultTextMapGetter, defaultTextMapSetter } from "@opentelemetry/api";
 import { SeverityNumber } from "@opentelemetry/api-logs";
@@ -7,10 +8,12 @@ import { LoggerProvider } from "@opentelemetry/sdk-logs";
 import { TracerProvider } from "@opentelemetry/sdk-trace";
 import { defaultResource, resourceFromAttributes } from "@opentelemetry/resources";
 import { HUE_SCOPE } from "./config.js";
+import { hostedServerAddresses, hostedToolActivity, hostedToolProvider } from "./provider-tools.js";
 import { encodeContent, noopSpan, safeSpan } from "./safety.js";
 import { createHueTransport, HueExportError } from "./transport.js";
 import { verifyTrace } from "./receipt.js";
 import { sdkVersion } from "./version.js";
+import { MAX_FILE_DATA_BYTES } from "./config.js";
 /**
  * Thrown by {@link HueClient.checkConnection} and {@link HueClient.verifyTrace} when Hue cannot be
  * reached, rejects the project key or answers unexpectedly. The message is fixed and safe to log;
@@ -34,12 +37,28 @@ function identifier(value) {
         value.length > 4096 ||
         value.includes("\u0000") ||
         !value.isWellFormed())
-        throw new TypeError("Session/user identifiers must contain 1–4096 valid characters");
+        throw new TypeError("Session/user/workspace identifiers must contain 1–4096 valid characters");
     return value;
 }
 /** A usable metadata label: a non-blank string of at most 256 characters. */
 function isLabel(value) {
-    return typeof value === "string" && value.trim() !== "" && value.length <= 256;
+    return (typeof value === "string" &&
+        value.trim() !== "" &&
+        value.length <= 256 &&
+        !value.includes("\u0000") &&
+        value.isWellFormed());
+}
+/** A source label uses the stricter wire-safe validation without changing existing labels. */
+function isSourceLabel(value) {
+    return (typeof value === "string" &&
+        value.trim() !== "" &&
+        value.length <= 256 &&
+        !value.includes("\u0000") &&
+        value.isWellFormed());
+}
+/** A label that is also free of NUL and unpaired surrogates, which export would reject. */
+function isTextLabel(value) {
+    return isLabel(value) && !value.includes("\u0000") && value.isWellFormed();
 }
 /**
  * Runs `work` exactly once with `active` as OpenTelemetry's current context, so instrumentations
@@ -96,6 +115,7 @@ class ContextualTracer {
                     ...options.attributes,
                     ...(active?.sessionId ? { "gen_ai.conversation.id": active.sessionId } : {}),
                     ...(active?.userId ? { "user.id": active.userId } : {}),
+                    ...(active?.workspaceId ? { "hue.workspace.id": active.workspaceId } : {}),
                 },
             }, parent ?? active?.context ?? context.active()), this.failed);
         }
@@ -238,6 +258,7 @@ export class HueClient {
                     context: options.parentContext ?? inherited?.context ?? context.active(),
                     sessionId: identifier(options.sessionId ?? inherited?.sessionId),
                     userId: identifier(options.userId ?? inherited?.userId),
+                    workspaceId: identifier(options.workspaceId ?? inherited?.workspaceId),
                     model: inherited?.model,
                 };
                 span = this.storage.run(active, () => this.tracer.startSpan(name, { kind: options.kind ?? SpanKind.INTERNAL, attributes: options.attributes }, active.context));
@@ -301,18 +322,19 @@ export class HueClient {
      * `options.callId` is recorded as `gen_ai.tool.call.id`, like the Python `call_id=` keyword.
      * `options.mcp` records the MCP `initialize` `serverInfo` as `mcp.server.name` /
      * `mcp.server.version` so a generic tool name can be attributed to the server that
-     * handled it. Pass `client.getServerVersion()`.
+     * handled it. Pass `client.getServerVersion()`. `mcp.provider` / `mcp.surface` record the Hue
+     * provider and surface as `hue.mcp.provider` / `hue.mcp.surface`.
      */
     async tool(name, input, execute, options = {}) {
         const attributes = {
             "gen_ai.operation.name": "execute_tool",
             "gen_ai.tool.name": name,
         };
-        const stamp = (key, value) => {
+        const stamp = (key, value, valid = isLabel) => {
             if (value === undefined)
                 return;
             // A blank or non-string label is omitted and counted; the tool call itself still runs.
-            if (isLabel(value))
+            if (valid(value))
                 attributes[key] = value;
             else if (this.enabled && !this.closed)
                 this.transport.instrumentationFailure();
@@ -320,6 +342,8 @@ export class HueClient {
         stamp("gen_ai.tool.call.id", options.callId);
         stamp("mcp.server.name", options.mcp?.name);
         stamp("mcp.server.version", options.mcp?.version);
+        stamp("hue.mcp.provider", options.mcp?.provider, isSourceLabel);
+        stamp("hue.mcp.surface", options.mcp?.surface, isSourceLabel);
         return this.withSpan(`execute_tool ${name}`, async ({ span }) => {
             this.setContent(span, "gen_ai.tool.call.arguments", input);
             const result = await execute();
@@ -337,7 +361,8 @@ export class HueClient {
      * `gen_ai.request.model` and `gen_ai.provider.name`. The argument order matches `withSpan`. The
      * handle's `setInput`/`setOutput` record `gen_ai.input.messages` / `gen_ai.output.messages`,
      * which should use the GenAI semantic-convention message shape; `recordMessages` inside the
-     * callback inherits the request metadata.
+     * callback inherits the request metadata. `options.systemInstructions` and `options.tools` are
+     * recorded as `gen_ai.system_instructions` and `gen_ai.tool.definitions`, content like `input`.
      */
     async model(model, callback, options) {
         // A disabled or closed client creates no span, so invalid metadata is not an instrumentation
@@ -357,7 +382,7 @@ export class HueClient {
             ? `${operation} ${requestModel}`
             : label(options.name, `${operation} ${requestModel}`);
         const metadata = { operation, provider, requestModel };
-        const { sessionId, userId, parentContext, input } = options ?? {};
+        const { sessionId, userId, workspaceId, parentContext, input, systemInstructions, tools, } = options ?? {};
         return this.withSpan(name, (span) => {
             const handle = {
                 ...span,
@@ -366,12 +391,17 @@ export class HueClient {
             };
             if (input !== undefined)
                 handle.setInput(input);
+            if (systemInstructions !== undefined)
+                this.setContent(span.span, "gen_ai.system_instructions", systemInstructions);
+            if (tools !== undefined)
+                this.setContent(span.span, "gen_ai.tool.definitions", tools);
             // recordMessages inside the callback copies this request metadata onto its log record.
             const store = this.storage.getStore() ?? { context: span.context };
             return this.storage.run({ ...store, model: metadata }, () => callback(handle));
         }, {
             sessionId,
             userId,
+            workspaceId,
             parentContext,
             kind: SpanKind.CLIENT,
             attributes: {
@@ -462,6 +492,8 @@ export class HueClient {
                 body["gen_ai.input.messages"] = messages.input;
             if (messages.output !== undefined)
                 body["gen_ai.output.messages"] = messages.output;
+            if (messages.systemInstructions !== undefined)
+                body["gen_ai.system_instructions"] = messages.systemInstructions;
             // Request metadata is inherited only when the record correlates with the enclosing helper
             // scope; an unrelated explicit context carries caller-supplied values alone.
             const enclosing = explicitContext === undefined || explicitContext === store?.context ? store : undefined;
@@ -492,6 +524,166 @@ export class HueClient {
             this.transport.instrumentationFailure("logs");
         }
     }
+    /**
+     * Records the tools a model provider executed itself while producing `response`, which no
+     * `hue.tool()` call saw: OpenAI Responses `mcp_call`, `web_search_call`, `file_search_call` and
+     * `code_interpreter_call` items, and Anthropic Messages `mcp_tool_use` / `server_tool_use`
+     * blocks with their result blocks. Each becomes an `execute_tool {name}` child span of the active
+     * (or given) context with `gen_ai.tool.type` `extension` and `gen_ai.tool.call.id`; MCP calls add
+     * `mcp.server.name` (the provider's label, or the `servers` entry for it). Arguments and results
+     * follow `captureContent`; a failed call carries `error.type` and ERROR status. An OpenAI
+     * `mcp_list_tools` item becomes a `tools/list` child span carrying that server's tools as
+     * `gen_ai.tool.definitions`. Call it inside `hue.model()` so the spans nest under the model call
+     * and `provider` defaults to its provider; pass `request` to record each server's host as
+     * `server.address`. The spans have no duration of their own: the provider ran the tools inside
+     * the model request. Unreadable items are skipped and counted; nothing is thrown.
+     */
+    recordProviderToolCalls(response, options = {}) {
+        if (!this.enabled || this.closed)
+            return;
+        try {
+            const store = this.storage.getStore();
+            const provider = options.provider ?? hostedToolProvider(store?.model?.provider);
+            if (provider === undefined)
+                throw new TypeError("Unknown provider for hosted tool calls");
+            const parent = options.parentContext ?? store?.context ?? context.active();
+            const addresses = hostedServerAddresses(provider, options.request);
+            const activity = hostedToolActivity(provider, response);
+            if (activity.skipped > 0)
+                this.transport.instrumentationFailure("traces", undefined, activity.skipped);
+            const server = (label) => {
+                const attributes = {};
+                if (label === undefined)
+                    return attributes;
+                const info = options.servers?.[label];
+                for (const [key, value] of [
+                    ["mcp.server.name", info?.name ?? label],
+                    ["mcp.server.version", info?.version],
+                    ["hue.mcp.provider", info?.provider],
+                    ["hue.mcp.surface", info?.surface],
+                ]) {
+                    if (value === undefined)
+                        continue;
+                    if (isLabel(value))
+                        attributes[key] = value;
+                    else
+                        this.transport.instrumentationFailure();
+                }
+                const address = addresses.get(label);
+                if (address !== undefined)
+                    attributes["server.address"] = address;
+                return attributes;
+            };
+            const fail = (span, type) => {
+                span.setAttribute("error.type", type);
+                span.setStatus({ code: SpanStatusCode.ERROR });
+            };
+            for (const call of activity.calls) {
+                const span = this.tracer.startSpan(`execute_tool ${call.name}`, {
+                    kind: SpanKind.INTERNAL,
+                    attributes: {
+                        "gen_ai.operation.name": "execute_tool",
+                        "gen_ai.tool.name": call.name,
+                        "gen_ai.tool.type": "extension",
+                        ...(call.callId === undefined ? {} : { "gen_ai.tool.call.id": call.callId }),
+                        ...server(call.server),
+                    },
+                }, parent);
+                if (call.arguments !== undefined)
+                    this.setContent(span, "gen_ai.tool.call.arguments", call.arguments);
+                if (call.result !== undefined)
+                    this.setContent(span, "gen_ai.tool.call.result", call.result);
+                if (call.errorType !== undefined)
+                    fail(span, call.errorType);
+                span.end();
+            }
+            for (const listing of activity.listings) {
+                const span = this.tracer.startSpan("tools/list", {
+                    kind: SpanKind.INTERNAL,
+                    attributes: { "mcp.method.name": "tools/list", ...server(listing.server) },
+                }, parent);
+                this.setContent(span, "gen_ai.tool.definitions", listing.definitions);
+                if (listing.errorType !== undefined)
+                    fail(span, listing.errorType);
+                span.end();
+            }
+        }
+        catch {
+            this.transport.instrumentationFailure();
+        }
+    }
+    /**
+     * Adds a `hue.file` event to the active (or given) span for a file the work read, received or
+     * produced: `hue.file.sha256`, `hue.file.role`, `hue.file.media_type`, `hue.file.size` when known
+     * and, when `captureContent` is true, `hue.file.name`. `data` is hashed and measured locally and
+     * never exported. The event is metadata, so it is recorded in both capture modes. An invalid
+     * record, or one without an active span, is omitted and counted, never thrown; an invalid name
+     * alone is omitted and counted while the rest is recorded.
+     */
+    recordFile(file, explicitContext) {
+        if (!this.enabled || this.closed)
+            return;
+        try {
+            const span = trace.getSpan(explicitContext ?? this.storage.getStore()?.context ?? context.active());
+            if (!span?.isRecording())
+                throw new Error("File records require an active span");
+            const { role, mediaType, data, name } = file;
+            if (role !== "input" && role !== "attachment" && role !== "output")
+                throw new TypeError("Invalid file role");
+            if (!isTextLabel(mediaType))
+                throw new TypeError("Invalid media type");
+            let sha256 = typeof file.sha256 === "string" ? file.sha256.toLowerCase() : file.sha256;
+            let byteSize = file.byteSize;
+            if (data !== undefined) {
+                const bytes = typeof data === "string"
+                    ? (() => {
+                        // Buffer.byteLength measures UTF-8 without allocating the copy that hashing would
+                        // otherwise require. Reject before Buffer.from/createHash can retain large input.
+                        if (data.length > MAX_FILE_DATA_BYTES ||
+                            Buffer.byteLength(data, "utf8") > MAX_FILE_DATA_BYTES)
+                            throw new RangeError("File data exceeds Hue's 25 MiB limit");
+                        return Buffer.from(data, "utf8");
+                    })()
+                    : data instanceof Uint8Array
+                        ? data.byteLength <= MAX_FILE_DATA_BYTES
+                            ? data
+                            : (() => {
+                                throw new RangeError("File data exceeds Hue's 25 MiB limit");
+                            })()
+                        : undefined;
+                if (!bytes)
+                    throw new TypeError("File data must be bytes or a string");
+                const digest = createHash("sha256").update(bytes).digest("hex");
+                // A caller-supplied digest or size must describe the same bytes.
+                if ((sha256 !== undefined && sha256 !== digest) ||
+                    (byteSize !== undefined && byteSize !== bytes.byteLength))
+                    throw new TypeError("File digest or size does not match its data");
+                sha256 = digest;
+                byteSize = bytes.byteLength;
+            }
+            if (typeof sha256 !== "string" || !/^[0-9a-f]{64}$/.test(sha256))
+                throw new TypeError("A file needs a SHA-256 digest or its data");
+            if (byteSize !== undefined && (!Number.isSafeInteger(byteSize) || byteSize < 0))
+                throw new TypeError("Invalid file size");
+            const attributes = {
+                "hue.file.sha256": sha256,
+                "hue.file.role": role,
+                "hue.file.media_type": mediaType,
+            };
+            if (byteSize !== undefined)
+                attributes["hue.file.size"] = byteSize;
+            if (this.captureContent && name !== undefined) {
+                if (isTextLabel(name))
+                    attributes["hue.file.name"] = name;
+                else
+                    this.transport.instrumentationFailure();
+            }
+            span.addEvent("hue.file", attributes);
+        }
+        catch {
+            this.transport.instrumentationFailure();
+        }
+    }
     setContent(span, key, value) {
         if (!this.enabled || this.closed || !this.captureContent)
             return;

package/dist/config.d.ts

@@ -3,6 +3,8 @@ export declare const MAX_BODY_BYTES: number;
 export declare const MAX_CONTENT_BYTES: number;
 /** Instrumentation scope of the client's own tracer and logger. */
 export declare const HUE_SCOPE = "@hue-run/sdk";
+/** Maximum bytes accepted when recordFile hashes caller-provided data locally. */
+export declare const MAX_FILE_DATA_BYTES: number;
 /** Loopback hostnames that may use plain HTTP without opting in. */
 export declare function isLoopbackHost(hostname: string): boolean;
 /** True when a validated origin exports over plain HTTP to a host other than loopback. */

package/dist/config.js

@@ -2,6 +2,8 @@ export const MAX_BODY_BYTES = 1024 * 1024;
 export const MAX_CONTENT_BYTES = 256 * 1024;
 /** Instrumentation scope of the client's own tracer and logger. */
 export const HUE_SCOPE = "@hue-run/sdk";
+/** Maximum bytes accepted when recordFile hashes caller-provided data locally. */
+export const MAX_FILE_DATA_BYTES = 25 * 1024 * 1024;
 /** Loopback hostnames that may use plain HTTP without opting in. */
 export function isLoopbackHost(hostname) {
     return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";

package/dist/environment/tools.d.ts

@@ -29,7 +29,7 @@ export interface BindEnvironmentToolsOptions {
 /**
  * Binds a run's generated catalog to plain local callables without changing the agent
  * framework. Each call is recorded through {@link HueClient.tool}. Catalog entries that
- * include `mcp` stamp `mcp.server.name` / `mcp.server.version` so a generic verb is
- * attributed to that MCP server.
+ * include `mcp` stamp `mcp.server.name` / `mcp.server.version` and `hue.mcp.provider` /
+ * `hue.mcp.surface` so a generic verb is attributed to that MCP server and Hue surface.
  */
 export declare function bindEnvironmentTools(options: BindEnvironmentToolsOptions): Record<string, EnvironmentTool>;

package/dist/environment/tools.js

@@ -2,8 +2,8 @@ import { randomUUID } from "node:crypto";
 /**
  * Binds a run's generated catalog to plain local callables without changing the agent
  * framework. Each call is recorded through {@link HueClient.tool}. Catalog entries that
- * include `mcp` stamp `mcp.server.name` / `mcp.server.version` so a generic verb is
- * attributed to that MCP server.
+ * include `mcp` stamp `mcp.server.name` / `mcp.server.version` and `hue.mcp.provider` /
+ * `hue.mcp.surface` so a generic verb is attributed to that MCP server and Hue surface.
  */
 export function bindEnvironmentTools(options) {
     const tools = {};

package/dist/environment/types.d.ts

@@ -252,8 +252,9 @@ export interface ActionDefinition {
     /** Generated input contract. */
     inputSchema: ActionSchema;
     /**
-     * MCP `initialize` identity when this action is served by one MCP surface.
-     * Bound environment tools record it on the tool span as `mcp.server.name`.
+     * MCP `initialize` identity and Hue provider/surface when this action is served by one MCP
+     * surface. Bound environment tools record it on the tool span as `mcp.server.name`,
+     * `mcp.server.version`, `hue.mcp.provider` and `hue.mcp.surface`.
      */
     mcp?: McpServerInfo;
 }

package/dist/experimental-telemetry.d.ts

@@ -2,7 +2,8 @@ import type { HueClient } from "./client.js";
 import type { ExperimentalTelemetrySettings } from "./types.js";
 /**
  * Per-call telemetry for AI SDK 6: pass as `experimental_telemetry`. Spans are created with Hue's
- * tracer, so they parent under `withSpan` and inherit session/user identifiers, and prompt/response
- * recording follows `captureContent`. AI SDK 7 applications use `hueTelemetry` from `@hue-run/sdk/ai-sdk`.
+ * tracer, so they parent under `withSpan` and inherit session, user and workspace identifiers, and
+ * prompt/response recording follows `captureContent`. AI SDK 7 applications use `hueTelemetry`
+ * from `@hue-run/sdk/ai-sdk`.
  */
 export declare function hueExperimentalTelemetry(hue: HueClient): ExperimentalTelemetrySettings;

package/dist/experimental-telemetry.js

@@ -1,7 +1,8 @@
 /**
  * Per-call telemetry for AI SDK 6: pass as `experimental_telemetry`. Spans are created with Hue's
- * tracer, so they parent under `withSpan` and inherit session/user identifiers, and prompt/response
- * recording follows `captureContent`. AI SDK 7 applications use `hueTelemetry` from `@hue-run/sdk/ai-sdk`.
+ * tracer, so they parent under `withSpan` and inherit session, user and workspace identifiers, and
+ * prompt/response recording follows `captureContent`. AI SDK 7 applications use `hueTelemetry`
+ * from `@hue-run/sdk/ai-sdk`.
  */
 export function hueExperimentalTelemetry(hue) {
     return {

package/dist/inline-files.d.ts

@@ -0,0 +1,10 @@
+/** Inline file content larger than this many UTF-8 bytes is exported as its digest instead. */
+export declare const INLINE_FILE_LIMIT: number;
+/**
+ * Replaces inline files longer than {@link INLINE_FILE_LIMIT} in a recorded message attribute
+ * with their SHA-256 and byte size, so a span that inlines a large file exports the file's
+ * identity instead of being rejected for its size. The part keeps its other fields (`type`,
+ * `mime_type`, `modality`, `mediaType`, …). Other attributes, shorter messages and values that
+ * are not JSON are returned unchanged.
+ */
+export declare function hashInlineFiles(key: string, value: unknown): unknown;

package/dist/inline-files.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import { MAX_BODY_BYTES } from "./config.js";
+/** Inline file content larger than this many UTF-8 bytes is exported as its digest instead. */
+export const INLINE_FILE_LIMIT = 64 * 1024;
+const MAX_INLINE_FILE_TEXT = 8 * MAX_BODY_BYTES;
+/** Message attributes whose JSON can inline files: GenAI blob parts and AI SDK 6 file parts. */
+const messageKeys = new Set([
+    "gen_ai.input.messages",
+    "gen_ai.output.messages",
+    "ai.prompt.messages",
+]);
+/** Strict base64: alphabet characters only, padded to a multiple of four. */
+const base64 = /^[A-Za-z0-9+/]*={0,2}$/;
+const base64DataUrl = /^data:[^,]*;base64,/;
+function binaryMimeType(value) {
+    return (typeof value === "string" &&
+        !/^text\//i.test(value) &&
+        value.toLowerCase() !== "application/json");
+}
+/**
+ * The bytes an inline file part carries: base64 (plain or as a `data:` URL) is decoded, and
+ * anything else, such as a text file's content, is taken as UTF-8.
+ */
+function fileBytes(content, mimeType) {
+    const prefix = base64DataUrl.exec(content)?.[0].length ?? 0;
+    const payload = content.slice(prefix);
+    return (prefix > 0 || binaryMimeType(mimeType)) &&
+        payload.length % 4 === 0 &&
+        base64.test(payload)
+        ? Buffer.from(payload, "base64")
+        : Buffer.from(content, "utf8");
+}
+/** The key holding a part's inline content: GenAI `blob` parts and AI SDK 6 `file` parts. */
+function contentKey(part) {
+    return part.type === "blob" ? "content" : part.type === "file" ? "data" : undefined;
+}
+function hashNode(value, state, depth) {
+    if (depth > 256)
+        throw new Error("Message exceeds the supported nesting limit");
+    if (Array.isArray(value))
+        return value.map((item) => hashNode(item, state, depth + 1));
+    if (value === null || typeof value !== "object")
+        return value;
+    const part = value;
+    const key = contentKey(part);
+    const inline = key === undefined ? undefined : part[key];
+    const mimeType = part.mime_type ?? part.mediaType;
+    if (key !== undefined && typeof inline === "string") {
+        const bytes = fileBytes(inline, mimeType);
+        if (bytes.byteLength > INLINE_FILE_LIMIT) {
+            const { [key]: _omitted, ...rest } = part;
+            state.changed = true;
+            return {
+                ...rest,
+                sha256: createHash("sha256").update(bytes).digest("hex"),
+                size: bytes.byteLength,
+            };
+        }
+    }
+    return Object.fromEntries(Object.entries(part).map(([name, item]) => [name, hashNode(item, state, depth + 1)]));
+}
+/**
+ * Replaces inline files longer than {@link INLINE_FILE_LIMIT} in a recorded message attribute
+ * with their SHA-256 and byte size, so a span that inlines a large file exports the file's
+ * identity instead of being rejected for its size. The part keeps its other fields (`type`,
+ * `mime_type`, `modality`, `mediaType`, …). Other attributes, shorter messages and values that
+ * are not JSON are returned unchanged.
+ */
+export function hashInlineFiles(key, value) {
+    if (!messageKeys.has(key) ||
+        typeof value !== "string" ||
+        Buffer.byteLength(value, "utf8") <= INLINE_FILE_LIMIT ||
+        Buffer.byteLength(value, "utf8") > MAX_INLINE_FILE_TEXT ||
+        !(value.includes('"blob"') || value.includes('"file"')))
+        return value;
+    try {
+        const parsed = JSON.parse(value);
+        const state = { changed: false };
+        const hashed = hashNode(parsed, state, 0);
+        return state.changed ? JSON.stringify(hashed) : value;
+    }
+    catch {
+        // Not JSON, or nested too deeply to inspect: export decides the value's fate as before.
+        return value;
+    }
+}

package/dist/privacy.js

@@ -1,5 +1,8 @@
+import { SpanStatusCode } from "@opentelemetry/api";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { MAX_BODY_BYTES, MAX_CONTENT_BYTES } from "./config.js";
+import { scrubToolCredentials, withToolCatalogSummary } from "./tool-definitions.js";
+import { hashInlineFiles } from "./inline-files.js";
 /** Attribute keys (and their dotted children) removed in metadata-only mode. */
 export const contentPrefixes = [
     "gen_ai.input.messages",
@@ -95,9 +98,16 @@ function redactValue(value, path, options, budget, depth = 0) {
     return value;
 }
 function attributes(source, options, path, budget) {
-    return Object.fromEntries(Object.entries(source).flatMap(([key, value]) => !options.captureContent && isContentKey(key)
+    // Metadata-only export summarizes the tool definitions it removes by name and digest.
+    const summarized = options.captureContent ? source : withToolCatalogSummary(source);
+    return Object.fromEntries(Object.entries(summarized).flatMap(([key, value]) => !options.captureContent && isContentKey(key)
         ? []
-        : [[key, redactValue(value, `${path}.${key}`, options, budget)]]));
+        : [
+            [
+                key,
+                redactValue(scrubToolCredentials(key, hashInlineFiles(key, value)), `${path}.${key}`, options, budget),
+            ],
+        ]));
 }
 function redactResource(resource, options, cache, budget) {
     let result = cache.get(resource);
@@ -107,8 +117,43 @@ function redactResource(resource, options, cache, budget) {
     }
     return result;
 }
+/**
+ * Server identity and failure of an AI SDK 7 provider-executed (`extension`) tool span, read from
+ * its recorded result before content is stripped. OpenAI hosted MCP results carry
+ * `{ type: "call", serverLabel, name, arguments, output?, error? }`; nothing else names the server.
+ */
+function hostedMcpCall(attributes) {
+    const result = attributes["gen_ai.tool.call.result"];
+    if (attributes["gen_ai.tool.type"] !== "extension" || typeof result !== "string")
+        return { failed: false };
+    let parsed;
+    try {
+        parsed = JSON.parse(result);
+    }
+    catch {
+        return { failed: false };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return { failed: false };
+    const { type, serverLabel, error } = parsed;
+    if (type !== "call")
+        return { failed: false };
+    const valid = typeof serverLabel === "string" &&
+        serverLabel.trim() !== "" &&
+        serverLabel.length <= 256 &&
+        !serverLabel.includes("\u0000") &&
+        serverLabel.isWellFormed();
+    return { ...(valid ? { serverName: serverLabel } : {}), failed: error != null };
+}
 export function redactSpan(span, options, cache) {
     const budget = { bytes: 0, nodes: 0 };
+    // Derived before metadata-only stripping so the identity survives without the result itself.
+    const hosted = hostedMcpCall(span.attributes);
+    const source = {
+        ...(hosted.serverName === undefined ? {} : { "mcp.server.name": hosted.serverName }),
+        ...(hosted.failed ? { "error.type": "mcp_error" } : {}),
+        ...span.attributes,
+    };
     return {
         name: span.name,
         kind: span.kind,
@@ -119,12 +164,16 @@ export function redactSpan(span, options, cache) {
         duration: span.duration,
         ended: span.ended,
         status: {
-            code: span.status.code,
-            ...(options.captureContent && span.status.message !== undefined
+            code: hosted.failed && span.status.code === SpanStatusCode.UNSET
+                ? SpanStatusCode.ERROR
+                : span.status.code,
+            ...(options.captureContent &&
+                span.status.message !== undefined &&
+                !(hosted.failed && span.status.code === SpanStatusCode.UNSET)
                 ? { message: String(redactValue(span.status.message, "status.message", options, budget)) }
                 : {}),
         },
-        attributes: attributes(span.attributes, options, "attributes", budget),
+        attributes: attributes(source, options, "attributes", budget),
         events: span.events
             .filter((event) => options.captureContent ||
             !/^gen_ai\.(?:system|user|assistant|tool|choice)/.test(event.name))

package/dist/provider-tools.d.ts

@@ -0,0 +1,39 @@
+import type { HostedToolProvider } from "./types.js";
+/** One provider-executed tool call. `arguments` and `result` are content. */
+export interface HostedToolCall {
+    name: string;
+    callId?: string;
+    /** The provider's label (OpenAI `server_label`) or name (Anthropic `server_name`) for the MCP server. */
+    server?: string;
+    arguments?: unknown;
+    result?: unknown;
+    /** Low-cardinality failure marker for `error.type`; absent when the call succeeded. */
+    errorType?: string;
+}
+/** One `mcp_list_tools` result: the tools a hosted MCP server offered. */
+export interface HostedToolListing {
+    server: string;
+    /** Tool definitions in the OpenTelemetry GenAI shape (`type`, `name`, `description`, `parameters`). */
+    definitions: Record<string, unknown>[];
+    errorType?: string;
+}
+export interface HostedToolActivity {
+    calls: HostedToolCall[];
+    listings: HostedToolListing[];
+    /** Items that looked like hosted calls but could not be read. */
+    skipped: number;
+}
+/**
+ * Reads the hosted tool calls out of a provider response: the `output` items of an OpenAI
+ * Responses API response, or the `content` blocks of an Anthropic Messages API response. An array
+ * is taken as those items directly. Anything else yields no calls.
+ */
+export declare function hostedToolActivity(provider: HostedToolProvider, response: unknown): HostedToolActivity;
+/**
+ * The host of each hosted MCP server's URL, by label, read from the request that produced the
+ * response: OpenAI `tools[].server_url` by `server_label`, Anthropic `mcp_servers[].url` by `name`.
+ * Nothing else in the request is read.
+ */
+export declare function hostedServerAddresses(provider: HostedToolProvider, request: unknown): Map<string, string>;
+/** The provider a `model()` call named, when this module can read its responses. */
+export declare function hostedToolProvider(value: unknown): HostedToolProvider | undefined;