@hue-run/sdk 0.7.0 → 0.8.1

package/dist/evals/local-worker.js

@@ -31,11 +31,16 @@ function localAgentTargetContext(context) {
         executionId: context.executionId,
         environmentRunId: context.environmentRunId,
         trace: { traceId: context.trace.traceId, spanId: context.trace.spanId },
-        mcp: {
-            url: context.mcp.url,
-            token: context.mcp.token,
-            expiresAt: context.mcp.expiresAt,
-        },
+        ...(context.world ? { world: structuredClone(context.world) } : {}),
+        ...(context.mcp
+            ? {
+                mcp: {
+                    url: context.mcp.url,
+                    token: context.mcp.token,
+                    expiresAt: context.mcp.expiresAt,
+                },
+            }
+            : {}),
         ...(context.connectionBundle
             ? { connectionBundle: structuredClone(context.connectionBundle) }
             : {}),
@@ -178,6 +183,9 @@ export async function runLocalAgent(options) {
                             inputs,
                             context,
                             requested,
+                            // The registered revision is the agent revision under test.
+                            agentRevision: options.agent.revision,
+                            deprecationWarnings: options.deprecationWarnings,
                             signal: options.signal,
                             target: (targetInputs, targetContext) => target(structuredClone(targetInputs), targetContext.tools, localAgentTargetContext(targetContext)),
                         });

package/dist/evals/runner.d.ts

@@ -50,7 +50,7 @@ interface RunnerOptions {
      * (for example a Hue-operated grading worker that owns the evaluator source) instead of
      * refusing the run. Their IDs are reported in `deferredScorerVersionIds`. */
     deferUnboundLocalScorers?: boolean;
-    /** Cases in flight at once, 1–16. Default 1. */
+    /** Cases in flight at once, 1–64. Default 1. */
     concurrency?: number;
     /** Deadline for JSON Schema scoring in its worker, 100–60000 ms. Default 2000. */
     schemaTimeoutMillis?: number;

package/dist/evals/runner.js

@@ -80,8 +80,8 @@ function settings(options) {
     if (typeof options.persistResultContent !== "boolean")
         throw new TypeError("Choose persistResultContent explicitly: true or false");
     const concurrency = options.concurrency ?? 1;
-    if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 16)
-        throw new RangeError("concurrency must be 1–16");
+    if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 64)
+        throw new RangeError("concurrency must be 1–64");
     const timeout = options.schemaTimeoutMillis ?? 2000;
     if (!Number.isInteger(timeout) || timeout < 100 || timeout > 60_000)
         throw new RangeError("schemaTimeoutMillis must be 100–60000");

package/dist/evals/simulation.d.ts

@@ -1,7 +1,7 @@
 import type { HueClient } from "../client.js";
 import { type EnvironmentClient } from "../environment/client.js";
 import type { EnvironmentTool } from "../environment/tools.js";
-import type { EnvironmentIdentity, PublishableEnvironmentDefinition } from "../environment/types.js";
+import type { EnvironmentIdentity, PublishableEnvironmentDefinition, WorldHandoff } from "../environment/types.js";
 import { type EvaluationClient } from "./client.js";
 import type { ActualAgentManifestInputV2, AttemptConnectionBundleV2, RequestedAttemptProviderV2 } from "./attempt.js";
 import { type RunnerReport } from "./runner.js";
@@ -109,10 +109,15 @@ export interface SimulationTargetContext {
     executionId: string;
     /** Stable world identity for adapter control operations such as coverage reporting. */
     environmentRunId: string;
-    /** Framework-neutral local callables backed by this attempt's isolated world. */
+    /** Framework-neutral local callables backed by this attempt's isolated world; empty for a
+     * gateway world, whose calls go to the provider mirrors in `world`. */
     tools: Record<string, EnvironmentTool>;
-    /** Short-lived capability for providers that execute MCP remotely. */
-    mcp: SimulationMcpCapability;
+    /** The mirror URLs, world token, environment carriers and MCP configuration of a gateway
+     * world; absent for a world created while the gateway was off. */
+    world?: WorldHandoff;
+    /** One MCP endpoint and bearer: the gateway world's first MCP mirror with the world token, or
+     * the deprecated execution-scoped `hue_sim_` capability of a legacy world. */
+    mcp?: SimulationMcpCapability;
     /** Credential-bearing provider connections for this callback only. Hue never
      * checkpoints, logs or adds this response to parity digests. */
     connectionBundle?: AttemptConnectionBundleV2;
@@ -149,7 +154,7 @@ export interface RunSimulationOptions {
     };
     /** Local scorer callbacks bound by their declared source digests. */
     localScorers?: LocalScorer[];
-    /** Cases in flight, 1–16; defaults to 1. */
+    /** Cases in flight, 1–64; defaults to 1. */
     concurrency?: number;
     /** JSON Schema worker deadline in milliseconds. */
     schemaTimeoutMillis?: number;
@@ -157,6 +162,10 @@ export interface RunSimulationOptions {
     maxSteps?: number;
     /** Per-world lease in seconds, 1–86400. */
     ttlSeconds?: number;
+    /** The agent revision under test, sent on world create for the world's fingerprint. */
+    agentRevision?: string;
+    /** Emit a one-time `DeprecationWarning` when the deployment serves a legacy world; on by default. */
+    deprecationWarnings?: boolean;
     /** Cooperative caller cancellation signal. */
     signal?: AbortSignal;
     /** Optional display name for the fresh experiment. */

package/dist/evals/simulation.js

@@ -378,10 +378,21 @@ export async function runSimulation(options) {
         baseUrl: options.client.baseUrl,
     });
     try {
-        const scenarioDigest = digest(definitionIdentity(definition));
+        // The agent revision is part of the attempt: a resume after it changed would otherwise
+        // finish the remaining cases under a different revision than the completed ones. A
+        // checkpoint written before revisions were tracked carries the definition digest alone and
+        // still matches its definition.
+        const scenarioDigest = digest({
+            definition: definitionIdentity(definition),
+            agentRevision: options.agentRevision ?? null,
+        });
         let attempt = await store.read("active-attempt");
-        if (attempt && attempt.stage !== "completed" && attempt.scenarioDigest !== scenarioDigest)
-            throw new Error("Recover the unfinished simulation before running a changed scenario");
+        const previousDigest = digest(definitionIdentity(definition));
+        if (attempt &&
+            attempt.stage !== "completed" &&
+            attempt.scenarioDigest !== scenarioDigest &&
+            attempt.scenarioDigest !== previousDigest)
+            throw new Error("Recover the unfinished simulation before running a changed scenario or agent revision");
         if (!attempt || attempt.stage === "completed") {
             attempt = {
                 scenarioDigest,
@@ -432,6 +443,8 @@ export async function runSimulation(options) {
                 requested,
                 maxSteps: options.maxSteps,
                 ttlSeconds: options.ttlSeconds,
+                agentRevision: options.agentRevision,
+                deprecationWarnings: options.deprecationWarnings,
                 signal: options.signal,
                 onProgress: (event) => options.onProgress?.({
                     ...event,
@@ -448,11 +461,16 @@ export async function runSimulation(options) {
                     executionId: targetContext.executionId,
                     environmentRunId: targetContext.environmentRunId,
                     tools: targetContext.tools,
-                    mcp: {
-                        url: targetContext.mcp.url,
-                        token: targetContext.mcp.token,
-                        expiresAt: targetContext.mcp.expiresAt,
-                    },
+                    ...(targetContext.world ? { world: structuredClone(targetContext.world) } : {}),
+                    ...(targetContext.mcp
+                        ? {
+                            mcp: {
+                                url: targetContext.mcp.url,
+                                token: targetContext.mcp.token,
+                                expiresAt: targetContext.mcp.expiresAt,
+                            },
+                        }
+                        : {}),
                     ...(targetContext.connectionBundle
                         ? { connectionBundle: structuredClone(targetContext.connectionBundle) }
                         : {}),

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;

package/dist/provider-tools.js

@@ -0,0 +1,222 @@
+import { MAX_CONTENT_BYTES } from "./config.js";
+const MAX_PROVIDER_ITEMS = 128;
+const MAX_PROVIDER_DEFINITIONS = 512;
+const MAX_PROVIDER_SERVERS = 512;
+function isItem(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === "string" &&
+        value.trim() !== "" &&
+        value.length <= 256 &&
+        !value.includes("\u0000") &&
+        value.isWellFormed()
+        ? value
+        : undefined;
+}
+/** MCP arguments arrive as a JSON string; record the structure when it parses, else the text. */
+function jsonArguments(value) {
+    if (typeof value !== "string")
+        return value;
+    if (Buffer.byteLength(value, "utf8") > MAX_CONTENT_BYTES)
+        return undefined;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+/** OpenAI Responses `output` items. Built-in tools are named by their kind; MCP calls by tool. */
+function openaiCalls(items, activity) {
+    const count = Math.min(items.length, MAX_PROVIDER_ITEMS);
+    activity.skipped += items.length - count;
+    for (let index = 0; index < count; index++) {
+        const item = items[index];
+        if (!isItem(item))
+            continue;
+        const callId = text(item.id);
+        switch (item.type) {
+            case "mcp_call": {
+                const name = text(item.name);
+                if (!name) {
+                    activity.skipped++;
+                    break;
+                }
+                activity.calls.push({
+                    name,
+                    callId,
+                    server: text(item.server_label),
+                    arguments: jsonArguments(item.arguments),
+                    ...(item.output !== undefined && item.output !== null ? { result: item.output } : {}),
+                    ...(item.error !== undefined && item.error !== null ? { errorType: "mcp_error" } : {}),
+                });
+                break;
+            }
+            case "mcp_list_tools": {
+                const server = text(item.server_label);
+                if (!server || !Array.isArray(item.tools)) {
+                    activity.skipped++;
+                    break;
+                }
+                const definitions = [];
+                const definitionCount = Math.min(item.tools.length, MAX_PROVIDER_DEFINITIONS);
+                activity.skipped += item.tools.length - definitionCount;
+                for (let index = 0; index < definitionCount; index++) {
+                    const tool = item.tools[index];
+                    if (!isItem(tool))
+                        continue;
+                    definitions.push({
+                        type: "function",
+                        ...(tool.name !== undefined ? { name: tool.name } : {}),
+                        ...(tool.description !== undefined ? { description: tool.description } : {}),
+                        ...(tool.input_schema !== undefined ? { parameters: tool.input_schema } : {}),
+                        ...(tool.annotations !== undefined ? { annotations: tool.annotations } : {}),
+                    });
+                }
+                activity.listings.push({
+                    server,
+                    definitions,
+                    ...(item.error !== undefined && item.error !== null ? { errorType: "mcp_error" } : {}),
+                });
+                break;
+            }
+            case "web_search_call":
+            case "file_search_call":
+            case "code_interpreter_call": {
+                const name = item.type.slice(0, -"_call".length);
+                const failed = item.status === "failed" ? { errorType: "failed" } : {};
+                if (item.type === "web_search_call")
+                    activity.calls.push({ name, callId, arguments: item.action, ...failed });
+                else if (item.type === "file_search_call")
+                    activity.calls.push({
+                        name,
+                        callId,
+                        arguments: { queries: item.queries },
+                        ...(item.results !== undefined && item.results !== null
+                            ? { result: item.results }
+                            : {}),
+                        ...failed,
+                    });
+                else
+                    activity.calls.push({
+                        name,
+                        callId,
+                        arguments: { code: item.code, container_id: item.container_id },
+                        ...(item.outputs !== undefined && item.outputs !== null
+                            ? { result: item.outputs }
+                            : {}),
+                        ...failed,
+                    });
+                break;
+            }
+            default:
+                // Messages, reasoning, approval requests and other items are not executed tools.
+                break;
+        }
+    }
+}
+/** Anthropic Messages `content` blocks: a use block paired with the result block that names it. */
+function anthropicCalls(blocks, activity) {
+    const results = new Map();
+    const count = Math.min(blocks.length, MAX_PROVIDER_ITEMS);
+    const truncated = blocks.length > MAX_PROVIDER_ITEMS;
+    activity.skipped += blocks.length - count;
+    for (let index = 0; index < count; index++) {
+        const block = blocks[index];
+        if (isItem(block) &&
+            typeof block.type === "string" &&
+            block.type.endsWith("_tool_result") &&
+            typeof block.tool_use_id === "string")
+            results.set(block.tool_use_id, block);
+    }
+    for (let index = 0; index < count; index++) {
+        const block = blocks[index];
+        if (!isItem(block) || (block.type !== "mcp_tool_use" && block.type !== "server_tool_use"))
+            continue;
+        const name = text(block.name);
+        const callId = text(block.id);
+        if (!name) {
+            activity.skipped++;
+            continue;
+        }
+        const result = callId === undefined ? undefined : results.get(callId);
+        // When the response was truncated, an unmatched use block may have its result outside the
+        // bounded prefix. Do not export it as a successful call with a missing result.
+        if (truncated && result === undefined) {
+            activity.skipped++;
+            continue;
+        }
+        const content = result?.content;
+        let errorType;
+        if (result?.is_error === true)
+            errorType = "mcp_error";
+        else if (isItem(content) && typeof content.type === "string" && content.type.endsWith("_error"))
+            errorType = text(content.error_code) ?? "error";
+        activity.calls.push({
+            name,
+            callId,
+            ...(block.type === "mcp_tool_use" ? { server: text(block.server_name) } : {}),
+            arguments: block.input,
+            ...(content !== undefined ? { result: content } : {}),
+            ...(errorType ? { errorType } : {}),
+        });
+    }
+}
+/**
+ * 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 function hostedToolActivity(provider, response) {
+    const activity = { calls: [], listings: [], skipped: 0 };
+    const items = Array.isArray(response)
+        ? response
+        : isItem(response)
+            ? response[provider === "openai" ? "output" : "content"]
+            : undefined;
+    if (!Array.isArray(items))
+        return activity;
+    if (provider === "openai")
+        openaiCalls(items, activity);
+    else
+        anthropicCalls(items, activity);
+    return activity;
+}
+/**
+ * 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 function hostedServerAddresses(provider, request) {
+    const addresses = new Map();
+    if (!isItem(request))
+        return addresses;
+    const entries = request[provider === "openai" ? "tools" : "mcp_servers"];
+    if (!Array.isArray(entries))
+        return addresses;
+    const count = Math.min(entries.length, MAX_PROVIDER_SERVERS);
+    for (let index = 0; index < count; index++) {
+        const entry = entries[index];
+        if (!isItem(entry))
+            continue;
+        const label = text(provider === "openai" ? entry.server_label : entry.name);
+        const url = provider === "openai" ? entry.server_url : entry.url;
+        if (!label || typeof url !== "string")
+            continue;
+        try {
+            const { hostname } = new URL(url);
+            if (hostname)
+                addresses.set(label, hostname);
+        }
+        catch {
+            // Not a URL; there is no address to record.
+        }
+    }
+    return addresses;
+}
+/** The provider a `model()` call named, when this module can read its responses. */
+export function hostedToolProvider(value) {
+    const provider = typeof value === "string" ? value.toLowerCase() : undefined;
+    return provider === "openai" || provider === "anthropic" ? provider : undefined;
+}

package/dist/tool-definitions.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function scrubToolCredentials(key: string, value: unknown): unknown;
+/**
+ * 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 declare function withToolCatalogSummary<T extends Record<string, unknown>>(source: T): T;