Add noninteractive, isolated Python environment tooling for agents

[Stella Huang (StellaHuang95)]

Add noninteractive, isolated Python environment tooling for agents

Summary

Add a private, versioned __pythonTools capability to the existing flat extension export so Python agent tools can configure environments, inspect interpreters/packages, and install packages without requiring extension-owned pickers or dialogs.

The companion Python-extension change consumes this capability. The public API contract is unchanged, and host tool approval remains in force.

Motivation

Agent requests currently reuse interactive environment workflows, which can pause for interpreter, manager, package, or environment-creation choices. A selected global interpreter can also become the package-installation target.

This change gives agents an explicit noninteractive path with isolation by default, actionable errors, and scoped results, without recording why an interpreter was selected.

Behavior

• Automatic configuration reuses a usable isolated environment or creates one for the project. A selected System/Pyenv base creates a venv using that interpreter; Conda base creates a project Conda environment with the same Python major/minor version.
• An explicit pythonPath still selects that exact existing interpreter. Package tools reject global/base environments even when selected explicitly.
• Queries do not create environments or change selection. Package installation does not implicitly configure an environment.
• Configuration and installation require an open, trusted, local workspace. Results identify the effective resource, environment, and execution information.
• Root selections survive reload, including when python.defaultInterpreterPath is configured. Nested targets persist exact project entries without replacing root defaults.
• Existing Poetry/Pipenv project caches and enabled PEP 723 scripts have noninteractive discovery/setup paths.
• Errors and partial creation results are returned explicitly. Same-scope operations are serialized; cancellation and timeouts await owned-process cleanup and report uncertainty instead of falsely claiming that a process stopped.
• Failed human venv initialization invalidates partial discovery and readiness state, so subsequent public lookups retry discovery instead of remaining on a stale global fallback. Private discovery remains independent of human onboarding.

Human-flow compatibility

Built-in managers opt in through internal symbol capabilities and explicit operation flags. Normal public selection, creation, package, and execution entry points retain their interactive behavior, including public quick-create's .venv-N suffixing.

This is not a claim that all shared code is untouched:

• Venv collection events can arrive earlier relative to base-manager onboarding.
• Public Conda command failures no longer generate the extra unhandled rejection caused by the old unused finally() promise.
• Agent selections, settings, and package changes intentionally remain visible to subsequent human operations.

Validation

• Full ESLint and TypeScript checks pass.
• Windows unit suite after rebasing onto current upstream main: 2,752 passing, 7 pending. Six new failure-path assertions failed before the retry fix and now pass; successful initialization remains cached. The new upstream venv deletion, unresolved-selection recovery, refresh selection-race, uv bootstrap, and scoped Conda discovery tests also pass with the combined implementation.
• Reviewer regression coverage verifies that private Conda execution preserves shell metacharacters as one argument with shell execution disabled, resolves Windows batch launchers to a real executable or fails actionably, and scopes both package queries and installation independently when two Poetry projects share one environment.
• Linux private/public boundary and owned-process suites with the retry fix: 116 passing.
• Real VS Code comparisons against the current base verified manual selection, package install/remove, Run Python File, debugging, unittest discovery/execution, switching back to global Python, and public quick-create.
• Real-host agent verification covered fresh/global setup, selected-base preservation, reload, multi-root, nested targets, Conda, Poetry/Pipenv, PEP 723, cancellation, no-workspace behavior, and invalid input.
• Critical flows were repeated against freshly built production VSIX contents. Installed files were compared with the packages rather than inferred from unchanged version numbers.
• An additional real VS Code before/after retry check used the loaded extension's actual venv manager, native discovery, a real newly created venv, public selection and Run Python File. A one-shot post-discovery base failure was injected only in the isolated test host. Both direct initialization and public-get retries recovered without manual manager refresh after the fix; the pre-fix build required refresh.

Known findings before merge

• Ordinary project .python-version / pyproject.toml interpreter constraints are not automatically resolved. Selected base interpreters and defaultInterpreterPath are honored; PEP 723 constraints are handled separately.
• macOS/remote E2E, arbitrary third-party integrations, and real-chat model choices/approval combinations have not been exhaustively verified.

Companion change

Python consumer PR: microsoft/vscode-python#26208.

The consumer checks the private version/method shape and retains a compatibility route when the capability is unavailable.

[Bill Schnurr (bschnurr)]

🔒 Automated review in progress — Bill Schnurr (@bschnurr) is auto-reviewing this PR.

[Bill Schnurr (bschnurr)]

Result: 🔴 could-not-verify

Verification details

Verification: The relevant tests could not be fully run in the isolated environment; this review is not fully verified.

Summary: [unavailable] Container verification could not start and local execution was not authorized for this PR HEAD: C:\Program Files\RedHat\Podman\podman.EXE --connection pyrx-automation failed: stderr: Error: unable to start container "051c6d0c6a956b5517c772b42aad7b236d7a17dac3df0c55d2d5c2bc0452f266": crun: open `memory.max` for writing: No such file or directory: OCI runtime attempted to invoke a command that was not found

Test runs: none recorded.

[Bill Schnurr (bschnurr)]

Result: 🔴 could-not-verify

Verification details

Verification: The relevant tests could not be fully run in the isolated environment; this review is not fully verified.

Summary: [unavailable] Container verification could not start and local execution was not authorized for this PR HEAD: C:\Program Files\RedHat\Podman\podman.EXE --connection pyrx-automation failed: stderr: Error: unable to start container "01a9ec8132191f11549aa0ae6eb6df8abe6a55e722642de5bc83b10a91860844": crun: open `memory.max` for writing: No such file or directory: OCI runtime attempted to invoke a command that was not found

Test runs: none recorded.

[Bill Schnurr (bschnurr)]

Approved via Review Center.