diff --git a/docs/roadmap/task-workspace-ga.md b/docs/roadmap/task-workspace-ga.md new file mode 100644 index 0000000..00cd1f0 --- /dev/null +++ b/docs/roadmap/task-workspace-ga.md @@ -0,0 +1,47 @@ +# Task Workspace GA Roadmap + +This roadmap turns the agent-workspace vision into release-sized milestones. + +Current baseline is `2.4.0`: + +- workspace persistence exists and the public surface is now workspace-first +- host crossing currently covers create-time seeding and later sync push +- no shell, export, diff, service, snapshot, reset, or secrets contract exists yet + +Locked roadmap decisions: + +- no backward compatibility goal for the current `task_*` naming +- workspace-first naming lands first, before later features +- snapshots are real named snapshots, not only reset-to-baseline + +Every milestone below must update CLI, SDK, and MCP together. Each milestone is +also expected to update: + +- `README.md` +- install/first-run docs +- `docs/public-contract.md` +- help text and runnable examples +- at least one real Firecracker smoke scenario + +## Milestones + +1. [`2.4.0` Workspace Contract Pivot](task-workspace-ga/2.4.0-workspace-contract-pivot.md) +2. [`2.5.0` PTY Shell Sessions](task-workspace-ga/2.5.0-pty-shell-sessions.md) +3. [`2.6.0` Structured Export And Baseline Diff](task-workspace-ga/2.6.0-structured-export-and-baseline-diff.md) +4. [`2.7.0` Service Lifecycle And Typed Readiness](task-workspace-ga/2.7.0-service-lifecycle-and-typed-readiness.md) +5. [`2.8.0` Named Snapshots And Reset](task-workspace-ga/2.8.0-named-snapshots-and-reset.md) +6. [`2.9.0` Secrets](task-workspace-ga/2.9.0-secrets.md) +7. [`2.10.0` Network Policy And Host Port Publication](task-workspace-ga/2.10.0-network-policy-and-host-port-publication.md) +8. [`3.0.0` Stable Workspace Product](task-workspace-ga/3.0.0-stable-workspace-product.md) +9. [`3.1.0` Secondary Disk Tools](task-workspace-ga/3.1.0-secondary-disk-tools.md) + +## Definition Of Done For The Roadmap + +The workspace product is ready to leave beta when: + +- the public contract is workspace-first rather than task-first +- an agent can inhabit a sandbox through shell, exec, service, diff, export, + snapshot, reset, and explicit host-crossing operations +- the main docs lead with the workspace product, not one-shot VM execution +- the remaining deliberate deferrals are secondary disk tools rather than core + workspace features diff --git a/docs/roadmap/task-workspace-ga/2.10.0-network-policy-and-host-port-publication.md b/docs/roadmap/task-workspace-ga/2.10.0-network-policy-and-host-port-publication.md new file mode 100644 index 0000000..20256d5 --- /dev/null +++ b/docs/roadmap/task-workspace-ga/2.10.0-network-policy-and-host-port-publication.md @@ -0,0 +1,43 @@ +# `2.10.0` Network Policy And Host Port Publication + +## Goal + +Replace the coarse current network toggle with an explicit workspace network +policy and make services host-probeable through controlled published ports. + +## Public API Changes + +- `workspace create` gains explicit network policy instead of a simple boolean +- `workspace service start` gains published-port configuration +- `workspace service status/list` returns published-port information + +Recommended policy model: + +- `off` +- `egress` +- `egress+published-ports` + +## Implementation Boundaries + +- Host port publication is localhost-only by default. +- Ports remain attached to services, not generic VM networking. +- Published-port details are queryable from CLI, SDK, and MCP. +- Keep network access explicit and visible in the workspace spec. + +## Non-Goals + +- no remote exposure defaults +- no advanced ingress routing +- no general-purpose networking product surface + +## Acceptance Scenarios + +- start a service, wait for readiness, probe it from the host, inspect logs, + then stop it +- keep a workspace fully offline and confirm no implicit network access exists + +## Required Repo Updates + +- docs that show app validation from the host side +- examples that use typed readiness plus localhost probing +- real Firecracker smoke for published-port probing diff --git a/docs/roadmap/task-workspace-ga/2.4.0-workspace-contract-pivot.md b/docs/roadmap/task-workspace-ga/2.4.0-workspace-contract-pivot.md new file mode 100644 index 0000000..8113545 --- /dev/null +++ b/docs/roadmap/task-workspace-ga/2.4.0-workspace-contract-pivot.md @@ -0,0 +1,70 @@ +# `2.4.0` Workspace Contract Pivot + +## Goal + +Make the public product read as a workspace-first sandbox instead of a +task-flavored alpha by replacing the `task_*` surface with `workspace_*`. + +## Public API Changes + +- CLI: + - `pyro workspace create` + - `pyro workspace sync push` + - `pyro workspace exec` + - `pyro workspace status` + - `pyro workspace logs` + - `pyro workspace delete` +- SDK: + - `create_workspace` + - `sync_push_workspace` + - `exec_workspace` + - `status_workspace` + - `logs_workspace` + - `delete_workspace` +- MCP: + - `workspace_create` + - `workspace_sync_push` + - `workspace_exec` + - `workspace_status` + - `workspace_logs` + - `workspace_delete` + +Field renames: + +- `task_id` -> `workspace_id` +- `source_path` on create -> `seed_path` +- `task.json` / `tasks/` -> `workspace.json` / `workspaces/` + +No compatibility aliases. Remove `task_*` from the public contract in the same +release. + +## Implementation Boundaries + +- Keep current behavior intact under the new names: + - persistent workspace creation + - create-time seed + - sync push + - exec/status/logs/delete +- Rename public result payloads and CLI help text to workspace language. +- Move on-disk persisted records to `workspaces/` and update rehydration logic + accordingly. +- Update examples, docs, and tests to stop using task terminology. + +## Non-Goals + +- no shell sessions yet +- no export, diff, services, snapshots, reset, or secrets in this release +- no attempt to preserve old CLI/SDK/MCP names + +## Acceptance Scenarios + +- create a seeded workspace, sync host changes into it, exec inside it, inspect + status/logs, then delete it +- the same flow works from CLI, SDK, and MCP with only workspace-first names +- one-shot `pyro run` remains unchanged + +## Required Repo Updates + +- replace task language in README/install/first-run/public contract/help +- update runnable examples to use `workspace_*` +- add one real Firecracker smoke for create -> sync push -> exec -> delete diff --git a/docs/roadmap/task-workspace-ga/2.5.0-pty-shell-sessions.md b/docs/roadmap/task-workspace-ga/2.5.0-pty-shell-sessions.md new file mode 100644 index 0000000..ccd3a30 --- /dev/null +++ b/docs/roadmap/task-workspace-ga/2.5.0-pty-shell-sessions.md @@ -0,0 +1,63 @@ +# `2.5.0` PTY Shell Sessions + +## Goal + +Add persistent interactive shells so an agent can inhabit a workspace instead +of only submitting one-shot `workspace exec` calls. + +## Public API Changes + +- CLI: + - `pyro workspace shell open` + - `pyro workspace shell read` + - `pyro workspace shell write` + - `pyro workspace shell signal` + - `pyro workspace shell close` +- SDK: + - `open_shell` + - `read_shell` + - `write_shell` + - `signal_shell` + - `close_shell` +- MCP: + - `shell_open` + - `shell_read` + - `shell_write` + - `shell_signal` + - `shell_close` + +Core shell identity: + +- `workspace_id` +- `shell_id` +- PTY size +- working directory +- running/stopped state + +## Implementation Boundaries + +- Shells are persistent PTY sessions attached to one workspace. +- Output buffering is append-only with cursor-based reads so callers can poll + incrementally. +- Shell sessions survive separate CLI/SDK/MCP calls and are cleaned up by + `workspace delete`. +- Keep `workspace exec` as the non-interactive path; do not merge the two + models. + +## Non-Goals + +- no terminal UI beyond structured shell I/O +- no service lifecycle changes in this milestone +- no export/diff/snapshot/reset changes yet + +## Acceptance Scenarios + +- open a shell, write commands, read output in chunks, send SIGINT, then close +- reopen a new shell in the same workspace after closing the first one +- delete a workspace with an open shell and confirm the shell is cleaned up + +## Required Repo Updates + +- shell-focused example in CLI, SDK, and MCP docs +- help text that explains shell vs exec clearly +- real Firecracker smoke for open -> write -> read -> signal -> close diff --git a/docs/roadmap/task-workspace-ga/2.6.0-structured-export-and-baseline-diff.md b/docs/roadmap/task-workspace-ga/2.6.0-structured-export-and-baseline-diff.md new file mode 100644 index 0000000..9a51d55 --- /dev/null +++ b/docs/roadmap/task-workspace-ga/2.6.0-structured-export-and-baseline-diff.md @@ -0,0 +1,47 @@ +# `2.6.0` Structured Export And Baseline Diff + +## Goal + +Complete the next explicit host-crossing step by letting a workspace export +files back to the host and diff itself against its immutable create-time +baseline. + +## Public API Changes + +- CLI: + - `pyro workspace export WORKSPACE_ID PATH --output HOST_PATH` + - `pyro workspace diff WORKSPACE_ID` +- SDK: + - `export_workspace` + - `diff_workspace` +- MCP: + - `workspace_export` + - `workspace_diff` + +## Implementation Boundaries + +- Capture a baseline snapshot at `workspace create`. +- `workspace diff` compares current `/workspace` against that baseline. +- `workspace export` exports files or directories only from paths under + `/workspace`. +- Keep output structured: + - unified patch text for text files + - summary entries for binary or type changes + +## Non-Goals + +- no named snapshots yet +- no reset yet +- no export outside `/workspace` + +## Acceptance Scenarios + +- seed workspace, mutate files, diff against baseline, export a file to host +- sync push content after create, then confirm diff reports the synced changes +- unchanged workspace returns an empty diff summary cleanly + +## Required Repo Updates + +- docs that distinguish seed, sync push, diff, and export +- example showing reproduce -> mutate -> diff -> export +- real Firecracker smoke for diff and export diff --git a/docs/roadmap/task-workspace-ga/2.7.0-service-lifecycle-and-typed-readiness.md b/docs/roadmap/task-workspace-ga/2.7.0-service-lifecycle-and-typed-readiness.md new file mode 100644 index 0000000..d606401 --- /dev/null +++ b/docs/roadmap/task-workspace-ga/2.7.0-service-lifecycle-and-typed-readiness.md @@ -0,0 +1,50 @@ +# `2.7.0` Service Lifecycle And Typed Readiness + +## Goal + +Make app-style workspaces practical by adding first-class services and typed +readiness checks. + +## Public API Changes + +- CLI: + - `pyro workspace service start` + - `pyro workspace service list` + - `pyro workspace service status` + - `pyro workspace service logs` + - `pyro workspace service stop` +- SDK/MCP mirror the same shape + +Readiness types: + +- file +- TCP +- HTTP +- command as an escape hatch + +## Implementation Boundaries + +- Support multiple named services per workspace from the first release. +- Service state and logs live outside `/workspace`. +- `workspace status` stays aggregate; detailed service inspection lives under + `workspace service ...`. +- Prefer typed readiness in docs/examples instead of shell-heavy readiness + commands. + +## Non-Goals + +- no host-visible port publication yet +- no secrets or auth wiring in this milestone +- no shell/service unification + +## Acceptance Scenarios + +- start two services in one workspace, wait for readiness, inspect logs and + status, then stop them cleanly +- service files do not appear in `workspace diff` or `workspace export` + +## Required Repo Updates + +- cold-start validation example that uses services +- CLI help/examples for typed readiness +- real Firecracker smoke for multi-service start/status/logs/stop diff --git a/docs/roadmap/task-workspace-ga/2.8.0-named-snapshots-and-reset.md b/docs/roadmap/task-workspace-ga/2.8.0-named-snapshots-and-reset.md new file mode 100644 index 0000000..0a0ec16 --- /dev/null +++ b/docs/roadmap/task-workspace-ga/2.8.0-named-snapshots-and-reset.md @@ -0,0 +1,42 @@ +# `2.8.0` Named Snapshots And Reset + +## Goal + +Turn reset into a first-class workflow primitive and add explicit named +snapshots, not only the implicit create-time baseline. + +## Public API Changes + +- CLI: + - `pyro workspace snapshot create` + - `pyro workspace snapshot list` + - `pyro workspace snapshot delete` + - `pyro workspace reset WORKSPACE_ID [--snapshot SNAPSHOT_ID|baseline]` +- SDK/MCP mirrors + +## Implementation Boundaries + +- Baseline snapshot is created automatically at workspace creation. +- Named snapshots are explicit user-created checkpoints. +- `workspace reset` recreates the full sandbox, not just `/workspace`. +- Reset may target either the baseline or a named snapshot. + +## Non-Goals + +- no secrets in this milestone +- no live host-sharing or mount semantics +- no branching/merge workflow on snapshots + +## Acceptance Scenarios + +- mutate workspace, create named snapshot, mutate again, reset to snapshot, + confirm state restoration +- mutate service and `/tmp` state, reset to baseline, confirm full sandbox + recreation +- diff after reset is clean when expected + +## Required Repo Updates + +- docs that teach reset over repair explicitly +- example showing baseline reset and named snapshot reset +- real Firecracker smoke for snapshot create -> mutate -> reset diff --git a/docs/roadmap/task-workspace-ga/2.9.0-secrets.md b/docs/roadmap/task-workspace-ga/2.9.0-secrets.md new file mode 100644 index 0000000..efb6c62 --- /dev/null +++ b/docs/roadmap/task-workspace-ga/2.9.0-secrets.md @@ -0,0 +1,41 @@ +# `2.9.0` Secrets + +## Goal + +Add explicit secrets so workspaces can handle private dependencies, +authenticated startup, and secret-aware shell or exec flows without weakening +the fail-closed sandbox model. + +## Public API Changes + +- `workspace create` gains secrets +- `workspace exec`, `workspace shell open`, and `workspace service start` gain + per-call secret-to-env mapping +- SDK and MCP mirror the same model + +## Implementation Boundaries + +- Support literal secrets and host-file-backed secrets. +- Materialize secrets outside `/workspace`. +- Secret values never appear in status, logs, diffs, or exports. +- Reset recreates secrets from persisted secret material, not from the original + host source path. + +## Non-Goals + +- no post-create secret editing +- no secret listing beyond safe metadata +- no mount-based secret transport + +## Acceptance Scenarios + +- create a workspace with a literal secret and a file-backed secret +- run exec and shell flows with mapped env vars +- start a service that depends on a secret-backed readiness path +- confirm redaction in command, shell, and service output + +## Required Repo Updates + +- docs for private dependency workflows +- explicit redaction tests +- real Firecracker smoke for secret-backed exec or service start diff --git a/docs/roadmap/task-workspace-ga/3.0.0-stable-workspace-product.md b/docs/roadmap/task-workspace-ga/3.0.0-stable-workspace-product.md new file mode 100644 index 0000000..44a9de7 --- /dev/null +++ b/docs/roadmap/task-workspace-ga/3.0.0-stable-workspace-product.md @@ -0,0 +1,37 @@ +# `3.0.0` Stable Workspace Product + +## Goal + +Freeze the workspace-first public contract and promote the product from a +one-shot runner with extras to a stable agent workspace. + +## Public API Changes + +No new capability is required in this milestone. The main change is stability: + +- workspace-first names are the only public contract +- shell, sync, export, diff, services, snapshots, reset, secrets, and network + policy are all part of the stable product surface + +## Implementation Boundaries + +- remove remaining beta/alpha language from workspace docs +- rewrite landing docs so the workspace product is first-class and `pyro run` + is the entry point rather than the center +- lock the stable contract in `docs/public-contract.md` + +## Non-Goals + +- no new secondary tooling +- no job-runner, queue, or CI abstractions + +## Acceptance Scenarios + +- all core vision workflows are documented and runnable from CLI, SDK, and MCP +- the repo no longer presents the workspace model as provisional + +## Required Repo Updates + +- top-level README repositioning around the workspace product +- stable public contract doc for `3.x` +- changelog entry that frames the workspace product as stable diff --git a/docs/roadmap/task-workspace-ga/3.1.0-secondary-disk-tools.md b/docs/roadmap/task-workspace-ga/3.1.0-secondary-disk-tools.md new file mode 100644 index 0000000..a9015db --- /dev/null +++ b/docs/roadmap/task-workspace-ga/3.1.0-secondary-disk-tools.md @@ -0,0 +1,41 @@ +# `3.1.0` Secondary Disk Tools + +## Goal + +Add the disk-level tools the vision explicitly places last, while keeping them +secondary to the workspace identity. + +## Public API Changes + +Representative additions: + +- stopped-workspace disk export/import helpers +- offline inspection helpers +- disk-oriented snapshot inspection + +Exact command names should reinforce that these are supporting tools rather than +the primary product contract. + +## Implementation Boundaries + +- keep these tools scoped to seeding, inspection, and offline workflows +- do not replace shell, exec, services, diff, export, or reset as the main + interaction model +- prefer explicit stopped-workspace or offline semantics + +## Non-Goals + +- no drift into generic image tooling identity +- no replacement of workspace-level host crossing + +## Acceptance Scenarios + +- inspect or export a stopped workspace disk for offline analysis +- import or snapshot content through disk-level tools without changing the main + workspace workflow + +## Required Repo Updates + +- docs that clearly mark disk tools as secondary +- examples that show when disk tools are faster than a full boot +- real smoke coverage for at least one offline inspection flow diff --git a/docs/vision.md b/docs/vision.md index 93a4d33..41a6600 100644 --- a/docs/vision.md +++ b/docs/vision.md @@ -170,6 +170,9 @@ Features should be prioritized in this order: 6. Explicit secrets and network policy 7. Secondary disk-level import/export and inspection tools +The implementation roadmap that turns those priorities into release-sized +milestones lives in [roadmap/task-workspace-ga.md](roadmap/task-workspace-ga.md). + ## Naming Guidance Prefer language that reinforces the workspace model: