Summary

Add a read-only workspace file browser to the iOS and Android apps: browse the agent's working directory tree, preview text and image files, and export a file through the platform share sheet.

Problem to solve

Operators using the mobile apps cannot inspect what an agent has produced or changed in its workspace. Today the gateway exposes only an allowlisted set of bootstrap files (agents.files.*) and a session-scoped browser (sessions.files.*) that can list the workspace tree but only returns content for transcript-touched text files — no arbitrary in-root reads, no binary/image support, and it is keyed by session rather than agent. The mobile apps expose none of this, so checking a generated file, a log, or an edited config from the phone requires shell access to the gateway host.

Proposed solution

1. Gateway: one canonical read-only RPC pair, agent-scoped:
   • agents.workspace.list — bounded directory listing under the agent workspace root (deterministic ordering, pagination for large directories).
   • agents.workspace.read — bounded file read with byte-size caps and text/image type gating (UTF-8 text inline, images base64).
   • Root confinement via the existing fs-safe infrastructure: realpathed root, symlink/hardlink rejection, path-traversal rejection. Read scope only; no write operations.
   • Additive protocol schema + regenerated Swift models; traversal-attack negative tests.
2. iOS: a Files section on the agent surface with directory drill-down, syntax-highlighted text preview (reusing the chat code renderer), image preview, and share-sheet export.
3. Android: the same feature following existing navigation patterns, with preview and share-intent export.

Alternatives considered

• Consume sessions.files.* as-is: insufficient — content is restricted to transcript-touched files, text-only, and session-keyed; the mobile entry point is the agent.
• Land the full agents.workspace.* CRUD surface ([Feature]: Full Workspace File Management API for Remote/Container Deployments #61368 / feat: add workspace file management for agents #62417): the write surface needs a separate security/product decision; a read-only subset first keeps the boundary reviewable and matches the direction already suggested in that thread.
• Per-client ad hoc endpoints: rejected; one canonical pair serves mobile now and other clients later.

Impact

Affected: operators running agents remotely (containers, VPS, always-on gateways) who use the mobile apps.
Severity: workflow gap — no mobile visibility into agent output files.
Frequency: whenever an agent produces or edits files the operator wants to verify away from a desktop.
Consequence: SSH/desktop round-trips for simple "what did the agent write" checks.

Evidence/examples

• [Feature]: Full Workspace File Management API for Remote/Container Deployments #61368 — canonical workspace file management API request (full CRUD, needs product/security decision).
• [Feature]: Clickable file links in chat with file viewer sidebar; workspace navigator previews any in-root file #100615 — Control UI: workspace navigator should preview any in-root file.
• File Browser: Remove ALLOWED_FILE_NAMES whitelist, add scope levels #44108 — file browser scope levels request; documents the deliberate agents.files.* allowlist boundary.

Additional information

Security is the crux: the read path must be confined to the agent workspace root (realpath + reject escapes), size-capped, and type-gated. V1 is strictly read-only; write/delete/upload remain with #61368.