@hue-run/sdk 0.12.0 → 0.13.0

package/dist/evals/failure.js

@@ -0,0 +1,252 @@
+import { HueConnectionError } from "../client.js";
+import { HueEnvironmentError } from "../environment/client.js";
+import { HueApiError } from "./client.js";
+const TIMEOUT_NAMES = new Set(["TimeoutError", "APIConnectionTimeoutError", "APITimeoutError"]);
+/** Node's and Undici's codes for a call that timed out, connecting or waiting on the answer. */
+const TIMEOUT_CODES = new Set([
+    "ETIMEDOUT",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+]);
+const NETWORK_CODES = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EPIPE",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "UND_ERR_SOCKET",
+]);
+/** Links followed from the thrown error, and errors read at most. */
+const MAX_DEPTH = 6;
+const MAX_ERRORS = 64;
+/** The errors an error links to: its `cause`, and the `errors` and `lastError` of an
+ * `AggregateError` or a retry error. A property that throws when read links nothing. */
+function links(error) {
+    try {
+        const { cause, lastError, errors } = error;
+        return [cause, lastError, ...(Array.isArray(errors) ? errors.slice(0, MAX_ERRORS) : [])];
+    }
+    catch {
+        return [];
+    }
+}
+/** The thrown error and every error within `MAX_DEPTH` links of it, each once, so a cycle ends
+ * the walk. */
+function linked(error) {
+    const found = [];
+    const seen = new Set();
+    let level = [error];
+    for (let depth = 0; depth <= MAX_DEPTH && level.length; depth++) {
+        const next = [];
+        for (const item of level) {
+            if (typeof item !== "object" || item === null || seen.has(item))
+                continue;
+            if (found.length === MAX_ERRORS)
+                return found;
+            seen.add(item);
+            found.push(item);
+            next.push(...links(item));
+        }
+        level = next;
+    }
+    return found;
+}
+/** The error's `name` and its class names, since some SDKs never set `name`. */
+function names(error) {
+    const found = [];
+    const name = error.name;
+    if (typeof name === "string")
+        found.push(name);
+    let prototype = Object.getPrototypeOf(error);
+    for (let depth = 0; depth < MAX_DEPTH && prototype; depth++) {
+        const constructor = prototype.constructor;
+        if (typeof constructor?.name === "string")
+            found.push(constructor.name);
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    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) {
+    const { code } = error;
+    return ((typeof code === "string" && TIMEOUT_CODES.has(code)) ||
+        names(error).some((name) => TIMEOUT_NAMES.has(name)));
+}
+/** An error one of Hue's own clients threw, which carries the status Hue answered or none. */
+function hueClientError(error) {
+    return (error instanceof HueConnectionError ||
+        error instanceof HueEnvironmentError ||
+        error instanceof HueApiError);
+}
+function disconnected(error) {
+    // Hue's clients report a request that got no usable response without a status.
+    if (hueClientError(error) && error.status === undefined)
+        return true;
+    const { code, message } = error;
+    const classes = names(error);
+    return ((typeof code === "string" && NETWORK_CODES.has(code)) ||
+        classes.includes("APIConnectionError") ||
+        (classes.includes("TypeError") && message === "fetch failed"));
+}
+/** A retryable status a service answered with: on Hue's own clients, or on an error that also
+ * carries the exchange it came from (the OpenAI and Anthropic SDKs' `headers`, the AI SDK's
+ * `url` or `responseHeaders`, a fetch `response`), so an agent's own error that only names a
+ * status stays the agent's. */
+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.
+    const answered = response !== null && typeof response === "object"
+        ? response
+        : {};
+    return (exchanged &&
+        (retryable(status) ||
+            retryable(statusCode) ||
+            retryable(answered.status) ||
+            retryable(answered.statusCode)));
+}
+/** A status Hue's own client answered with that is neither a success nor retryable, a 3xx or a
+ * 4xx: Hue refused the caller's key, project, environment version or world, so the case could
+ * not run as configured. The clients fetch with `redirect: "error"`, so a redirect reaches here
+ * only as a status some caller constructed; a real one surfaces without a status, as a failed
+ * connection. Only Hue's clients show it; another service's 4xx stays the agent's. */
+function rejected(error) {
+    const { status } = error;
+    return (hueClientError(error) &&
+        typeof status === "number" &&
+        status >= 300 &&
+        status < 500 &&
+        !retryable(status));
+}
+/** Whether any error shows the signal; one whose properties throw when read shows none. */
+const any = (errors, signal) => errors.some((error) => {
+    try {
+        return signal(error);
+    }
+    catch {
+        return false;
+    }
+});
+/** 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 function serviceFailureType(error) {
+    const errors = linked(error);
+    if (any(errors, timedOut))
+        return "TimedOut";
+    if (any(errors, disconnected))
+        return "ConnectionFailed";
+    if (any(errors, refused))
+        return "ServiceRefused";
+    if (any(errors, rejected))
+        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/local-worker.d.ts

@@ -104,7 +104,7 @@ export interface RunLocalAgentOptions {
     concurrency?: number;
     /** What a case does when its telemetry is not accepted; see
      * `traceNotAccepted` of {@link runExperiment}. Defaults to `"stop"`. */
-    traceNotAccepted?: "stop" | "fail_case";
+    traceNotAccepted?: "stop" | "fail_case" | "pending";
     /** Called as each case is failed for its telemetry; see `onTelemetryNotAccepted` of
      * {@link runExperiment}. */
     onTelemetryNotAccepted?(entry: TelemetryNotAccepted): void | Promise<void>;

package/dist/evals/runner.d.ts

@@ -123,9 +123,13 @@ export interface RunExperimentOptions extends RunnerOptions {
      * rejects. `"fail_case"` completes the execution as failed instead, with the evidence omitted
      * under the reason `telemetry_not_accepted` and without its output or generated files, so no
      * scorer can pass it; reports it in {@link RunnerReport.telemetryNotAccepted} and goes on with
-     * the other cases.
+     * the other cases. `"pending"` completes the execution in its true state with
+     * `traceEvidence: "pending"` and the count of spans the case ended: Hue scores the sealed world
+     * at once and attaches the trace once it holds every span, or records the evidence omitted a
+     * day later; reports it in {@link RunnerReport.tracePending} and goes on. A saved outcome whose
+     * export the receipt does not accept on resume completes the same way.
      */
-    traceNotAccepted?: "stop" | "fail_case";
+    traceNotAccepted?: "stop" | "fail_case" | "pending";
     /** Called when this call completes a case as failed under `traceNotAccepted: "fail_case"`,
      * before the run goes on, so the failure is known even if a later case stops the run. A call
      * that resumes an already completed case lists it in the report without calling again. */
@@ -152,6 +156,21 @@ export interface RunnerReport {
     /** Cases completed as failed because their telemetry was not accepted, under
      * `traceNotAccepted: "fail_case"`; absent when there were none. */
     telemetryNotAccepted?: TelemetryNotAccepted[];
+    /** Cases completed with their trace evidence pending, under `traceNotAccepted: "pending"`;
+     * absent when there were none. */
+    tracePending?: TracePending[];
+}
+/** A case completed with its trace still to arrive. */
+export interface TracePending {
+    /** Frozen case ID. */
+    caseId: string;
+    /** The case's external key. */
+    caseKey: string;
+    /** Execution completed pending. */
+    executionId: string;
+    /** How many spans the case ended, which Hue holds the arriving trace to; absent when the
+     * checkpoint recorded no count. */
+    spanCount?: number;
 }
 /** Export issue counts, never content: which signal, what happened, the HTTP status when Hue
  * answered, and how many records. */

package/dist/evals/runner.js

@@ -6,6 +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 { 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";
@@ -252,6 +253,20 @@ async function pool(items, concurrency, execute) {
 /** Whether Hue holds the case's telemetry, read from the trace receipt: its root span and at
  * least as many spans as the case ended; false when they are not there by the wait's end or the
  * receipt cannot be read, and for a checkpoint an older runner saved without the span. */
+/** Turn a prepared completion into a pending one: the trace is declared but still to arrive,
+ * and the span count the checkpoint recorded at the flush goes with it, so Hue freezes the trace
+ * only once it holds every span the case ended, never a root span alone. */
+function pendingCompletion(prepared) {
+    prepared.complete.traceEvidence = "pending";
+    delete prepared.complete.omissionReason;
+    if (prepared.trace?.spans !== undefined)
+        prepared.complete.traceSpanCount = prepared.trace.spans;
+}
+/** The reverse, once the receipt accepted the trace after all: required evidence, no count. */
+function acceptedCompletion(prepared) {
+    prepared.complete.traceEvidence = "required";
+    delete prepared.complete.traceSpanCount;
+}
 async function traceLanded(hue, trace) {
     // Without the count of spans the case ended, the receipt cannot tell a lost child span from a
     // landed trace, and does not accept.
@@ -417,17 +432,28 @@ export async function runExperiment(options) {
         const filesRoot = resolve(options.filesDirectory ?? join(options.checkpointDirectory, "files"));
         const sanitize = (message) => message.slice(0, 4000).toWellFormed().replaceAll("\u0000", "");
         // 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.
-        const errorPayload = (error) => ({
-            type: error instanceof OutputTooLargeError
-                ? "OutputTooLarge"
-                : error instanceof TargetTimeoutError
-                    ? "TargetTimeout"
-                    : "TargetError",
-            ...(options.persistResultContent && error instanceof Error
-                ? { message: sanitize(error.message) }
-                : {}),
-        });
+        // 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, 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. */
@@ -707,7 +733,15 @@ export async function runExperiment(options) {
                     if (options.traceEvidence.mode !== "omit")
                         throw error;
                 }
-                if (exportError !== undefined && options.traceEvidence.mode !== "omit") {
+                if (exportError !== undefined &&
+                    options.traceEvidence.mode !== "omit" &&
+                    options.traceNotAccepted === "pending") {
+                    // The outcome stands as the target gave it; Hue attaches the trace once it holds
+                    // every span the case ended, which the checkpoint's count tells it.
+                    pendingCompletion(checkpoint);
+                    await store.write(file, checkpoint);
+                }
+                else if (exportError !== undefined && options.traceEvidence.mode !== "omit") {
                     if (options.traceNotAccepted !== "fail_case")
                         throw exportError;
                     // Required evidence that Hue did not accept fails the case rather than leaving its
@@ -746,9 +780,26 @@ export async function runExperiment(options) {
                 prepared.complete.traceEvidence !== "omit" &&
                 (await traceLanded(options.hue, prepared.trace))) {
                 prepared.exportState = "accepted";
+                // A completion made pending by an earlier receipt read is required again: the trace
+                // landed, so Hue freezes it at completion as for any accepted case.
+                if (prepared.complete.traceEvidence === "pending")
+                    acceptedCompletion(prepared);
                 await store.write(file, prepared);
             }
-            if (prepared.exportState !== "accepted" && prepared.complete.traceEvidence !== "omit")
+            // Under the pending policy a saved outcome the receipt does not accept, whether no flush
+            // decided it or an export failure named its trace, completes with the trace pending rather
+            // than being refused: Hue attaches the trace when it arrives in full.
+            if (options.traceNotAccepted === "pending" &&
+                prepared.exportState !== "accepted" &&
+                prepared.exportState !== "not_accepted" &&
+                prepared.complete.traceEvidence !== "omit" &&
+                prepared.complete.traceEvidence !== "pending") {
+                pendingCompletion(prepared);
+                await store.write(file, prepared);
+            }
+            if (prepared.exportState !== "accepted" &&
+                prepared.complete.traceEvidence !== "omit" &&
+                prepared.complete.traceEvidence !== "pending")
                 throw new TraceExportUnacknowledgedError(prepared.executionId);
             const save = () => store.write(file, prepared);
             const notAccepted = prepared.exportState === "not_accepted"
@@ -770,6 +821,15 @@ export async function runExperiment(options) {
             }
             if (notAccepted)
                 (report.telemetryNotAccepted ??= []).push(notAccepted);
+            if (prepared.complete.traceEvidence === "pending")
+                (report.tracePending ??= []).push({
+                    caseId: item.id,
+                    caseKey: item.externalKey,
+                    executionId: prepared.executionId,
+                    ...(prepared.complete.traceSpanCount !== undefined
+                        ? { spanCount: prepared.complete.traceSpanCount }
+                        : {}),
+                });
             const results = await uploadScores(options, experiment.evaluation.id, prepared.scores, save, versions);
             report.subjectIds.push(prepared.completion.subjectId);
             report.resultIds.push(...results);

package/dist/evals/simulation.d.ts

@@ -160,7 +160,7 @@ export interface RunSimulationOptions {
     };
     /** What a case does when required telemetry is not accepted; see
      * `traceNotAccepted` of {@link runExperiment}. Defaults to `"stop"`. */
-    traceNotAccepted?: "stop" | "fail_case";
+    traceNotAccepted?: "stop" | "fail_case" | "pending";
     /** Called as each case is failed for its telemetry; see `onTelemetryNotAccepted` of
      * {@link runExperiment}. */
     onTelemetryNotAccepted?(entry: TelemetryNotAccepted): void | Promise<void>;

package/dist/evals/types.d.ts

@@ -542,6 +542,16 @@ export interface TypedError {
     type: string;
     /** Optional message; stored only when result content is persisted. */
     message?: string;
+    /** For a runner of your own that writes a `type` of its own: the class Hue files it under
+     * (`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 {
@@ -570,10 +580,13 @@ export interface CompleteExecution {
     error?: TypedError;
     /** Trace revision the stored snapshot must have reached. */
     expectedTraceRevision?: number;
-    /** Whether stored trace evidence is required or explicitly omitted. */
-    traceEvidence?: "required" | "omit";
+    /** Whether stored trace evidence is required, explicitly omitted, or pending: declared and
+     * still to arrive, which Hue attaches once the export is complete. */
+    traceEvidence?: "required" | "omit" | "pending";
     /** Why trace evidence was omitted. */
     omissionReason?: string;
+    /** With `pending`: how many spans the case ended, which Hue holds the arriving trace to. */
+    traceSpanCount?: number;
 }
 /** Result of {@link EvaluationClient.completeExecution}. */
 export interface Completion {
@@ -633,8 +646,9 @@ export interface Subject {
     experimentId: string;
     /** Attempt number of the execution. */
     attempt: number;
-    /** Whether trace evidence was captured, omitted with a reason or not requested. */
-    traceEvidence: "captured" | "omitted" | "not_requested";
+    /** Whether trace evidence was captured, omitted with a reason, not requested, or is pending
+     * (declared and still to arrive; Hue attaches it once the export is complete). */
+    traceEvidence: "captured" | "omitted" | "not_requested" | "pending";
     /** Declared OpenTelemetry trace ID, or `null`. */
     traceExternalId: string | null;
     /** Reason trace evidence was omitted, or `null`. */

package/dist/evals.d.ts

@@ -1,7 +1,7 @@
 export { ArtifactSizeError, createEvaluationClient, EvaluationClient, HueApiError, isTransientApiError, } from "./evals/client.js";
 export type { EvaluationClientOptions } from "./evals/client.js";
 export { runExperiment, rescore, UncertainExecutionError, OutcomeSerializationError, TargetCancelledError, TargetOutcomeUncertainError, TargetTimeoutError, TraceExportUnacknowledgedError, } from "./evals/runner.js";
-export type { RunExperimentOptions, RunExperimentTargetContext, RescoreOptions, RunnerReport, TelemetryIssueCount, TelemetryNotAccepted, } from "./evals/runner.js";
+export type { RunExperimentOptions, RunExperimentTargetContext, RescoreOptions, RunnerReport, TelemetryIssueCount, TelemetryNotAccepted, TracePending, } from "./evals/runner.js";
 export { TargetResult, withFiles } from "./evals/types.js";
 export { CaseFileError, outputContentTypes, outputFileLimits, OutputFileError, safeFilename, targetFileRoles, } from "./evals/files.js";
 export type { CaseFileErrorCode } from "./evals/files.js";

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;