@hue-run/sdk 0.16.0 → 0.17.0

package/dist/blobs.js

@@ -2,19 +2,17 @@ import { createHash } from "node:crypto";
 import { context } from "@opentelemetry/api";
 import { suppressTracing } from "@opentelemetry/core";
 import { isLoopbackHost } from "./config.js";
-import { digestPart, hashInlineFiles, INLINE_FILE_LIMIT, INLINE_FILE_TEXT_PER_RECORD, inlineFileBytes, isMessageKey, largeInlineFileParts, MAX_INLINE_FILE_TEXT, } from "./inline-files.js";
+import { digestPart, hashInlineFiles, INLINE_FILE_LIMIT, INLINE_FILE_TEXT_PER_RECORD, mediaBytes, mediaContentType, isTextMediaType, mayInlineFiles, isMediaContentType, largeInlineFileParts, MAX_INLINE_FILE_TEXT, } from "./inline-files.js";
 import { TRUNCATED_KEY, truncatedMarker, withTruncatedKeys } from "./privacy.js";
 import { truncateUtf8 } from "./safety.js";
 /**
- * Values larger than Hue's inline limit travel apart from their span: the SDK uploads the value's
- * bytes straight to the project's evidence store through a presigned PUT that Hue answers at
- * `POST /api/v1/otlp/blobs`, keeps the value's first 16 KiB in the attribute it replaced, and
- * lists the value in the span attribute `hue.blobs`. A value that cannot be uploaded is exported
- * as it was before uploads existed: cut to the inline limit and listed under `hue.truncated` (an
- * inline file as its digest), reported as a warning and counted.
+ * Large values and binary media travel apart from their span through reservation, presigned PUT,
+ * and completion. Text keeps a 16 KiB prefix. Binary media keeps digest metadata on its part.
+ * Successful uploads are listed in `hue.blobs`; failures keep inline fallback or file metadata,
+ * are reported as warnings, and are counted.
  */
 /** The span attribute listing the values the SDK uploaded apart from the span: one compact JSON
- * object per value, `{"key", "sha256", "size", "content_type"}`, as Hue reads it. */
+ * object per value, `{"key", "sha256", "size", "content_type"}`, with an optional `name`. */
 export const BLOBS_KEY = "hue.blobs";
 /** The largest value one upload may hold (`Hue-Max-Blob-Bytes`): a larger value is cut inline. */
 export const MAX_BLOB_BYTES = 1_000_000_000;
@@ -50,28 +48,23 @@ export function uploadBudgetMillis(timeoutMillis) {
 }
 /** The fixed description of each fallback, as an export issue reports it. */
 export const FALLBACK_MESSAGES = {
-    unsupported: "This Hue server does not accept uploaded values; values over its inline limit were exported cut to it (inline files as their digest)",
-    failed: "Values over Hue's inline limit could not be uploaded; they were exported cut to it (inline files as their digest)",
-    tooLarge: "Values over Hue's 1 GB upload limit were exported cut to the inline limit",
-    budget: "Values over Hue's inline limit did not fit the SDK's upload budget; they were exported cut to it (inline files as their digest)",
+    unsupported: "This Hue server does not accept uploaded values; large values were cut inline and media kept digest metadata",
+    failed: "Content could not be uploaded; large values were cut inline and media kept digest metadata",
+    tooLarge: "Content over its upload limit kept inline fallback or file metadata",
+    budget: "Content did not fit the SDK's upload budget; large values were cut inline and media kept digest metadata",
 };
 export function newTally() {
     return { uploaded: 0, fallbacks: new Map() };
 }
-function countFallback(tally, reason, traceId) {
+export function countFallback(tally, reason, traceId) {
     const entry = tally.fallbacks.get(reason) ?? { count: 0, traceIds: new Set() };
     entry.count++;
     entry.traceIds.add(traceId);
     tally.fallbacks.set(reason, entry);
 }
-/** A media type Hue accepts for a value: `type/subtype` with optional parameters, 3 to 255
- * printable ASCII characters. */
-const CONTENT_TYPE = /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9!#$&^_.+-]+(?: *;[ -~]*)?$/;
+/** A media type accepted by the upload contract. */
 export function isBlobContentType(value) {
-    return (typeof value === "string" &&
-        value.length >= 3 &&
-        value.length <= 255 &&
-        CONTENT_TYPE.test(value));
+    return isMediaContentType(value);
 }
 function isBlobKey(key) {
     if (key.length < 1 || key.length > MAX_BLOB_KEY_LENGTH)
@@ -93,16 +86,6 @@ export function textContentType(text) {
         ? "application/json"
         : "text/plain; charset=utf-8";
 }
-/** The media type an inline file is stored under: the part's own (`mime_type`, `mediaType`), its
- * `data:` URL's, or else bytes, or UTF-8 text for content that was not encoded. */
-function fileContentType(part, file) {
-    for (const declared of [part.mime_type, part.mimeType, part.mediaType, part.media_type])
-        if (isBlobContentType(declared))
-            return declared;
-    if (isBlobContentType(file.urlMediaType))
-        return file.urlMediaType;
-    return file.decoded ? "application/octet-stream" : "text/plain; charset=utf-8";
-}
 export function blobPrefix(value) {
     if (typeof value !== "string")
         return Uint8Array.prototype.slice.call(value, 0, BLOB_PREFIX_BYTES);
@@ -149,8 +132,14 @@ export async function digestOf(value) {
     return { sha256: hash.digest("hex"), size };
 }
 /** The `hue.blobs` element for one uploaded value. */
-function blobEntry(key, sha256, size, contentType) {
-    return JSON.stringify({ key, sha256, size, content_type: contentType });
+export function blobEntry(key, sha256, size, contentType, name) {
+    return JSON.stringify({
+        key,
+        sha256,
+        size,
+        content_type: contentType,
+        ...(name ? { name } : {}),
+    });
 }
 /** HTTP header names (tokens) and values without line breaks or NUL. */
 const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
@@ -189,6 +178,7 @@ export class BlobUploader {
     running = 0;
     waiting = [];
     requests = new Set();
+    outcomes = new Map();
     constructor(options) {
         this.options = options;
     }
@@ -206,6 +196,7 @@ export class BlobUploader {
         for (const request of this.requests)
             request.destroy();
         this.requests.clear();
+        this.outcomes.clear();
         for (const run of this.waiting.splice(0)) {
             this.running++;
             run();
@@ -244,9 +235,49 @@ export class BlobUploader {
     }
     /**
      * Stores `value` under `key` of the trace: reserved, uploaded unless Hue already holds it, and
-     * completed. The caller holds a {@link limit} slot.
+     * completed. Only a fresh upload takes a {@link limit} slot: another reference to bytes the
+     * trace is already storing shares that upload's outcome without one, so repeated files never
+     * hold the slots new files need. The caller must not hold a slot.
      */
     async store(traceId, key, value, contentType, digest, upload) {
+        // Every occurrence is validated even when a previous occurrence already uploaded the bytes.
+        if (!isBlobKey(key) ||
+            !isBlobContentType(contentType) ||
+            !/^[0-9a-f]{32}$/.test(traceId) ||
+            /^0+$/.test(traceId) ||
+            !/^[0-9a-f]{64}$/.test(digest.sha256) ||
+            !Number.isSafeInteger(digest.size) ||
+            digest.size <= 0 ||
+            digest.size !== sizeOf(value))
+            return { ok: false, reason: "failed" };
+        if (digest.size > MAX_BLOB_BYTES)
+            return { ok: false, reason: "tooLarge" };
+        const identity = `${traceId}:${digest.sha256}`;
+        const known = this.outcomes.get(identity);
+        if (known)
+            return known.promise;
+        if (this.outcomes.size >= 4096) {
+            const oldest = [...this.outcomes].find(([, item]) => item.settled)?.[0];
+            if (oldest === undefined)
+                return { ok: false, reason: "budget" };
+            this.outcomes.delete(oldest);
+        }
+        const item = {
+            promise: Promise.resolve({ ok: false, reason: "failed" }),
+            settled: false,
+        };
+        this.outcomes.set(identity, item);
+        item.promise = this.limit(() => this.storeFresh(traceId, key, value, contentType, digest, upload))
+            .catch(() => ({ ok: false, reason: "failed" }))
+            .then((outcome) => {
+            item.settled = true;
+            if (!outcome.ok && this.outcomes.get(identity) === item)
+                this.outcomes.delete(identity);
+            return outcome;
+        });
+        return item.promise;
+    }
+    async storeFresh(traceId, key, value, contentType, digest, upload) {
         const refused = this.refusal();
         if (refused)
             return { ok: false, reason: refused };
@@ -295,10 +326,13 @@ export class BlobUploader {
         }
         if ("fallback" in reservation)
             return { ok: false, reason: reservation.fallback };
-        if (!reservation.exists)
+        if (!reservation.exists) {
             // For Hue's accounting only: a value is read whether or not it was completed, so a failed
             // completion is not retried.
-            await this.request("POST", new URL("/api/v1/otlp/blobs/complete", this.options.baseUrl), this.jsonHeaders(), JSON.stringify({ traceId, sha256: digest.sha256 }), Math.min(upload.deadline, Date.now() + this.options.timeoutMillis), MAX_JSON_RESPONSE_BYTES);
+            const completion = await this.request("POST", new URL("/api/v1/otlp/blobs/complete", this.options.baseUrl), this.jsonHeaders(), JSON.stringify({ traceId, sha256: digest.sha256 }), Math.min(upload.deadline, Date.now() + this.options.timeoutMillis), MAX_JSON_RESPONSE_BYTES);
+            if (!completion || completion.status >= 500 || completion.status === 429)
+                this.pause();
+        }
         return { ok: true, contentType: reservation.contentType };
     }
     jsonHeaders() {
@@ -323,7 +357,7 @@ export class BlobUploader {
                 return { fallback: "failed" };
             }
             const { status } = reply;
-            const answer = status === 200 || status === 404 ? parseJson(reply.body) : undefined;
+            const answer = status === 200 || status === 404 || status === 409 ? parseJson(reply.body) : undefined;
             // A receiver without the route answers its framework's not-found (Hue's own 404, an
             // archived project, is JSON with an `error`), refuses the method, or answers something
             // that is no reservation at all: it is not asked again for a while.
@@ -342,12 +376,15 @@ export class BlobUploader {
                     this.pause();
                 return reservation;
             }
+            if (status === 409 && isObject(answer) && answer.status === "exists")
+                return this.reservation(answer, size);
             if (status === 413)
                 return { fallback: "tooLarge" };
             if (status === 429) {
                 const wait = retryAfterMillis(reply.headers) ?? RETRY_DELAY_MILLIS;
                 if (Date.now() + wait < upload.deadline && (await upload.wait(wait)))
                     continue;
+                this.pause();
                 return { fallback: "failed" };
             }
             if (status >= 500) {
@@ -357,13 +394,12 @@ export class BlobUploader {
                 this.pause();
                 return { fallback: "failed" };
             }
-            // A conflict over this value alone (409) fails only it. Any other refusal (a refused key,
-            // an archived project, a request Hue could not read, a redirect) would meet every value
-            // alike, so uploads pause; the export's own requests report a key problem.
-            if (status !== 409)
+            // Bad values and conflicts refuse only this value. Transient service failures pause uploads.
+            if (status !== 400 && status !== 409)
                 this.pause();
             return { fallback: "failed" };
         }
+        this.pause();
         return { fallback: "failed" };
     }
     async delay(millis, upload) {
@@ -433,7 +469,7 @@ export class BlobUploader {
             return "stored";
         if (reply.status === 403)
             return reply.body.toString("utf8").includes("Request has expired") ? "expired" : "failed";
-        if (reply.status >= 500 || reply.status === 408)
+        if (reply.status >= 500 || reply.status === 408 || reply.status === 429)
             return "transient";
         return "failed";
     }
@@ -536,9 +572,9 @@ export class BlobUploader {
     }
 }
 /**
- * A span's own attributes with each candidate placed: an inline file part over 64 KiB in a
- * recorded message uploaded and replaced by its first 16 KiB (or by its digest, as before, when
- * it could not be), and a value still over the inline limit uploaded and replaced by its first
+ * A span's own attributes with each candidate placed: binary media becomes a digest, while
+ * text media over 64 KiB retains a 16 KiB prefix after upload or a digest on failure.
+ * A value still over the inline limit is uploaded and replaced by its first
  * 16 KiB (or cut to the limit), each upload listed under `hue.blobs`, each whole value cut or
  * uploaded listed under `hue.truncated`. Every fallback is counted in the tally.
  */
@@ -559,16 +595,19 @@ export async function offloadAttributes(attributes, collector, options) {
         fallback(uploader.unsupported() ? "unsupported" : "budget");
     let inspected = 0;
     const parts = async (index, key, text) => {
-        if (!isMessageKey(key) ||
-            text.length * 3 <= INLINE_FILE_LIMIT ||
-            !(text.includes('"blob"') || text.includes('"file"')))
-            return text;
-        const bytes = Buffer.byteLength(text, "utf8");
-        if (bytes <= INLINE_FILE_LIMIT || bytes > MAX_INLINE_FILE_TEXT)
+        // Both bounds count UTF-16 code units, as admission does.
+        if (!mayInlineFiles(key, text) || text.length > MAX_INLINE_FILE_TEXT)
             return text;
-        if (inspected + text.length > INLINE_FILE_TEXT_PER_RECORD)
-            return text;
-        inspected += text.length;
+        if (collector.inspected) {
+            // A message admission skipped stays as recorded.
+            if (!collector.inspected.has(key))
+                return text;
+        }
+        else {
+            if (inspected + text.length > INLINE_FILE_TEXT_PER_RECORD)
+                return text;
+            inspected += text.length;
+        }
         let parsed;
         let found;
         try {
@@ -582,33 +621,39 @@ export async function offloadAttributes(attributes, collector, options) {
             return text;
         let changed = false;
         await Promise.all(found.map((file, position) => {
-            const partKey = `${key}#${file.pointer}`;
+            const decoded = mediaBytes(file);
+            if (!decoded.bytes.byteLength)
+                return Promise.resolve();
+            const contentType = mediaContentType(file, decoded);
+            const textual = isTextMediaType(contentType);
+            if (textual && decoded.bytes.byteLength <= INLINE_FILE_LIMIT)
+                return Promise.resolve();
+            const partKey = `${key}#${textual ? file.pointer : file.partPointer}`;
             const slot = slots > 0 && isBlobKey(partKey) ? (slots--, true) : false;
-            return uploader.limit(async () => {
-                const decoded = inlineFileBytes(file.content);
-                if (decoded.bytes.byteLength <= INLINE_FILE_LIMIT) {
-                    if (slot)
-                        slots++;
-                    return;
-                }
+            return (async () => {
                 changed = true;
-                const digest = await digestOf(decoded.bytes);
+                const digest = options.memo
+                    ? options.memo.digest(file, decoded, traceId)
+                    : await digestOf(decoded.bytes);
                 const outcome = slot
-                    ? await uploader.store(traceId, partKey, decoded.bytes, fileContentType(file.part, decoded), digest, upload)
+                    ? await uploader.store(traceId, partKey, decoded.bytes, contentType, digest, upload)
                     : { ok: false, reason: "budget" };
                 if (outcome.ok) {
-                    file.part[file.key] = blobPrefix(file.content);
+                    if (textual)
+                        file.owner[file.key] = blobPrefix(file.content);
+                    else
+                        digestPart(file, digest);
                     entries.push({
                         order: [index, position],
-                        entry: blobEntry(partKey, digest.sha256, digest.size, outcome.contentType),
+                        entry: blobEntry(partKey, digest.sha256, digest.size, outcome.contentType, file.name),
                     });
                     tally.uploaded++;
                 }
                 else {
-                    digestPart(file.part, file.key, digest);
+                    digestPart(file, digest);
                     fallback(outcome.reason);
                 }
-            });
+            })();
         }));
         return changed ? JSON.stringify(parsed) : text;
     };
@@ -627,17 +672,15 @@ export async function offloadAttributes(attributes, collector, options) {
             return;
         }
         slots--;
-        const stored = await uploader.limit(async () => {
+        const stored = await (async () => {
             if (size > MAX_BLOB_BYTES)
                 return { ok: false, reason: "tooLarge" };
-            const refused = uploader.refusal();
-            if (refused)
-                return { ok: false, reason: refused };
-            const digest = await digestOf(placed);
+            // Hashing a large value takes a slot as its upload does; the upload takes its own.
+            const digest = await uploader.limit(() => digestOf(placed));
             const contentType = typeof placed === "string" ? textContentType(placed) : "application/octet-stream";
             const outcome = await uploader.store(traceId, key, placed, contentType, digest, upload);
             return outcome.ok ? { ...outcome, digest } : outcome;
-        });
+        })();
         if (stored.ok) {
             result[key] = typeof placed === "string" ? blobPrefix(placed) : blobPrefix(placed);
             entries.push({
@@ -652,6 +695,26 @@ export async function offloadAttributes(attributes, collector, options) {
         }
     };
     await Promise.all(collector.candidates.map((candidate, index) => place(index, candidate)));
+    await Promise.all((collector.attachments ?? []).map((file, position) => {
+        if (!file.bytes.byteLength)
+            return Promise.resolve();
+        const slot = slots > 0 ? (slots--, true) : false;
+        return (async () => {
+            const key = `event:hue.file:${file.digest.sha256}`;
+            const outcome = slot
+                ? await uploader.store(traceId, key, file.bytes, file.contentType, file.digest, upload)
+                : { ok: false, reason: "budget" };
+            if (outcome.ok) {
+                entries.push({
+                    order: [collector.candidates.length, position],
+                    entry: blobEntry(key, file.digest.sha256, file.digest.size, outcome.contentType, file.name),
+                });
+                tally.uploaded++;
+            }
+            else
+                fallback(outcome.reason);
+        })();
+    }));
     if (listed.length)
         result[TRUNCATED_KEY] = withTruncatedKeys(result[TRUNCATED_KEY], listed.sort((a, b) => a.order - b.order).map(({ key }) => key));
     if (entries.length) {
@@ -666,9 +729,11 @@ export async function offloadAttributes(attributes, collector, options) {
  * over the inline limit cut to it (bytes replaced by the receiver's marker) and listed under
  * `hue.truncated`.
  */
-export function fallbackAttributes(attributes, collector, valueBytes, tally, traceId) {
+export function fallbackAttributes(attributes, collector, valueBytes, tally, traceId, memo) {
     const result = { ...attributes };
     const listed = [];
+    for (const _file of collector.attachments ?? [])
+        countFallback(tally, "failed", traceId);
     for (let index = 0; index < collector.cut.length; index++)
         countFallback(tally, "failed", traceId);
     for (const { key, value } of collector.candidates) {
@@ -676,7 +741,8 @@ export function fallbackAttributes(attributes, collector, valueBytes, tally, tra
         // Each large inline file is reported as a value not uploaded, as the upload step reports it.
         const count = { files: 0 };
         try {
-            placed = hashInlineFiles(key, value, count);
+            if (!collector.inspected || collector.inspected.has(key))
+                placed = hashInlineFiles(key, value, count, memo, traceId);
         }
         catch {
             // Left as it is: cut below when over the limit.

package/dist/cli/eval-direct.d.ts

@@ -11,8 +11,9 @@ import type { JsonValue } from "../types.js";
  *   <case dir>/output/                where the command writes what it produced
  *
  * Everything under `output/` becomes the execution's generated files. Optional helpers there:
- * `manifest.json` (`{ "primary": "<filename>", "output": <json> }`), `result.json` (the JSON
- * output) and `summary.txt` / `summary.md` (recorded as `{ "summary": "…" }`).
+ * `manifest.json` (`{ "primary": "<filename>", "output": <json>, "contentTypes": { "<path>": "<MIME>" } }`),
+ * `result.json` (the JSON output) and `summary.txt` / `summary.md` (recorded as `{ "summary": "…" }`).
+ * MP4 and WebM outputs require a contentTypes declaration because either container can hold audio or video.
  */
 export declare const directCaseEnvironment: readonly ["HUE_CASE_DIR", "HUE_CASE_INPUTS", "HUE_CASE_OUTPUT_DIR", "HUE_CASE_ID", "HUE_CASE_KEY", "HUE_EXECUTION_ID"];
 /** Generated-file extensions Hue accepts and the content type recorded for each. */

package/dist/cli/eval-direct.js

@@ -14,8 +14,9 @@ import { withFiles } from "../evals/types.js";
  *   <case dir>/output/                where the command writes what it produced
  *
  * Everything under `output/` becomes the execution's generated files. Optional helpers there:
- * `manifest.json` (`{ "primary": "<filename>", "output": <json> }`), `result.json` (the JSON
- * output) and `summary.txt` / `summary.md` (recorded as `{ "summary": "…" }`).
+ * `manifest.json` (`{ "primary": "<filename>", "output": <json>, "contentTypes": { "<path>": "<MIME>" } }`),
+ * `result.json` (the JSON output) and `summary.txt` / `summary.md` (recorded as `{ "summary": "…" }`).
+ * MP4 and WebM outputs require a contentTypes declaration because either container can hold audio or video.
  */
 export const directCaseEnvironment = [
     "HUE_CASE_DIR",
@@ -38,8 +39,25 @@ export const outputExtensions = {
     ".jpg": "image/jpeg",
     ".jpeg": "image/jpeg",
     ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".avif": "image/avif",
+    ".mp3": "audio/mpeg",
+    ".mpeg": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".ogg": "audio/ogg",
+    ".m4a": "audio/mp4",
+    ".flac": "audio/flac",
+    ".opus": "audio/opus",
+    ".aac": "audio/aac",
 };
-for (const type of Object.values(outputExtensions))
+const ambiguousOutputExtensions = {
+    ".mp4": ["audio/mp4", "video/mp4"],
+    ".webm": ["audio/webm", "video/webm"],
+};
+for (const type of [
+    ...Object.values(outputExtensions),
+    ...Object.values(ambiguousOutputExtensions).flat(),
+])
     if (!outputContentTypes.includes(type))
         throw new Error(`outputExtensions maps to a content type Hue does not accept: ${type}`);
 const HELPER_FILES = new Set(["manifest.json", "result.json", "output.json"]);
@@ -251,18 +269,43 @@ export async function collectDirectOutputs(outputDirectory, fallbackOutput, seam
     const entries = listed.filter((entry) => !HELPER_FILES.has(entry.name) && !SUMMARY_FILES.includes(entry.name));
     // Directory order differs between filesystems; keep uploads stable.
     entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-    const unsupported = entries.filter((entry) => !outputExtensions[extname(entry.name).toLowerCase()]);
+    const declaredTypes = manifest && typeof manifest === "object" && !Array.isArray(manifest)
+        ? manifest.contentTypes
+        : undefined;
+    if (declaredTypes !== undefined &&
+        (!declaredTypes || typeof declaredTypes !== "object" || Array.isArray(declaredTypes)))
+        throw new Error("manifest.json contentTypes must map output paths to MIME type strings");
+    for (const [name, type] of Object.entries(declaredTypes ?? {})) {
+        if (typeof type !== "string" || !outputContentTypes.includes(type))
+            throw new Error(`manifest.json declares an unsupported content type for ${name}`);
+        if (!entries.some((entry) => entry.name === name))
+            throw new Error(`manifest.json declares a content type for a file that was not written: ${name}`);
+    }
+    const unsupported = entries.filter((entry) => {
+        const extension = extname(entry.name).toLowerCase();
+        return !outputExtensions[extension] && !ambiguousOutputExtensions[extension];
+    });
     if (unsupported.length)
-        throw new Error(`The agent wrote files Hue does not accept as generated documents: ${unsupported.map((entry) => entry.name).join(", ")} (accepted: ${Object.keys(outputExtensions).join(" ")})`);
+        throw new Error(`The agent wrote files Hue does not accept as generated documents: ${unsupported.map((entry) => entry.name).join(", ")} (accepted: ${[...Object.keys(outputExtensions), ...Object.keys(ambiguousOutputExtensions)].join(" ")})`);
     const files = [];
     for (const entry of entries) {
+        const extension = extname(entry.name).toLowerCase();
+        const declared = declaredTypes && Object.hasOwn(declaredTypes, entry.name)
+            ? declaredTypes[entry.name]
+            : undefined;
+        const contentType = declared ?? outputExtensions[extension];
+        const acceptedTypes = ambiguousOutputExtensions[extension] ?? [outputExtensions[extension]];
+        if (contentType === undefined)
+            throw new Error(`Declare ${entry.name} as ${acceptedTypes.join(" or ")} in manifest.json contentTypes`);
+        if (typeof contentType !== "string" || !acceptedTypes.includes(contentType))
+            throw new Error(`manifest.json content type for ${entry.name} must be ${acceptedTypes.join(" or ")}`);
         const bytes = (await readAgentFile(entry.path, `Generated file ${entry.name}`, outputFileLimits.bytes, entry.identity));
         if (!bytes.byteLength)
             throw new Error(`The agent wrote an empty file: ${entry.name}`);
         files.push({
             bytes,
             filename: artifactFilename(entry.name),
-            contentType: outputExtensions[extname(entry.name).toLowerCase()],
+            contentType,
         });
     }
     if (typeof declaredPrimary === "string") {

package/dist/client.d.ts

@@ -149,13 +149,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;
     /**