thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions
pyro-mcp/docs/roadmap/task-workspace-ga/2.5.0-pty-shell-sessions.md
Thales Maciel 3f8293ad24 Add persistent workspace shell sessions 
Let agents inhabit a workspace across separate calls instead of only submitting one-shot execs.

Add workspace shell open/read/write/signal/close across the CLI, Python SDK, and MCP server, with persisted shell records, a local PTY-backed mock implementation, and guest-agent support for real Firecracker workspaces.

Mark the 2.5.0 roadmap milestone done, refresh docs/examples and the release metadata, and verify with uv lock, UV_CACHE_DIR=.uv-cache make check, and UV_CACHE_DIR=.uv-cache make dist-check.
2026-03-12 02:31:57 -03:00

1.6 KiB
Raw Permalink Blame History

2.5.0 PTY Shell Sessions

Status: Done

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