fix(agent): never sync the uv environment as a launch side effect

The CLI proxies the project's local environment; `uv run` implicitly
re-locking and installing packages when launching an agent is a
surprising side effect (and can change dependency versions mid-debug).
Move --no-sync into findPythonBinary so both the version pre-flight and
the launch run against the environment as it exists on disk.

Since the launch no longer installs missing dependencies, the version
probe now distinguishes "interpreter ran but livekit-agents isn't
installed" and the pre-flight fails fast with a `uv sync` hint
instead of letting the agent die with ModuleNotFoundError.

Author: u9g

cmd/lk/python_sdk_version_test.go

@@ -18,6 +18,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/require"
@@ -71,7 +72,9 @@ func setupUvAgentProject(t *testing.T, stubVersion, depSpec string, sync bool) s
 
 func TestResolvePythonAgentVersion_ReadsInstalledVersion(t *testing.T) {
 	dir := setupUvAgentProject(t, "1.6.7", "livekit-agents", true)
-	require.Equal(t, "1.6.7", resolvePythonAgentVersion(dir, agentfs.ProjectTypePythonUV))
+	version, notInstalled := resolvePythonAgentVersion(dir, agentfs.ProjectTypePythonUV)
+	require.Equal(t, "1.6.7", version)
+	require.False(t, notInstalled)
 }
 
 func TestCheckPythonSDKVersion_TooOld(t *testing.T) {
@@ -88,9 +91,32 @@ func TestCheckPythonSDKVersion_InstalledBeatsLooseConstraint(t *testing.T) {
 	require.NoError(t, checkPythonSDKVersion(AgentStartConfig{Dir: dir, ProjectType: agentfs.ProjectTypePythonUV}))
 }
 
-func TestCheckPythonSDKVersion_FallsBackToFilesWhenNotInstalled(t *testing.T) {
-	// Not synced: `uv run --no-sync` can't resolve an installed version, so the
-	// check falls back to parsing the pyproject constraint (>=1.6.0 satisfies).
+func TestCheckPythonSDKVersion_UnsyncedUVProjectSuggestsSync(t *testing.T) {
+	// Models a fresh clone where dependencies were never installed. The CLI is
+	// a proxy for the local environment and never syncs it implicitly, so the
+	// agent would die at launch with ModuleNotFoundError; the pre-flight must
+	// fail fast and tell the user how to fix it instead.
 	dir := setupUvAgentProject(t, "1.6.7", "livekit-agents>=1.6.0", false)
-	require.NoError(t, checkPythonSDKVersion(AgentStartConfig{Dir: dir, ProjectType: agentfs.ProjectTypePythonUV}))
+	err := checkPythonSDKVersion(AgentStartConfig{Dir: dir, ProjectType: agentfs.ProjectTypePythonUV})
+	require.ErrorContains(t, err, "uv sync")
+}
+
+func TestFindPythonBinary_UVRunDoesNotSyncEnvironment(t *testing.T) {
+	// Models a user who synced their env, then edited a dependency's version
+	// without re-syncing. Running through the CLI-resolved interpreter must
+	// execute against the environment as it exists on disk — a plain `uv run`
+	// would re-lock and install 9.9.9 as a side effect of launching.
+	dir := setupUvAgentProject(t, "1.6.7", "livekit-agents", true)
+	stubPyproject := filepath.Join(dir, "stub", "pyproject.toml")
+	orig, err := os.ReadFile(stubPyproject)
+	require.NoError(t, err)
+	require.NoError(t, os.WriteFile(stubPyproject, []byte(strings.Replace(string(orig), "1.6.7", "9.9.9", 1)), 0o644))
+
+	bin, prefixArgs, err := findPythonBinary(dir, agentfs.ProjectTypePythonUV)
+	require.NoError(t, err)
+	cmd := exec.Command(bin, append(prefixArgs, "-c", `import importlib.metadata as m; print(m.version("livekit-agents"))`)...)
+	cmd.Dir = dir
+	out, err := cmd.Output()
+	require.NoError(t, err)
+	require.Equal(t, "1.6.7", strings.TrimSpace(string(out)))
 }

cmd/lk/simulate_subprocess.go

@@ -58,7 +58,9 @@ func findPythonBinary(dir string, projectType agentfs.ProjectType) (string, []st
 	if projectType == agentfs.ProjectTypePythonUV {
 		uvPath, err := exec.LookPath("uv")
 		if err == nil {
-			return uvPath, []string{"run", "python"}, nil
+			// --no-sync: the CLI proxies the environment as it exists on disk
+			// and must never install or upgrade packages as a side effect.
+			return uvPath, []string{"run", "--no-sync", "python"}, nil
 		}
 	}
 
@@ -180,22 +182,27 @@ func checkNodeSDKVersion(cfg AgentStartConfig) error {
 	return nil
 }
 
-// pythonResolveVersionScript prints the installed livekit-agents version, or
-// exits non-zero if it isn't importable.
-const pythonResolveVersionScript = `import importlib.metadata as m; print(m.version("livekit-agents"))`
+// pythonResolveVersionScript prints the installed livekit-agents version, or a
+// sentinel when the interpreter runs fine but the package isn't installed —
+// distinguishing "dependencies not synced" from probe failures (no
+// interpreter, timeout), which exit non-zero.
+const pythonResolveVersionScript = `import importlib.metadata as m
+try:
+    print(m.version("livekit-agents"))
+except m.PackageNotFoundError:
+    print("` + pythonAgentNotInstalled + `")`
+
+const pythonAgentNotInstalled = "__NOT_INSTALLED__"
 
 // resolvePythonAgentVersion returns the installed livekit-agents version read
 // via the project's interpreter, so any installer (uv, pip, poetry) reports the
-// version that will actually run. Returns "" when it can't be determined (no
-// interpreter, dependencies not installed, etc.). For uv it reads the existing
-// environment without syncing, so a pre-flight check never mutates or downloads.
-func resolvePythonAgentVersion(dir string, projectType agentfs.ProjectType) string {
+// version that will actually run. notInstalled reports that the interpreter ran
+// but the package is missing from its environment; version is "" when it can't
+// be determined at all (no interpreter, probe failure, etc.).
+func resolvePythonAgentVersion(dir string, projectType agentfs.ProjectType) (version string, notInstalled bool) {
 	pythonBin, prefixArgs, err := findPythonBinary(dir, projectType)
 	if err != nil {
-		return ""
-	}
-	if projectType == agentfs.ProjectTypePythonUV && len(prefixArgs) > 0 && prefixArgs[0] == "run" {
-		prefixArgs = append([]string{"run", "--no-sync"}, prefixArgs[1:]...)
+		return "", false
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 	defer cancel()
@@ -204,17 +211,27 @@ func resolvePythonAgentVersion(dir string, projectType agentfs.ProjectType) stri
 	cmd.Dir = dir
 	out, err := cmd.Output()
 	if err != nil {
-		return ""
+		return "", false
 	}
-	return strings.TrimSpace(string(out))
+	v := strings.TrimSpace(string(out))
+	if v == pythonAgentNotInstalled {
+		return "", true
+	}
+	return v, false
 }
 
 // checkPythonSDKVersion gates a Python agent on thinCLIMinVersion. It prefers
 // the installed version (resolved via the interpreter, accurate regardless of
 // the package manager and not fooled by a loose version constraint); when
 // dependencies aren't installed it falls back to static project-file parsing.
 func checkPythonSDKVersion(cfg AgentStartConfig) error {
-	if version := resolvePythonAgentVersion(cfg.Dir, cfg.ProjectType); version != "" {
+	version, notInstalled := resolvePythonAgentVersion(cfg.Dir, cfg.ProjectType)
+	if notInstalled && cfg.ProjectType == agentfs.ProjectTypePythonUV {
+		// The launch runs `uv run --no-sync`, so a missing package won't be
+		// installed on the way up — fail fast with the fix instead.
+		return fmt.Errorf("livekit-agents is not installed in the project environment; run `uv sync` and try again")
+	}
+	if version != "" {
 		// An unparseable version (e.g. a local "0.0.0.dev" tag) shouldn't block a run.
 		if ok, err := agentfs.IsVersionSatisfied(version, thinCLIMinVersion); err == nil && !ok {
 			return fmt.Errorf("livekit-agents version %s is too old, please upgrade to %s or newer", version, thinCLIMinVersion)
@@ -324,7 +341,7 @@ const thinCLIMinVersion = "1.6.0"
 // buildAgentCommand resolves the interpreter and argv for an agent subprocess,
 // branching on project type. Python uses the thin CLI:
 // `<python> <runtime-args> -m livekit.agents SUBCOMMAND ENTRYPOINT FLAGS`
-// (uv prefixes `run python`). Node runs the entrypoint directly:
+// (uv prefixes `run --no-sync python`). Node runs the entrypoint directly:
 // `node [--experimental-strip-types] <runtime-args> ENTRYPOINT SUBCOMMAND FLAGS`,
 // where the type-stripping flag lets a `.ts` entrypoint run without a build.
 func buildAgentCommand(cfg AgentStartConfig) (string, []string, error) {