@hue-run/sdk 0.16.0 → 0.18.0

package/dist/client.d.ts

@@ -127,6 +127,24 @@ export declare class HueClient {
         /** `gen_ai.request.model` for the record; defaults to the enclosing `model()` span's value. */
         model?: string;
     }, explicitContext?: Context): void;
+    /** Writes each attachment as its digest part, `null` for an invalid one, collecting them. */
+    private placer;
+    /**
+     * The files of the attachments a value placed that are uploaded: an invalid attachment, and
+     * an invalid name with content capture, count as instrumentation failures; nothing is uploaded
+     * without content capture or with setup credentials; a value that was `cut`, or a part deeper
+     * than Hue reads, keeps its digest part and counts as not uploaded.
+     */
+    private attachmentFiles;
+    /** Stages the attachments a span's `attribute` now holds, replacing its earlier ones. */
+    private stageAttachments;
+    /**
+     * Span attributes as recorded: a value that is an {@link Attachment}, an object or array holding
+     * one, or JSON data OpenTelemetry cannot hold as an attribute (an object, or an array that is not
+     * of one primitive type), becomes its JSON text with each attachment as its digest part (an
+     * invalid attachment alone is omitted); every other value is left to OpenTelemetry as given.
+     */
+    private attributeValues;
     /**
      * 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
@@ -149,13 +167,15 @@ export declare class HueClient {
      * 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
+     * uploaded only with `upload: true`. 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: 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;
+    /** Distinguishes requests whose helper events otherwise have identical metadata. */
+    private fileEventTimes;
     /** A content value's bounds: Hue's value cap as the receiver last advertised it. */
     private contentLimits;
     /**

package/dist/client.js

@@ -1,18 +1,20 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
+import { digestFormBytes, INLINE_FILE_TEXT_PER_RECORD, isMediaName } from "./inline-files.js";
 import { context, isSpanContextValid, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
 import { defaultTextMapGetter, defaultTextMapSetter } from "@opentelemetry/api";
 import { SeverityNumber } from "@opentelemetry/api-logs";
-import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { isAttributeValue, W3CTraceContextPropagator } from "@opentelemetry/core";
 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, providerErrorDescription, } from "./provider-tools.js";
 import { toolCatalogSummary } from "./tool-definitions.js";
-import { contentLimitsOf, encodeBoundedContent, encodeContent, noopSpan, safeSpan, } from "./safety.js";
+import { contentLimitsOf, encodeBoundedContent, encodeContent, noopSpan, safeSpan, spanSource, } from "./safety.js";
 import { TRUNCATED_KEY, withTruncatedKeys } from "./privacy.js";
-import { MAX_BLOB_BYTES } from "./blobs.js";
+import { countFallback, MAX_BLOB_BYTES, newTally } from "./blobs.js";
+import { attachmentPart, attachmentState, holdsAttachment, MAX_ATTACHMENT_DEPTH, } from "./attachment.js";
 import { createHueTransport, exportBudgetMillis, HueExportError, } from "./transport.js";
 import { verifyTrace } from "./receipt.js";
 import { sdkVersion } from "./version.js";
@@ -169,6 +171,19 @@ const OWNED_SPAN_LIMITS = {
 /** A provider tool listing's bounds before its catalog summary: one export request, 64 levels and
  * 65,536 values, as the Python SDK's content snapshot. */
 const catalogLimits = { bytes: MAX_BODY_BYTES, nodes: 65_536, depth: 64 };
+/** Whether a span attribute passed to a helper is recorded as JSON text: an attachment, a value
+ * holding one, or JSON data OpenTelemetry cannot hold as an attribute (a plain object, or an array
+ * that is not of one primitive type). */
+function recordedAsJson(value) {
+    if (holdsAttachment(value))
+        return true;
+    if (value === null || typeof value !== "object" || isAttributeValue(value))
+        return false;
+    if (Array.isArray(value))
+        return true;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
 /**
  * Hue tracing client. Helpers create spans through a private tracer and local async context, never
  * through global OpenTelemetry registration, and they fail open: capture problems are counted in
@@ -285,7 +300,10 @@ export class HueClient {
                     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));
+                const { attributes, placed } = this.attributeValues(options.attributes);
+                span = this.storage.run(active, () => this.tracer.startSpan(name, { kind: options.kind ?? SpanKind.INTERNAL, attributes }, active.context));
+                for (const [key, found] of placed)
+                    this.stageAttachments(span, key, found, this.captureContent);
             }
             catch {
                 this.instrumentationFailed();
@@ -534,18 +552,127 @@ export class HueClient {
             stamp("gen_ai.provider.name", messages.provider, enclosing?.model?.provider);
             stamp("gen_ai.request.model", messages.model, enclosing?.model?.requestModel);
             stamp("gen_ai.conversation.id", undefined, enclosing?.sessionId);
-            this.logger.emit({
-                context: active,
-                severityNumber: SeverityNumber.INFO,
-                eventName: "gen_ai.client.inference.operation.details",
-                attributes,
-                body: JSON.parse(encodeContent(body, this.contentLimits())),
-            });
+            // While media may be uploaded, the body may hold files past the value cap: it is emitted
+            // when it fits the cap with each file as its digest, and export uploads the files (under
+            // `body#<pointer>` keys) or cuts the body as before. Otherwise a body over the cap is
+            // refused, as before. Each attachment is written as its digest part.
+            const limits = this.contentLimits();
+            const placed = [];
+            const place = this.placer(placed, true);
+            let text;
+            if (this.transport.holdsValues()) {
+                text = encodeContent(body, { ...limits, bytes: limits.bytes + INLINE_FILE_TEXT_PER_RECORD }, place);
+                if (Buffer.byteLength(text) > limits.bytes &&
+                    digestFormBytes(JSON.parse(text)) > limits.bytes)
+                    throw new RangeError("Content limit exceeded");
+            }
+            else
+                text = encodeContent(body, limits, place);
+            const recorded = JSON.parse(text);
+            // Attachments in the body are staged with the body until this transport admits the record;
+            // export uploads them with the media the body holds.
+            const traceId = trace.getSpanContext(active).traceId;
+            const files = this.attachmentFiles(placed, true, "logs", traceId, false);
+            if (files.length)
+                this.transport.stageLogParts(recorded, traceId, files);
+            try {
+                this.logger.emit({
+                    context: active,
+                    severityNumber: SeverityNumber.INFO,
+                    eventName: "gen_ai.client.inference.operation.details",
+                    attributes,
+                    body: recorded,
+                });
+            }
+            finally {
+                this.transport.unstageLogParts(recorded);
+            }
         }
         catch {
             this.instrumentationFailed("logs");
         }
     }
+    /** Writes each attachment as its digest part, `null` for an invalid one, collecting them. */
+    placer(placed, captureContent) {
+        return (attachment, pointer, depth) => {
+            const state = attachmentState(attachment);
+            const part = attachmentPart(state, captureContent);
+            placed.push({ state, ...(part ? { part } : {}), pointer, depth });
+            return part ?? null;
+        };
+    }
+    /**
+     * The files of the attachments a value placed that are uploaded: an invalid attachment, and
+     * an invalid name with content capture, count as instrumentation failures; nothing is uploaded
+     * without content capture or with setup credentials; a value that was `cut`, or a part deeper
+     * than Hue reads, keeps its digest part and counts as not uploaded.
+     */
+    attachmentFiles(placed, captureContent, signal, traceId, cut) {
+        const files = [];
+        const tally = newTally();
+        for (const { state, part, depth } of placed) {
+            if (!part || !state.bytes || !state.sha256) {
+                this.instrumentationFailed(signal);
+                continue;
+            }
+            if (state.invalidName && captureContent)
+                this.instrumentationFailed(signal);
+            if (!this.transport.offloadsValues() || !state.bytes.byteLength)
+                continue;
+            if (cut || depth > MAX_ATTACHMENT_DEPTH) {
+                countFallback(tally, "budget", traceId);
+                continue;
+            }
+            files.push({
+                bytes: state.bytes,
+                digest: { sha256: state.sha256, size: state.bytes.byteLength },
+                contentType: state.contentType,
+                ...(state.name === undefined ? {} : { name: state.name }),
+            });
+        }
+        if (tally.fallbacks.size)
+            this.transport.reportOffload(tally, signal);
+        return files;
+    }
+    /** Stages the attachments a span's `attribute` now holds, replacing its earlier ones. */
+    stageAttachments(span, attribute, placed, captureContent, cut = false) {
+        const traceId = span.spanContext().traceId;
+        const files = this.attachmentFiles(placed, captureContent, "traces", traceId, cut);
+        if (span.isRecording())
+            this.transport.stageParts(span, attribute, files);
+    }
+    /**
+     * Span attributes as recorded: a value that is an {@link Attachment}, an object or array holding
+     * one, or JSON data OpenTelemetry cannot hold as an attribute (an object, or an array that is not
+     * of one primitive type), becomes its JSON text with each attachment as its digest part (an
+     * invalid attachment alone is omitted); every other value is left to OpenTelemetry as given.
+     */
+    attributeValues(input) {
+        const placed = [];
+        if (!input || typeof input !== "object")
+            return { attributes: input, placed };
+        let attributes;
+        for (const [key, value] of Object.entries(input)) {
+            if (!recordedAsJson(value))
+                continue;
+            attributes ??= { ...input };
+            const found = [];
+            try {
+                const text = encodeContent(value, this.contentLimits(), this.placer(found, this.captureContent));
+                if (text === "null")
+                    delete attributes[key];
+                else
+                    attributes[key] = text;
+            }
+            catch {
+                delete attributes[key];
+                this.instrumentationFailed();
+                continue;
+            }
+            placed.push([key, found]);
+        }
+        return { attributes: attributes ?? input, placed };
+    }
     /**
      * 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
@@ -662,7 +789,7 @@ export class HueClient {
      * 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
+     * uploaded only with `upload: true`. 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.
      */
@@ -680,26 +807,30 @@ export class HueClient {
                 throw new TypeError("Invalid media type");
             let sha256 = typeof file.sha256 === "string" ? file.sha256.toLowerCase() : file.sha256;
             let byteSize = file.byteSize;
+            let bytes;
             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
-                            : (() => {
+                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");
-                            })()
-                        : undefined;
+                            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");
+                const digest = bytes.byteLength > 0 && file.upload === true && this.transport.holdsValues()
+                    ? this.transport.digestMedia(bytes, span.spanContext().traceId).sha256
+                    : 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))
@@ -719,12 +850,55 @@ export class HueClient {
             if (byteSize !== undefined)
                 attributes["hue.file.size"] = byteSize;
             if (this.captureContent && name !== undefined) {
-                if (isLabel(name))
+                if (isMediaName(name))
                     attributes["hue.file.name"] = name;
                 else
                     this.instrumentationFailed();
             }
-            span.addEvent("hue.file", attributes);
+            // Let OpenTelemetry use the span's wall-clock anchor, then keep this event's exact
+            // timestamp for upload admission. A dropped event cannot authorize an upload.
+            const source = spanSource(span);
+            const previous = this.fileEventTimes.get(source);
+            const after = (time) => {
+                if (previous &&
+                    (time[0] < previous[0] || (time[0] === previous[0] && time[1] <= previous[1]))) {
+                    time[0] = previous[0];
+                    time[1] = previous[1] + 1;
+                    if (time[1] === 1_000_000_000) {
+                        time[0]++;
+                        time[1] = 0;
+                    }
+                }
+                return time;
+            };
+            let eventTime;
+            if (Array.isArray(source.events)) {
+                const previousEvent = source.events.at(-1);
+                span.addEvent("hue.file", attributes);
+                const event = source.events.at(-1);
+                eventTime = event && event !== previousEvent ? after(event.time) : undefined;
+            }
+            else {
+                // A span that does not expose its events (an API-only wrapper in attach mode): stamp the
+                // event with the wall clock and keep that exact time for upload admission.
+                const now = Date.now();
+                eventTime = after([Math.floor(now / 1000), (now % 1000) * 1_000_000]);
+                span.addEvent("hue.file", attributes, [eventTime[0], eventTime[1]]);
+            }
+            if (eventTime)
+                this.fileEventTimes.set(source, eventTime);
+            if (file.upload === true && this.transport.offloadsValues()) {
+                if (!this.transport.stageMedia(span, bytes && eventTime
+                    ? {
+                        bytes,
+                        digest: { sha256, size: bytes.byteLength },
+                        contentType: mediaType,
+                        eventTime,
+                        ...(isMediaName(name) ? { name } : {}),
+                    }
+                    : undefined))
+                    this.instrumentationFailed();
+            }
         }
         catch {
             this.instrumentationFailed();
@@ -732,6 +906,8 @@ export class HueClient {
     }
     /** The keys of each span's content values that were cut to Hue's value cap, for `hue.truncated`. */
     truncatedKeys = new WeakMap();
+    /** Distinguishes requests whose helper events otherwise have identical metadata. */
+    fileEventTimes = new WeakMap();
     /** A content value's bounds: Hue's value cap as the receiver last advertised it. */
     contentLimits() {
         return contentLimitsOf(this.transport.receiverLimits().valueBytes);
@@ -749,10 +925,17 @@ export class HueClient {
         if (!this.enabled || this.closed || !this.captureContent)
             return;
         try {
+            const encode = (limits) => {
+                const placed = [];
+                return {
+                    ...encodeBoundedContent(value, limits, true, this.placer(placed, true)),
+                    placed,
+                };
+            };
             let encoded;
             if (this.transport.holdsValues())
                 try {
-                    encoded = encodeBoundedContent(value, {
+                    encoded = encode({
                         ...this.contentLimits(),
                         bytes: MAX_BLOB_BYTES,
                         nodes: MAX_RECORD_NODES,
@@ -761,8 +944,10 @@ export class HueClient {
                 catch {
                     // Past the runtime's longest string, or its memory: cut to the cap instead.
                 }
-            const { text, truncated } = encoded ?? encodeBoundedContent(value, this.contentLimits());
+            const { text, truncated, placed } = encoded ?? encode(this.contentLimits());
             span.setAttribute(key, text);
+            // The attachments the value holds are staged for upload in place of any it held before.
+            this.stageAttachments(span, key, placed, true, truncated);
             // 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) ?? []);

package/dist/evals/client.d.ts

@@ -1,4 +1,5 @@
 import type { ProjectConnection } from "../types.js";
+import { MediaClient } from "./media.js";
 import { type AttemptConnectionBundleV2, type PrepareAttemptRequestV2 } from "./attempt.js";
 import type { ArtifactReservation, ArtifactUpload, CaseConversion, CaseConversionSummary, CaseWrite, CompleteExecution, Completion, Dataset, DatasetCase, DatasetVersion, EvalSet, EvalSetCase, EvalSetVersion, EvaluationItem, EvaluationRun, EvaluationRunSummary, EnvironmentEvidenceSnapshot, Execution, Experiment, ExperimentCase, ExperimentItem, Evaluator, EvaluatorVersion, JsonValue, LocalAgentClaim, LocalAgentRegistration, RegisteredLocalAgent, JudgeBudget, JudgeJob, Page, PageOptions, RegistryPageOptions, Result, ResultSummary, Run, RunCase, Scorer, ScorerDefinition, ScorerVersion, Scoring, ScoringResultInput, ScoringResultSummary, ScoringSubject, ScoringSummary, SimulationMcpCapability, StartExecution, Subject, StoredResult, StoredScoringResult, IdentityUpdate, Tag, TaggedIdentity, UpdatedRun } from "./types.js";
 /** Connection options for {@link createEvaluationClient}. */
@@ -59,6 +60,9 @@ export declare class EvaluationClient {
     #private;
     /** Validated Hue origin. */
     readonly baseUrl: string;
+    /** Recorded media read back by digest: one file (`fetch`) or every digest part of a recorded
+     * value (`resolve`). Needs a key that may read recorded content (Read, or Read and write). */
+    readonly media: MediaClient;
     private readonly timeoutMillis;
     private readonly maxAttempts;
     constructor(options: EvaluationClientOptions);
@@ -97,7 +101,16 @@ export declare class EvaluationClient {
     getDatasetVersion(id: string): Promise<DatasetVersion>;
     /** Lists the full cases of a dataset version; use small page limits for large values. */
     listCases(id: string, page?: PageOptions): Promise<Page<DatasetCase>>;
-    /** Adds a case to a draft version using optimistic concurrency on `expectedRevision`. */
+    /**
+     * Adds a case to a draft version using optimistic concurrency on `expectedRevision`. Each of
+     * `files` given as bytes or a path is checked against the artifact policy and uploaded as a
+     * verified artifact first, under a key derived from the version, the case's `externalKey`, the
+     * role and the bytes, so sending the same case again reuses the artifact. Every file and the
+     * case itself are checked before the first upload.
+     *
+     * @throws TypeError or RangeError for `files` outside the artifact policy, or a case Hue would
+     * refuse for its fields or size, before any request.
+     */
     addCase(id: string, input: CaseWrite): Promise<{
         /** The stored case. */
         item: DatasetCase;

package/dist/evals/client.js

@@ -1,5 +1,6 @@
 import { isLoopbackHost, validateOptions } from "../config.js";
 import { json, uuid, valueBounds } from "./json.js";
+import { MediaClient } from "./media.js";
 import { attemptBindingRead, parsePrepareAttemptResultV2, parseRefreshedAttemptResultV2, parseRevocationResult, prepareAttemptInputV2, validateAttemptConnectionBundleV2, } from "./attempt.js";
 /** Thrown for a failed evaluation API request; the message is fixed and never includes response text. */
 export class HueApiError extends Error {
@@ -149,6 +150,42 @@ function productRunFields(value, kind) {
         result.scoring = result.evaluation;
     return result;
 }
+/** The bounds of a request body as a whole: 1 MiB, with each value's node and depth bounds. */
+const REQUEST_BOUNDS = { ...valueBounds, bytes: 1024 * 1024 };
+/** A request body as it is sent: checked as JSON within `bounds`. Optional top-level fields are
+ * omitted intentionally; nested undefined remains invalid. */
+function payloadOf(body, bounds) {
+    return JSON.stringify(json(Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined)), bounds));
+}
+/**
+ * Checks what a case write's fields can be checked for here, as Hue checks them: a positive
+ * integer `expectedRevision`, an `externalKey` of 1–200 UTF-16 code units of well-formed text
+ * without NUL, `inputs`, `expected` and an object `metadata` within one value's JSON bounds, and an
+ * `environmentVersionId` that is a UUID or null.
+ */
+function checkCaseWrite(input) {
+    if (!input || typeof input !== "object")
+        throw new TypeError("A case write must be an object");
+    if (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 1)
+        throw new TypeError("expectedRevision must be a positive integer");
+    const key = input.externalKey;
+    if (typeof key !== "string" ||
+        !key.length ||
+        key.length > 200 ||
+        !key.isWellFormed() ||
+        key.includes("\u0000"))
+        throw new TypeError("externalKey must be 1–200 UTF-16 code units of well-formed text");
+    json(input.inputs, valueBounds);
+    if (input.expected !== undefined)
+        json(input.expected, valueBounds);
+    if (input.metadata !== undefined) {
+        if (!input.metadata || typeof input.metadata !== "object" || Array.isArray(input.metadata))
+            throw new TypeError("metadata must be an object");
+        json(input.metadata, valueBounds);
+    }
+    if (input.environmentVersionId !== undefined && input.environmentVersionId !== null)
+        uuid(input.environmentVersionId);
+}
 /** Times a refused request is sent again before its refusal is the caller's error. */
 const REFUSAL_RETRIES = 4;
 /** A refusal asking for a longer wait fails at once rather than holding the caller. */
@@ -183,6 +220,9 @@ function refusalRetryAfter(response) {
 export class EvaluationClient {
     /** Validated Hue origin. */
     baseUrl;
+    /** Recorded media read back by digest: one file (`fetch`) or every digest part of a recorded
+     * value (`resolve`). Needs a key that may read recorded content (Read, or Read and write). */
+    media;
     #apiKey;
     timeoutMillis;
     maxAttempts;
@@ -199,6 +239,11 @@ export class EvaluationClient {
         if (!Number.isInteger(attempts) || attempts < 1 || attempts > 10)
             throw new RangeError("maxAttempts must be 1–10");
         this.maxAttempts = attempts;
+        this.media = new MediaClient({
+            baseUrl: this.baseUrl,
+            apiKey: validated.apiKey,
+            timeoutMillis: this.timeoutMillis,
+        });
     }
     /** Sends one request to Hue, again after the wait while Hue refuses it with a short
      * `Retry-After`. `init` runs for every attempt, so each has its own timeout; `signal` also ends
@@ -235,15 +280,12 @@ export class EvaluationClient {
                 throw new HueApiError(response.status, askedRetryAfter(response));
         }
     }
-    async request(method, path, body, bounds = { ...valueBounds, bytes: 1024 * 1024 }, signal, 
+    async request(method, path, body, bounds = REQUEST_BOUNDS, signal, 
     /** Overrides the retry decision `retryable` takes from the method and body. */
     idempotent) {
         // Serialized once, outside the attempts: a body this client cannot encode is a caller error
-        // no attempt fixes. Optional top-level fields are omitted intentionally; nested undefined
-        // remains invalid.
-        const payload = body === undefined
-            ? undefined
-            : JSON.stringify(json(Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined)), bounds));
+        // no attempt fixes.
+        const payload = body === undefined ? undefined : payloadOf(body, bounds);
         const attempts = retryable(method, body, idempotent) ? this.maxAttempts : 1;
         for (let attempt = 1;; attempt++) {
             try {
@@ -433,9 +475,31 @@ export class EvaluationClient {
     listCases(id, page) {
         return this.request("GET", `/dataset-versions/${uuid(id)}/cases${this.page(page)}`);
     }
-    /** Adds a case to a draft version using optimistic concurrency on `expectedRevision`. */
-    addCase(id, input) {
-        return this.request("POST", `/dataset-versions/${uuid(id)}/cases`, input);
+    /**
+     * Adds a case to a draft version using optimistic concurrency on `expectedRevision`. Each of
+     * `files` given as bytes or a path is checked against the artifact policy and uploaded as a
+     * verified artifact first, under a key derived from the version, the case's `externalKey`, the
+     * role and the bytes, so sending the same case again reuses the artifact. Every file and the
+     * case itself are checked before the first upload.
+     *
+     * @throws TypeError or RangeError for `files` outside the artifact policy, or a case Hue would
+     * refuse for its fields or size, before any request.
+     */
+    async addCase(id, input) {
+        // The canonical spelling: the reservation keys of uploaded files name the version.
+        const versionId = uuid(id).toLowerCase();
+        checkCaseWrite(input);
+        let body = input;
+        if (input.files !== undefined) {
+            // Loaded on use: the artifact helpers import this client.
+            const { caseFileReferences } = await import("./files.js");
+            body = {
+                ...input,
+                // The case is checked as it will be sent, with a stand-in for each upload's artifact.
+                files: await caseFileReferences(this, versionId, input, (files) => payloadOf({ ...input, files }, REQUEST_BOUNDS)),
+            };
+        }
+        return this.request("POST", `/dataset-versions/${versionId}/cases`, body);
     }
     /** Freezes a draft version at the given revision; frozen versions are immutable. */
     freezeDatasetVersion(id, expectedRevision) {

package/dist/evals/files.d.ts

@@ -1,5 +1,5 @@
 import { type EvaluationClient } from "./client.js";
-import type { CaseFile, LocalFile, OutputFile, SubjectFile } from "./types.js";
+import type { CaseFile, CaseFileReference, CaseWrite, LocalFile, OutputFile, SubjectFile } from "./types.js";
 /** Roles the target receives. Organization templates stay with grading, as in the managed protocol. */
 export declare const targetFileRoles: readonly CaseFile["role"][];
 /** Hue's artifact policy: the pilot file size and the accepted document types. */
@@ -112,5 +112,15 @@ export declare const artifactSettling: {
  * finished verifying after an earlier attempt stopped waiting.
  */
 export declare function uploadOutputFiles(client: EvaluationClient, executionId: string, files: StagedOutputFile[], save: () => Promise<void>, timing?: typeof artifactSettling): Promise<void>;
+/**
+ * The `files` of a case write as the case API takes them: references kept, and each file given
+ * as bytes or a path checked against the artifact policy (role, name, one of
+ * `outputContentTypes`, 1 byte to 25 MiB) and uploaded as a verified artifact. Every file is
+ * checked, and then `beforeUpload` is given the references with a stand-in ID for each upload,
+ * before the first upload. The reservation key names the version, the case's `externalKey`, the
+ * role and the bytes, so the same write sent again reuses its artifacts. Each artifact is pinned
+ * once with a role, even when a reference names the artifact a file was uploaded as.
+ */
+export declare function caseFileReferences(client: EvaluationClient, versionId: string, input: CaseWrite, beforeUpload?: (references: CaseFileReference[]) => void, timing?: typeof artifactSettling): Promise<CaseFileReference[]>;
 /** Project uploaded staged files as the verified local files handed to scorers. */
 export declare function localOutputFiles(files: StagedOutputFile[]): LocalFile[];