Add workspace-first roadmap milestones
Break the updated workspace vision into a checked-in roadmap from 2.4.0 through 3.1.0 so later implementation can be driven milestone by milestone. Link the roadmap from the vision doc and keep each release slice scoped to one product capability, from the workspace contract pivot through shells, export/diff, services, snapshots, secrets, networking, and GA promotion. This is a docs-only planning scaffold; runtime behavior stays unchanged in this commit.
This commit is contained in:
parent
dccc2152e3
commit
f57454bcb4
11 changed files with 484 additions and 0 deletions
47
docs/roadmap/task-workspace-ga.md
Normal file
47
docs/roadmap/task-workspace-ga.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
63
docs/roadmap/task-workspace-ga/2.5.0-pty-shell-sessions.md
Normal file
63
docs/roadmap/task-workspace-ga/2.5.0-pty-shell-sessions.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
41
docs/roadmap/task-workspace-ga/2.9.0-secrets.md
Normal file
41
docs/roadmap/task-workspace-ga/2.9.0-secrets.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
41
docs/roadmap/task-workspace-ga/3.1.0-secondary-disk-tools.md
Normal file
41
docs/roadmap/task-workspace-ga/3.1.0-secondary-disk-tools.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue