feat(cli): add lk agent session for headless text-mode agent runs

[toubatbrian]

Summary

Adds lk agent session start|say|end — a headless, text-mode way to drive a LiveKit agent (Python or JS) straight from the terminal, with no audio/CGO dependency (it lives under the default tag-free build, not the console audio build).

It uses a three-process model that mirrors the existing lk agent console plumbing:

1. Ephemeral CLI command (start/say/end) — short-lived, talks to the daemon and exits.
2. Detached singleton daemon — the lk binary re-exec'd into a hidden daemon mode (gated by an env var, never exposed as a subcommand). It binds a fixed loopback TCP port to enforce a single active session, spawns the agent, and applies text mode.
3. Agent subprocess — the user's agent, connected over the lk.agent.session protobuf protocol.

The CLI↔daemon control protocol reuses pkg/ipc length-prefixed framing on the same TCP port, disambiguated from agent connections by a 4-byte magic preamble. The headless renderer (session_render.go) prints user turns, agent replies, tool calls/outputs, and handoffs.

Command running / IO example

$ lk agent session start examples/voice_agents/basic_agent.py
Detected Python agent (basic_agent.py in .../examples/voice_agents)
Session started. Use `lk agent session say "..."` to talk, `lk agent session end` to stop.

$ lk agent session say "what's the weather in San Francisco?"

  ● You
    what's the weather in San Francisco?

  ● function_tool: lookup_weather
    ✓ sunny with a temperature of 70 degrees.

  ● Agent
    The weather in San Francisco is sunny with a temperature of 70 degrees. Want to know the forecast for any other city?

$ lk agent session say "thanks, that's all"

  ● You
    thanks, that's all

  ● function_tool: end_call
    ✓ say goodbye to the user

  ● Agent
    Goodbye! Have a great day!

$ lk agent session end
Session ended.

Notes

• Singleton enforcement: a second start while a session is live is rejected (a session is already running on 127.0.0.1:<port>).
• No CGO/audio: builds in the default tag-free binary; the audio pipeline stays behind the console tag. This drops the temporary //lint:file-ignore U1000 directives that were added while the shared spawn/detect helpers were unused.
• TODO(node) / TODO(audio) placeholders mark the follow-up surfaces (JS agent detection, audio mode).

Test plan

• go build ./... (default) and CGO_ENABLED=1 go build -tags console ./...
• go vet -tags console ./cmd/lk/, gofmt clean
• End-to-end start → say (tool call) → say (handoff/end_call) → end against basic_agent.py (see IO example above)
• JS agent run (pending TODO(node))

[theomonnom]

uh stamped the wrong PR

[rektdeckard]

Sorry for late question, but now that console feature is compiled by default on all platforms, how different is this from just using console in text mode?

[toubatbrian]

From my understanding, lk agent session gives users/agents a way to send multiple independent commands to a session.

With console, you don’t really get that separation, since it starts an interactive terminal UI. There isn’t a command-line-friendly way to distinguish between starting a session and sending input to that session, which is especially important for AI agents using a bash tool.

cc @theomonnom in case you have more thoughts on the goal/scope of this feature.

[rektdeckard]

@toubatbrian got it, makes sense

[u9g]

Is this supposed to be used in a way where the agent starts the room (if so, what's the command for that? is it just starting the agent via npm start?) and then the agent uses a different terminal to send text messages to the agent via lk agent session?

[toubatbrian]

Is this supposed to be used in a way where the agent starts the room (if so, what's the command for that? is it just starting the agent via npm start?) and then the agent uses a different terminal to send text messages to the agent via lk agent session?

It's reuse the console mode, so lk agent session starts the actual agent in a subprocess and communicate via tcp.