workspace: add assets module for sharing files via R2

[aron-cf]

This change adds an assets publishing surface for @cloudflare/workspace. A Workspace can now upload a file from its virtual filesystem to R2 and return a short-lived presigned URL. The URL key is unique per share, includes only the filename, and carries the right content type, disposition, and metadata.

The public API lives at @cloudflare/workspace/assets and follows the same factory shape as the git client: bind the workspace, bucket, and signing configuration once, then call share() for each file.

import { createAssets } from "@cloudflare/workspace/assets";

const assets = createAssets({
  ws,
  bucket: env.ASSETS,
  s3: { bucket: "agent-assets" },
  env,
});

const url = await assets.share("/workspace/out/image.png", {
  expiresAfter: 30 * 1000,
  prefix: `agent-${ws.sessionId}`,
});

R2 bucket bindings can upload objects, but they cannot mint presigned URLs. The signer therefore uses R2's S3-compatible credentials, resolved from explicit s3 options or from the usual environment values: CLOUDFLARE_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, and R2_ENDPOINT when set. Uploads still go through the R2 binding; only the presigned GET URL uses the S3 signing path.

The object key has this shape:

<prefix>/<random-id>/<filename>

The random id is 16 bytes encoded as Crockford base32, so sharing the same file twice creates two distinct objects. Only the filename appears in the URL path; the full workspace path is stored only in R2 custom metadata. The body is streamed from the virtual filesystem through FixedLengthStream before calling bucket.put(), because R2 requires stream uploads to have a known length.

Workspaces can also expose the publisher to the worker backend's just-bash shell by attaching the assets client at construction time:

const ws = new Workspace({
  storage: ctx.storage,
  backends: [
    new WorkerBackend({
      loader: env.LOADER,
      workspace: { binding: "MyWorkspace", id: ctx.id.toString() },
      ctx,
    }),
  ],
  assets: (ws) =>
    createAssets({
      ws,
      bucket: env.ASSETS,
      s3: { bucket: "agent-assets" },
      env,
    }),
});

That makes a new shell command available inside the Dynamic Worker:

assets publish /workspace/out/image.png
assets publish ./out/image.png 30s
assets publish report.pdf 5m
assets publish build.zip 2h

The command prints the share URL to stdout. It accepts absolute paths or paths relative to the current working directory. The optional expiry defaults to one hour; a bare number is milliseconds, and ms, s, m, and h suffixes are supported. The Dynamic Worker never receives the R2 binding or signing secrets; it forwards to the host workspace over the existing RPC loopback.

This also adds an examples/assets project that turns a one-shot prompt into an image link. The Worker accepts POST /prompt, runs the FLUX.2 [klein] 9B Workers AI image model, writes the generated PNG into a backend-less Workspace, publishes it through the assets client, and returns { path, url }.

curl -X POST https://workspace-assets-example.<your-subdomain>.workers.dev/prompt \
  -H 'content-type: application/json' \
  -d '{"prompt":"a sunset over the alps, oil painting"}'

{
  "path": "/workspace/0d58d8c2-7c5c-48a2-bd22-c25f9dd5c824.png",
  "url": "https://<account>.r2.cloudflarestorage.com/..."
}

The example is production-only. It needs an R2 bucket, Workers AI, and R2 S3 credentials set as secrets. A .dev.vars.example documents the required values, but a local dev stack will not produce a working public link.

Manual verification:

wrangler r2 bucket create workspace-assets-example
wrangler secret put R2_ACCESS_KEY_ID
wrangler secret put R2_SECRET_ACCESS_KEY
wrangler secret put CLOUDFLARE_ACCOUNT_ID
npm run deploy --workspace @example/workspace-assets

Then call POST /prompt and open the returned URL before it expires.

The change is covered by unit and integration tests for key generation, MIME inference, SigV4 signing, fixed-length R2 uploads, share() behavior against a real SQLite-backed Workspace, WorkspaceStub.assets, and the worker-backend assets publish command. The validation run was:

npm run format
npx biome check .
npx vitest run --workspace @cloudflare/workspace
npx vitest run --workspace @cloudflare/workspace -- --config vitest.config.worker-backend.ts
npx tsc -p packages/workspace/tsconfig.build.json --noEmit
npm run build --workspace @cloudflare/workspace
npm run typecheck --workspace @cloudflare/example-think
npm run typecheck --workspace @example/workspace-assets

Documentation was added for the assets interface, the worker backend shell command, and the new example. The think example now wires the same assets publisher into both its model-facing share tool and the worker shell's assets publish command when the R2 credentials are present.