Thales Maciel
9e11dcf9ab
Tasks could start from host content in 2.2.0, but there was still no post-create path to update a live workspace from the host. This change adds the next host-to-task step so repeated fix or review loops do not require recreating the task for every local change. Add task sync push across the CLI, Python SDK, and MCP server, reusing the existing safe archive import path from seeded task creation instead of introducing a second transfer stack. The implementation keeps sync separate from workspace_seed metadata, validates destinations under /workspace, and documents the current non-atomic recovery path as delete-and-recreate. Validation: - uv lock - UV_CACHE_DIR=.uv-cache uv run pytest --no-cov tests/test_cli.py tests/test_vm_manager.py tests/test_api.py tests/test_server.py tests/test_public_contract.py - UV_CACHE_DIR=.uv-cache make check - UV_CACHE_DIR=.uv-cache make dist-check - real guest-backed smoke: task create --source-path, task sync push, task exec to verify both files, task delete
169 lines
5.3 KiB
Markdown
169 lines
5.3 KiB
Markdown
# Public Contract
|
|
|
|
This document defines the supported public interface for `pyro-mcp` `2.x`.
|
|
|
|
## Package Identity
|
|
|
|
- Distribution name: `pyro-mcp`
|
|
- Public executable: `pyro`
|
|
- Public Python import: `from pyro_mcp import Pyro`
|
|
- Public package-level factory: `from pyro_mcp import create_server`
|
|
|
|
## CLI Contract
|
|
|
|
Top-level commands:
|
|
|
|
- `pyro env list`
|
|
- `pyro env pull`
|
|
- `pyro env inspect`
|
|
- `pyro env prune`
|
|
- `pyro mcp serve`
|
|
- `pyro run`
|
|
- `pyro task create`
|
|
- `pyro task sync push`
|
|
- `pyro task exec`
|
|
- `pyro task status`
|
|
- `pyro task logs`
|
|
- `pyro task delete`
|
|
- `pyro doctor`
|
|
- `pyro demo`
|
|
- `pyro demo ollama`
|
|
|
|
Stable `pyro run` interface:
|
|
|
|
- positional environment name
|
|
- `--vcpu-count`
|
|
- `--mem-mib`
|
|
- `--timeout-seconds`
|
|
- `--ttl-seconds`
|
|
- `--network`
|
|
- `--allow-host-compat`
|
|
- `--json`
|
|
|
|
Behavioral guarantees:
|
|
|
|
- `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`.
|
|
- `pyro demo ollama` prints log lines plus a final summary line.
|
|
- `pyro task create` auto-starts a persistent workspace.
|
|
- `pyro task create --source-path PATH` seeds `/workspace` from a host directory or a local
|
|
`.tar` / `.tar.gz` / `.tgz` archive before the task is returned.
|
|
- `pyro task sync push TASK_ID SOURCE_PATH [--dest WORKSPACE_PATH]` imports later host-side
|
|
directory or archive content into a started task workspace.
|
|
- `pyro task exec` runs in the persistent `/workspace` for that task and does not auto-clean.
|
|
- `pyro task logs` returns persisted command history for that task until `pyro task delete`.
|
|
- Task create/status results expose `workspace_seed` metadata describing how `/workspace` was
|
|
initialized.
|
|
|
|
## Python SDK Contract
|
|
|
|
Primary facade:
|
|
|
|
- `Pyro`
|
|
|
|
Supported public entrypoints:
|
|
|
|
- `create_server()`
|
|
- `Pyro.create_server()`
|
|
- `Pyro.list_environments()`
|
|
- `Pyro.pull_environment(environment)`
|
|
- `Pyro.inspect_environment(environment)`
|
|
- `Pyro.prune_environments()`
|
|
- `Pyro.create_vm(...)`
|
|
- `Pyro.create_task(...)`
|
|
- `Pyro.push_task_sync(task_id, source_path, *, dest="/workspace")`
|
|
- `Pyro.start_vm(vm_id)`
|
|
- `Pyro.exec_vm(vm_id, *, command, timeout_seconds=30)`
|
|
- `Pyro.exec_task(task_id, *, command, timeout_seconds=30)`
|
|
- `Pyro.stop_vm(vm_id)`
|
|
- `Pyro.delete_vm(vm_id)`
|
|
- `Pyro.delete_task(task_id)`
|
|
- `Pyro.status_vm(vm_id)`
|
|
- `Pyro.status_task(task_id)`
|
|
- `Pyro.logs_task(task_id)`
|
|
- `Pyro.network_info_vm(vm_id)`
|
|
- `Pyro.reap_expired()`
|
|
- `Pyro.run_in_vm(...)`
|
|
|
|
Stable public method names:
|
|
|
|
- `create_server()`
|
|
- `list_environments()`
|
|
- `pull_environment(environment)`
|
|
- `inspect_environment(environment)`
|
|
- `prune_environments()`
|
|
- `create_vm(...)`
|
|
- `create_task(...)`
|
|
- `push_task_sync(task_id, source_path, *, dest="/workspace")`
|
|
- `start_vm(vm_id)`
|
|
- `exec_vm(vm_id, *, command, timeout_seconds=30)`
|
|
- `exec_task(task_id, *, command, timeout_seconds=30)`
|
|
- `stop_vm(vm_id)`
|
|
- `delete_vm(vm_id)`
|
|
- `delete_task(task_id)`
|
|
- `status_vm(vm_id)`
|
|
- `status_task(task_id)`
|
|
- `logs_task(task_id)`
|
|
- `network_info_vm(vm_id)`
|
|
- `reap_expired()`
|
|
- `run_in_vm(...)`
|
|
|
|
Behavioral defaults:
|
|
|
|
- `Pyro.create_vm(...)` and `Pyro.run_in_vm(...)` default to `vcpu_count=1` and `mem_mib=1024`.
|
|
- `Pyro.create_task(...)` defaults to `vcpu_count=1` and `mem_mib=1024`.
|
|
- `allow_host_compat` defaults to `False` on `create_vm(...)` and `run_in_vm(...)`.
|
|
- `allow_host_compat` defaults to `False` on `create_task(...)`.
|
|
- `Pyro.create_task(..., source_path=...)` seeds `/workspace` from a host directory or a local
|
|
`.tar` / `.tar.gz` / `.tgz` archive before the task is returned.
|
|
- `Pyro.push_task_sync(...)` imports later host-side directory or archive content into a started
|
|
task workspace.
|
|
- `Pyro.exec_vm(...)` runs one command and auto-cleans that VM after the exec completes.
|
|
- `Pyro.exec_task(...)` runs one command in the persistent task workspace and leaves the task alive.
|
|
|
|
## MCP Contract
|
|
|
|
Primary tool:
|
|
|
|
- `vm_run`
|
|
|
|
Advanced lifecycle tools:
|
|
|
|
- `vm_list_environments`
|
|
- `vm_create`
|
|
- `vm_start`
|
|
- `vm_exec`
|
|
- `vm_stop`
|
|
- `vm_delete`
|
|
- `vm_status`
|
|
- `vm_network_info`
|
|
- `vm_reap_expired`
|
|
|
|
Task workspace tools:
|
|
|
|
- `task_create`
|
|
- `task_sync_push`
|
|
- `task_exec`
|
|
- `task_status`
|
|
- `task_logs`
|
|
- `task_delete`
|
|
|
|
Behavioral defaults:
|
|
|
|
- `vm_run` and `vm_create` default to `vcpu_count=1` and `mem_mib=1024`.
|
|
- `task_create` defaults to `vcpu_count=1` and `mem_mib=1024`.
|
|
- `vm_run` and `vm_create` expose `allow_host_compat`, which defaults to `false`.
|
|
- `task_create` exposes `allow_host_compat`, which defaults to `false`.
|
|
- `task_create` accepts optional `source_path` and seeds `/workspace` from a host directory or a
|
|
local `.tar` / `.tar.gz` / `.tgz` archive before the task is returned.
|
|
- `task_sync_push` imports later host-side directory or archive content into a started task
|
|
workspace, with an optional `dest` under `/workspace`.
|
|
- `vm_exec` runs one command and auto-cleans that VM after the exec completes.
|
|
- `task_exec` runs one command in a persistent `/workspace` and leaves the task alive.
|
|
|
|
## Versioning Rule
|
|
|
|
- `pyro-mcp` uses SemVer.
|
|
- Environment names are stable identifiers in the shipped catalog.
|
|
- Changing a public command name, public flag, public method name, public MCP tool name, or required request field is a breaking change.
|