agent CLI: friendly errors for old SDK + worker start failures

- Pre-flight: reuse agentfs.CheckSDKVersion (pinned to 1.6.0, the thin-CLI baseline) in startAgent so start/dev/console/simulate fail fast with 'too old, upgrade to ...' instead of a cryptic subprocess error.
- diagnoseAgentFailure: when the worker exits early or never registers/connects, infer the likely cause (missing venv/deps vs bad LIVEKIT_ credentials), show the agent's output tail, and point at the full log. Wired into simulate (CI + TUI) and console.

Author: theomonnom

cmd/lk/console.go

@@ -20,7 +20,6 @@ import (
 	"io"
 	"log"
 	"net"
-	"os"
 	"os/signal"
 	"strings"
 	"syscall"
@@ -171,23 +170,12 @@ func runConsole(ctx context.Context, cmd *cli.Command) error {
 			return fmt.Errorf("agent connection: %w", res.err)
 		}
 		conn = res.conn
-	case err := <-agentProc.Done():
+	case <-agentProc.Done():
 		stopSpinner()
-		logs := agentProc.RecentLogs(20)
-		for _, l := range logs {
-			fmt.Fprintln(os.Stderr, l)
-		}
-		if err != nil {
-			return fmt.Errorf("agent exited before connecting: %w", err)
-		}
-		return fmt.Errorf("agent exited before connecting")
+		return fmt.Errorf("the agent exited before connecting.\n\n%s", diagnoseAgentFailure(agentProc))
 	case <-time.After(60 * time.Second):
 		stopSpinner()
-		logs := agentProc.RecentLogs(20)
-		for _, l := range logs {
-			fmt.Fprintln(os.Stderr, l)
-		}
-		return fmt.Errorf("timed out waiting for agent to connect")
+		return fmt.Errorf("timed out waiting for the agent to connect.\n\n%s", diagnoseAgentFailure(agentProc))
 	case <-ctx.Done():
 		stopSpinner()
 		return ctx.Err()

cmd/lk/simulate_ci.go

@@ -84,15 +84,12 @@ func runSimulateCI(ctx context.Context, config *simulateConfig) error {
 	case <-agent.Ready():
 		logFwd.enabled.Store(false)
 		fmt.Fprintf(os.Stdout, "✓ Agent registered (%s)\n", time.Since(start).Round(time.Millisecond))
-	case err := <-agent.Done():
+	case <-agent.Done():
 		fmt.Fprintln(os.Stdout, "::endgroup::")
-		if err != nil {
-			return fmt.Errorf("agent exited before registering: %w", err)
-		}
-		return fmt.Errorf("agent exited before registering")
+		return fmt.Errorf("the agent exited before registering.\n\n%s", diagnoseAgentFailure(agent))
 	case <-timeout.C:
 		fmt.Fprintln(os.Stdout, "::endgroup::")
-		return fmt.Errorf("timed out waiting for agent to register (%s)", agentRegisterTimeout)
+		return fmt.Errorf("timed out after %s waiting for the agent to register.\n\n%s", agentRegisterTimeout, diagnoseAgentFailure(agent))
 	case <-ctx.Done():
 		fmt.Fprintln(os.Stdout, "::endgroup::")
 		return ctx.Err()

cmd/lk/simulate_subprocess.go

@@ -134,13 +134,63 @@ type AgentStartConfig struct {
 	ForwardOutput io.Writer // if set, forward each output line to this writer
 }
 
+// thinCLIMinVersion is the first livekit-agents release that exposes the
+// start/dev/console/simulate subcommands under `python -m livekit.agents`.
+const thinCLIMinVersion = "1.6.0"
+
+// diagnoseAgentFailure turns an agent that exited early or never registered into
+// a human-friendly explanation, inferring common causes from its output.
+func diagnoseAgentFailure(ap *AgentProcess) string {
+	logs := ap.RecentLogs(0)
+	hay := strings.ToLower(strings.Join(logs, "\n"))
+	var hint string
+	switch {
+	case strings.Contains(hay, "modulenotfounderror"), strings.Contains(hay, "no module named"):
+		hint = "The Python environment is missing dependencies - check that the right virtualenv is active and the agent is installed (pip install / uv sync)."
+	case strings.Contains(hay, "api key"), strings.Contains(hay, "api_key"),
+		strings.Contains(hay, "api secret"), strings.Contains(hay, "unauthorized"),
+		strings.Contains(hay, "invalid token"), strings.Contains(hay, "401"):
+		hint = "Looks like a credentials problem - check LIVEKIT_URL, LIVEKIT_API_KEY and LIVEKIT_API_SECRET."
+	default:
+		hint = "The agent worker didn't start. Its output below (and the full log) should show why."
+	}
+	msg := hint
+	if tail := lastNonEmptyLines(logs, 8); len(tail) > 0 {
+		msg += "\n\nAgent output:\n  " + strings.Join(tail, "\n  ")
+	}
+	if ap.LogPath != "" {
+		msg += "\n\nFull agent log: " + ap.LogPath
+	}
+	return msg
+}
+
+// lastNonEmptyLines returns up to n trailing non-blank lines, in order.
+func lastNonEmptyLines(lines []string, n int) []string {
+	var out []string
+	for i := len(lines) - 1; i >= 0 && len(out) < n; i-- {
+		if strings.TrimSpace(lines[i]) != "" {
+			out = append([]string{lines[i]}, out...)
+		}
+	}
+	return out
+}
+
 // startAgent launches a Python agent subprocess and monitors its output.
 func startAgent(cfg AgentStartConfig) (*AgentProcess, error) {
 	pythonBin, prefixArgs, err := findPythonBinary(cfg.Dir, cfg.ProjectType)
 	if err != nil {
 		return nil, err
 	}
 
+	// Reuse the SDK-version reader (parses the project's deps) to fail fast with a
+	// friendly message when livekit-agents is older than the thin-CLI baseline.
+	if err := agentfs.CheckSDKVersion(cfg.Dir, cfg.ProjectType, map[string]string{
+		"python-min-sdk-version": thinCLIMinVersion,
+		"node-min-sdk-version":   thinCLIMinVersion,
+	}); err != nil {
+		return nil, err
+	}
+
 	// Launch via the framework CLI module rather than running the user's file
 	// directly: python -m livekit.agents SUBCOMMAND ENTRYPOINT FLAGS. The framework
 	// discovers the AgentServer from the entrypoint and drives the thin CLI. Requires a

cmd/lk/simulate_tui.go

@@ -296,14 +296,11 @@ func (m *simulateModel) waitAgentReadyCmd() tea.Cmd {
 		select {
 		case <-m.agent.Ready():
 			return agentReadyMsg{elapsed: time.Since(stepStart)}
-		case err := <-m.agent.Done():
-			if err != nil {
-				return agentReadyMsg{err: fmt.Errorf("agent exited before registering: %w", err)}
-			}
-			return agentReadyMsg{err: fmt.Errorf("agent exited before registering")}
+		case <-m.agent.Done():
+			return agentReadyMsg{err: fmt.Errorf("the agent exited before registering.\n\n%s", diagnoseAgentFailure(m.agent))}
 		case <-timeout.C:
 			m.agent.Kill()
-			return agentReadyMsg{err: fmt.Errorf("timed out waiting for agent to register (%s)", agentRegisterTimeout)}
+			return agentReadyMsg{err: fmt.Errorf("timed out after %s waiting for the agent to register.\n\n%s", agentRegisterTimeout, diagnoseAgentFailure(m.agent))}
 		case <-m.setupCtx.Done():
 			return agentReadyMsg{err: m.setupCtx.Err()}
 		}