Wire MCP resources/read through host + chat renderer for resource_link

[mgoldsborough]

Summary

Completes the host-side half of the MCP resource_link story. Tools that return large artifacts (PDFs, images) can now produce tiny resource_link content blocks pointing at a URI, and the host fetches the bytes via standard MCP resources/read in three places that matter:

1. New HTTP endpoint POST /v1/resources/read — symmetric with /v1/tools/call. Bundles expose resources, host proxies via the same middleware stack.
2. Bridge plumbing — iframe apps can call synapse.readResource(uri) (the SDK counterpart is synapse#2). The bridge now has a case "resources/read": next to case "tools/call": that forwards to the new HTTP endpoint.
3. Chat renderer — tool results with resource_link blocks now render inline in the chat stream via a new ResourceLinkView component that dispatches on mimeType (PDF → iframe, image/* → <img>, text/* → <pre>, else → download link).

Net: a tool returning a 50-page PDF via resource_link produces a ~450-byte tool result and the bytes are fetched out-of-band. No more 1MB tool-result cap failures on artifact-returning tools.

Why

Tools returning large binary artifacts used to inline base64 bytes in the CallToolResult.content. That hits the engine's 1MB maxToolResultSize cap (killed a multi-hour Collateral session; see issue context). Inlining also pollutes the model's context with useless data it can't read.

The MCP spec already offers resource_link content blocks for exactly this. A tool returns a URI; the client calls resources/read to get the bytes. This PR implements the client half for NimbleBrain — host + iframe + chat all speak the resource channel properly.

Architecture

iframe → synapse.readResource(uri)
  → postMessage "resources/read" → web bridge (parent frame)
    → fetch POST /v1/resources/read { server, uri }
      → handleReadResource → runtime.readAppResource(server, uri, wsId)
        → source.readResource(uri) → MCP JSON-RPC → bundle

Design principle: symmetry with tools/call. resources/read is a peer MCP method, not a special case. Same middleware, same proxy pattern, same shape — just a different spec method.

What changed

Server

File	Change
src/api/handlers.ts	New handleReadResource. Returns MCP ReadResourceResult JSON; base64-encodes blob for binary, passes text through. 403 cross-workspace, 404 null, 400 bad body. Exports bytesToBase64.
src/api/routes/resources.ts	POST /v1/resources/read mounted alongside the existing GET route, sharing auth + workspace middleware with /v1/tools/call.
src/runtime/runtime.ts	readAppResource now passes URIs with any scheme through unchanged (previously hardcoded ui:// prefix). Keeps ui:// fallback for legacy callers.
src/engine/content-helpers.ts	New extractResourceLinks(content) helper + ResourceLinkInfo type.
src/engine/engine.ts	Scans finalResult.content for resource_link blocks after tool execution, attaches them to the tool.done event under resourceLinks.
src/engine/types.ts	Extends ToolCallRecord with optional resourceLinks.

Web bridge

File	Change
web/src/bridge/bridge.ts	New case "resources/read": handler. Mirrors case "tools/call": — same security posture (server scoped to appName unless internal), error envelope on failure.
web/src/bridge/types.ts	ResourcesReadMessage, UiResourceResultResponse, UiResourceResultError wired into the host/app message unions.
web/src/api/client.ts	New readResource(server, uri) client function + ReadResourceResult / ReadResourceContent types. Mirrors callTool.

Chat renderer

File	Change
web/src/components/ResourceLinkView.tsx	New component. Fetches via readResource(appName, uri), decodes base64, creates object URL, dispatches on mimeType (PDF iframe / image / text <pre> / download link). Object URL lifecycle managed (create on blob change, revoke on unmount).
web/src/components/MessageList.tsx	Renders a <ResourceLinkView> per resource_link block on each tool call. Existing InlineAppView path untouched (different concern — ui:// HTML app binding).
web/src/hooks/useChat.ts	ToolCallDisplay carries resourceLinks, populated from tool.done and from loaded conversation metadata.
web/src/types.ts	ResourceLinkInfo, extended ToolDoneEvent + ToolCallRecord.

Test plan

• test/unit/api/read-resource-handler.test.ts — 12 tests covering shape, binary/text dispatch, base64 encoding, workspace scoping, 400/403/404 paths, URI passthrough for any scheme (ui://, collateral://, https://).
• test/unit/bridge-resources-read.test.ts — 4 tests: URI forwarding, appName scoping for non-internal apps, internal bundle override behavior, error envelope on failure.
• test/unit/engine.test.ts — 2 new tests: resource_link blocks propagate onto tool.done.resourceLinks; absence doesn't create a spurious empty array.
• bun run verify — 2179/2179 tests pass (1764 unit + 61 web + 338 integration + 16 smoke), lint clean, typecheck clean, build clean.

Dependency

Runtime-wise, this PR stands alone — the new endpoint works today against any MCP server that exposes resources. The iframe path specifically uses synapse.readResource which is added in synapse#2. For iframe apps to actually call into this, synapse#2 needs to land and be released first. For the chat renderer (in-app React component), no synapse dep — it calls /v1/resources/read directly.

Compatibility

• Additive — no existing API changed. The GET /v1/apps/:name/resources/* route stays for ui:// HTML app serving. The POST /v1/resources/read is new.
• runtime.readAppResource scheme generalization — was ui://-only, now passes any scheme through. Backward-compatible because the ui:// branch remains as fallback when no scheme is present in the input.
• No config changes. No env vars. No migrations.

Risk

Low. The new endpoint is auth+workspace-gated via the same middleware that protects every other /v1 route. Binary content is base64-encoded per spec. The bridge forwarding is a direct pass-through — we aren't interpreting resource_link URIs, just carrying them.

The main user-visible change is that tool.done events now carry resourceLinks — any consumer (CLI, logs, conversation store) that deserializes these events will see the new field. All in-tree consumers updated.

[mgoldsborough]

Addressed QA review in 6cbbc62.

Warning 1 (stale persistence type) — fixed. StoredMessage.metadata.toolCalls in src/conversation/types.ts now declares resourceLinks?: Array<{ uri; name?; mimeType?; description? }>. The web-side mirror in useChat.ts gets the same extension. The tc as Record<string, unknown> cast on the reload path is gone — everything is typed end-to-end.

Suggestion 1 (duplicate INTERNAL_APPS) — fixed. Hoisted to a module-level const at the top of web/src/bridge/bridge.ts so both tools/call and resources/read share one source of truth. No more drift hazard if the trust list grows.

Suggestion 2 (PDF iframe sandbox) — fixed with a correction. QA proposed sandbox=\"allow-same-origin\", but that would actually block scripts (Chrome's PDF viewer needs them) without isolating the iframe. The correct defense-in-depth is sandbox=\"allow-scripts\" without allow-same-origin — PDF JS runs in a null origin, can't reach cookies / storage / same-origin resources. That's what landed on ResourceLinkView.tsx. Added a comment explaining the choice.

Suggestion 3 (Bun native Buffer) — fixed. bytesToBase64 now prefers Buffer.from(bytes).toString(\"base64\") when available (Bun + Node), falling back to the chunked btoa path for portability. On Bun this is a single native call — noticeable on large PDFs where this handler is the hot path.

Suggestion 4 (SSRF comment) — fixed. One-line comment in the bridge's resources/read case clarifying that URI passthrough is safe because only URIs advertised via the bundle's resources/list will resolve — SSRF safety lives in the bundle, not the host.

Verification after changes:

• bunx tsc --noEmit — clean
• bun run verify — 1764 unit + 61 web + 338 integration + 16 smoke = 2179/2179 pass
• cd web && bun run build — clean

Ready for re-review.