Add model-native workspace file operations

Remove shell-escaped file mutation from the stable workspace flow by adding explicit file and patch tools across the CLI, SDK, and MCP surfaces.

This adds workspace file list/read/write plus unified text patch application, backed by new guest and manager file primitives that stay scoped to started workspaces and /workspace only. Patch application is preflighted on the host, file writes stay text-only and bounded, and the existing diff/export/reset semantics remain intact.

The milestone also updates the 3.2.0 roadmap, public contract, docs, examples, and versioning, and includes focused coverage for the new helper module and dispatch paths.

Validation:
- uv lock
- UV_CACHE_DIR=.uv-cache make check
- UV_CACHE_DIR=.uv-cache make dist-check
- real guest-backed smoke for workspace file read, patch apply, exec, export, and delete

docs/first-run.md

@@ -22,7 +22,7 @@ Networking: tun=yes ip_forward=yes
 
 ```bash
 $ uvx --from pyro-mcp pyro env list
-Catalog version: 3.1.0
+Catalog version: 3.2.0
 debian:12 [installed|not installed] Debian 12 environment with Git preinstalled for common agent workflows.
 debian:12-base [installed|not installed] Minimal Debian 12 environment for shell and core Unix tooling.
 debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.
@@ -76,6 +76,8 @@ a source checkout.
 $ uvx --from pyro-mcp pyro workspace create debian:12 --seed-path ./repo --json | tee /tmp/pyro-workspace.json
 $ export WORKSPACE_ID="$(python -c 'import json,sys; print(json.load(sys.stdin)["workspace_id"])' < /tmp/pyro-workspace.json)"
 $ uvx --from pyro-mcp pyro workspace sync push "$WORKSPACE_ID" ./changes
+$ uvx --from pyro-mcp pyro workspace file read "$WORKSPACE_ID" note.txt
+$ uvx --from pyro-mcp pyro workspace patch apply "$WORKSPACE_ID" --patch "$(cat fix.patch)"
 $ uvx --from pyro-mcp pyro workspace exec "$WORKSPACE_ID" -- cat note.txt
 $ uvx --from pyro-mcp pyro workspace snapshot create "$WORKSPACE_ID" checkpoint
 $ uvx --from pyro-mcp pyro workspace service start "$WORKSPACE_ID" web --ready-file .web-ready -- sh -lc 'touch .web-ready && while true; do sleep 60; done'
@@ -95,6 +97,10 @@ $ uvx --from pyro-mcp pyro workspace delete "$WORKSPACE_ID"
 $ uvx --from pyro-mcp pyro demo
 $ uvx --from pyro-mcp pyro workspace create debian:12 --seed-path ./repo
 $ uvx --from pyro-mcp pyro workspace sync push WORKSPACE_ID ./changes
+$ uvx --from pyro-mcp pyro workspace file list WORKSPACE_ID src --recursive
+$ uvx --from pyro-mcp pyro workspace file read WORKSPACE_ID src/app.py
+$ uvx --from pyro-mcp pyro workspace file write WORKSPACE_ID src/app.py --text 'print("hi")'
+$ uvx --from pyro-mcp pyro workspace patch apply WORKSPACE_ID --patch "$(cat fix.patch)"
 $ uvx --from pyro-mcp pyro workspace create debian:12 --network-policy egress
 $ uvx --from pyro-mcp pyro workspace create debian:12 --secret API_TOKEN=expected --secret-file PIP_TOKEN=./token.txt
 $ uvx --from pyro-mcp pyro workspace exec WORKSPACE_ID --secret-env API_TOKEN -- sh -lc 'test "$API_TOKEN" = "expected"'
@@ -128,6 +134,17 @@ Command count: 0
 $ uvx --from pyro-mcp pyro workspace sync push WORKSPACE_ID ./changes --dest src
 [workspace-sync] workspace_id=... mode=directory source=... destination=/workspace/src entry_count=... bytes_written=... execution_mode=guest_vsock
 
+$ uvx --from pyro-mcp pyro workspace file list WORKSPACE_ID src --recursive
+Workspace file path: /workspace/src
+- /workspace/src/note.txt [file] bytes=...
+
+$ uvx --from pyro-mcp pyro workspace file read WORKSPACE_ID src/note.txt
+hello from synced workspace
+[workspace-file-read] workspace_id=... path=/workspace/src/note.txt size_bytes=... truncated=False execution_mode=guest_vsock
+
+$ uvx --from pyro-mcp pyro workspace patch apply WORKSPACE_ID --patch "$(cat fix.patch)"
+[workspace-patch] workspace_id=... total=... added=... modified=... deleted=... execution_mode=guest_vsock
+
 $ uvx --from pyro-mcp pyro workspace exec WORKSPACE_ID -- cat src/note.txt
 hello from synced workspace
 [workspace-exec] workspace_id=... sequence=1 cwd=/workspace execution_mode=guest_vsock exit_code=0 duration_ms=...
@@ -231,11 +248,12 @@ State: started
 Use `--seed-path` when the workspace should start from a host directory or a local
 `.tar` / `.tar.gz` / `.tgz` archive instead of an empty `/workspace`. Use
 `pyro workspace sync push` when you need to import later host-side changes into a started
-workspace. Sync is non-atomic in `3.1.0`; if it fails partway through, prefer `pyro workspace reset`
+workspace. Sync is non-atomic in `3.2.0`; if it fails partway through, prefer `pyro workspace reset`
 to recover from `baseline` or one named snapshot. Use `pyro workspace diff` to compare the current
 `/workspace` tree to its immutable create-time baseline, `pyro workspace snapshot *` to create
 named checkpoints, and `pyro workspace export` to copy one changed file or directory back to the
-host. Use `pyro workspace exec` for one-shot commands and `pyro workspace shell *` when you
+host. Use `pyro workspace file *` and `pyro workspace patch apply` for model-native text edits,
+`pyro workspace exec` for one-shot commands, and `pyro workspace shell *` when you
 need a persistent interactive PTY session in that same workspace. Use `pyro workspace service *`
 when the workspace needs long-running background processes with typed readiness checks. Internal
 service state and logs stay outside `/workspace`, so service runtime data does not appear in

docs/install.md

@@ -85,7 +85,7 @@ uvx --from pyro-mcp pyro env list
 Expected output:
 
 ```bash
-Catalog version: 3.1.0
+Catalog version: 3.2.0
 debian:12 [installed|not installed] Debian 12 environment with Git preinstalled for common agent workflows.
 debian:12-base [installed|not installed] Minimal Debian 12 environment for shell and core Unix tooling.
 debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.
@@ -142,6 +142,8 @@ for the published package, or `uv run pyro ...` from a source checkout.
 uv tool install pyro-mcp
 WORKSPACE_ID="$(pyro workspace create debian:12 --seed-path ./repo --json | python -c 'import json,sys; print(json.load(sys.stdin)["workspace_id"])')"
 pyro workspace sync push "$WORKSPACE_ID" ./changes
+pyro workspace file read "$WORKSPACE_ID" note.txt
+pyro workspace patch apply "$WORKSPACE_ID" --patch "$(cat fix.patch)"
 pyro workspace exec "$WORKSPACE_ID" -- cat note.txt
 pyro workspace snapshot create "$WORKSPACE_ID" checkpoint
 pyro workspace service start "$WORKSPACE_ID" web --ready-file .web-ready -- sh -lc 'touch .web-ready && while true; do sleep 60; done'
@@ -154,6 +156,7 @@ This is the stable persistent-workspace contract:
 
 - `workspace create` seeds `/workspace`
 - `workspace sync push` imports later host-side changes
+- `workspace file *` and `workspace patch apply` cover model-native text inspection and edits
 - `workspace exec` and `workspace shell *` keep work inside one sandbox
 - `workspace service *` manages long-running processes with typed readiness
 - `workspace snapshot *` and `workspace reset` make reset-over-repair explicit
@@ -208,6 +211,7 @@ After the CLI path works, you can move on to:
 - live workspace updates: `pyro workspace sync push WORKSPACE_ID ./changes`
 - guest networking policy: `pyro workspace create debian:12 --network-policy egress`
 - workspace secrets: `pyro workspace create debian:12 --secret API_TOKEN=expected --secret-file PIP_TOKEN=./token.txt`
+- model-native file editing: `pyro workspace file read WORKSPACE_ID src/app.py`, `pyro workspace file write WORKSPACE_ID src/app.py --text 'print("hi")'`, and `pyro workspace patch apply WORKSPACE_ID --patch "$(cat fix.patch)"`
 - baseline diff: `pyro workspace diff WORKSPACE_ID`
 - snapshots and reset: `pyro workspace snapshot create WORKSPACE_ID checkpoint` and `pyro workspace reset WORKSPACE_ID --snapshot checkpoint`
 - host export: `pyro workspace export WORKSPACE_ID note.txt --output ./note.txt`
@@ -229,6 +233,10 @@ pyro workspace create debian:12 --network-policy egress
 pyro workspace create debian:12 --seed-path ./repo --secret API_TOKEN=expected
 pyro workspace create debian:12 --network-policy egress+published-ports
 pyro workspace sync push WORKSPACE_ID ./changes --dest src
+pyro workspace file list WORKSPACE_ID src --recursive
+pyro workspace file read WORKSPACE_ID src/note.txt
+pyro workspace file write WORKSPACE_ID src/app.py --text 'print("hi")'
+pyro workspace patch apply WORKSPACE_ID --patch "$(cat fix.patch)"
 pyro workspace exec WORKSPACE_ID -- cat src/note.txt
 pyro workspace exec WORKSPACE_ID --secret-env API_TOKEN -- sh -lc 'test "$API_TOKEN" = "expected"'
 pyro workspace diff WORKSPACE_ID
@@ -261,7 +269,7 @@ Workspace commands default to the persistent `/workspace` directory inside the g
 the identifier programmatically, use `--json` and read the `workspace_id` field. Use `--seed-path`
 when the workspace should start from a host directory or a local `.tar` / `.tar.gz` / `.tgz`
 archive. Use `pyro workspace sync push` for later host-side changes to a started workspace. Sync
-is non-atomic in `3.1.0`; if it fails partway through, prefer `pyro workspace reset` to recover
+is non-atomic in `3.2.0`; if it fails partway through, prefer `pyro workspace reset` to recover
 from `baseline` or one named snapshot. Use `pyro workspace diff` to compare the current workspace
 tree to its immutable create-time baseline, `pyro workspace snapshot *` to capture named
 checkpoints, and `pyro workspace export` to copy one changed file or directory back to the host. Use

docs/integrations.md

@@ -32,6 +32,7 @@ Recommended surface:
 
 - `vm_run`
 - `workspace_create(seed_path=...)` + `workspace_sync_push` + `workspace_exec` when the agent needs persistent workspace state
+- `workspace_file_list` / `workspace_file_read` / `workspace_file_write` / `workspace_patch_apply` when the agent needs model-native file inspection and text edits inside one live workspace
 - `workspace_create(..., secrets=...)` + `workspace_exec(..., secret_env=...)` when the workspace needs private tokens or authenticated setup
 - `workspace_create(..., network_policy="egress+published-ports")` + `start_service(..., published_ports=[...])` when the host must probe one workspace service
 - `workspace_diff` + `workspace_export` when the agent needs explicit baseline comparison or host-out file transfer
@@ -73,6 +74,7 @@ Recommended default:
 
 - `Pyro.run_in_vm(...)`
 - `Pyro.create_workspace(seed_path=...)` + `Pyro.push_workspace_sync(...)` + `Pyro.exec_workspace(...)` when repeated workspace commands are required
+- `Pyro.list_workspace_files(...)` / `Pyro.read_workspace_file(...)` / `Pyro.write_workspace_file(...)` / `Pyro.apply_workspace_patch(...)` when the agent needs model-native file inspection and text edits inside one live workspace
 - `Pyro.create_workspace(..., secrets=...)` + `Pyro.exec_workspace(..., secret_env=...)` when the workspace needs private tokens or authenticated setup
 - `Pyro.create_workspace(..., network_policy="egress+published-ports")` + `Pyro.start_service(..., published_ports=[...])` when the host must probe one workspace service
 - `Pyro.diff_workspace(...)` + `Pyro.export_workspace(...)` when the agent needs baseline comparison or host-out file transfer
@@ -88,6 +90,9 @@ Lifecycle note:
   `/workspace` that starts from host content
 - use `push_workspace_sync(...)` when later host-side changes need to be imported into that
   running workspace without recreating it
+- use `list_workspace_files(...)`, `read_workspace_file(...)`, `write_workspace_file(...)`, and
+  `apply_workspace_patch(...)` when the agent should inspect or edit workspace files without shell
+  quoting tricks
 - use `create_workspace(..., secrets=...)` plus `secret_env` on exec, shell, or service start when
   the agent needs private tokens or authenticated startup inside that workspace
 - use `create_workspace(..., network_policy="egress+published-ports")` plus

docs/public-contract.md

@@ -29,7 +29,11 @@ Top-level commands:
 - `pyro workspace stop`
 - `pyro workspace start`
 - `pyro workspace exec`
+- `pyro workspace file list`
+- `pyro workspace file read`
+- `pyro workspace file write`
 - `pyro workspace export`
+- `pyro workspace patch apply`
 - `pyro workspace disk export`
 - `pyro workspace disk list`
 - `pyro workspace disk read`
@@ -79,6 +83,9 @@ Behavioral guarantees:
 - `pyro workspace sync push WORKSPACE_ID SOURCE_PATH [--dest WORKSPACE_PATH]` imports later host-side directory or archive content into a started workspace.
 - `pyro workspace stop WORKSPACE_ID` stops one persistent workspace without deleting its `/workspace`, snapshots, or command history.
 - `pyro workspace start WORKSPACE_ID` restarts one stopped workspace without resetting `/workspace`.
+- `pyro workspace file list WORKSPACE_ID [PATH] [--recursive]` returns metadata for one live path under `/workspace`.
+- `pyro workspace file read WORKSPACE_ID PATH [--max-bytes N]` reads one regular text file under `/workspace`.
+- `pyro workspace file write WORKSPACE_ID PATH --text TEXT` creates or replaces one regular text file under `/workspace`, creating missing parent directories automatically.
 - `pyro workspace export WORKSPACE_ID PATH --output HOST_PATH` exports one file or directory from `/workspace` back to the host.
 - `pyro workspace disk export WORKSPACE_ID --output HOST_PATH` copies the stopped guest-backed workspace rootfs as raw ext4 to the host.
 - `pyro workspace disk list WORKSPACE_ID [PATH] [--recursive]` inspects a stopped guest-backed workspace rootfs offline without booting the guest.
@@ -92,6 +99,7 @@ Behavioral guarantees:
 - `pyro workspace exec --secret-env SECRET_NAME[=ENV_VAR]` maps one persisted secret into one exec call.
 - `pyro workspace service start --secret-env SECRET_NAME[=ENV_VAR]` maps one persisted secret into one service start call.
 - `pyro workspace exec` runs in the persistent `/workspace` for that workspace and does not auto-clean.
+- `pyro workspace patch apply WORKSPACE_ID --patch TEXT` applies one unified text patch with add/modify/delete operations under `/workspace`.
 - `pyro workspace shell open --secret-env SECRET_NAME[=ENV_VAR]` maps one persisted secret into the opened shell environment.
 - `pyro workspace shell *` manages persistent PTY sessions inside a started workspace.
 - `pyro workspace logs` returns persisted command history for that workspace until `pyro workspace delete`.
@@ -121,7 +129,11 @@ Supported public entrypoints:
 - `Pyro.push_workspace_sync(workspace_id, source_path, *, dest="/workspace")`
 - `Pyro.stop_workspace(workspace_id)`
 - `Pyro.start_workspace(workspace_id)`
+- `Pyro.list_workspace_files(workspace_id, path="/workspace", recursive=False)`
+- `Pyro.read_workspace_file(workspace_id, path, *, max_bytes=65536)`
+- `Pyro.write_workspace_file(workspace_id, path, *, text)`
 - `Pyro.export_workspace(workspace_id, path, *, output_path)`
+- `Pyro.apply_workspace_patch(workspace_id, *, patch)`
 - `Pyro.export_workspace_disk(workspace_id, *, output_path)`
 - `Pyro.list_workspace_disk(workspace_id, path="/workspace", recursive=False)`
 - `Pyro.read_workspace_disk(workspace_id, path, *, max_bytes=65536)`
@@ -165,7 +177,11 @@ Stable public method names:
 - `push_workspace_sync(workspace_id, source_path, *, dest="/workspace")`
 - `stop_workspace(workspace_id)`
 - `start_workspace(workspace_id)`
+- `list_workspace_files(workspace_id, path="/workspace", recursive=False)`
+- `read_workspace_file(workspace_id, path, *, max_bytes=65536)`
+- `write_workspace_file(workspace_id, path, *, text)`
 - `export_workspace(workspace_id, path, *, output_path)`
+- `apply_workspace_patch(workspace_id, *, patch)`
 - `export_workspace_disk(workspace_id, *, output_path)`
 - `list_workspace_disk(workspace_id, path="/workspace", recursive=False)`
 - `read_workspace_disk(workspace_id, path, *, max_bytes=65536)`
@@ -209,7 +225,9 @@ Behavioral defaults:
 - `Pyro.push_workspace_sync(...)` imports later host-side directory or archive content into a started workspace.
 - `Pyro.stop_workspace(...)` stops one persistent workspace without deleting its `/workspace`, snapshots, or command history.
 - `Pyro.start_workspace(...)` restarts one stopped workspace without resetting `/workspace`.
+- `Pyro.list_workspace_files(...)`, `Pyro.read_workspace_file(...)`, and `Pyro.write_workspace_file(...)` provide structured live `/workspace` inspection and text edits without shell quoting.
 - `Pyro.export_workspace(...)` exports one file or directory from `/workspace` to an explicit host path.
+- `Pyro.apply_workspace_patch(...)` applies unified text patches for add/modify/delete operations under `/workspace`.
 - `Pyro.export_workspace_disk(...)` copies the stopped guest-backed workspace rootfs as raw ext4 to an explicit host path.
 - `Pyro.list_workspace_disk(...)` inspects a stopped guest-backed workspace rootfs offline without booting the guest.
 - `Pyro.read_workspace_disk(...)` reads one regular file from a stopped guest-backed workspace rootfs offline.
@@ -256,7 +274,11 @@ Persistent workspace tools:
 - `workspace_stop`
 - `workspace_start`
 - `workspace_exec`
+- `workspace_file_list`
+- `workspace_file_read`
+- `workspace_file_write`
 - `workspace_export`
+- `workspace_patch_apply`
 - `workspace_disk_export`
 - `workspace_disk_list`
 - `workspace_disk_read`
@@ -291,7 +313,9 @@ Behavioral defaults:
 - `workspace_sync_push` imports later host-side directory or archive content into a started workspace, with an optional `dest` under `/workspace`.
 - `workspace_stop` stops one persistent workspace without deleting its `/workspace`, snapshots, or command history.
 - `workspace_start` restarts one stopped workspace without resetting `/workspace`.
+- `workspace_file_list`, `workspace_file_read`, and `workspace_file_write` provide structured live `/workspace` inspection and text edits without shell quoting.
 - `workspace_export` exports one file or directory from `/workspace` to an explicit host path.
+- `workspace_patch_apply` applies unified text patches for add/modify/delete operations under `/workspace`.
 - `workspace_disk_export` copies the stopped guest-backed workspace rootfs as raw ext4 to an explicit host path.
 - `workspace_disk_list` inspects a stopped guest-backed workspace rootfs offline without booting the guest.
 - `workspace_disk_read` reads one regular file from a stopped guest-backed workspace rootfs offline.

docs/roadmap/llm-chat-ergonomics.md

@@ -6,7 +6,7 @@ goal:
 make the core agent-workspace use cases feel trivial from a chat-driven LLM
 interface.
 
-Current baseline is `3.1.0`:
+Current baseline is `3.2.0`:
 
 - the stable workspace contract exists across CLI, SDK, and MCP
 - one-shot `pyro run` still exists as the narrow entrypoint
@@ -45,12 +45,17 @@ More concretely, the model should not need to:
 
 ## Milestones
 
-1. [`3.2.0` Model-Native Workspace File Ops](llm-chat-ergonomics/3.2.0-model-native-workspace-file-ops.md)
+1. [`3.2.0` Model-Native Workspace File Ops](llm-chat-ergonomics/3.2.0-model-native-workspace-file-ops.md) - Done
 2. [`3.3.0` Workspace Naming And Discovery](llm-chat-ergonomics/3.3.0-workspace-naming-and-discovery.md)
 3. [`3.4.0` Tool Profiles And Canonical Chat Flows](llm-chat-ergonomics/3.4.0-tool-profiles-and-canonical-chat-flows.md)
 4. [`3.5.0` Chat-Friendly Shell Output](llm-chat-ergonomics/3.5.0-chat-friendly-shell-output.md)
 5. [`3.6.0` Use-Case Recipes And Smoke Packs](llm-chat-ergonomics/3.6.0-use-case-recipes-and-smoke-packs.md)
 
+Completed so far:
+
+- `3.2.0` added model-native `workspace file *` and `workspace patch apply` so chat-driven agents
+  can inspect and edit `/workspace` without shell-escaped file mutation flows.
+
 ## Expected Outcome
 
 After this roadmap, the product should still look like an agent workspace, not

docs/roadmap/llm-chat-ergonomics/3.2.0-model-native-workspace-file-ops.md

@@ -1,6 +1,6 @@
 # `3.2.0` Model-Native Workspace File Ops
 
-Status: Planned
+Status: Done
 
 ## Goal
 
@@ -57,3 +57,9 @@ Planned additions:
 - docs and examples that show model-native file editing instead of shell-heavy
   file writes
 - at least one real smoke scenario centered on a repro-plus-fix loop
+
+## Outcome
+
+- shipped `workspace file list|read|write` and `workspace patch apply` across CLI, SDK, and MCP
+- kept the surface scoped to started workspaces and `/workspace`
+- updated docs, help text, examples, and smoke coverage around model-native editing flows