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.

Author: u9g

cmd/lk/agent_run.go

@@ -26,6 +26,8 @@ import (
 	"syscall"
 
 	"github.com/urfave/cli/v3"
+
+	"github.com/livekit/livekit-cli/v2/pkg/agentfs"
 )
 
 func init() {
@@ -51,15 +53,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",
@@ -70,6 +72,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")
 
@@ -106,10 +113,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 {
@@ -126,7 +133,7 @@ func runAgentStart(ctx context.Context, cmd *cli.Command) error {
 	}
 	fmt.Fprintf(os.Stderr, "Detected %s agent (%s in %s)\n", projectType.Lang(), entrypoint, projectDir)
 
-	cliArgs, err := buildCLIArgs("start", cmd, quietOutput)
+	cliArgs, err := buildCLIArgs(projectType, "start", cmd, quietOutput)
 	if err != nil {
 		return err
 	}
@@ -135,6 +142,7 @@ func runAgentStart(ctx context.Context, cmd *cli.Command) error {
 		Dir:           projectDir,
 		Entrypoint:    entrypoint,
 		ProjectType:   projectType,
+		RuntimeArgs:   forwardedArgs(cmd),
 		CLIArgs:       cliArgs,
 		ForwardOutput: os.Stdout,
 	})
@@ -147,7 +155,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 {
@@ -167,19 +175,28 @@ func runAgentDev(ctx context.Context, cmd *cli.Command) error {
 		return err
 	}
 
-	cliArgs, err := buildCLIArgs("start", cmd, outputToStderr)
+	// 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, outputToStderr)
 	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,54 @@
+// 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))
+
+	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 != "" {
@@ -64,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 session` daemon.
 func buildConsoleArgs(addr string, record bool) []string {
@@ -73,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

@@ -82,15 +82,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),
@@ -109,15 +113,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
 }
@@ -145,14 +151,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
 }
@@ -178,7 +186,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

@@ -43,7 +43,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{
@@ -143,7 +143,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()
@@ -183,6 +185,15 @@ func runConsole(ctx context.Context, cmd *cli.Command) error {
 			return fmt.Errorf("agent exited before connecting: %w", err)
 		}
 		return fmt.Errorf("agent exited before connecting")
+	case <-agentProc.Failed():
+		stopSpinner()
+		// The crash marker arrives mid-traceback; give trailing output a moment.
+		time.Sleep(500 * time.Millisecond)
+		logs := agentProc.RecentLogs(40)
+		for _, l := range logs {
+			fmt.Fprintln(os.Stderr, l)
+		}
+		return fmt.Errorf("agent job crashed before connecting")
 	case <-time.After(60 * time.Second):
 		stopSpinner()
 		logs := agentProc.RecentLogs(20)

cmd/lk/proc_unix.go

@@ -32,7 +32,7 @@ func (ap *AgentProcess) sendKill() {
 }
 
 // sendShutdown sends SIGINT to the main process only (not the group),
-// letting Python manage its own child cleanup.
+// letting the agent manage its own child cleanup.
 func (ap *AgentProcess) sendShutdown() {
 	if ap.cmd.Process != nil {
 		ap.cmd.Process.Signal(syscall.SIGINT)