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 a clear 'too old, upgrade to ...' instead of a cryptic subprocess error.
- On early exit / failed register/connect, surface the agent's OWN output (the real error) plus the full log path - no string-match guessing of the cause. Wired into simulate (CI + TUI) and console.

Verified against staging with a broken .venv (shows the ModuleNotFoundError) and an old declared SDK (shows the upgrade message).

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", agentExitDetail(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", agentExitDetail(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", agentExitDetail(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, agentExitDetail(agent))
 	case <-ctx.Done():
 		fmt.Fprintln(os.Stdout, "::endgroup::")
 		return ctx.Err()

cmd/lk/simulate_subprocess.go

@@ -134,13 +134,54 @@ 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"
+
+// agentExitDetail surfaces the agent's own output (the real error) and a pointer
+// to the full log, for when the worker exits early or never registers/connects.
+// It does not try to guess the cause — the agent's output already says it.
+func agentExitDetail(ap *AgentProcess) string {
+	var b strings.Builder
+	if tail := lastNonEmptyLines(ap.RecentLogs(0), 12); len(tail) > 0 {
+		b.WriteString("Agent output:\n  " + strings.Join(tail, "\n  "))
+	}
+	if ap.LogPath != "" {
+		if b.Len() > 0 {
+			b.WriteString("\n\n")
+		}
+		b.WriteString("Full log: " + ap.LogPath)
+	}
+	return b.String()
+}
+
+// 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", agentExitDetail(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, agentExitDetail(m.agent))}
 		case <-m.setupCtx.Done():
 			return agentReadyMsg{err: m.setupCtx.Err()}
 		}