@hue-run/sdk 0.18.1 → 0.18.2

package/dist/blobs.js

@@ -3,6 +3,7 @@ import { context } from "@opentelemetry/api";
 import { suppressTracing } from "@opentelemetry/core";
 import { isLoopbackHost } from "./config.js";
 import { digestPart, hashInlineFiles, hashNestedInlineFiles, INLINE_FILE_LIMIT, INLINE_FILE_TEXT_PER_RECORD, isMessageKey, keepsPrefix, literalKeys, mediaBytes, mediaContentType, mediaIn, isTextMediaType, mayInlineFiles, isMediaContentType, MAX_INLINE_FILE_TEXT, placeable, placedMediaText, prefixPart, readMediaText, reencodeMedia, } from "./inline-files.js";
+import { isByteSource, JoinedText, longFileBytes, longHead, placedLargeText, readLargeMediaText, } from "./large-media.js";
 import { capLogBody, TRUNCATED_KEY, truncatedMarker, withTruncatedKeys } from "./privacy.js";
 import { truncateUtf8 } from "./safety.js";
 /**
@@ -99,40 +100,53 @@ export function blobPrefix(value) {
     return Buffer.from(truncateUtf8(value, BLOB_PREFIX_BYTES), "utf8").toString("utf8");
 }
 /** A value's size in bytes as it is uploaded: a string's UTF-8 encoding, counted, not made. */
-function sizeOf(value) {
-    return typeof value === "string" ? Buffer.byteLength(value, "utf8") : value.byteLength;
+export function sizeOf(value) {
+    if (typeof value === "string")
+        return Buffer.byteLength(value, "utf8");
+    return isByteSource(value) ? value.size : value.byteLength;
+}
+/** The bytes a value holds in memory: none for a source read as it is uploaded. */
+export function heldBytesOf(value) {
+    return isByteSource(value) ? 0 : value.byteLength;
 }
 /** A string's UTF-8 encoding a slice at a time, never splitting a surrogate pair. */
 function* utf8Chunks(text) {
+    // One buffer, reused: a reader is done with each slice before it asks for the next.
+    const buffer = Buffer.allocUnsafe(TEXT_CHUNK_UNITS * 3);
     for (let start = 0; start < text.length;) {
         let end = Math.min(text.length, start + TEXT_CHUNK_UNITS);
         if (end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1]))
             end--;
-        yield Buffer.from(text.slice(start, end), "utf8");
+        yield buffer.subarray(0, buffer.write(text.slice(start, end), "utf8"));
         start = end;
     }
 }
 /** The bytes an upload carries, a slice at a time: no second copy of a large value is made. */
-function* uploadChunks(value) {
-    if (typeof value === "string") {
-        yield* utf8Chunks(value);
-        return;
-    }
-    for (let start = 0; start < value.byteLength; start += TEXT_CHUNK_UNITS)
-        yield value.subarray(start, Math.min(value.byteLength, start + TEXT_CHUNK_UNITS));
+function uploadChunks(value) {
+    if (isByteSource(value))
+        return value.chunks();
+    return (function* () {
+        if (typeof value === "string") {
+            yield* utf8Chunks(value);
+            return;
+        }
+        for (let start = 0; start < value.byteLength; start += TEXT_CHUNK_UNITS)
+            yield value.subarray(start, Math.min(value.byteLength, start + TEXT_CHUNK_UNITS));
+    })();
 }
 const nextTurn = () => new Promise((resolve) => setImmediate(resolve));
 /** The SHA-256 (lowercase hex) and byte size of what an upload of `value` carries, yielding to
- * the event loop between slices so a large value does not stall the application. */
-export async function digestOf(value) {
+ * the event loop between slices so a large value does not stall the application. Past
+ * `deadline`, it throws rather than read on. */
+export async function digestOf(value, deadline = Infinity) {
     const hash = createHash("sha256");
     let size = 0;
-    let slices = 0;
-    for (const chunk of uploadChunks(value)) {
+    for await (const chunk of uploadChunks(value)) {
         hash.update(chunk);
         size += chunk.byteLength;
-        if (++slices % 4 === 0)
-            await nextTurn();
+        await nextTurn();
+        if (Date.now() >= deadline)
+            throw new Error("The upload ran out of time");
     }
     return { sha256: hash.digest("hex"), size };
 }
@@ -258,9 +272,12 @@ export class BlobUploader {
         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;
+        for (let known = this.outcomes.get(identity); known; known = this.outcomes.get(identity)) {
+            const shared = await known.promise;
+            // Another reference's file changed since it was recorded: this one tries its own bytes.
+            if (shared.ok || !shared.changed)
+                return shared;
+        }
         if (this.outcomes.size >= 4096) {
             const oldest = [...this.outcomes].find(([, item]) => item.settled)?.[0];
             if (oldest === undefined)
@@ -308,6 +325,8 @@ export class BlobUploader {
             const put = await this.put(grant, value, digest.size, upload.deadline);
             if (put === "stored")
                 break;
+            if (put === "changed")
+                return { ok: false, reason: "failed", changed: true };
             if (this.closed)
                 return { ok: false, reason: "failed" };
             const expired = put === "expired" || Date.now() >= grant.expiresAt;
@@ -464,14 +483,21 @@ export class BlobUploader {
             grant: { url, headers, expiresAt: Number.isFinite(expiresAt) ? expiresAt : Infinity },
         };
     }
-    /** The PUT of the value's bytes, with exactly the headers Hue signed. */
+    /** The PUT of the value's bytes, with exactly the headers Hue signed. A source that no longer
+     * holds its bytes (a file changed since it was recorded) ends the request before its body is
+     * complete, and fails the value without a retry. */
     async put(grant, value, size, deadline) {
         const reply = await this.request("PUT", grant.url, grant.headers, value, deadline, MAX_ERROR_RESPONSE_BYTES, size);
+        if (isByteSource(value) && value.changed)
+            return "changed";
         if (!reply)
             return "transient";
-        // 412: the object exists already (another upload of the same value won).
-        if ((reply.status >= 200 && reply.status < 300) || reply.status === 412)
+        // 412: the object exists already (another upload of the same value won). A success answered
+        // before the whole body was written stores nothing that was sent.
+        if (reply.status === 412)
             return "stored";
+        if (reply.status >= 200 && reply.status < 300)
+            return reply.complete ? "stored" : "failed";
         if (reply.status === 403)
             return reply.body.toString("utf8").includes("Request has expired") ? "expired" : "failed";
         if (reply.status >= 500 || reply.status === 408 || reply.status === 429)
@@ -501,6 +527,8 @@ export class BlobUploader {
             return undefined;
         return new Promise((resolve) => {
             let settled = false;
+            // Whether the whole body was handed to the request.
+            let ended = false;
             let request;
             const finish = (reply) => {
                 if (settled)
@@ -509,16 +537,20 @@ export class BlobUploader {
                 clearTimeout(timer);
                 if (request) {
                     this.requests.delete(request);
-                    if (!reply)
+                    // An answer before the whole body was handed over ends the request: a store that
+                    // neither reads nor closes would otherwise hold it, and its source, open.
+                    if (!reply || !ended)
                         request.destroy();
                 }
                 resolve(reply);
             };
             const timer = setTimeout(() => finish(), Math.max(1, deadline - Date.now()));
+            // The bytes handed to the request: its body is complete once they are its length.
+            let sentBytes = 0;
+            const written = () => length === undefined || sentBytes === length;
             const requestHeaders = { ...headers };
             if (length === undefined)
-                requestHeaders["Content-Length"] =
-                    typeof body === "string" ? Buffer.byteLength(body, "utf8") : body.byteLength;
+                requestHeaders["Content-Length"] = sizeOf(body);
             try {
                 // Uploads are the SDK's own export traffic: an http instrumentation must not trace them.
                 request = context.with(suppressTracing(context.active()), () => http.request(url, { method, headers: requestHeaders, agent: false }, (response) => {
@@ -528,6 +560,7 @@ export class BlobUploader {
                         status: response.statusCode ?? 0,
                         headers: response.headers,
                         body: Buffer.concat(chunks),
+                        complete: written(),
                     });
                     response.on("data", (chunk) => {
                         size += chunk.byteLength;
@@ -552,26 +585,41 @@ export class BlobUploader {
             sent.on("error", () => finish());
             sent.setTimeout(this.options.timeoutMillis, () => finish());
             void (async () => {
-                if (length === undefined) {
+                if (length === undefined && !isByteSource(body)) {
+                    ended = true;
                     sent.end(body);
                     return;
                 }
-                for (const chunk of uploadChunks(body)) {
+                // A source or a text may reuse a slice's memory for the next: each slice is written out
+                // before the next is read. Bytes are views of memory that does not change.
+                const reused = !(body instanceof Uint8Array);
+                for await (const chunk of uploadChunks(body)) {
                     if (settled)
                         return;
-                    if (!sent.write(chunk))
-                        await new Promise((drained) => {
-                            const done = () => {
-                                sent.off("drain", done);
-                                sent.off("close", done);
-                                drained();
-                            };
+                    sentBytes += chunk.byteLength;
+                    await new Promise((proceed) => {
+                        const done = () => {
+                            sent.off("drain", done);
+                            sent.off("close", done);
+                            proceed();
+                        };
+                        sent.on("close", done);
+                        if (reused) {
+                            sent.write(chunk, () => done());
+                            return;
+                        }
+                        if (sent.write(chunk))
+                            done();
+                        else
                             sent.on("drain", done);
-                            sent.on("close", done);
-                        });
+                    });
+                    if (settled)
+                        return;
                 }
-                if (!settled)
-                    sent.end();
+                if (settled)
+                    return;
+                ended = true;
+                sent.end();
             })().catch(() => finish());
         });
     }
@@ -615,30 +663,46 @@ export async function offloadRecord(attributes, collector, options) {
      * uploaded keeps its bytes inline, except in a recorded message: a span's own message keeps its
      * digest, and a log record's keeps the digest of a file over the inline limit, as nested
      * messages kept them before log records uploaded. */
-    const placeFiles = async (index, key, files) => {
+    const placeFiles = async (index, key, files, long) => {
         const message = isMessageKey(key);
         let changed = false;
         await Promise.all(files.map((file, position) => {
-            const decoded = mediaBytes(file);
-            if (!placeable(file, decoded))
+            // A file whose content is a long string is read from its place in the recorded text, a
+            // slice at a time: never decoded or copied whole.
+            const inPlace = long?.get(file.content);
+            const decoded = inPlace ? longFileBytes(file, inPlace) : mediaBytes(file);
+            const bytes = "source" in decoded ? decoded.source : decoded.bytes;
+            const size = sizeOf(bytes);
+            if (!placeable(file, decoded, size))
                 return Promise.resolve();
             const contentType = mediaContentType(file, decoded);
             const textual = isTextMediaType(contentType);
-            if (textual && decoded.bytes.byteLength <= INLINE_FILE_LIMIT)
+            if (textual && size <= INLINE_FILE_LIMIT)
                 return Promise.resolve();
             const prefix = keepsPrefix(file, textual, decoded);
             const partKey = `${key}#${prefix ? file.pointer : file.partPointer}`;
             const slot = slots > 0 && isBlobKey(partKey) ? (slots--, true) : false;
             return (async () => {
-                const digest = options.memo
-                    ? options.memo.digest(file, decoded, traceId)
-                    : await digestOf(decoded.bytes);
+                // Hashing a long file takes an upload place, as hashing a large value does; one the
+                // export's upload budget cannot hash stays as recorded and is not uploaded.
+                let digest;
+                try {
+                    digest = isByteSource(bytes)
+                        ? await uploader.limit(() => digestOf(bytes, upload.deadline))
+                        : options.memo
+                            ? options.memo.digest(file, decoded, traceId)
+                            : await digestOf(bytes);
+                }
+                catch {
+                    fallback("failed");
+                    return;
+                }
                 const outcome = slot
-                    ? await uploader.store(traceId, partKey, decoded.bytes, contentType, digest, upload)
+                    ? await uploader.store(traceId, partKey, bytes, contentType, digest, upload)
                     : { ok: false, reason: "budget" };
                 if (outcome.ok) {
                     if (prefix)
-                        prefixPart(file, blobPrefix(file.content));
+                        prefixPart(file, blobPrefix(inPlace ? longHead(inPlace, BLOB_PREFIX_BYTES + 1) : file.content));
                     else
                         digestPart(file, digest);
                     changed = true;
@@ -649,7 +713,7 @@ export async function offloadRecord(attributes, collector, options) {
                     tally.uploaded++;
                 }
                 else {
-                    if (message && (!collector.log || decoded.bytes.byteLength > INLINE_FILE_LIMIT)) {
+                    if (message && (!collector.log || size > INLINE_FILE_LIMIT)) {
                         digestPart(file, digest);
                         changed = true;
                     }
@@ -661,30 +725,59 @@ export async function offloadRecord(attributes, collector, options) {
     };
     const literal = literalKeys(attributes);
     const parts = async (index, key, text) => {
-        // Both bounds count UTF-16 code units, as admission does. Literal text holds no file.
-        if (!mayInlineFiles(key, text) || text.length > MAX_INLINE_FILE_TEXT || literal.has(key))
+        // Literal text holds no file.
+        if (!mayInlineFiles(key, text) || literal.has(key))
             return text;
-        if (collector.inspected) {
-            // A value admission skipped stays as recorded.
-            if (!collector.inspected.has(key))
-                return text;
+        let media;
+        let large;
+        if (collector.large?.has(key)) {
+            // Held whole past the inspection bounds: its long strings were read in place, the JSON
+            // around them within the per-attribute bound.
+            media = large = largeReads.get(index);
         }
         else {
-            if (inspected + text.length > INLINE_FILE_TEXT_PER_RECORD)
+            // Both bounds count UTF-16 code units, as admission does.
+            if (text.length > MAX_INLINE_FILE_TEXT)
                 return text;
-            inspected += text.length;
+            if (collector.inspected) {
+                // A value 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;
+            }
+            try {
+                media = readMediaText(key, text);
+            }
+            catch {
+                return text;
+            }
         }
-        let media;
+        if (!media?.files.length)
+            return text;
+        if (!(await placeFiles(index, key, media.files, large?.long)))
+            return text;
+        return large ? await placedLargeText(large) : placedMediaText(media);
+    };
+    // The values read in place are scanned first, in candidate order, between turns of the event
+    // loop: places in `hue.blobs` are then taken in candidate order, as for any value.
+    const largeReads = new Map();
+    for (const [index, { key, value }] of collector.candidates.entries()) {
+        if (typeof value !== "string" ||
+            !collector.large?.has(key) ||
+            !mayInlineFiles(key, value) ||
+            literal.has(key))
+            continue;
         try {
-            media = readMediaText(key, text);
+            largeReads.set(index, await readLargeMediaText(key, value, options.longUnits));
         }
         catch {
-            return text;
+            // JSON that does not parse holds no file: the value stays as recorded.
         }
-        if (!media?.files.length)
-            return text;
-        return (await placeFiles(index, key, media.files)) ? placedMediaText(media) : text;
-    };
+    }
     /** A log record's body with its files placed. Each file's content counts toward the record's
      * inspection bounds, as an attribute's text does. */
     const placeBody = async (body) => {
@@ -710,14 +803,22 @@ export async function offloadRecord(attributes, collector, options) {
         return media.box.value;
     };
     const place = async (index, { key, value }) => {
-        const placed = typeof value === "string" ? await parts(index, key, value) : value;
-        const size = sizeOf(placed);
+        const read = typeof value === "string" ? await parts(index, key, value) : value;
+        // Text joined from pieces of the recorded text is made one string only when it is kept
+        // inline; otherwise it is measured, hashed, uploaded and cut from its pieces.
+        const joined = read instanceof JoinedText ? read : undefined;
+        const size = joined ? joined.utf8Size() : sizeOf(read);
         if (size <= valueBytes) {
-            result[key] = placed;
+            result[key] = joined ? joined.text() : read;
             return;
         }
+        const placed = joined ? joined.source(size) : read;
         listed.push({ order: index, key });
-        const cut = () => typeof placed === "string" ? truncateUtf8(placed, valueBytes) : truncatedMarker(size);
+        const cut = () => joined
+            ? truncateUtf8(joined.head(valueBytes + 1), valueBytes)
+            : typeof placed === "string"
+                ? truncateUtf8(placed, valueBytes)
+                : truncatedMarker(size);
         // A log record's value is cut, as no log reader pages an uploaded text value.
         if (collector.log) {
             result[key] = cut();
@@ -733,13 +834,27 @@ export async function offloadRecord(attributes, collector, options) {
             if (size > MAX_BLOB_BYTES)
                 return { ok: false, reason: "tooLarge" };
             // 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";
+            let digest;
+            try {
+                digest = await uploader.limit(() => digestOf(placed, upload.deadline));
+            }
+            catch {
+                return { ok: false, reason: "failed" };
+            }
+            const contentType = joined
+                ? textContentType(joined.head(256) + joined.tail(256))
+                : 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);
+            result[key] = joined
+                ? blobPrefix(joined.head(BLOB_PREFIX_BYTES + 1))
+                : typeof placed === "string"
+                    ? blobPrefix(placed)
+                    : blobPrefix(placed);
             entries.push({
                 order: [index, Infinity],
                 entry: blobEntry(key, stored.digest.sha256, stored.digest.size, stored.contentType),
@@ -754,7 +869,7 @@ export async function offloadRecord(attributes, collector, options) {
     const body = collector.body ? placeBody(collector.body.value) : undefined;
     await Promise.all(collector.candidates.map((candidate, index) => place(index, candidate)));
     await Promise.all((collector.attachments ?? []).map((file, position) => {
-        if (!file.bytes.byteLength)
+        if (!sizeOf(file.bytes))
             return Promise.resolve();
         const slot = slots > 0 ? (slots--, true) : false;
         return (async () => {

package/dist/client.d.ts

@@ -166,10 +166,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
-     * 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.
+     * and, when `captureContent` is true, `hue.file.name`. `data` or the file at `path` is hashed and
+     * measured locally and uploaded only with `upload: true`: `data` and a file up to 25 MiB are
+     * held in memory until then, while a larger regular file, up to Hue's 1 GB upload limit, is
+     * hashed a slice at a time and read again from disk when it is uploaded, and is uploaded only if
+     * it still has the size and SHA-256 it was recorded with; a `path` that is no regular file, such
+     * as a named pipe, is refused without waiting on it. 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`. */

package/dist/client.js

@@ -13,8 +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 { countFallback, MAX_BLOB_BYTES, newTally } from "./blobs.js";
-import { attachmentPart, attachmentState, holdsAttachment, MAX_ATTACHMENT_DEPTH, } from "./attachment.js";
+import { countFallback, MAX_BLOB_BYTES, newTally, sizeOf } from "./blobs.js";
+import { attachmentPart, attachmentState, fileSource, holdsAttachment, MAX_ATTACHMENT_DEPTH, readPath, } from "./attachment.js";
 import { createHueTransport, exportBudgetMillis, HueExportError, } from "./transport.js";
 import { verifyTrace } from "./receipt.js";
 import { sdkVersion } from "./version.js";
@@ -611,21 +611,22 @@ export class HueClient {
         const files = [];
         const tally = newTally();
         for (const { state, part, depth } of placed) {
-            if (!part || !state.bytes || !state.sha256) {
+            if (!part || state.size === undefined || !state.sha256) {
                 this.instrumentationFailed(signal);
                 continue;
             }
             if (state.invalidName && captureContent)
                 this.instrumentationFailed(signal);
-            if (!this.transport.offloadsValues() || !state.bytes.byteLength)
+            if (!this.transport.offloadsValues() || !state.size)
                 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 },
+                // A file given by path over 25 MiB is read again from disk when it is uploaded.
+                bytes: state.file ? fileSource(state.file) : state.bytes,
+                digest: { sha256: state.sha256, size: state.size },
                 contentType: state.contentType,
                 ...(state.name === undefined ? {} : { name: state.name }),
             });
@@ -788,10 +789,15 @@ 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
-     * 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.
+     * and, when `captureContent` is true, `hue.file.name`. `data` or the file at `path` is hashed and
+     * measured locally and uploaded only with `upload: true`: `data` and a file up to 25 MiB are
+     * held in memory until then, while a larger regular file, up to Hue's 1 GB upload limit, is
+     * hashed a slice at a time and read again from disk when it is uploaded, and is uploaded only if
+     * it still has the size and SHA-256 it was recorded with; a `path` that is no regular file, such
+     * as a named pipe, is refused without waiting on it. 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, explicitContext) {
         if (!this.enabled || this.closed)
@@ -800,7 +806,7 @@ export class HueClient {
             const span = trace.getSpan(explicitContext ?? this.storage.getStore()?.context ?? context.active());
             if (!span?.isRecording())
                 throw new Error("File records require an active span");
-            const { role, mediaType, data, name } = file;
+            const { role, mediaType, data, name, path } = file;
             if (role !== "input" && role !== "attachment" && role !== "output")
                 throw new TypeError("Invalid file role");
             if (!isLabel(mediaType))
@@ -808,7 +814,31 @@ export class HueClient {
             let sha256 = typeof file.sha256 === "string" ? file.sha256.toLowerCase() : file.sha256;
             let byteSize = file.byteSize;
             let bytes;
-            if (data !== undefined) {
+            // A file given by path over 25 MiB: hashed now and read again from disk when it is uploaded.
+            let onDisk;
+            let given = data;
+            if (path !== undefined) {
+                if (data !== undefined)
+                    throw new TypeError("A file takes data or a path, not both");
+                if (typeof path !== "string" || !path)
+                    throw new TypeError("Invalid file path");
+                const read = readPath(path);
+                if (!read)
+                    throw new RangeError("File must be a regular file within Hue's 1 GB upload limit");
+                if ("bytes" in read)
+                    given = read.bytes;
+                else {
+                    onDisk = read.file;
+                    // A caller-supplied digest or size must describe the same bytes.
+                    if ((sha256 !== undefined && sha256 !== onDisk.sha256) ||
+                        (byteSize !== undefined && byteSize !== onDisk.size))
+                        throw new TypeError("File digest or size does not match its data");
+                    sha256 = onDisk.sha256;
+                    byteSize = onDisk.size;
+                }
+            }
+            if (given !== undefined) {
+                const data = given;
                 bytes =
                     typeof data === "string"
                         ? (() => {
@@ -888,10 +918,11 @@ export class HueClient {
             if (eventTime)
                 this.fileEventTimes.set(source, eventTime);
             if (file.upload === true && this.transport.offloadsValues()) {
-                if (!this.transport.stageMedia(span, bytes && eventTime
+                const upload = bytes ?? (onDisk ? fileSource(onDisk) : undefined);
+                if (!this.transport.stageMedia(span, upload && eventTime
                     ? {
-                        bytes,
-                        digest: { sha256, size: bytes.byteLength },
+                        bytes: upload,
+                        digest: { sha256, size: sizeOf(upload) },
                         contentType: mediaType,
                         eventTime,
                         ...(isMediaName(name) ? { name } : {}),

package/dist/inline-files.d.ts

@@ -137,20 +137,21 @@ export declare function placedMediaText(media: MediaValue): string;
 /** Each JSON-encoded string a placed file sits in, written again, innermost first: the string as
  * recorded with only its placed files changed. */
 export declare function reencodeMedia(media: MediaValue): void;
-/** Whether a found file has bytes to place: nonempty, and a whole string's `data:` URL decodes. */
-export declare function placeable(file: InlineFilePart, decoded: InlineFileBytes): boolean;
+/** Whether a found file has bytes to place: nonempty (`size` bytes), and a whole string's `data:`
+ * URL decodes. */
+export declare function placeable(file: InlineFilePart, decoded: Pick<InlineFileBytes, "decoded">, size: number): boolean;
 /** Whether an uploaded file keeps a 16 KiB prefix of its content in place (text media in a
  * provider part, whose entry names the content) rather than its digest. A whole string, a file
  * inside a JSON-encoded string, and a text file a part holds as bare base64 (a GenAI `blob`,
  * Vertex `media` or AI SDK part, whose content is not the text itself) take the digest form. */
-export declare function keepsPrefix(file: InlineFilePart, textual: boolean, decoded: InlineFileBytes): boolean;
+export declare function keepsPrefix(file: InlineFilePart, textual: boolean, decoded: Pick<InlineFileBytes, "bareBase64">): boolean;
 /** A file's bytes: a field its convention declares base64 decoded, any other content read as
  * Hue's reader reads it, whatever the part's media type (`inlineFileBytes`): a `data:` URL by its
  * own encoding, text that reads as base64 decoded (what the GenAI conventions, and
  * `client.media.resolve`, write in a `blob` or `media` part for every media type), anything else
  * as its UTF-8. */
 export declare function mediaBytes(file: InlineFilePart): InlineFileBytes;
-export declare function mediaContentType(file: InlineFilePart, decoded: InlineFileBytes): string;
+export declare function mediaContentType(file: InlineFilePart, decoded: Pick<InlineFileBytes, "decoded" | "urlMediaType">): string;
 export interface FileDigest {
     sha256: string;
     size: number;

package/dist/inline-files.js

@@ -707,9 +707,10 @@ export function reencodeMedia(media) {
         });
     }
 }
-/** Whether a found file has bytes to place: nonempty, and a whole string's `data:` URL decodes. */
-export function placeable(file, decoded) {
-    return decoded.bytes.byteLength > 0 && (!file.whole || decoded.decoded);
+/** Whether a found file has bytes to place: nonempty (`size` bytes), and a whole string's `data:`
+ * URL decodes. */
+export function placeable(file, decoded, size) {
+    return size > 0 && (!file.whole || decoded.decoded);
 }
 /** Whether an uploaded file keeps a 16 KiB prefix of its content in place (text media in a
  * provider part, whose entry names the content) rather than its digest. A whole string, a file
@@ -841,7 +842,7 @@ export function digestMedia(media, nested, count, memo, traceId = "") {
     let changed = false;
     for (const file of media.files) {
         const decoded = mediaBytes(file);
-        if (!placeable(file, decoded))
+        if (!placeable(file, decoded, decoded.bytes.byteLength))
             continue;
         if ((nested || isTextMediaType(mediaContentType(file, decoded))) &&
             decoded.bytes.byteLength <= INLINE_FILE_LIMIT)
@@ -875,7 +876,7 @@ export function digestFormBytes(value) {
             continue;
         inspected += units;
         const decoded = mediaBytes(file);
-        if (!placeable(file, decoded))
+        if (!placeable(file, decoded, decoded.bytes.byteLength))
             continue;
         if (isTextMediaType(mediaContentType(file, decoded)) &&
             decoded.bytes.byteLength <= INLINE_FILE_LIMIT)