@hue-run/sdk 0.8.0 → 0.9.0

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,16 @@ 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. */
+/** A usable metadata label: non-blank, at most 256 UTF-16 code units, with no NUL or unpaired surrogate. */
 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());
 }
 /**
  * Runs `work` exactly once with `active` as OpenTelemetry's current context, so instrumentations
@@ -96,6 +103,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 +246,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,7 +310,8 @@ 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 = {
@@ -320,6 +330,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);
+        stamp("hue.mcp.surface", options.mcp?.surface);
         return this.withSpan(`execute_tool ${name}`, async ({ span }) => {
             this.setContent(span, "gen_ai.tool.call.arguments", input);
             const result = await execute();
@@ -337,7 +349,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 +370,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 +379,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 +480,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 +512,168 @@ 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 && Object.hasOwn(options.servers, label)
+                    ? options.servers[label]
+                    : undefined;
+                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 (!isLabel(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 (isLabel(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

@@ -16,12 +16,18 @@ export declare class HueEnvironmentError extends Error {
     readonly status?: number | undefined;
     /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
     readonly retryAfterMs?: number | undefined;
+    /** The server's `X-Hue-Diagnostic` code, when it is a short snake-case value. */
+    readonly diagnostic?: string | undefined;
     constructor(
     /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
     status?: number | undefined, 
     /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
-    retryAfterMs?: number | undefined);
+    retryAfterMs?: number | undefined, 
+    /** The server's `X-Hue-Diagnostic` code, when it is a short snake-case value. */
+    diagnostic?: string | undefined);
 }
+/** A connection failure or a status the client retries; seal polling continues through these. */
+export declare function isTransientEnvironmentError(error: unknown): boolean;
 /** Typed client for authored environments, isolated runs and immutable journals. */
 export declare class EnvironmentClient {
     /** Validated Hue origin. */
@@ -47,7 +53,9 @@ export declare class EnvironmentClient {
     /** Creates or recovers one fresh isolated world using a stable idempotency key. */
     createRun(input: CreateRunInput): Promise<EnvironmentRun>;
     /** Reads authoritative current or sealed world state. */
-    getRun(runId: string): Promise<{
+    getRun(runId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
         id: string;
         environmentVersionId: string;
         executionId: string | null;

package/dist/environment/client.js

@@ -4,20 +4,35 @@ import { aggregateBounds, json, uuid, valueBounds } from "../evals/json.js";
 export class HueEnvironmentError extends Error {
     status;
     retryAfterMs;
+    diagnostic;
     constructor(
     /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
     status, 
     /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
-    retryAfterMs) {
+    retryAfterMs, 
+    /** The server's `X-Hue-Diagnostic` code, when it is a short snake-case value. */
+    diagnostic) {
         super(status
-            ? `Hue environment request failed (HTTP ${status})`
+            ? `Hue environment request failed (HTTP ${status}${diagnostic ? `, ${diagnostic}` : ""})`
             : "Hue environment connection or response failed");
         this.status = status;
         this.retryAfterMs = retryAfterMs;
+        this.diagnostic = diagnostic;
         this.name = "HueEnvironmentError";
     }
 }
+const DIAGNOSTIC = /^[a-z_]{1,64}$/;
+/** The response's diagnostic code, or undefined when absent or invalid. */
+function diagnosticOf(response) {
+    const value = response.headers.get("x-hue-diagnostic");
+    return value !== null && DIAGNOSTIC.test(value) ? value : undefined;
+}
 const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
+/** A connection failure or a status the client retries; seal polling continues through these. */
+export function isTransientEnvironmentError(error) {
+    return (error instanceof HueEnvironmentError &&
+        (error.status === undefined || RETRYABLE.has(error.status)));
+}
 /** 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}$/;
@@ -64,9 +79,10 @@ export class EnvironmentClient {
             throw new RangeError("maxAttempts must be 1–10");
         this.maxAttempts = attempts;
     }
-    async send(method, path, payload) {
+    async send(method, path, payload, options = {}) {
         let response;
         try {
+            const timeout = AbortSignal.timeout(this.timeoutMillis);
             response = await fetch(`${this.baseUrl}/api/v1${path}`, {
                 method,
                 headers: {
@@ -75,7 +91,7 @@ export class EnvironmentClient {
                 },
                 body: payload,
                 redirect: "error",
-                signal: AbortSignal.timeout(this.timeoutMillis),
+                signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout,
             });
         }
         catch {
@@ -83,7 +99,7 @@ export class EnvironmentClient {
         }
         if (!response.ok) {
             await response.body?.cancel();
-            throw new HueEnvironmentError(response.status, response.status === 429 || response.status === 503 ? retryAfterMillis(response) : undefined);
+            throw new HueEnvironmentError(response.status, response.status === 429 || response.status === 503 ? retryAfterMillis(response) : undefined, diagnosticOf(response));
         }
         try {
             const reader = response.body?.getReader();
@@ -111,25 +127,40 @@ export class EnvironmentClient {
             throw new HueEnvironmentError();
         }
     }
-    async request(method, path, body) {
+    async request(method, path, body, options = {}) {
         // Serialize once: a body this client cannot encode is a caller error that no retry fixes.
         const payload = body === undefined
             ? undefined
             : JSON.stringify(json(Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined)), REQUEST_BOUNDS));
         for (let attempt = 1;; attempt++) {
             try {
-                return await this.send(method, path, payload);
+                return await this.send(method, path, payload, options);
             }
             catch (error) {
                 if (!(error instanceof HueEnvironmentError))
                     throw error;
-                const recoverable = error.status === undefined || RETRYABLE.has(error.status);
-                if (!recoverable || attempt >= this.maxAttempts)
+                if (options.signal?.aborted)
+                    throw error;
+                if (!isTransientEnvironmentError(error) || 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);
                 const wait = error.retryAfterMs ?? backoff + Math.random() * backoff;
-                await new Promise((resolve) => setTimeout(resolve, wait));
+                await new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => {
+                        options.signal?.removeEventListener("abort", abort);
+                        resolve();
+                    }, wait);
+                    const abort = () => {
+                        clearTimeout(timer);
+                        options.signal?.removeEventListener("abort", abort);
+                        reject(new HueEnvironmentError());
+                    };
+                    if (options.signal?.aborted)
+                        abort();
+                    else
+                        options.signal?.addEventListener("abort", abort, { once: true });
+                });
             }
         }
     }
@@ -194,8 +225,8 @@ export class EnvironmentClient {
         });
     }
     /** Reads authoritative current or sealed world state. */
-    async getRun(runId) {
-        const run = await this.request("GET", `/environment-runs/${uuid(runId)}`);
+    async getRun(runId, options = {}) {
+        const run = await this.request("GET", `/environment-runs/${uuid(runId)}`, undefined, options);
         return { validity: "not_assessed", coverageGap: null, ...run };
     }
     /** Record a known coverage gap with durable identity; retries reuse the exact request. */

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

@@ -173,6 +173,35 @@ export interface EnvironmentDefinition {
 /** The extendable legacy name remains V1. Publication and runs select their
  * explicit version; provider context is validated by the authoritative server. */
 export type EnvironmentDefinitionV1 = EnvironmentDefinition;
+/** Gmail mailbox carrier holding messages and drafts in the simplified shape Hue's
+ * `hue.gmail.*` actions read. */
+export interface GmailMailboxConfigurationV1 {
+    /** Gmail mailbox configuration discriminator. */
+    kind: "gmail_mailbox/v1";
+    /** Collection containing synthetic messages. */
+    messagesCollection: string;
+    /** Collection containing synthetic drafts. */
+    draftsCollection: string;
+    /** Synthetic mailbox address. */
+    mailboxAddress: string;
+}
+/** Gmail mailbox carrier served by Hue's simulation gateway: messages, drafts and labels in the
+ * entity shapes the Gmail mirrors serve, with threads derived from each message's `threadId`. A
+ * definition whose provider instances all use it may publish with no actions. */
+export interface GmailMailboxConfigurationV2 {
+    /** Gmail mailbox configuration discriminator. */
+    kind: "gmail_mailbox/v2";
+    /** Collection containing synthetic messages. */
+    messagesCollection: string;
+    /** Collection containing synthetic drafts, each naming a `DRAFT`-labelled message. */
+    draftsCollection: string;
+    /** Collection containing synthetic labels. */
+    labelsCollection: string;
+    /** Synthetic mailbox address; Hue accepts only `owner@example.test`, in any letter case. */
+    mailboxAddress: string;
+}
+/** Either Gmail mailbox carrier, discriminated by `kind`; Hue validates both at publication. */
+export type GmailMailboxConfiguration = GmailMailboxConfigurationV1 | GmailMailboxConfigurationV2;
 /** One synthetic Gmail principal and its world-state collection bindings. */
 export interface GmailProviderInstance {
     /** Stable instance key referenced by attempt provider selection. */
@@ -182,16 +211,7 @@ export interface GmailProviderInstance {
     /** Synthetic principal UUID, canonicalized to lowercase by Hue. */
     syntheticPrincipalId: string;
     /** Versioned mapping from Gmail concepts to authored-world collections. */
-    configuration: {
-        /** Gmail mailbox configuration discriminator. */
-        kind: "gmail_mailbox/v1";
-        /** Collection containing synthetic messages. */
-        messagesCollection: string;
-        /** Collection containing synthetic drafts. */
-        draftsCollection: string;
-        /** Synthetic mailbox address. */
-        mailboxAddress: string;
-    };
+    configuration: GmailMailboxConfiguration;
 }
 /** V2 authored world with immutable provider-instance bindings. */
 export interface EnvironmentDefinitionV2 extends Omit<EnvironmentDefinition, "schemaVersion"> {
@@ -252,8 +272,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/environment.d.ts

@@ -1,4 +1,4 @@
-export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, } from "./environment/client.js";
+export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, isTransientEnvironmentError, } from "./environment/client.js";
 export type { EnvironmentClientOptions } from "./environment/client.js";
 export { bindEnvironmentTools } from "./environment/tools.js";
 export type { BindEnvironmentToolsOptions, EnvironmentTool } from "./environment/tools.js";

package/dist/environment.js

@@ -1,3 +1,3 @@
-export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, } from "./environment/client.js";
+export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, isTransientEnvironmentError, } from "./environment/client.js";
 export { bindEnvironmentTools } from "./environment/tools.js";
 export { agentEnvironment, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, writeMcpConfig, } from "./environment/world.js";

package/dist/evals/environment-target.d.ts

@@ -91,6 +91,11 @@ export interface RunEnvironmentTargetOptions {
     onProgress?(event: EnvironmentTargetProgress): void | Promise<void>;
     target(inputs: JsonValue, context: EnvironmentTargetContext): JsonValue | undefined | Promise<JsonValue | undefined>;
 }
+/** The completion grace is five seconds; cap an unexpectedly distant timestamp and let reads
+ * force the seal after the grace. */
+export declare const MAX_GRACE_WAIT_MS = 10000;
+export declare const SEAL_POLL_MS = 250;
+export declare const SEAL_WAIT_MS = 30000;
 /** The W3C context of the case span, sent on create so the world span parents on it. The
  * flags are the span's own: an unsampled case span is not exported, and the World API must not
  * be told otherwise. */