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

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)