feat: agent-driven uploads (images, traces, files)

[benvinegar]

Agents can now push binary and structured artifacts — images, screenshots, agent traces, arbitrary files — over all three tiers (CLI, MCP, raw HTTP), and the viewer surfaces them natively.

Summary

This implements a complete asset upload system with two new part kinds (image and trace) that agents can reference by ID. Assets are stored separately from surfaces to avoid bloating the 2 MB surface limit with binary data, and include reference-aware LRU eviction to stay within a per-board budget.

Key changes

• New Asset entity in server/types.ts: stores uploaded blobs with metadata (kind, contentType, byteLength, filename). Scoped to sessions for cascade deletion.
• Two new part kinds:
  • ImagePart: references an uploaded image by assetId, rendered natively by the viewer as a trusted <img> (no iframe).
  • TracePart: renders a step timeline beside the surface. Steps can travel inline (small, structured) or live in an uploaded JSON/JSONL file offered for download.
• HTTP API (POST /api/assets, GET /a/:id): accepts raw bytes with metadata in query params, or base64-JSON bodies. Serves assets with security-conscious headers (raster images inline, SVG/JSON/text as attachments to prevent script execution).
• Storage:
  • SqlStore: new assets table with BLOB data column (33% smaller than base64, no decode-on-serve).
  • JsonFileStore: new assets[] entry; bytes persist/load as base64 (JSON limitation), live as Uint8Array in memory.
• Reference-aware LRU eviction: when a new upload would exceed MAX_BOARD_ASSET_BYTES (~2 GB), putAsset evicts oldest-lastAccessedAt-first, but partitioned so unreferenced assets go first. Assets still referenced by live surface parts are only evicted as a last resort. lastAccessedAt is bumped on every serve, protecting raw-URL embeds that referencedAssetIds() can't see.
• CLI commands: sideshow upload, sideshow image, sideshow trace to push assets and publish them as surfaces. sideshow publish --image to add an image part to an html surface.
• MCP support: upload_asset tool in the MCP schema; coerceParts validates image and trace parts from tool args.
• Viewer components: ImagePart.tsx and TracePart.tsx render assets natively. Missing/evicted assets show a clear placeholder rather than broken images.
• Security: CSP updated to allow origin in img-src and media-src so uploaded assets at <origin>/a/:id embed by URL. Sandboxed iframes still can't access them directly (opaque origin), but <img> and fetch work.

Implementation details

• Uint8Array is the standard-lib type for bytes across the Store interface and in memory; base64 is only an edge encoding (HTTP request bodies, MCP args, JsonFileStore on-disk JSON).
• partsByteLength() extended to count image/trace part refs (small); asset bytes are bounded separately by the board budget.
• firstHtml/stripParts remain correct — image/trace parts are structured data, passed through untouched like diff.
• Both stores pass the extended test/storeContract.ts suite, which now includes asset tests.
• E2E tests cover image embedding, trace rendering (inline and uploaded), and asset eviction scenarios.

https://claude.ai/code/session_01XWa7rTcBdXdEHg3Px9rXGY