@hue-run/sdk 0.17.0 → 0.18.1

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

package/dist/client.js

@@ -1,10 +1,10 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
-import { isMediaName } from "./inline-files.js";
+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";
@@ -13,7 +13,8 @@ import { hostedServerAddresses, hostedToolActivity, hostedToolProvider, provider
 import { toolCatalogSummary } from "./tool-definitions.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";
@@ -170,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
@@ -286,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();
@@ -535,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
@@ -799,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,
@@ -811,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);
@@ -75,6 +79,7 @@ export declare class EvaluationClient {
     }): Promise<Uint8Array>;
     /** Stage bytes at the storage capability Hue issued. The Hue key is never sent to storage. */
     uploadArtifactBytes(upload: ArtifactUpload, bytes: Uint8Array, contentType: string): Promise<void>;
+    private putArtifact;
     private page;
     private registryPage;
     /** Reads the current project to confirm the key and origin. */
@@ -97,7 +102,20 @@ 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. A file given by `path` is hashed a slice at
+     * a time when it is checked and read again when it is uploaded, one file at a time, so no more
+     * than one file is held in memory; only bytes that match the checked SHA-256 are sent.
+     *
+     * @throws TypeError or RangeError for `files` outside the artifact policy, or a case Hue would
+     * refuse for its fields or size, before any request. TypeError when a file given by `path`
+     * changed after it was checked, or can no longer be read, before any of its bytes are sent: it
+     * is not staged and the case is not written.
+     */
     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 {
@@ -360,17 +402,29 @@ export class EvaluationClient {
         }
     }
     /** Stage bytes at the storage capability Hue issued. The Hue key is never sent to storage. */
-    async uploadArtifactBytes(upload, bytes, contentType) {
+    uploadArtifactBytes(upload, bytes, contentType) {
+        return this.putArtifact(upload, contentType, bytes);
+    }
+    /** @internal Stage `byteSize` bytes read from `body` a slice at a time, without the copy a
+     * byte body is given; the request declares their length, as it does for bytes. */
+    uploadArtifactStream(upload, body, byteSize, contentType) {
+        return this.putArtifact(upload, contentType, body, byteSize);
+    }
+    async putArtifact(upload, contentType, body, byteSize) {
         const uploadUrl = signedUploadUrl(upload.uploadUrl);
         if (upload.method !== "PUT")
             throw new HueApiError();
         const headers = signedUploadHeaders(upload.headers, contentType);
+        // Storage refuses a body of unknown length, which a stream would otherwise be sent as.
+        if (byteSize !== undefined)
+            headers["content-length"] = String(byteSize);
         let response;
         try {
             response = await fetch(uploadUrl, {
                 method: "PUT",
                 headers,
-                body: bytes,
+                body,
+                ...(byteSize !== undefined ? { duplex: "half" } : {}),
                 redirect: "error",
                 signal: AbortSignal.timeout(Math.max(this.timeoutMillis, 120_000)),
             });
@@ -433,9 +487,35 @@ 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. A file given by `path` is hashed a slice at
+     * a time when it is checked and read again when it is uploaded, one file at a time, so no more
+     * than one file is held in memory; only bytes that match the checked SHA-256 are sent.
+     *
+     * @throws TypeError or RangeError for `files` outside the artifact policy, or a case Hue would
+     * refuse for its fields or size, before any request. TypeError when a file given by `path`
+     * changed after it was checked, or can no longer be read, before any of its bytes are sent: it
+     * is not staged and the case is not written.
+     */
+    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[];