feat(files): open markdown, HTML, and PDF files outside the workspace

[juliusmarminge]

Agents regularly write a report to a temp directory and link it in their reply. That chip was a dead end: the files panel only accepted workspace-relative paths, and projects.readFile rejected anything outside the root. HTML and PDF links outside the workspace failed one layer down, because the browser preview always minted a workspace-scoped asset URL.

How

• Server: WorkspaceFileSystem.readFile accepts an absolute path and reads that host file in place. Workspace-relative paths keep the root and symlink containment checks, and writeFile still rejects absolute paths, so host files are read-only. The media-file asset resource now also accepts .html, .htm, and .pdf, using the same exact-file, inode-pinned token; workspace HTML keeps using the directory-scoped workspace-file resource so sibling assets load.
• Web: file chips carry a panelPath that falls back to the absolute host path for non-media files outside the workspace, so they open in the files panel. The panel renders host files read-only (rendered Markdown works, checkboxes do not write back) with breadcrumbs starting at the filesystem root. openFileInPreview picks workspace-file or media-file by workspace membership, so the panel's browser button and PDF chips work for host files.
• Mobile: outside-workspace chips route to the file screen (PDFs to the existing PDF preview with a media-file resource), and the asset URL hook picks media-file for host paths.
• Docs: user note in composer.md; environment-auth.md updated, since it explicitly stated the workspace boundary still applied to HTML and PDF.

No wire changes: media-file and readFile keep their shapes, so older clients keep working.

One deliberate widening to flag: an authenticated orchestration:read client can now read any text file the server account can read, not only workspace files. That matches what filesystem.browse and media-file already allow and is documented as such.

Demo

Clicking a /tmp/...cleanup-report.md chip opens it in the files panel, toggling to rendered Markdown, then opening the .html chip beside it:

https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/7191626f13944a44/outside-workspace-files.webm

Verification

• apps/server: WorkspaceFileSystem.test.ts (absolute read, absolute write rejected), AssetAccess.test.ts (HTML/PDF minting), http.test.ts
• apps/web: filePath.test.ts (host breadcrumbs), markdown-links.test.ts, ChatMarkdown.*.test.tsx, FilePreviewPanel.test.ts
• apps/mobile: filePath.test.ts (route segments round-trip)
• Per-package typecheck and lint on the changed files; web flow exercised end to end in the recording above.

Written by Claude Fable 5 in Claude Code.

🤖 Generated with Claude Code

---

Note

Medium Risk
Expands what authenticated orchestration:read clients can read and preview on the host (any text file via absolute readFile, HTML/PDF via media-file), though writes stay workspace-bound and HTML gets a sandbox CSP.

Overview
Agents can link files outside the project (e.g. /tmp/.../report.md); this PR wires those links through end-to-end instead of stopping at workspace-only paths.

Server: projects.readFile / WorkspaceFileSystem.readFile now accept an absolute host path and read that file in place (still read-only—writeFile rejects absolutes). Workspace-relative reads keep root/symlink containment; opens use non-blocking mode so FIFOs fail instead of hanging. The media-file asset resource now allows HTML and PDF (via hostPreviewMimeTypeFromExtension), and inline HTML responses add a sandbox CSP.

Web & mobile: File chips carry a panelPath that can be the absolute host path; the files panel shows host files read-only (markdown render on, task-list edits off) with breadcrumbs from the filesystem root. openFileInPreview and asset URL minting choose workspace-file vs media-file based on whether the path is inside the workspace. Mobile thread links navigate to the file screen (or PDF preview) for absolute paths. Markdown relative links can anchor on imageBaseDir when rendering a file outside the repo.

Docs/contracts: User and environment-auth docs describe host file read and expanded media preview; contract comments/error text updated—no wire shape changes.

^{Reviewed by Cursor Bugbot for commit c0fa311. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Support opening markdown, HTML, and PDF files outside the workspace

• Server WorkspaceFileSystem.readFile now accepts absolute host paths via resolveReadTarget, resolving them through realpath without applying the workspace-root boundary check; writes remain workspace-relative only.
• Asset URL issuance and resolution in AssetAccess accept HTML and PDF (in addition to images and videos) using the new shared hostPreviewMimeTypeFromExtension classifier; unsupported extensions still return no asset.
• Web and mobile clients classify absolute paths as host files, render them read-only in the file panel, and use exact media-file asset URLs for out-of-workspace previews. Markdown link resolution gains an optional baseDir so relative links anchor to the rendered file's directory rather than only the workspace cwd.
• HTML asset responses now include a sandbox content-security policy (permitting scripts, forms, popups, modals) alongside the UTF-8 content type.
• File breadcrumbs and path utilities handle POSIX, Windows drive, and UNC absolute paths, starting at the filesystem root instead of the project name.
• Risk: WorkspaceFileSystem.resolveReadTarget bypasses the workspace-root boundary check for absolute reads — any reachable host file path is readable. HTML sandbox CSP permits scripts and forms within the sandboxed context; separately served HTML cannot load adjacent scripts, styles, or images.

^{Macroscope summarized c0fa311.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.4 KiB	13.2 KiB	−242 B (−1.8%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	−8 B (−0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.5 KiB	6.3 KiB	−234 B (−3.5%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	57.0 KiB	55.5 KiB	−1.5 KiB (−2.6%)	66.4 KiB	✅
Codex	Live turn messages	10	8	−2 (−20.0%)	21	✅
Claude	Total thread wire	13.5 KiB	13.4 KiB	−23 B (−0.2%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	−5 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.6 KiB	6.6 KiB	−18 B (−0.3%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	57.8 KiB	57.8 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	10	10	0 (0.0%)	21	✅

Baseline: ea71a19 · PR result: c0fa311 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{Bugbot Autofix is ON, but a cloud agent failed to start.}

^{Reviewed by Cursor Bugbot for commit e52e413. Configure here.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds an end-to-end capability for authenticated clients to read server-host files by absolute path and preview external HTML/PDF, changing filesystem and browser security boundaries across server, web, and mobile. The changed test also adds a file-level static-analysis diagnostic suppression, so the authorization expansion and analysis override require human review.

^{You can add or adjust custom eligibility rules. Learn more.}