simulate: Node agent support, --view mode, and TUI/start UX fixes (#878)

* feat(session): support Node.js agents in the local session daemon

The `lk agent session` daemon could previously only spawn Python agents;
Node/JS projects were rejected at detection time. This wires up the Node
path so a JS/TS agent can be driven over the same text-mode console
protocol as Python.

- agent_utils.go: stop gating `detectProject` on Python-only. Accept Node
  projects too (DetectProjectRoot already recognizes them via package.json)
  and update the error to reflect both supported runtimes.
- simulate_subprocess.go: extract interpreter/argv resolution into
  `buildAgentCommand`, branching on project type. Python keeps
  `<python> <entry> <args>` (uv prefixes `run python`); Node runs
  `node [--experimental-strip-types] <entry> <args>`. Add `findNodeBinary`
  (resolves `node` from PATH) and `isTypeScriptEntry` so a `.ts`/`.mts`/
  `.cts` entrypoint runs directly via the type-stripping loader with no
  build step.
- session_daemon.go: drop the stale TODO; the daemon now spawns either
  runtime via `buildConsoleArgs` (`console --connect-addr <addr>`).

Verified end-to-end: `lk agent session start examples/src/console_text_agent.ts`
spawns the JS agent, connects to the Go TCP console server, completes the
text-mode handshake, and round-trips multi-turn `say` requests including a
function-tool call.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(agent): Node.js agent support for lk agent dev/start/console (#868)

* feat(agent): support Node.js agents in lk agent dev/start/console

Builds on the Node project detection and spawn helpers from the session
daemon work (#861) to wire the remaining agent run commands for Node:

- `lk agent dev`/`start`: spawn the agents-js `dev` subcommand (Python
  keeps `start --dev`), normalize --log-level casing per runtime
  (agents-js only accepts lowercase, Python expects uppercase), and make
  the reload-server handshake (--reload-addr) Python-only — Node reloads
  are a plain kill+respawn since agents-js has no job-restore protocol.
- Entrypoint discovery: probe per-runtime candidate lists (agent.ts,
  agent.js, src/agent.{ts,js} for Node; agent.py, src/agent.py for
  Python) instead of a single root default, and make the not-found
  message runtime-aware.
- Probe `node --version` before running a TypeScript entrypoint and fail
  with a clear message on Node < 22.6 (no --experimental-strip-types).
- resolveCredentials: ignore the global --url flag's default value so
  the project config (--project) can supply the URL; previously the
  spawned agent was always pointed at http://localhost:7880 unless --url
  or LIVEKIT_URL was set explicitly.

`lk agent console` needed no changes beyond #861 — the spawn path was
already runtime-agnostic.

Tested end to end against agents-js' console CLI branch (#1706):
console text mode, audio mode (mic/speaker + playback-finished
handshake), ctrl-T mode toggle, --record output, dev worker
registration, file-watch reload, and clean shutdown.

* feat(agent): load discovered .env files into Node agents via --env-file

Node agents spawned by lk agent dev/start/console inherited only the shell
environment, so credentials in a project .env file were never seen (Python
agents conventionally load_dotenv() themselves). Discover a known env file
in the project dir and pass it to Node's built-in dotenv with --env-file.

The flag requires Node >= 20.6, so the type-stripping version check is
refactored into a shared nodeVersion probe and the flag is skipped on older
Nodes. Shell-exported variables still take precedence over file values.

* feat(console): fail fast when the agent job crashes before connecting

A pre-connect job crash (e.g. missing API key in the entrypoint) leaves the
worker process alive, so lk agent console sat on the spinner for the full
60s connect timeout before surfacing the traceback. Scan agent output for
crash markers (Python's "job crashed" shutdown reason, agents-js's FATAL
"console mode failed:") via a new FailSignals option on AgentStartConfig,
and abort the connect wait immediately with the recent logs. The session
daemon's wait gets the same treatment, reporting the log path through the
ready pipe.

Verified against agents @ a61578853: a missing .env now fails in ~4s with
the full traceback instead of timing out at 60s.

* Revert "feat(agent): load discovered .env files into Node agents via --env-file"

This reverts commit 2430a24.

Per PR review, agent code is expected to load its own env; auto-loading
a discovered .env file second-guesses that. Arbitrary arg forwarding
(e.g. a -- separator) is the preferred ease-of-use mechanism instead.

* feat(agent): forward runtime args after -- to node/python

Per PR review, replace the reverted .env auto-loading with explicit
arg forwarding: everything after a -- separator is passed to the
runtime interpreter ahead of the entrypoint in lk agent
dev/start/console and the session daemon, so
`lk agent console agent.ts -- --env-file=.env` runs
`node --env-file=.env agent.ts console ...`.

urfave/cli strips the -- and folds the trailing args into the
positionals, so splitForwardedArgs recovers the split from os.Args;
detectProject uses it so a forwarded flag with no entrypoint argument
isn't mistaken for one. The detached session daemon receives the args
JSON-encoded via LK_SESSION_FWD.

* test(agent): trim agent run tests to the fail-signal case

Remove the log-level, entrypoint-resolution, arg-splitting, and command-
building unit tests along with the session forwarded-args round-trip test,
keeping TestAgentProcessFailSignal.

* simulate: Node agent support, --view mode, and TUI/start UX fixes

Ports our simulate work onto the Node-support branch:
- Node agent start: normalizeLogLevel, --log-format only for Python,
  main.ts/main.js entrypoints, and refuse entrypoint discovery when
  package.json defines a build task; drop the Python-only guard.
- `lk agent simulate --view <runID>`: open a pre-existing simulation and
  print the reopen command on close.
- TUI: ←/→ arrow navigation in/out of simulation detail, richer
  agent-exit errors (start command + recent output), and quit when the
  agent fails to register.

* fix(agent): resolve Node SDK version via the runtime, gate Node separately

The local-run version gate ran main's file-based CheckSDKVersion for Node
too, which (a) couldn't find @livekit/agents in monorepo/workspace layouts
where the dep is a `workspace:*` symlink rather than a versioned entry, and
(b) gated on the Python thin-CLI baseline (1.6.0), the wrong floor for the
Node SDK.

Resolve the installed @livekit/agents via Node's own module resolution
(embedded node_resolve_version.js), starting from the entrypoint's directory
so pnpm/workspace symlinks and hoisting resolve exactly as they will at
runtime, and gate Node on its own nodeAgentMinVersion. Python keeps the
existing CheckSDKVersion path. Export IsVersionSatisfied for the reused
comparison.

---------

Co-authored-by: Toubat <brian.yin@livekit.io>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

cmd/lk/agent_run.go

@@ -22,6 +22,8 @@ import (
 	"syscall"
 
 	"github.com/urfave/cli/v3"
+
+	"github.com/livekit/livekit-cli/v2/pkg/agentfs"
 )
 
 func init() {
@@ -38,15 +40,15 @@ var agentRunFlags = []cli.Flag{
 var startCommand = &cli.Command{
 	Name:      "start",
 	Usage:     "Run an agent in production mode",
-	ArgsUsage: "[entrypoint]",
+	ArgsUsage: "[entrypoint] [-- node/python-args...]",
 	Flags:     agentRunFlags,
 	Action:    runAgentStart,
 }
 
 var devCommand = &cli.Command{
 	Name:      "dev",
 	Usage:     "Run an agent in development mode with auto-reload",
-	ArgsUsage: "[entrypoint]",
+	ArgsUsage: "[entrypoint] [-- node/python-args...]",
 	Flags: append(agentRunFlags, &cli.BoolFlag{
 		Name:  "no-reload",
 		Usage: "Disable auto-reload on file changes",
@@ -57,6 +59,11 @@ var devCommand = &cli.Command{
 // resolveCredentials returns CLI args (--url, --api-key, --api-secret) for the agent subprocess.
 func resolveCredentials(cmd *cli.Command, loadOpts ...loadOption) ([]string, error) {
 	url := cmd.String("url")
+	if !cmd.IsSet("url") {
+		// Ignore the global flag's default (http://localhost:7880) so the
+		// project config can supply the URL.
+		url = ""
+	}
 	apiKey := cmd.String("api-key")
 	apiSecret := cmd.String("api-secret")
 
@@ -93,10 +100,10 @@ func resolveCredentials(cmd *cli.Command, loadOpts ...loadOption) ([]string, err
 	return args, nil
 }
 
-func buildCLIArgs(subcmd string, cmd *cli.Command, loadOpts ...loadOption) ([]string, error) {
+func buildCLIArgs(projectType agentfs.ProjectType, subcmd string, cmd *cli.Command, loadOpts ...loadOption) ([]string, error) {
 	args := []string{subcmd}
 	if logLevel := cmd.String("log-level"); logLevel != "" {
-		args = append(args, "--log-level", logLevel)
+		args = append(args, "--log-level", normalizeLogLevel(projectType, logLevel))
 	}
 	creds, err := resolveCredentials(cmd, loadOpts...)
 	if err != nil {
@@ -113,7 +120,7 @@ func runAgentStart(ctx context.Context, cmd *cli.Command) error {
 	}
 	out.Statusf("Detected %s agent (%s in %s)", projectType.Lang(), entrypoint, projectDir)
 
-	cliArgs, err := buildCLIArgs("start", cmd)
+	cliArgs, err := buildCLIArgs(projectType, "start", cmd)
 	if err != nil {
 		return err
 	}
@@ -122,6 +129,7 @@ func runAgentStart(ctx context.Context, cmd *cli.Command) error {
 		Dir:           projectDir,
 		Entrypoint:    entrypoint,
 		ProjectType:   projectType,
+		RuntimeArgs:   forwardedArgs(cmd),
 		CLIArgs:       cliArgs,
 		ForwardOutput: os.Stdout,
 	})
@@ -134,7 +142,7 @@ func runAgentStart(ctx context.Context, cmd *cli.Command) error {
 	sigCh := make(chan os.Signal, 1)
 	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
 
-	// Forward every signal to the agent — Python decides
+	// Forward every signal to the agent — the agent decides:
 	// first = graceful shutdown, second = force exit.
 	go func() {
 		for range sigCh {
@@ -154,19 +162,28 @@ func runAgentDev(ctx context.Context, cmd *cli.Command) error {
 		return err
 	}
 
-	cliArgs, err := buildCLIArgs("start", cmd)
+	// Python has no dedicated dev subcommand: dev mode is `start --dev`.
+	// agents-js has a `dev` subcommand that already defaults to debug logs.
+	subcmd := "dev"
+	if projectType.IsPython() {
+		subcmd = "start"
+	}
+	cliArgs, err := buildCLIArgs(projectType, subcmd, cmd)
 	if err != nil {
 		return err
 	}
-	cliArgs = append(cliArgs, "--dev")
-	if cmd.String("log-level") == "" {
-		cliArgs = append(cliArgs, "--log-level", "DEBUG")
+	if projectType.IsPython() {
+		cliArgs = append(cliArgs, "--dev")
+		if cmd.String("log-level") == "" {
+			cliArgs = append(cliArgs, "--log-level", "DEBUG")
+		}
 	}
 
 	cfg := AgentStartConfig{
 		Dir:           projectDir,
 		Entrypoint:    entrypoint,
 		ProjectType:   projectType,
+		RuntimeArgs:   forwardedArgs(cmd),
 		CLIArgs:       cliArgs,
 		ForwardOutput: os.Stdout,
 	}

cmd/lk/agent_run_test.go

@@ -0,0 +1,60 @@
+// Copyright 2026 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/livekit/livekit-cli/v2/pkg/agentfs"
+)
+
+func TestAgentProcessFailSignal(t *testing.T) {
+	if _, err := exec.LookPath("node"); err != nil {
+		t.Skip("node not on PATH")
+	}
+
+	// An agent whose job crashes logs a marker but keeps the process alive;
+	// Failed() must fire without waiting for exit.
+	dir := t.TempDir()
+	script := `console.log('shutting down job task {"reason": "job crashed"}'); setTimeout(() => {}, 30000);`
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "agent.js"), []byte(script), 0o644))
+	// startAgent gates on the SDK version, which Node resolves from node_modules,
+	// so install a satisfying @livekit/agents stub.
+	agentsDir := filepath.Join(dir, "node_modules", "@livekit", "agents")
+	require.NoError(t, os.MkdirAll(agentsDir, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(agentsDir, "package.json"),
+		[]byte(`{"name": "@livekit/agents", "version": "1.6.0"}`), 0o644))
+
+	ap, err := startAgent(AgentStartConfig{
+		Dir:         dir,
+		Entrypoint:  "agent.js",
+		ProjectType: agentfs.ProjectTypeNode,
+		FailSignals: consoleCrashSignals,
+	})
+	require.NoError(t, err)
+	defer ap.Kill()
+
+	select {
+	case <-ap.Failed():
+	case <-time.After(10 * time.Second):
+		t.Fatal("Failed() did not fire on crash marker")
+	}
+}

cmd/lk/agent_utils.go

@@ -18,14 +18,46 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 
 	"github.com/urfave/cli/v3"
 
 	"github.com/livekit/livekit-cli/v2/pkg/agentfs"
 )
 
+// splitForwardedArgs recovers the argument split around a "--" separator.
+// urfave/cli strips the separator and appends everything after it to the
+// parsed positional args, so the forwarded tail is recovered from the raw
+// process argv and trimmed off the positionals.
+func splitForwardedArgs(rawArgs, positional []string) (entryArgs, forwarded []string) {
+	for i, a := range rawArgs {
+		if a != "--" {
+			continue
+		}
+		forwarded = rawArgs[i+1:]
+		if len(forwarded) > len(positional) {
+			// The "--" was consumed as a flag's value, not a separator.
+			return positional, nil
+		}
+		return positional[:len(positional)-len(forwarded)], forwarded
+	}
+	return positional, nil
+}
+
+// forwardedArgs returns the args the user passed after a "--" separator,
+// forwarded to the runtime interpreter (node/python) ahead of the
+// entrypoint, e.g. `lk agent console agent.ts -- --env-file=.env`.
+func forwardedArgs(cmd *cli.Command) []string {
+	_, fwd := splitForwardedArgs(os.Args, cmd.Args().Slice())
+	return fwd
+}
+
 func detectProject(cmd *cli.Command) (string, agentfs.ProjectType, string, error) {
-	explicit := cmd.Args().First()
+	entryArgs, _ := splitForwardedArgs(os.Args, cmd.Args().Slice())
+	var explicit string
+	if len(entryArgs) > 0 {
+		explicit = entryArgs[0]
+	}
 
 	detectFrom := "."
 	if explicit != "" {
@@ -44,11 +76,8 @@ func detectProject(cmd *cli.Command) (string, agentfs.ProjectType, string, error
 		return "", "", "", noAgentError()
 	}
 
-	// TODO(node): support JS/Node agents here. DetectProjectRoot already
-	// recognizes Node projects; once the session daemon can spawn a Node
-	// agent in console mode, drop this gate and branch on projectType.
-	if !projectType.IsPython() {
-		return "", "", "", fmt.Errorf("currently only supports Python agents (detected: %s)", projectType)
+	if !projectType.IsPython() && !projectType.IsNode() {
+		return "", "", "", fmt.Errorf("only Python and Node agents are supported (detected: %s)", projectType)
 	}
 
 	if explicit != "" {
@@ -67,6 +96,16 @@ func detectProject(cmd *cli.Command) (string, agentfs.ProjectType, string, error
 	return projectDir, projectType, entrypoint, nil
 }
 
+// consoleCrashSignals are output markers meaning the console job died even
+// though the worker process may stay alive: the Python SDK keeps the worker
+// running after the job task crashes (logging `"reason": "job crashed"`), and
+// agents-js logs FATAL `console mode failed:` before exiting. Without these,
+// a pre-connect crash leaves the user waiting out the full connect timeout.
+var consoleCrashSignals = []string{
+	`"job crashed"`,
+	"console mode failed:",
+}
+
 // buildConsoleArgs builds the agent subprocess argv for console mode, shared by
 // `lk agent console` and the `lk agent daemon` daemon.
 func buildConsoleArgs(addr string, record bool) []string {
@@ -76,3 +115,12 @@ func buildConsoleArgs(addr string, record bool) []string {
 	}
 	return args
 }
+
+// normalizeLogLevel adapts the log level to the agent runtime's convention:
+// agents-js accepts only lowercase levels, Python expects uppercase.
+func normalizeLogLevel(projectType agentfs.ProjectType, level string) string {
+	if projectType.IsNode() {
+		return strings.ToLower(level)
+	}
+	return strings.ToUpper(level)
+}

cmd/lk/agent_watcher.go

@@ -80,15 +80,19 @@ func newAgentWatcher(config AgentStartConfig) (*agentWatcher, error) {
 		return nil, fmt.Errorf("failed to setup file watcher: %w", err)
 	}
 
-	rs, err := newReloadServer()
-	if err != nil {
-		w.Close()
-		return nil, err
+	// The reload protocol (capture running jobs from the old process, restore
+	// them in the new one) is Python-only; Node reloads are a plain kill+respawn.
+	var rs *reloadServer
+	if config.ProjectType.IsPython() {
+		rs, err = newReloadServer()
+		if err != nil {
+			w.Close()
+			return nil, err
+		}
+		// Append --reload-addr to CLI args so the Python process connects back
+		config.CLIArgs = append(config.CLIArgs, "--reload-addr", rs.addr())
 	}
 
-	// Append --dev and --reload-addr to CLI args so the Python process connects back
-	config.CLIArgs = append(config.CLIArgs, "--dev", "--reload-addr", rs.addr())
-
 	return &agentWatcher{
 		config:    config,
 		exts:      watchExtensions(config.ProjectType),
@@ -107,15 +111,17 @@ func (aw *agentWatcher) start() error {
 	aw.agent = agent
 
 	// Accept connection from new Python process in background
-	go func() {
-		conn, err := aw.reloadSrv.listener.Accept()
-		if err != nil {
-			return
-		}
-		aw.conn = conn
-		// Serve the initial restore request (will be empty on first start)
-		go aw.reloadSrv.serveNewProcess(conn)
-	}()
+	if aw.reloadSrv != nil {
+		go func() {
+			conn, err := aw.reloadSrv.listener.Accept()
+			if err != nil {
+				return
+			}
+			aw.conn = conn
+			// Serve the initial restore request (will be empty on first start)
+			go aw.reloadSrv.serveNewProcess(conn)
+		}()
+	}
 
 	return nil
 }
@@ -143,14 +149,16 @@ func (aw *agentWatcher) restart() error {
 	aw.agent = agent
 
 	// 4. Accept new connection and serve restored jobs
-	go func() {
-		conn, err := aw.reloadSrv.listener.Accept()
-		if err != nil {
-			return
-		}
-		aw.conn = conn
-		go aw.reloadSrv.serveNewProcess(conn)
-	}()
+	if aw.reloadSrv != nil {
+		go func() {
+			conn, err := aw.reloadSrv.listener.Accept()
+			if err != nil {
+				return
+			}
+			aw.conn = conn
+			go aw.reloadSrv.serveNewProcess(conn)
+		}()
+	}
 
 	return nil
 }
@@ -176,7 +184,9 @@ func (aw *agentWatcher) Run(done <-chan struct{}) error {
 		if aw.conn != nil {
 			aw.conn.Close()
 		}
-		aw.reloadSrv.close()
+		if aw.reloadSrv != nil {
+			aw.reloadSrv.close()
+		}
 		aw.watcher.Close()
 	}()
 

cmd/lk/console.go

@@ -41,7 +41,7 @@ func init() {
 var consoleCommand = &cli.Command{
 	Name:      "console",
 	Usage:     "Voice chat with an agent via mic/speakers",
-	ArgsUsage: "[entrypoint]",
+	ArgsUsage: "[entrypoint] [-- node/python-args...]",
 	Category:  "Core",
 	Flags: []cli.Flag{
 		&cli.IntFlag{
@@ -141,7 +141,9 @@ func runConsole(ctx context.Context, cmd *cli.Command) error {
 		Dir:         projectDir,
 		Entrypoint:  entrypoint,
 		ProjectType: projectType,
+		RuntimeArgs: forwardedArgs(cmd),
 		CLIArgs:     buildConsoleArgs(actualAddr, cmd.Bool("record")),
+		FailSignals: consoleCrashSignals,
 	})
 	if err != nil {
 		stopSpinner()
@@ -171,9 +173,17 @@ func runConsole(ctx context.Context, cmd *cli.Command) error {
 			return fmt.Errorf("agent connection: %w", res.err)
 		}
 		conn = res.conn
-	case <-agentProc.Done():
+	case err := <-agentProc.Done():
 		stopSpinner()
+		if err != nil {
+			return fmt.Errorf("the agent exited before connecting: %w\n\n%s", err, agentExitDetail(agentProc))
+		}
 		return fmt.Errorf("the agent exited before connecting.\n\n%s", agentExitDetail(agentProc))
+	case <-agentProc.Failed():
+		stopSpinner()
+		// The crash marker arrives mid-traceback; give trailing output a moment.
+		time.Sleep(500 * time.Millisecond)
+		return fmt.Errorf("the agent job crashed before connecting.\n\n%s", agentExitDetail(agentProc))
 	case <-time.After(60 * time.Second):
 		stopSpinner()
 		return fmt.Errorf("timed out waiting for the agent to connect.\n\n%s", agentExitDetail(agentProc))