thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions

Add daily-loop prepare and readiness checks

Browse source 
Make the local chat-host loop explicit and cheap so users can warm the machine once instead of rediscovering environment and guest setup on every session.

Add cache-backed daily-loop manifests plus the new `pyro prepare` flow, extend `pyro doctor --environment` with warm/cold/stale readiness reporting, and add `make smoke-daily-loop` to prove the warmed repro-fix reset path end to end.

Also fix `python -m pyro_mcp.cli` to invoke `main()` so the new smoke and `dist-check` actually exercise the CLI module, and update the docs/roadmap to present `doctor -> prepare -> connect host -> reset` as the recommended daily path.

Validation: `uv lock`, `UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make check`, `UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make dist-check`, and `UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make smoke-daily-loop`.
This commit is contained in:
Thales Maciel 2026-03-13 21:17:59 -03:00
parent d0cf6d8f21
commit 663241d5d2
26 changed files with 1592 additions and 199 deletions
Download patch file Download diff file Expand all files Collapse all files

21
docs/first-run.md
View file

@ -14,13 +14,16 @@ path is still being shaped.
## 1. Verify the host
```bash
$ uvx --from pyro-mcp pyro doctor
$ uvx --from pyro-mcp pyro doctor --environment debian:12
Platform: linux-x86_64
Runtime: PASS
KVM: exists=yes readable=yes writable=yes
Environment cache: /home/you/.cache/pyro-mcp/environments
Catalog version: 4.5.0
Capabilities: vm_boot=yes guest_exec=yes guest_network=yes
Networking: tun=yes ip_forward=yes
Daily loop: COLD (debian:12)
Run: pyro prepare debian:12
```
## 2. Inspect the catalog
@ -71,6 +74,16 @@ streams, so they may appear in either order in terminals or capture tools. Use
## 5. Start the MCP server
Warm the daily loop first so the host is already ready for repeated create and
reset cycles:
```bash
$ uvx --from pyro-mcp pyro prepare debian:12
Prepare: debian:12
Daily loop: WARM
Result: prepared network_prepared=no
```
Use a named mode when one workflow already matches the job:
```bash
@ -191,6 +204,12 @@ That runner creates real guest-backed workspaces, exercises all five documented
stories, exports concrete results where relevant, and cleans up on both success
and failure.
For the machine-level warmup plus retry story specifically:
```bash
$ make smoke-daily-loop
```
## 9. Optional one-shot demo
```bash

47
docs/install.md
View file

@ -46,29 +46,27 @@ Use either of these equivalent evaluator paths:
```bash
# Package without install
uvx --from pyro-mcp pyro doctor
uvx --from pyro-mcp pyro env list
uvx --from pyro-mcp pyro env pull debian:12
uvx --from pyro-mcp pyro prepare debian:12
uvx --from pyro-mcp pyro run debian:12 -- git --version
```
```bash
# Already installed
pyro doctor
pyro env list
pyro env pull debian:12
pyro prepare debian:12
pyro run debian:12 -- git --version
```
If you are running from a repo checkout instead, replace `pyro` with
`uv run pyro`.
After that one-shot proof works, the intended next step is a named chat mode
through `pyro host connect` or `pyro host print-config`.
After that one-shot proof works, the intended next step is a warmed daily loop
plus a named chat mode through `pyro host connect` or `pyro host print-config`.
## 1. Check the host
```bash
uvx --from pyro-mcp pyro doctor
uvx --from pyro-mcp pyro doctor --environment debian:12
```
Expected success signals:
@ -78,8 +76,11 @@ Platform: linux-x86_64
Runtime: PASS
KVM: exists=yes readable=yes writable=yes
Environment cache: /home/you/.cache/pyro-mcp/environments
Catalog version: 4.5.0
Capabilities: vm_boot=yes guest_exec=yes guest_network=yes
Networking: tun=yes ip_forward=yes
Daily loop: COLD (debian:12)
Run: pyro prepare debian:12
```
If `Runtime: FAIL`, stop here and use [troubleshooting.md](troubleshooting.md).
@ -139,7 +140,17 @@ The guest command output and the `[run] ...` summary are written to different
streams, so they may appear in either order. Use `--json` if you need a
deterministic structured result.
## 5. Connect a chat host
## 5. Warm the daily loop
```bash
uvx --from pyro-mcp pyro prepare debian:12
```
That one command ensures the environment is installed, proves one guest-backed
create/exec/reset/delete loop, and records a warm manifest so the next
`pyro prepare debian:12` call can reuse it instead of repeating the full cycle.
## 6. Connect a chat host
Use the helper flow first:
@ -221,23 +232,24 @@ Use the generic no-mode path when the named mode is too narrow. Move to
`--profile workspace-full` only when the chat truly needs shells, services,
snapshots, secrets, network policy, or disk tools.
## 6. Go from zero to hero
## 7. Go from zero to hero
The intended user journey is:
1. validate the host with `pyro doctor`
2. pull `debian:12`
1. validate the host with `pyro doctor --environment debian:12`
2. warm the machine with `pyro prepare debian:12`
3. prove guest execution with `pyro run debian:12 -- git --version`
4. connect Claude Code, Codex, or OpenCode with one named mode such as
`pyro host connect codex --mode repro-fix`, then use raw
`pyro mcp serve --mode ...` or the generic no-mode path when needed
5. start with one use-case recipe from [use-cases/README.md](use-cases/README.md)
6. trust but verify with `make smoke-use-cases`
5. use `workspace reset` as the normal retry step inside that warmed loop
6. start with one use-case recipe from [use-cases/README.md](use-cases/README.md)
7. trust but verify with `make smoke-use-cases`
If you want the shortest chat-first story, start with
[use-cases/repro-fix-loop.md](use-cases/repro-fix-loop.md).
## 7. Manual terminal workspace flow
## 8. Manual terminal workspace flow
If you want to inspect the workspace model directly from the terminal, use the
companion flow below. This is for understanding and debugging the chat-host
@ -269,7 +281,7 @@ When you need deeper debugging or richer recipes, add:
private tokens
- `pyro workspace stop` plus `workspace disk *` for offline inspection
## 8. Trustworthy verification path
## 9. Trustworthy verification path
The five recipe docs in [use-cases/README.md](use-cases/README.md) are backed
by a real Firecracker smoke pack:
@ -288,9 +300,8 @@ If you already installed the package, the same path works with plain `pyro ...`:
```bash
uv tool install pyro-mcp
pyro --version
pyro doctor
pyro env list
pyro env pull debian:12
pyro doctor --environment debian:12
pyro prepare debian:12
pyro run debian:12 -- git --version
pyro mcp serve
```

14
docs/integrations.md
View file

@ -3,6 +3,7 @@
This page documents the intended product path for `pyro-mcp`:
- validate the host with the CLI
- warm the daily loop with `pyro prepare debian:12`
- run `pyro mcp serve`
- connect a chat host
- let the agent work inside disposable workspaces
@ -13,6 +14,13 @@ path is still being shaped.
Use this page after you have already validated the host and guest execution
through [install.md](install.md) or [first-run.md](first-run.md).
Recommended first commands before connecting a host:
```bash
pyro doctor --environment debian:12
pyro prepare debian:12
```
## Recommended Modes
Use a named mode when one workflow already matches the job:
@ -241,3 +249,9 @@ Validate the whole story with:
```bash
make smoke-use-cases
```
For the machine-warmup plus reset/retry path specifically:
```bash
make smoke-daily-loop
```

17
docs/public-contract.md
View file

@ -30,11 +30,11 @@ documents the chat-host path the project is actively shaping.
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
2. `pyro prepare debian:12`
3. `pyro run debian:12 -- git --version`
4. `pyro mcp serve`
5. connect Claude Code, Codex, or OpenCode
6. use `workspace reset` as the normal retry step
7. run one of the documented recipe-backed workflows
8. validate the whole story with `make smoke-use-cases`
@ -44,6 +44,7 @@ These terminal commands are the documented companion path for the chat-host
product:
- `pyro doctor`
- `pyro prepare`
- `pyro env list`
- `pyro env pull`
- `pyro run`
@ -55,10 +56,12 @@ What to expect from that path:
- `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`
`pyro env prune`, `pyro doctor`, and `pyro prepare` 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 prepare debian:12` proves the warmed daily loop with one throwaway
workspace create, exec, reset, and delete cycle
- `pyro demo` proves the one-shot create/start/exec/delete VM lifecycle end to
end

11
docs/roadmap/llm-chat-ergonomics.md
View file

@ -6,7 +6,7 @@ goal:
make the core agent-workspace use cases feel trivial from a chat-driven LLM
interface.
Current baseline is `4.4.0`:
Current baseline is `4.5.0`:
- `pyro mcp serve` is now the default product entrypoint
- `workspace-core` is now the default MCP profile
@ -83,7 +83,7 @@ capability gaps:
13. [`4.2.0` Host Bootstrap And Repair](llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md) - Done
14. [`4.3.0` Reviewable Agent Output](llm-chat-ergonomics/4.3.0-reviewable-agent-output.md) - Done
15. [`4.4.0` Opinionated Use-Case Modes](llm-chat-ergonomics/4.4.0-opinionated-use-case-modes.md) - Done
16. [`4.5.0` Faster Daily Loops](llm-chat-ergonomics/4.5.0-faster-daily-loops.md) - Planned
16. [`4.5.0` Faster Daily Loops](llm-chat-ergonomics/4.5.0-faster-daily-loops.md) - Done
Completed so far:
@ -126,10 +126,9 @@ Completed so far:
- `4.4.0` adds named use-case modes so chat hosts can start from `repro-fix`,
`inspect`, `cold-start`, or `review-eval` instead of choosing from the full
generic workspace surface first.
Planned next:
- [`4.5.0` Faster Daily Loops](llm-chat-ergonomics/4.5.0-faster-daily-loops.md)
- `4.5.0` adds `pyro prepare`, daily-loop readiness in `pyro doctor`, and a
real `make smoke-daily-loop` verification path so the local machine warmup
story is explicit before the chat host connects.
## Expected Outcome

20
docs/roadmap/llm-chat-ergonomics/4.5.0-faster-daily-loops.md
View file

@ -1,6 +1,6 @@
# `4.5.0` Faster Daily Loops
Status: Planned
Status: Done
## Goal
@ -9,11 +9,11 @@ for normal work, not only for special high-isolation tasks.
## Public API Changes
The product should add an explicit fast-path for repeated local use, such as:
The product now adds an explicit fast-path for repeated local use:
- a prewarm or prepare path for the recommended environment and runtime
- a clearer fast reset or retry path for repeated repro-fix loops
- visible diagnostics for cache, prewarm, or ready-state health
- `pyro prepare [ENVIRONMENT] [--network] [--force] [--json]`
- `pyro doctor --environment ENVIRONMENT` daily-loop readiness output
- `make smoke-daily-loop` to prove the warmed machine plus reset/retry story
The exact command names can still move, but the user-visible story needs to be:
@ -50,8 +50,8 @@ The exact command names can still move, but the user-visible story needs to be:
## Required Repo Updates
- docs updated to show the recommended daily-use fast path
- diagnostics and help text updated so the user can tell whether the machine is
already warm and ready
- at least one repeat-loop smoke or benchmark-style verification scenario
added to prevent regressions in the daily workflow
- docs now show the recommended daily-use fast path
- diagnostics and help text now show whether the machine is already warm and
ready
- the repo now includes `make smoke-daily-loop` as a repeat-loop verification
scenario for the daily workflow