@hue-run/sdk 0.7.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/client.d.ts

@@ -1,4 +1,4 @@
-import type { ActionInput, ActionResult, CoverageGapInput, CoverageGapResult, CreateRunInput, Environment, PublishableEnvironmentDefinition, EnvironmentIdentity, EnvironmentPage, EnvironmentPageOptions, EnvironmentRun, EnvironmentSummary, EnvironmentVersion, EnvironmentVersionSummary, FinishRunInput, SealedRun, StepPage, StepPageOptions } from "./types.js";
+import type { ActionInput, ActionResult, CoverageGapInput, CoverageGapResult, CreateRunInput, Environment, PublishableEnvironmentDefinition, EnvironmentIdentity, EnvironmentPage, EnvironmentPageOptions, EnvironmentRun, EnvironmentSummary, EnvironmentVersion, EnvironmentVersionSummary, FinishRunInput, SealedRun, StepPage, StepPageOptions, WorldEvidence, WorldEvidenceOptions } from "./types.js";
 /** Connection and retry options for {@link createEnvironmentClient}. */
 export interface EnvironmentClientOptions {
     /** Project service key sent as a bearer token; server-side only. */
@@ -14,9 +14,13 @@ export interface EnvironmentClientOptions {
 export declare class HueEnvironmentError extends Error {
     /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
     readonly status?: number | undefined;
+    /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
+    readonly retryAfterMs?: number | undefined;
     constructor(
     /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
-    status?: number | undefined);
+    status?: number | undefined, 
+    /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
+    retryAfterMs?: number | undefined);
 }
 /** Typed client for authored environments, isolated runs and immutable journals. */
 export declare class EnvironmentClient {
@@ -57,6 +61,13 @@ export declare class EnvironmentClient {
         sealedAt: string | null;
         stateDigest: string;
         finalState?: import("./types.js").JsonValue;
+        worldId?: string;
+        lifecycle?: import("./types.js").WorldLifecycle;
+        completingUntil?: string | null;
+        traceExternalId?: string | null;
+        surfaces?: import("./types.js").WorldSurface[];
+        flags?: import("./types.js").WorldFlag[];
+        connection?: null;
         validity: "environment_incomplete" | "not_assessed";
         coverageGap: import("./types.js").CoverageGap | null;
     }>;
@@ -68,6 +79,9 @@ export declare class EnvironmentClient {
     listSteps(runId: string, page?: StepPageOptions): Promise<StepPage>;
     /** Seals a world as completed or abandoned and freezes its evidence. */
     finishRun(runId: string, input: FinishRunInput): Promise<SealedRun>;
+    /** Reads a sealed world's evaluator-only evidence with the project key; a world token never
+     * can. An open world answers 409 until it is sealed. */
+    getEvidence(runId: string, options?: WorldEvidenceOptions): Promise<WorldEvidence>;
 }
 /** Creates a typed simulated-environment client. */
 export declare function createEnvironmentClient(options: EnvironmentClientOptions): EnvironmentClient;

package/dist/environment/client.js

@@ -3,17 +3,38 @@ import { aggregateBounds, json, uuid, valueBounds } from "../evals/json.js";
 /** Sanitized environment API failure that never includes response text or credentials. */
 export class HueEnvironmentError extends Error {
     status;
+    retryAfterMs;
     constructor(
     /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
-    status) {
+    status, 
+    /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
+    retryAfterMs) {
         super(status
             ? `Hue environment request failed (HTTP ${status})`
             : "Hue environment connection or response failed");
         this.status = status;
+        this.retryAfterMs = retryAfterMs;
         this.name = "HueEnvironmentError";
     }
 }
 const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
+/** A `Retry-After` longer than this waits this long: Hue asks for a second, never minutes. */
+const MAX_RETRY_AFTER_MS = 10_000;
+const TRACEPARENT = /^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/;
+/** Version 00 with real identifiers: an all-zero trace or span ID is invalid, and Hue refuses it. */
+function validTraceparent(value) {
+    if (!TRACEPARENT.test(value))
+        return false;
+    const [, traceId, spanId] = value.split("-");
+    return !/^0+$/.test(traceId) && !/^0+$/.test(spanId);
+}
+/** Whole seconds only, as Hue sends them; a date or garbage is ignored. */
+function retryAfterMillis(response) {
+    const header = response.headers.get("retry-after");
+    if (header === null || !/^\d{1,6}$/.test(header.trim()))
+        return undefined;
+    return Math.min(Number(header.trim()) * 1000, MAX_RETRY_AFTER_MS);
+}
 const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
 const REQUEST_BOUNDS = { ...valueBounds, bytes: 1024 * 1024 };
 /** The server bounds JSON inside each entity independently, then permits the parsed
@@ -62,7 +83,7 @@ export class EnvironmentClient {
         }
         if (!response.ok) {
             await response.body?.cancel();
-            throw new HueEnvironmentError(response.status);
+            throw new HueEnvironmentError(response.status, response.status === 429 || response.status === 503 ? retryAfterMillis(response) : undefined);
         }
         try {
             const reader = response.body?.getReader();
@@ -105,8 +126,10 @@ export class EnvironmentClient {
                 const recoverable = error.status === undefined || RETRYABLE.has(error.status);
                 if (!recoverable || attempt >= this.maxAttempts)
                     throw error;
+                // Hue's admission refusals say how long to wait; anything else backs off.
                 const backoff = Math.min(100 * 2 ** (attempt - 1), 2000);
-                await new Promise((resolve) => setTimeout(resolve, backoff + Math.random() * backoff));
+                const wait = error.retryAfterMs ?? backoff + Math.random() * backoff;
+                await new Promise((resolve) => setTimeout(resolve, wait));
             }
         }
     }
@@ -157,6 +180,13 @@ export class EnvironmentClient {
             throw new RangeError("ttlSeconds must be 1–86400");
         if (input.seed !== undefined && !/^[a-f0-9]{32}$/.test(input.seed))
             throw new TypeError("Seed must be 32 lowercase hexadecimal characters");
+        if (input.traceparent !== undefined && !validTraceparent(input.traceparent))
+            throw new TypeError("traceparent must be a version-00 W3C trace context");
+        if (input.agentRevision !== undefined &&
+            (typeof input.agentRevision !== "string" ||
+                input.agentRevision.length < 1 ||
+                input.agentRevision.length > 256))
+            throw new RangeError("agentRevision must be 1–256 characters");
         return this.request("POST", "/environment-runs", {
             ...input,
             environmentVersionId: uuid(input.environmentVersionId),
@@ -202,6 +232,19 @@ export class EnvironmentClient {
     finishRun(runId, input) {
         return this.request("POST", `/environment-runs/${uuid(runId)}/finish`, input);
     }
+    /** Reads a sealed world's evaluator-only evidence with the project key; a world token never
+     * can. An open world answers 409 until it is sealed. */
+    getEvidence(runId, options = {}) {
+        const query = new URLSearchParams();
+        if (options.section !== undefined) {
+            if (!["all", "start", "end", "diff", "ledger"].includes(options.section))
+                throw new TypeError("Evidence section must be all, start, end, diff or ledger");
+            query.set("section", options.section);
+        }
+        if (options.bodies !== undefined)
+            query.set("bodies", options.bodies ? "true" : "false");
+        return this.request("GET", `/environment-runs/${uuid(runId)}/evidence${query.size ? `?${query}` : ""}`);
+    }
 }
 /** Creates a typed simulated-environment client. */
 export function createEnvironmentClient(options) {

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 = {};