@hue-run/sdk 0.12.1 → 0.13.0

package/CLI.md

@@ -42,7 +42,7 @@ project manifest are refused because managers can update ancestor locks; Python
 The generated `hue.setup.mjs` or `hue_setup.py` always selects `captureContent: false` /
 `capture_content=False`. For a supported application, setup installs the dependency and adds the
 managed import and middleware registration to the existing entrypoint; an unreferenced helper is
-not a completed integration. TypeScript uses `@hue-run/sdk@0.12.1`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.13.0`, `@opentelemetry/api@1.9.1` and
 `@opentelemetry/context-async-hooks@2.11.0`; Python setup uses its separately tested package pin.
 Content capture requires an ordinary account-managed key and a later explicit application decision.
 
@@ -469,7 +469,7 @@ node packages/sdk-typescript/scripts/verify-package.mjs --artifacts-dir .artifac
 # Set project to an existing supported fixture; use the same directory on resume.
 project=/absolute/path/to/supported-fixture
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.12.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.13.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -480,7 +480,7 @@ the private local handoff and finish the real browser claim, then reconcile the
 
 ```sh
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.12.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.13.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -576,7 +576,9 @@ Hue-owned `world_outcome` checks are graded after the world seals. An experiment
 every case of the saved version; there is no case subset.
 
 `--command "<shell command>"` spawns the command once per case with the world's environment
-(`HUE_WORLD_ID`, `HUE_WORLD_TOKEN`, one `HUE_SIM_<SURFACE ID>_URL` per provider mirror,
+(`HUE_WORLD_ID`, `HUE_WORLD_TOKEN`, `HUE_WORLD_NOW` (the world's clock at creation, RFC 3339: read
+today's date from it, never from the wall clock), one `HUE_SIM_<SURFACE ID>_URL` per provider
+mirror,
 `HUE_MCP_CONFIG` naming an owner-only `mcpServers` file that is removed after the case, and
 `HUE_MCP_URL`, `HUE_MCP_TOKEN`, `HUE_MCP_EXPIRES_AT` for the first MCP mirror; these name the
 world's simulated MCP server and replace a `HUE_MCP_URL` that `hue login` stored for Hue's project

package/ENVIRONMENTS.md

@@ -220,10 +220,24 @@ automatically because identity creation and publication have no request key.
 Where a Hue deployment has the simulation gateway on, `createRun` returns the World API handoff
 beside the run: `token` (a `hue_world_…` credential that lives exactly as long as the world),
 `surfaces[]` (one mirror URL per pinned provider surface, such as the Gmail MCP and REST mirrors),
-`env` (`HUE_WORLD_ID`, `HUE_WORLD_TOKEN`, `BAGGAGE`, `TRACEPARENT` and one
-`HUE_SIM_<SURFACE ID>_URL` per surface) and `mcpConfig` (the common `mcpServers` shape with the
-token in the `Authorization` header). The agent is pointed at the mirrors by configuration only:
-its own Gmail MCP or REST client, the mirror URL, the world token where the Google credential went.
+`now` (the world's clock at creation as an RFC 3339 timestamp), `env` (`HUE_WORLD_ID`,
+`HUE_WORLD_TOKEN`, `HUE_WORLD_NOW`, `BAGGAGE`, `TRACEPARENT` and one `HUE_SIM_<SURFACE ID>_URL`
+per surface) and `mcpConfig` (the common `mcpServers` shape with the token in the `Authorization`
+header). The agent is pointed at the mirrors by configuration only: its own Gmail MCP or REST
+client, the mirror URL, the world token where the Google credential went.
+
+The world has its own date. A trace-built world's clock is frozen at the recorded start, so a
+run that begins days or months after the recording still finds the recorded emails, events and
+records at their recorded times. An agent that reads the wall clock for "today", "tomorrow" or
+`newer_than:7d` asks the world about dates it holds nothing for; one that reads the world's date
+lands on the recorded ones. Read it with `worldNow`: from the handoff, or from the environment of
+an agent child, where `agentEnvironment` and `hue eval --command` set `HUE_WORLD_NOW`.
+
+```ts
+import { worldNow } from "@hue-run/sdk/environment";
+
+const today = worldNow() ?? new Date(); // HUE_WORLD_NOW in this process, else the wall clock
+```
 
 ```ts
 import {

package/README.md

@@ -45,7 +45,6 @@ await hue.withSpan(
   async (span) => {
     const output = await hue.tool("uppercase", "hello", () => "hello".toUpperCase());
     span.setOutput(output);
-    hue.recordMessages({ output: [{ role: "assistant", content: output }] });
   },
   { sessionId: "session-123", userId: "user-123", input: "hello" },
 );
@@ -107,7 +106,8 @@ by the semantic conventions'
 [input messages](https://github.com/open-telemetry/semantic-conventions/blob/v1.41.0/docs/gen-ai/gen-ai-input-messages.json)
 and
 [output messages](https://github.com/open-telemetry/semantic-conventions/blob/v1.41.0/docs/gen-ai/gen-ai-output-messages.json)
-JSON schemas, so any semantic-convention-aware backend can read them. Convert provider-native
+JSON schemas. GenAI conventions are in Development; Hue supports the fields described here
+and accepts caller-supplied JSON without validating the full draft. Convert provider-native
 messages before recording them:
 
 ```ts
@@ -313,7 +313,7 @@ policy forbids sending that content to another service. `redact` and the credent
 described below apply in both modes.
 
 `captureContent: false` disables manual input/output/messages/tool content and
-removes recognized GenAI, Vercel, OpenInference and OpenLLMetry content attributes,
+removes recognized GenAI, Vercel, OpenInference, OpenLLMetry and Langfuse content attributes,
 legacy GenAI content events, log bodies, status messages and exception text before
 export. The exported `contentPrefixes` array lists the attribute keys (and their dotted
 children) that are removed. Model/provider/token metadata remains available. Generic custom attribute
@@ -323,7 +323,13 @@ names cannot be classified automatically; use them deliberately.
 there is no SDK retention timer or automatic content expiry. To redact strings
 before export, supply `redact(value, path)`; it applies to supported strings in
 attributes, resources, event/link attributes and log bodies. Return a string.
-Invalid/oversized helper content is omitted with an instrumentation failure; the span can still be delivered. Export-time redactor failures reject the affected record and are reported by flush. Shared resources are redacted once per
+Invalid helper content is omitted with an instrumentation failure; the span can still be delivered.
+A content value over Hue's 256 KiB value cap is not omitted: text is cut to a UTF-8 prefix and
+bytes or a structured log body are replaced by the receiver's own marker
+(`{ "hue.truncated": true, "hue.truncated_bytes": <size> }`), and the value's key is listed in
+the record's `hue.truncated` attribute, where Hue's receiver lists the values it cuts itself,
+so the span still carries the call, the recorded part of its value and the rest of its evidence.
+Export-time redactor failures reject the affected record and are reported by flush. Shared resources are redacted once per
 export batch. Do not put user content or secrets in span names or scope names.
 
 Hosted tools carry credentials in their definitions, such as the `authorization` and `headers` of
@@ -355,7 +361,7 @@ rotates. Only definitions another integration recorded can be summarized: `hueTe
 inputs and exports through Hue's attached processors gets the summary.
 Recorded messages can inline files: GenAI `blob` parts in `gen_ai.input.messages` /
 `gen_ai.output.messages` (what the AI SDK 7 adapter records for a file part) and AI SDK 6 `file`
-parts in `ai.prompt.messages`. A span whose messages exceed 256 KiB would be rejected, so when a
+parts in `ai.prompt.messages`. A span whose messages exceed 256 KiB would be cut, so when a
 record is queued Hue replaces the `content`/`data` of any such part longer than 64 KiB with the
 file's `sha256` and `size`, both of the file's own bytes whatever its media type (base64 content
 and `;base64` `data:` URLs decoded, other `data:` URLs percent-decoded, anything else as UTF-8 text), keeping the part's other fields such as `type`, `mime_type` and `mediaType`. Smaller inline
@@ -379,8 +385,8 @@ span in `finally`.
 the active span, with the messages in its body. The record also carries `gen_ai.operation.name`,
 `gen_ai.provider.name` and `gen_ai.request.model` as attributes, copied from the enclosing
 `hue.model()` span or passed as `operation`, `provider` and `model`, and `gen_ai.conversation.id`
-from the active session, so a collector fan-out to another GenAI-aware backend keeps the request
-context.
+from the active session, when those values are known. Use `recordMessages` inside `hue.model()` or
+supply `operation` and `provider` explicitly to include the required inference context.
 
 ## Existing OpenTelemetry providers
 
@@ -447,7 +453,8 @@ that accepts `/api/v1/otlp/v1/traces` and `/api/v1/otlp/v1/logs` (for example an
 Collector `otlp` receiver with `http.traces_url_path` and `logs_url_path` set to those paths,
 forwarding to Jaeger or the debug exporter) and pass any placeholder `apiKey`; HTTP is allowed
 for loopback origins. `checkConnection()` and `verifyTrace()` are Hue-only diagnostics and are
-not available against a generic collector.
+not available against a generic collector. Set `liveSpans: false` so Hue-specific placeholders
+do not reach the collector's other destinations.
 
 A collector on a private network is not loopback: a docker-compose sibling such as
 `http://otel-collector:4318` or an in-cluster service requires the explicit opt-in
@@ -461,6 +468,7 @@ const hue = createHue({
   serviceName: "my-agent",
   captureContent: true,
   baseUrl: "http://otel-collector:4318",
+  liveSpans: false,
   allowInsecureHttp: true,
 });
 ```
@@ -470,7 +478,11 @@ const hue = createHue({
 Exports retry temporary HTTP/network failures (429, 502, 503, 504 and connection errors,
 honoring `Retry-After`) within the export timeout, by OpenTelemetry's OTLP/HTTP exporter rules. Each
 request is limited to 1 MiB before gzip (with space reserved for gzip overhead) and each content value to 256 KiB. Batches
-split at record boundaries. Each signal queues at most 2,048 records, including
+split at record boundaries. A record over the request limit on its own sheds its content values,
+largest first, each replaced by the receiver's marker and listed under `hue.truncated`, until it
+fits; only a record too large without any content value is lost, reported as an `invalid` issue,
+and counted on its trace's root span as `hue.sdk.dropped_records` when the root is exported, so
+Hue reads the trace as incomplete by that many records. Each signal queues at most 2,048 records, including
 exports in flight; overflow is reported through the callback, counters and next
 flush. This is an in-memory queue, not durable storage.
 
@@ -522,10 +534,14 @@ short span may send none and appear in Hue only when it finishes.
   record and byte budgets, and skipped silently otherwise. While queued they count in
   `pendingSpans` and `pendingBytes`, but never as accepted, rejected, failed or dropped records.
   Losing only placeholders records a warning and does not make `flush()` throw.
-- A Hue server that accepts placeholders sends `Hue-Pending-Spans: 1` on trace acknowledgements.
-  When a response to a request carrying placeholders lacks it, the receiver predates them: the
-  transport attributes up to one rejection per placeholder to them, records one warning and stops
-  sending placeholders for that client. Other rejections count against real spans as usual.
+- Placeholders travel in their own requests, after an export's completed spans, so a rejection
+  count is always one kind of record's: a completed span's rejection is never credited to a
+  placeholder, and a rejected request of placeholders is a warning. A Hue server that accepts
+  placeholders sends `Hue-Pending-Spans: 1` on every trace acknowledgement. The first trace
+  acknowledgement without it, whatever its request carried, shows the receiver predates them: the
+  transport records one warning (counting the placeholders the receiver rejected in that request, if any) and stops
+  sending placeholders for that client, so a receiver that acknowledged completed spans first
+  never receives one.
 - Opt out with `liveSpans: false`. Setup credentials never send placeholders.
 - With an existing provider, announcements start in `spanProcessor.onStart`. A wrapping processor
   that forwards `onStart` should forward `onEnd` for the same spans: a span that ends without

package/dist/client.d.ts

@@ -154,6 +154,14 @@ export declare class HueClient {
      * alone is omitted and counted while the rest is recorded.
      */
     recordFile(file: FileRecord, explicitContext?: Context): void;
+    /** The keys of each span's content values that were cut to Hue's value cap, for `hue.truncated`. */
+    private truncatedKeys;
+    /**
+     * A content value as a JSON attribute within Hue's 256 KiB value cap. A larger value is cut to
+     * a UTF-8 prefix and its key listed under `hue.truncated`, where Hue's receiver lists the
+     * values it cuts itself: the span carries the call and the recorded part of its value instead
+     * of losing the value whole. Only a value that cannot be encoded is omitted and counted.
+     */
     private setContent;
     /**
      * Confirms the key and origin by reading the current project; a setup and CI diagnostic, not a

package/dist/client.js

@@ -10,7 +10,8 @@ import { defaultResource, resourceFromAttributes } from "@opentelemetry/resource
 import { HUE_SCOPE } from "./config.js";
 import { hostedServerAddresses, hostedToolActivity, hostedToolProvider, providerErrorDescription, } from "./provider-tools.js";
 import { toolCatalogSummary } from "./tool-definitions.js";
-import { encodeContent, noopSpan, safeSpan } from "./safety.js";
+import { encodeBoundedContent, encodeContent, noopSpan, safeSpan, } from "./safety.js";
+import { TRUNCATED_KEY, withTruncatedKeys } from "./privacy.js";
 import { createHueTransport, HueExportError } from "./transport.js";
 import { verifyTrace } from "./receipt.js";
 import { sdkVersion } from "./version.js";
@@ -712,11 +713,31 @@ export class HueClient {
             this.instrumentationFailed();
         }
     }
+    /** The keys of each span's content values that were cut to Hue's value cap, for `hue.truncated`. */
+    truncatedKeys = new WeakMap();
+    /**
+     * A content value as a JSON attribute within Hue's 256 KiB value cap. A larger value is cut to
+     * a UTF-8 prefix and its key listed under `hue.truncated`, where Hue's receiver lists the
+     * values it cuts itself: the span carries the call and the recorded part of its value instead
+     * of losing the value whole. Only a value that cannot be encoded is omitted and counted.
+     */
     setContent(span, key, value) {
         if (!this.enabled || this.closed || !this.captureContent)
             return;
         try {
-            span.setAttribute(key, encodeContent(value));
+            const { text, truncated } = encodeBoundedContent(value);
+            span.setAttribute(key, text);
+            // The span's list as it stands: the application's own entries (read from the SDK span,
+            // which carries its attributes; the API alone shows none) and this helper's earlier ones.
+            const listed = withTruncatedKeys(span.attributes?.[TRUNCATED_KEY], this.truncatedKeys.get(span) ?? []);
+            const keys = truncated
+                ? withTruncatedKeys(listed, [key])
+                : listed.filter((entry) => entry !== key);
+            if (truncated || listed.includes(key)) {
+                // A whole value replacing a cut one unmarks its key; an untouched list is left alone.
+                this.truncatedKeys.set(span, keys);
+                span.setAttribute(TRUNCATED_KEY, keys);
+            }
         }
         catch {
             this.instrumentationFailed();

package/dist/environment/types.d.ts

@@ -364,7 +364,11 @@ export interface WorldHandoff {
     baggage: string;
     /** Mirror surfaces of every provider instance the environment version binds. */
     surfaces: WorldSurface[];
-    /** `HUE_WORLD_ID`, `HUE_WORLD_TOKEN`, `BAGGAGE`, `TRACEPARENT` and one
+    /** The world's clock at creation (RFC 3339): the date an agent computes its dates from in
+     * place of the wall clock, a trace-built world's recorded start. Also `env.HUE_WORLD_NOW`;
+     * null for a Hue that names neither. */
+    now: string | null;
+    /** `HUE_WORLD_ID`, `HUE_WORLD_TOKEN`, `HUE_WORLD_NOW`, `BAGGAGE`, `TRACEPARENT` and one
      * `HUE_SIM_<SURFACE ID>_URL` per surface. */
     env: Record<string, string>;
     /** The `mcpServers` configuration for the MCP surfaces. */
@@ -378,6 +382,9 @@ export interface EnvironmentRun {
     environmentVersionId: string;
     /** Current virtual nanoseconds as a decimal string. */
     clockNs: string;
+    /** The world's clock at creation as an RFC 3339 timestamp (`clockNs` as a date): a
+     * trace-built world's recorded start. Absent from a Hue that predates it. */
+    now?: string;
     /** Digest of current world state. */
     stateDigest: string;
     /** Maximum recorded actions. */

package/dist/environment/world.d.ts

@@ -5,6 +5,14 @@ import type { EnvironmentRun, LegacyMcpCapability, WorldHandoff } from "./types.
  * mirror URLs. The handoff carries the world token; keep it out of logs and checkpoints.
  */
 export declare function worldHandoff(run: EnvironmentRun): WorldHandoff | null;
+/**
+ * The world's clock: what an agent reads for today's date in place of the wall clock, so a
+ * date-relative request (tomorrow, `newer_than:7d`, this month) lands on the dates the world
+ * holds however long after the recording the run starts. From the handoff's `now`, else from
+ * `HUE_WORLD_NOW` in the given environment (this process's by default, where `hue eval
+ * --command` and `agentEnvironment` set it). Null when neither names it.
+ */
+export declare function worldNow(source?: WorldHandoff | Record<string, string | undefined>): Date | null;
 /** Variables that authenticate against Hue's control plane rather than a simulated provider. */
 export declare const HUE_CONTROL_PLANE_VARIABLES: readonly string[];
 /** True for a control-plane variable by name, or for any variable holding a Hue credential. */

package/dist/environment/world.js

@@ -18,6 +18,7 @@ export function worldHandoff(run) {
         completingUntil: run.completingUntil ?? null,
         traceparent: run.traceparent ?? null,
         baggage: run.baggage ?? `hue-world=${id}`,
+        now: run.now ?? run.env.HUE_WORLD_NOW ?? null,
         surfaces: run.surfaces.map((surface) => ({ ...surface })),
         env: { ...run.env },
         mcpConfig: {
@@ -28,6 +29,22 @@ export function worldHandoff(run) {
         },
     };
 }
+/**
+ * The world's clock: what an agent reads for today's date in place of the wall clock, so a
+ * date-relative request (tomorrow, `newer_than:7d`, this month) lands on the dates the world
+ * holds however long after the recording the run starts. From the handoff's `now`, else from
+ * `HUE_WORLD_NOW` in the given environment (this process's by default, where `hue eval
+ * --command` and `agentEnvironment` set it). Null when neither names it.
+ */
+export function worldNow(source = process.env) {
+    const text = "env" in source && typeof source.env === "object" && source.env !== null
+        ? (source.now ?? source.env.HUE_WORLD_NOW)
+        : source.HUE_WORLD_NOW;
+    if (!text)
+        return null;
+    const date = new Date(text);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
 /** Variables that authenticate against Hue's control plane rather than a simulated provider. */
 export const HUE_CONTROL_PLANE_VARIABLES = [
     "HUE_API_KEY",

package/dist/environment.d.ts

@@ -3,5 +3,5 @@ export type { EnvironmentClientOptions } from "./environment/client.js";
 export { bindEnvironmentTools } from "./environment/tools.js";
 export type { BindEnvironmentToolsOptions, EnvironmentTool } from "./environment/tools.js";
 export type * from "./environment/types.js";
-export { agentEnvironment, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, writeMcpConfig, } from "./environment/world.js";
+export { agentEnvironment, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, worldNow, writeMcpConfig, } from "./environment/world.js";
 export type { AgentEnvironmentOptions, McpConfigFile } from "./environment/world.js";

package/dist/environment.js

@@ -1,3 +1,3 @@
 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";
+export { agentEnvironment, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, worldNow, writeMcpConfig, } from "./environment/world.js";

package/dist/evals/failure.d.ts

@@ -10,9 +10,26 @@
  * The runner records the type on the execution in place of `TargetError`; Hue classes the first
  * three as infrastructure and the last as configuration, so an error from Hue's own clients is
  * never filed as the agent's. Anything else is the agent's own error.
+ *
+ * A simulated world the agent reaches through its own client (an MCP client, a REST client, a
+ * fetch) answers Hue's gateway refusals with a status and a diagnostic: `503
+ * authorization_unavailable` when Hue could not authorize the world token because its database
+ * could not answer, `503 gateway_failure` when the gateway failed. The MCP SDK's transport throws
+ * these as `StreamableHTTPError` or `SseError` with the status as `code` and no response, so the
+ * status is read from there too; the diagnostic is the error's cause (`serviceFailureCause`),
+ * recorded beside the type so a run's reader sees what refused it.
  */
 export type ServiceFailureType = "ServiceRefused" | "ConnectionFailed" | "TimedOut" | "ConfigurationRejected";
 /** The service failure a target's throw shows, by the errors linked from it, in precedence
  * order: a timeout, a failed connection, a retryable refusal, a status Hue's own client was
  * refused with; null for the agent's own error. */
 export declare function serviceFailureType(error: unknown): ServiceFailureType | null;
+/**
+ * The service's own word for what failed, when the answer a target's throw carries names one:
+ * Hue's gateway diagnostic (`authorization_unavailable`, `gateway_failure`), read from the
+ * `x-hue-diagnostic` header or the JSON body's `diagnostic` of any error linked from the throw,
+ * nearest first. Undefined when no answer names one, or the name is not a diagnostic's token.
+ * Read for a service failure (`serviceFailureType`), where the runner records it as the error's
+ * `cause`.
+ */
+export declare function serviceFailureCause(error: unknown): string | undefined;

package/dist/evals/failure.js

@@ -69,6 +69,17 @@ function names(error) {
     }
     return found;
 }
+/** The MCP TypeScript SDK's transport errors, which carry the HTTP status as `code` and no
+ * response: a POST the server answered with a failing status (`StreamableHTTPError`) or an SSE
+ * stream it refused (`SseError`). Recognized by class name, never imported. */
+const MCP_TRANSPORT_NAMES = new Set(["StreamableHTTPError", "SseError"]);
+/** The status an MCP transport error carries, or undefined for any other error. */
+function transportStatus(error) {
+    const { code } = error;
+    return typeof code === "number" && names(error).some((name) => MCP_TRANSPORT_NAMES.has(name))
+        ? code
+        : undefined;
+}
 const retryable = (status) => typeof status === "number" &&
     (status === 408 || status === 429 || (status >= 500 && status < 600));
 function timedOut(error) {
@@ -99,6 +110,9 @@ function disconnected(error) {
 function refused(error) {
     if (hueClientError(error))
         return retryable(error.status);
+    // An MCP transport error is the exchange itself: the server answered the status it carries.
+    if (retryable(transportStatus(error)))
+        return true;
     const { status, statusCode, headers, response, url, responseHeaders } = error;
     const exchanged = [headers, response, url, responseHeaders].some((item) => item !== undefined && item !== null);
     // A fetch `Response` carries the status itself.
@@ -148,3 +162,91 @@ export function serviceFailureType(error) {
         return "ConfigurationRejected";
     return null;
 }
+/** The header Hue's gateway names its diagnostic in, beside the JSON body's `diagnostic`. */
+const DIAGNOSTIC_HEADER = "x-hue-diagnostic";
+/** A diagnostic's spelling: a short lower-case token (`authorization_unavailable`). */
+const DIAGNOSTIC = /^[a-z][a-z0-9_]{0,63}$/;
+/** The most of a body or message read for a diagnostic. */
+const MAX_BODY = 8192;
+/** A header's value from a `Headers`, a record of names to values (case-insensitive), or a
+ * record of names to arrays, as the HTTP clients spell them; undefined otherwise. */
+function headerValue(headers, name) {
+    if (headers === null || typeof headers !== "object")
+        return undefined;
+    const get = headers.get;
+    if (typeof get === "function") {
+        const value = get.call(headers, name);
+        return typeof value === "string" ? value : undefined;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== name)
+            continue;
+        const first = Array.isArray(value) ? value[0] : value;
+        return typeof first === "string" ? first : undefined;
+    }
+    return undefined;
+}
+/** The `diagnostic` a JSON body names: an object's, at the top or in a JSON-RPC error's `data`,
+ * or the object a string carries from its first brace (an MCP transport error's message quotes
+ * the body it was answered). */
+function bodyDiagnostic(body) {
+    if (typeof body === "string") {
+        const start = body.indexOf("{");
+        if (start < 0 || body.length - start > MAX_BODY)
+            return undefined;
+        try {
+            return bodyDiagnostic(JSON.parse(body.slice(start)));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (body === null || typeof body !== "object")
+        return undefined;
+    // Hue's REST refusal names it at the top; its MCP refusal, a JSON-RPC error, in `error.data`.
+    const { diagnostic, error } = body;
+    if (typeof diagnostic === "string")
+        return diagnostic;
+    const data = error !== null && typeof error === "object" ? error.data : undefined;
+    const named = data !== null && typeof data === "object"
+        ? data.diagnostic
+        : undefined;
+    return typeof named === "string" ? named : undefined;
+}
+/** The diagnostic one error carries: the one it names itself (Hue's own clients read the header
+ * into `diagnostic`), else the header on its `headers`, `responseHeaders` or `response.headers`,
+ * else the body on its `responseBody`, `body` or, for an MCP transport error, its message. */
+function diagnosticOf(error) {
+    const { diagnostic, headers, responseHeaders, response, responseBody, body, message } = error;
+    const answered = response !== null && typeof response === "object"
+        ? response.headers
+        : undefined;
+    return ((typeof diagnostic === "string" ? diagnostic : undefined) ??
+        headerValue(headers, DIAGNOSTIC_HEADER) ??
+        headerValue(responseHeaders, DIAGNOSTIC_HEADER) ??
+        headerValue(answered, DIAGNOSTIC_HEADER) ??
+        bodyDiagnostic(responseBody) ??
+        bodyDiagnostic(body) ??
+        (transportStatus(error) !== undefined ? bodyDiagnostic(message) : undefined));
+}
+/**
+ * The service's own word for what failed, when the answer a target's throw carries names one:
+ * Hue's gateway diagnostic (`authorization_unavailable`, `gateway_failure`), read from the
+ * `x-hue-diagnostic` header or the JSON body's `diagnostic` of any error linked from the throw,
+ * nearest first. Undefined when no answer names one, or the name is not a diagnostic's token.
+ * Read for a service failure (`serviceFailureType`), where the runner records it as the error's
+ * `cause`.
+ */
+export function serviceFailureCause(error) {
+    for (const item of linked(error)) {
+        try {
+            const diagnostic = diagnosticOf(item);
+            if (diagnostic !== undefined && DIAGNOSTIC.test(diagnostic))
+                return diagnostic;
+        }
+        catch {
+            // A property that throws when read names nothing.
+        }
+    }
+    return undefined;
+}

package/dist/evals/runner.js

@@ -6,7 +6,7 @@ import { ROOT_CONTEXT } from "@opentelemetry/api";
 import { HueExportError } from "../transport.js";
 import { HueApiError } from "./client.js";
 import { loadEnvironmentEvidence } from "./environment-evidence.js";
-import { serviceFailureType } from "./failure.js";
+import { serviceFailureCause, serviceFailureType } from "./failure.js";
 import { CheckpointStore } from "./checkpoint.js";
 import { onForcedExit } from "./exit-cleanup.js";
 import { assertSafeFileNames, downloadCaseFiles, downloadCaseInputs, localOutputFiles, verifyCaseFiles, OutputFileError, stageOutputFiles, targetFileRoles, uploadOutputFiles, } from "./files.js";
@@ -434,17 +434,26 @@ export async function runExperiment(options) {
         // A target stopped at its world's deadline is a `TargetTimeout`, told apart from an error the
         // target raised itself: the agent did not finish, rather than finishing wrongly. A service the
         // agent called that refused, dropped the connection or timed out is named apart from the
-        // agent's own error (`failure.ts`), so Hue counts it as infrastructure, not as the agent.
-        const errorPayload = (error) => ({
-            type: error instanceof OutputTooLargeError
-                ? "OutputTooLarge"
-                : error instanceof TargetTimeoutError
-                    ? "TargetTimeout"
-                    : (serviceFailureType(error) ?? "TargetError"),
-            ...(options.persistResultContent && error instanceof Error
-                ? { message: sanitize(error.message) }
-                : {}),
-        });
+        // agent's own error (`failure.ts`), so Hue counts it as infrastructure, not as the agent, with
+        // the service's own word for what failed as the error's `cause` when its answer names one
+        // (Hue's gateway diagnostic).
+        const errorPayload = (error) => {
+            const service = error instanceof OutputTooLargeError || error instanceof TargetTimeoutError
+                ? null
+                : serviceFailureType(error);
+            const cause = service ? serviceFailureCause(error) : undefined;
+            return {
+                type: error instanceof OutputTooLargeError
+                    ? "OutputTooLarge"
+                    : error instanceof TargetTimeoutError
+                        ? "TargetTimeout"
+                        : (service ?? "TargetError"),
+                ...(cause === undefined ? {} : { cause }),
+                ...(options.persistResultContent && error instanceof Error
+                    ? { message: sanitize(error.message) }
+                    : {}),
+            };
+        };
         /** Publish staged files, score with every verified file on disk and save the completion. */
         async function prepare(file, saved, frozenCase, caseDirectory, 
         /** The target's output, in memory when result content is not persisted. */

package/dist/evals/types.d.ts

@@ -546,6 +546,12 @@ export interface TypedError {
      * (`agent`, `infrastructure`, `configuration`, `telemetry` or `unsupported`), which Hue reads
      * only for a name it does not know. The SDK's own types need none. */
     class?: "agent" | "infrastructure" | "configuration" | "telemetry" | "unsupported";
+    /** For a service failure (`ServiceRefused`, `ConnectionFailed`, `TimedOut`,
+     * `ConfigurationRejected`): the service's own word for what failed, when its answer names one,
+     * such as Hue's gateway diagnostic (`authorization_unavailable`) from the answer's
+     * `x-hue-diagnostic` header or its JSON body's `diagnostic`. A short lower-case token; absent
+     * when the answer names none. */
+    cause?: string;
 }
 /** Input for {@link EvaluationClient.startExecution}. */
 export interface StartExecution {

package/dist/privacy.d.ts

@@ -2,8 +2,26 @@ import type { ReadableSpan } from "@opentelemetry/sdk-trace";
 import type { ReadableLogRecord } from "@opentelemetry/sdk-logs";
 import { type Resource } from "@opentelemetry/resources";
 import type { HueOptions } from "./types.js";
+import { truncateUtf8 } from "./safety.js";
+export { truncateUtf8 };
 /** Attribute keys (and their dotted children) removed in metadata-only mode. */
 export declare const contentPrefixes: string[];
+export declare function isContentKey(key: string): boolean;
+/** The record attribute listing the keys whose values were cut to fit Hue's 256 KiB value cap:
+ * Hue's receiver writes it for the values it cuts, and the SDK writes it for the values it cuts
+ * before export, under the same name, so a reader learns of a cut value from one place. */
+export declare const TRUNCATED_KEY = "hue.truncated";
+/** The size of a structured value the marker replaced. */
+export declare const TRUNCATED_BYTES_KEY = "hue.truncated_bytes";
+/** The root span attribute counting this trace's records the SDK could not export at all (a
+ * record over the request limit even with every content value shed, or one its queue had no
+ * room for): what Hue stores of the trace is incomplete by that many records. */
+export declare const DROPPED_RECORDS_KEY = "hue.sdk.dropped_records";
+/** Hue's receiver's own marker for a structured value it replaced: nothing of the value, its
+ * size, and the flag a reader tests. */
+export declare function truncatedMarker(bytes: number): Record<string, unknown>;
+/** `listed` with `keys` added, each once, in order. */
+export declare function withTruncatedKeys(listed: unknown, keys: readonly string[]): string[];
 export type ResourceCache = WeakMap<Resource, Resource>;
 export declare function redactSpan(span: ReadableSpan, options: HueOptions, cache: ResourceCache): ReadableSpan;
 export declare function redactLog(log: ReadableLogRecord, options: HueOptions, cache: ResourceCache): ReadableLogRecord;