Add Python repl_prepare runtime preparation

[t-kalinowski]

Summary

Adds a Python-only repl_prepare tool for cases where a caller wants to change, select, or preflight the Python environment before later repl calls. The Python REPL itself still starts ready for evaluation; repl_prepare is for environment preparation, not for making repl usable.

Tool schema

repl_prepare is advertised only by Python servers when uv is available. R servers continue to advertise repl_reset; Python servers no longer advertise repl_reset.

repl_prepare({
  requirements?: {
    packages?: string[];
    python_version?: string;
    action?: "add" | "remove" | "set";      // default: "add"
    restart?: "if_needed" | "no" | "yes";   // default: "if_needed"
  };
  python?: {
    executable?: string; // absolute path
    venv?: string;       // absolute path to a virtual environment
  };
})

Contract details:

• Do not call repl_prepare just to make repl available; the REPL starts ready.
• Use requirements when the caller needs managed packages or a managed Python version before evaluation.
• Use python when the caller needs an existing interpreter or virtual environment.
• Omit all arguments only to realize the current managed requirements manifest without changing it.
• The managed manifest starts as packages=["numpy"] and python_version=null.
• Provide either requirements or python, not both.
• Inside python, provide exactly one of executable or venv.
• requirements.action updates the persistent managed manifest with add, remove, or set.
• requirements.restart controls whether preparation may restart the active Python session.
• requirements.python_version is forwarded to uv as supplied.
• Explicit python selections use the requested interpreter or venv as-is and do not mutate the managed manifest.
• The tool does not execute user code, import packages, attach modules, or define aliases.
• There is no timeout_ms argument.

Scenario examples

The snippets below use pseudo tool-call syntax. Each repl(...) call is a later Python REPL evaluation after repl_prepare(...) returns.

Add a package before importing it:

repl_prepare(requirements = {packages: ["pandas"]})

repl("""
import pandas as pd
print(pd.DataFrame({"x": [1, 2]}).shape)
""")
# (2, 1)

Build up a persistent managed manifest:

repl_prepare(requirements = {packages: ["pandas"]})
repl_prepare(requirements = {packages: ["plotnine"]})

repl("""
import pandas
import plotnine
print("ready")
""")
# ready

Replace the whole managed manifest and request a Python version constraint:

repl_prepare(requirements = {
  packages: ["numpy", "pandas"],
  python_version: ">=3.11,<3.13",
  action: "set"
})

repl("""
import sys
import numpy
import pandas
print(sys.version_info >= (3, 11))
""")
# True

Preserve existing session state if preparation would require a restart:

repl("_marker = 'kept'")

repl_prepare(requirements = {
  packages: ["plotnine"],
  restart: "no"
})
# returns an error if satisfying the request requires a restart
# session unchanged; no user state discarded

repl("print(_marker)")
# kept

Force a fresh session for the current managed manifest:

repl("_marker = 'discarded'")

repl_prepare(requirements = {restart: "yes"})
# session restarted; user state discarded

repl("print('_marker' in globals())")
# False

Switch to an existing project virtual environment:

repl_prepare(python = {venv: "/absolute/path/to/project/.venv"})

repl("""
import sys
print(sys.prefix)
""")
# /absolute/path/to/project/.venv

Switch to an explicit Python executable:

repl_prepare(python = {executable: "/absolute/path/to/python"})

repl("""
import sys
print(sys.executable)
""")
# /absolute/path/to/python

Remove a package from the managed manifest before returning to that managed environment:

repl_prepare(requirements = {packages: ["plotnine"], action: "remove"})

repl("""
import importlib.util
print(importlib.util.find_spec("plotnine") is None)
""")
# True

Reset Python without environment preparation:

repl("<Ctrl-D>")
# new session started

R keeps the existing reset tool:

repl_reset()
# new session started

Internal changes

• Adds Python runtime preparation and requirement resolution through uv.
• Propagates prepared Python executable and module search-path overrides into embedded Python workers.
• Adds worker replacement support and lightweight user-state tracking for restart decisions.
• Splits server tool surfaces into R reset, Python prepare, and Python repl-only variants.
• Adds public MCP coverage for tool listing, schema validation, manifest updates, restart policy behavior, active-work replacement, and explicit Python selection.

Diff composition

Measured against the merge base with main, this PR is 2079 insertions and 107 deletions across 22 files.

• runtime src/: +1058/-95 (52.7% of churn)
• inline tests inside src/: +3/-0 (0.1% of churn)
• tests in tests/: +924/-8 (42.6% of churn)
• docs: +94/-4 (4.5% of churn)

Largest files:

• tests/python_repl_prepare.rs: +904/-0
• src/server.rs: +387/-49
• src/python_prepare.rs: +399/-0
• src/worker_supervisor.rs: +88/-25
• src/python_runtime.rs: +71/-17