Thales Maciel
dc86d84e96
Add workspace summary across the CLI, SDK, and MCP, and include it in the workspace-core profile so chat hosts can review one concise view of the current session. Persist lightweight review events for syncs, file edits, patch applies, exports, service lifecycle, and snapshot activity, then synthesize them with command history, current services, snapshot state, and current diff data since the last reset. Update the walkthroughs, use-case docs, public contract, changelog, and roadmap for 4.3.0, and make dist-check invoke the CLI module directly so local package reinstall quirks do not break the packaging gate. Validation: uv lock; ./.venv/bin/pytest --no-cov tests/test_vm_manager.py tests/test_cli.py tests/test_api.py tests/test_server.py tests/test_public_contract.py tests/test_workspace_use_case_smokes.py; UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make check; UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make dist-check; real guest-backed workspace create -> patch apply -> workspace summary --json -> delete smoke.
170 lines
5.2 KiB
Markdown
170 lines
5.2 KiB
Markdown
# Public Contract
|
|
|
|
This document describes the chat way to use `pyro-mcp` in `4.x`.
|
|
|
|
`pyro-mcp` currently has no users. Expect breaking changes while this chat-host
|
|
path is still being shaped.
|
|
|
|
This document is intentionally biased. It describes the path users are meant to
|
|
follow today:
|
|
|
|
- prove the host with the terminal companion commands
|
|
- serve disposable workspaces over MCP
|
|
- connect Claude Code, Codex, or OpenCode
|
|
- use the recipe-backed workflows
|
|
|
|
This page does not try to document every building block in the repo. It
|
|
documents the chat-host path the project is actively shaping.
|
|
|
|
## Package Identity
|
|
|
|
- distribution name: `pyro-mcp`
|
|
- public executable: `pyro`
|
|
- primary product entrypoint: `pyro mcp serve`
|
|
|
|
`pyro-mcp` is a disposable MCP workspace for chat-based coding agents on Linux
|
|
`x86_64` KVM hosts.
|
|
|
|
## Supported Product Path
|
|
|
|
The intended user journey is:
|
|
|
|
1. `pyro doctor`
|
|
2. `pyro env list`
|
|
3. `pyro env pull debian:12`
|
|
4. `pyro run debian:12 -- git --version`
|
|
5. `pyro mcp serve`
|
|
6. connect Claude Code, Codex, or OpenCode
|
|
7. run one of the documented recipe-backed workflows
|
|
8. validate the whole story with `make smoke-use-cases`
|
|
|
|
## Evaluator CLI
|
|
|
|
These terminal commands are the documented companion path for the chat-host
|
|
product:
|
|
|
|
- `pyro doctor`
|
|
- `pyro env list`
|
|
- `pyro env pull`
|
|
- `pyro run`
|
|
- `pyro demo`
|
|
|
|
What to expect from that path:
|
|
|
|
- `pyro run <environment> -- <command>` defaults to `1 vCPU / 1024 MiB`
|
|
- `pyro run` fails if guest boot or guest exec is unavailable unless
|
|
`--allow-host-compat` is set
|
|
- `pyro run`, `pyro env list`, `pyro env pull`, `pyro env inspect`,
|
|
`pyro env prune`, and `pyro doctor` are human-readable by default and return
|
|
structured JSON with `--json`
|
|
- the first official environment pull downloads from public Docker Hub into the
|
|
local environment cache
|
|
- `pyro demo` proves the one-shot create/start/exec/delete VM lifecycle end to
|
|
end
|
|
|
|
These commands exist to validate and debug the chat-host path. They are not the
|
|
main product destination.
|
|
|
|
## MCP Entry Point
|
|
|
|
The product entrypoint is:
|
|
|
|
```bash
|
|
pyro mcp serve
|
|
```
|
|
|
|
What to expect:
|
|
|
|
- bare `pyro mcp serve` starts `workspace-core`
|
|
- from a repo root, bare `pyro mcp serve` also auto-detects the current Git
|
|
checkout so `workspace_create` can omit `seed_path`
|
|
- `workspace-core` is the default product path for chat hosts
|
|
- `pyro mcp serve --profile workspace-full` explicitly opts into the larger
|
|
tool surface
|
|
- `pyro mcp serve --profile vm-run` exposes the smallest one-shot-only surface
|
|
- `pyro mcp serve --project-path /abs/path/to/repo` is the fallback when the
|
|
host does not preserve cwd
|
|
- `pyro mcp serve --repo-url ... [--repo-ref ...]` starts from a clean clone
|
|
source instead of a local checkout
|
|
|
|
Host-specific setup docs:
|
|
|
|
- [claude_code_mcp.md](../examples/claude_code_mcp.md)
|
|
- [codex_mcp.md](../examples/codex_mcp.md)
|
|
- [opencode_mcp_config.json](../examples/opencode_mcp_config.json)
|
|
- [mcp_client_config.md](../examples/mcp_client_config.md)
|
|
|
|
The chat-host bootstrap helper surface is:
|
|
|
|
- `pyro host connect claude-code`
|
|
- `pyro host connect codex`
|
|
- `pyro host print-config opencode`
|
|
- `pyro host doctor`
|
|
- `pyro host repair HOST`
|
|
|
|
These helpers wrap the same `pyro mcp serve` entrypoint and are the preferred
|
|
setup and repair path for supported hosts.
|
|
|
|
## Chat-Facing Workspace Contract
|
|
|
|
`workspace-core` is the normal chat path. It exposes:
|
|
|
|
- `vm_run`
|
|
- `workspace_create`
|
|
- `workspace_list`
|
|
- `workspace_update`
|
|
- `workspace_status`
|
|
- `workspace_sync_push`
|
|
- `workspace_exec`
|
|
- `workspace_logs`
|
|
- `workspace_summary`
|
|
- `workspace_file_list`
|
|
- `workspace_file_read`
|
|
- `workspace_file_write`
|
|
- `workspace_patch_apply`
|
|
- `workspace_diff`
|
|
- `workspace_export`
|
|
- `workspace_reset`
|
|
- `workspace_delete`
|
|
|
|
That is enough for the normal persistent editing loop:
|
|
|
|
- create one workspace, often without `seed_path` when the server already has a
|
|
project source
|
|
- sync or seed repo content
|
|
- inspect and edit files without shell quoting
|
|
- run commands repeatedly in one sandbox
|
|
- review the current session in one concise summary
|
|
- diff and export results
|
|
- reset and retry
|
|
- delete the workspace when the task is done
|
|
|
|
Move to `workspace-full` only when the chat truly needs:
|
|
|
|
- persistent PTY shell sessions
|
|
- long-running services and readiness probes
|
|
- secrets
|
|
- guest networking and published ports
|
|
- stopped-workspace disk inspection
|
|
|
|
## Recipe-Backed Workflows
|
|
|
|
The documented product workflows are:
|
|
|
|
| Workflow | Recommended profile | Doc |
|
|
| --- | --- | --- |
|
|
| Cold-start repo validation | `workspace-full` | [use-cases/cold-start-repo-validation.md](use-cases/cold-start-repo-validation.md) |
|
|
| Repro plus fix loop | `workspace-core` | [use-cases/repro-fix-loop.md](use-cases/repro-fix-loop.md) |
|
|
| Parallel isolated workspaces | `workspace-core` | [use-cases/parallel-workspaces.md](use-cases/parallel-workspaces.md) |
|
|
| Unsafe or untrusted code inspection | `workspace-core` | [use-cases/untrusted-inspection.md](use-cases/untrusted-inspection.md) |
|
|
| Review and evaluation workflows | `workspace-full` | [use-cases/review-eval-workflows.md](use-cases/review-eval-workflows.md) |
|
|
|
|
Treat this smoke pack as the trustworthy guest-backed verification path for the
|
|
advertised product:
|
|
|
|
```bash
|
|
make smoke-use-cases
|
|
```
|
|
|
|
The chat-host MCP path above is the thing the docs are intentionally shaping
|
|
around.
|