ai-persistence: capBodySize strips the body's known length, so artifacts can't be persisted to Cloudflare R2 #1030

Summary

withGenerationPersistence cannot persist artifacts to a Cloudflare R2 BlobStore. Every generation that produces media fails with:

TypeError: Provided readable stream must have a known length
(request/response body or readable half of FixedLengthStream)
    at Object.put (src/lib/persistence.server.ts)
    at persistGenerationArtifacts (@tanstack/ai-persistence/dist/esm/middleware.js)
    at applyGenerationResultTransforms (@tanstack/ai/dist/esm/activities/middleware/run.js)
    at runGenerateImage (@tanstack/ai/dist/esm/activities/generateImage/index.js)

This affects any Worker following the shipped ai-persistence/build-cloudflare-artifact-store skill, whose recipe is incorrect on this point (details in "3." below).

Environment: @tanstack/ai-persistence (pkg.pr.new build for #1011) + @tanstack/ai, TanStack Start on Cloudflare Workers via @cloudflare/vite-plugin, workerd 1.20260730.1, wrangler 4.116.0. Artifacts sourced from fal / Gemini / xAI result URLs.

Root cause

descriptorBody() resolves a URL-backed descriptor by wrapping the response body:

body: capBodySize(response.body, maxBytes, descriptor.url),
size: 0,

and capBodySize enforces the cap with a TransformStream:

function capBodySize(body, maxBytes, url) {
  let seen = 0
  return body.pipeThrough(new TransformStream({ transform(chunk, controller) {
    seen += chunk.byteLength
    if (seen > maxBytes) { controller.error(...); return }
    controller.enqueue(chunk)
  }}))
}

The counting itself is fine — it streams, nothing is buffered. The problem is that a TransformStream's readable side carries no declared length, because a transform may emit any number of bytes. Response.body had a length; after pipeThrough it does not.

R2Bucket.put requires a known length for a single-shot upload (workerd will not implicitly buffer an arbitrary stream to discover it). So the BlobStore receives a body it cannot hand to R2.

There is no way to opt out from the caller side: the wrap is unconditional, and maxArtifactBytes: Infinity disables the threshold but not the wrapping.

Why the obvious fixes are wrong

Worth stating, since both look reasonable:

• Buffer the stream in the store. DEFAULT_MAX_ARTIFACT_BYTES is 100 MB against a 128 MB Worker memory limit. This works for images and becomes an OOM risk for video — it fails late and under load rather than immediately.
• Skip capBodySize whenever content-length is present. This is what I first assumed, but the code comment is right to reject it: fetch transparently decompresses, so on a content-encoding: gzip response content-length is the compressed size and the decoded body can be arbitrarily larger. Trusting it would open a decompression-bomb hole.

I worked around it by buffering one 8 MiB part and switching to an R2 multipart upload beyond that, which bounds memory regardless of artifact size. That works, but it is a fair amount of machinery for every Workers user to reinvent, and it costs the download/upload overlap that streaming straight to put would give.

Suggestions

Roughly in order of leverage:

1. Expose the known length to the store (additive, runtime-agnostic).

The middleware already knows declaredLength, and descriptorBody computes exact sizes for the bytes / json branches. Adding an optional hint to BlobPutOptions — say expectedLength?: number — would let a store choose single-shot vs multipart knowingly, or on workerd re-wrap with new FixedLengthStream(n). It changes no cap semantics and no existing behaviour.

2. Add a length-less stream to the conformance testkit.

runPersistenceConformance appears to exercise blobs.put with byte bodies. A case that puts a TransformStream-wrapped stream would have caught both this and the broken recipe as a test failure, instead of surfacing as a runtime error in an app. This is probably the highest-value change — a Uint8Array takes a different branch in most stores and proves nothing about the streaming path.

3. Fix ai-persistence/build-cloudflare-artifact-store.

The skill states:

BlobBody is ReadableStream<Uint8Array> | ArrayBuffer | ArrayBufferView | string | Blob — which is exactly what R2Bucket.put accepts, so the body flows straight through with no conversion.

That holds only for bodies that already carry a length, which is never true for the URL path — i.e. essentially every generated artifact. Anyone following this recipe gets a store that passes the conformance suite and fails on first real use.

4. Nit, same function.

const declaredLength = Number(response.headers.get('content-length'))
if (Number.isFinite(declaredLength) && declaredLength > maxBytes) { ... }

headers.get returns null when absent, and Number(null) === 0, which is finite — so a missing content-length reads as a declared length of 0 and always passes. Harmless today because the drain-time check is the real enforcement, but the early-reject silently never fires for chunked responses.

Reproduction

Any generateImage / generateVideo through withGenerationPersistence with an R2-backed blobs store, where the provider returns a result URL. Minimal shape of the failing call:

// R2 BlobStore.put — body is the capBodySize-wrapped stream
await bucket.put(key, body, { httpMetadata: { contentType } })
// TypeError: Provided readable stream must have a known length

Standalone, without any provider or this library — run inside a Worker with an R2 binding. The first put is a positive control isolating the pipeThrough as the sole cause:

// 1. Response.body straight through — succeeds, length preserved
await bucket.put('probe-direct', new Response('x'.repeat(1024)).body!)

// 2. Identical bytes via a pass-through TransformStream — throws
const lengthless = new Response('x'.repeat(1024)).body!.pipeThrough(new TransformStream())
await bucket.put('probe-wrapped', lengthless)

Observed on workerd 1.20260730.1:

Response.body direct           -> OK (length preserved)
pipeThrough(TransformStream)   -> THREW: Provided readable stream must have a known length
                                  (request/response body or readable half of FixedLengthStream)

Happy to send a PR for (1) and (2) if that direction seems right.