AHP large-resource transport: streamed/range resource reads (no whole-file-in-one-shot)

[nick-pape]

Extends the AHP resources channel (#1337). Opened as the wire-side blocker for the rich/binary document-preview carve-out of the GrackleCode live-docs epic (#1394).

The gap

The vendored AHP resources capability exposes a single whole-file read shape:

resourceRead{ uri, encoding? } -> { data, encoding, contentType? }

data is the entire file in one response (base64 for binary). There is no range read, no chunked/streamed read, no size negotiation in the protocol. As of the current vendored pin, upstream AHP has not designed for large file formats at all.

This is fine for the formats GrackleCode v0 actually renders — markdown / code / plain text comfortably fit a single read. It is not fine for the formats deferred to the rich-preview carve-out:

• image / audio / video / pdf / docx and other binary blobs

Base64-ing a large media file into one gRPC message is a non-starter (memory blowup, message-size limits, no progressive render).

What's needed (upstream-first)

1. An AHP wire capability for large/streamed resource transport — e.g. a range/offset read (resourceRead{ uri, offset, length }) and/or a streamed/chunked resource channel, plus a way to learn a resource's size + content-type without fetching its bytes (a resourceStat-style head). This is upstream protocol design in microsoft/agent-host-protocol; it does not exist yet.
2. PowerLine host support — once the wire exists, advertise + implement it in the AHP host (packages/powerline), mirroring how the read/list/watch handlers landed for AHP CO-1: resource channel (deferred — not advertised, spec-compliant) #1337/Live docs: Server AHP-client resource bridge (read/list/watch + web path) #1395.
3. Server bridge + web consumer — extend the resource bridge (Live docs: Server AHP-client resource bridge (read/list/watch + web path) #1395) and the GrackleCode preview registry to use ranged/streamed reads for the binary preview kinds (blob-URL'd <img>/<audio>/<video>, pdf.js, etc.), with a size guard.

Status / when to open for real

P3, blocked on upstream AHP design. No concrete consumer is committed yet — GrackleCode v0 (#1396) deliberately ships text-only and treats unknown/binary as a graceful "no preview available" fallback. Pick this up when (a) upstream AHP adds a large-resource transport, or we decide to drive that design, and (b) a rich/binary preview kind is actually scheduled. Until then this issue exists so the dependency isn't silently dropped.

Refs

• Resources channel: AHP CO-1: resource channel (deferred — not advertised, spec-compliant) #1337 · Resource bridge (merged): Live docs: Server AHP-client resource bridge (read/list/watch + web path) #1395
• Consumer that defers to this: GrackleCode live-docs epic Epic: Live collaborative documents (GrackleCode) #1394 / v0 viewer Live docs v0: tabbed read-only live file viewer (show_file + resourceRead/Watch) #1396