Closes #100705

What Problem This Solves

Operators running agents remotely (containers, VPS, always-on gateways) have no way to inspect what an agent produced or changed in its workspace from the mobile apps. The existing gateway file APIs cover only allowlisted bootstrap files (agents.files.*) or session-transcript-touched text files (sessions.files.*), so checking a generated report, a log, or an edited config from a phone requires SSH into the gateway host.

Why This Change Was Made

Ships the read-only slice of the workspace browser end to end: one canonical agent-scoped gateway RPC pair — agents.workspace.list (bounded, deterministically ordered directory listing with offset pagination) and agents.workspace.read (size-capped, type-gated file read: UTF-8 text ≤256 KB inline, images ≤5 MB base64, other binary rejected) — plus browse/preview/share UI on iOS (Agent tab Files section, reusing the chat code renderer and ShareLink) and Android (Settings → Workspace Files, share intent via the existing FileProvider). Reads are confined to the agent workspace root by path pre-normalization (absolute paths and .. rejected before any filesystem access) and the existing fs-safe root (realpath, symlink and hardlink rejection). Strictly read-only by design: write/delete/upload stay with the broader workspace API discussion (#61368 / #62417), and the agents.workspace.* namespace matches that direction so it can extend rather than conflict. Protocol schemas are additive; Swift models regenerated.

User Impact

Mobile operators can now open Files on the agent surface (iOS) or Settings → Workspace Files (Android), drill through the agent's workspace, preview text with syntax highlighting and images inline, and export any previewed file through the platform share sheet — without SSH or a desktop. Both methods are operator.read scope; nothing can modify the workspace.

Evidence

• Live gateway e2e (in this PR): test/agents-workspace.e2e.test.ts spawns a real gateway process and a real operator WebSocket client, then verifies dirs-first listing, drill-down parentPath, UTF-8 text read, byte-exact PNG base64 round-trip, and rejection of ../ and absolute-path escapes over the wire. Green via node scripts/run-vitest.mjs test/agents-workspace.e2e.test.ts.
• Handler regression tests: src/gateway/server-methods/agents-workspace.test.ts (10 tests) covers listing/pagination, text/image reads, and negative cases: traversal, absolute paths, symlink escape, oversize files, binary gating, unknown agent id. Verified fail-before/pass-after by removing the handler module.
• Android, real behavior on an emulator: debug APK built (:app:assemblePlayDebug), installed on an Android 16 ARM64 emulator, paired with a live local gateway through the app's own device/node approval flow, then exercised manually: workspace listing (directories first), live refresh picking up a file created on the host after pairing, drill-down, text preview (todo.md, 30 B · text/markdown, monospace), visible image preview (base64 → bitmap), and share-sheet export delivered to a target app. :app:testPlayDebugUnitTest green locally including the new WorkspaceFilesTest (5 parser/params tests).
• Swift/iOS: shared WorkspaceFileBrowser views + WorkspaceFileBrowserTests (7 tests: params encoding, payload decoding through a stub requester, language-id mapping, UTF-8/base64 export byte fidelity) live in OpenClawKit; the macos-swift CI job compiles them. SwiftFormat lint clean over the full iOS filelist (0/172 files require formatting).
• Repo gates run locally: pnpm tsgo:prod (core + extensions) clean, pnpm lint shards clean, pnpm check:docs clean after regenerating docs/docs_map.md, pnpm native:i18n:check clean after syncing the native i18n inventory, gateway-protocol package tests (250) and neighbor gateway suites (410 tests) green, full npm run build exit 0.