Files
luxe/crates/luxe-cli/src/cli/rpc.rs
Evan Whittaker d2129a886f Luxe 0.1.3: your sessions on your phone, joinable sessions, and nested AGENTS.md
- luxe remote puts the sessions on your computer in reach of your own phone or tablet over
  Tailscale: write, steer, answer prompts, send photos, browse files, diffs and GitHub, with a
  paired device and your own Tailscale login.
- luxe join lets another program on the same machine join a running session over the RPC protocol.
- An AGENTS.md in a subfolder reaches the model the first time it works there.
- Long sessions stay fast: no stall before each model call, lighter memory, cheaper drawing.
- A session is open in one Luxe at a time, web_search shares results across its phrasings, and a
  grep glob starting with ! excludes.

The CHANGELOG has the full list.
2026-10-20 02:40:13 -05:00

327 lines
12 KiB
Rust

//! RPC front-end mode — the engine's `Action`/`Event` protocol over stdio.
//!
//! One JSON object per line each way: wire actions in on stdin, events out on stdout. A client is
//! a *front-end*, with the authority of the person who launched it — it answers permission prompts
//! rather than having them auto-allowed, and the permission engine stays upstream of everything it
//! can ask for. `docs/guide/rpc.md` is the reference.
//!
//! stdout carries the protocol and nothing else. Diagnostics already go to a file rather than the
//! terminal (the TUI owns the screen), so that holds without any special care here — and
//! `rpc_stdout_carries_only_protocol_frames` keeps it holding.
mod frame;
mod translate;
use frame::write_frame;
pub(super) use frame::{Opening, SharedTranscript};
use luxe_core::engine::Action;
use luxe_core::event::Action as WireAction;
use luxe_core::Event;
use tokio::io::{AsyncBufReadExt, AsyncRead, AsyncWrite, BufReader};
use tokio::sync::mpsc;
use translate::{to_engine_action, Rejected};
pub(super) use translate::{CatalogResolver, GithubWrites, ModelResolver, Policy};
/// Depth of the channel carrying locally-generated frames (rejections) to the single writer.
///
/// Small on purpose: it holds refusals, and a client producing enough bad lines to fill it is
/// already being told so.
const LOCAL_FRAME_BUFFER: usize = 32;
/// The catalog a session's clients resolve and list models through, shared by every one of them.
pub(super) type Models = std::sync::Arc<dyn ModelResolver + Send + Sync>;
/// Run the RPC front-end against stdio until the client closes the stream or stdin ends.
///
/// Args: `(settings, github_writes)` — the second is `--github-writes`, which lets the client
/// publish to GitHub unless the session is read-only.
pub(crate) async fn run_rpc(
settings: crate::engine_setup::AgentSettings,
github_writes: bool,
) -> anyhow::Result<()> {
// Before anything is started: a child that shared the protocol's pipe could read frames, and
// on Windows would stall behind the read waiting on the client
let input = luxe_core::program::take_stdin()
.map_err(|error| anyhow::anyhow!("could not take stdin for the protocol: {error}"))?;
let mode = crate::engine_setup::effective_permission_mode(
&settings.state_root,
settings.permission_mode,
settings.trust_project,
);
let policy = Policy {
github_writes: GithubWrites::for_launch(github_writes, mode),
github_sections: luxe_core::config::Config::load(&settings.state_root).github.sections(),
joined: false,
};
let handle = crate::engine_setup::build_engine(
&settings,
luxe_core::HookRegistry::new(),
// A client can answer, unlike headless. Auto-allowing on its behalf would make the
// permission prompt invisible to the one front-end able to show it.
luxe_core::permission::AskResolution::Prompt,
)
.await?;
// Same bridge the TUI runs on, so an RPC client gets workspace snapshots and tool-activity
// cards rather than a thinner stream than the built-in front-end sees.
let events = crate::workspace_runtime::bridge(
handle.events,
crate::workspace_runtime::Roots {
state: settings.state_root.clone(),
work: settings.work_root.clone(),
},
crate::workspace_runtime::pull_request_watch(&settings.work_root),
);
// Shared like a terminal's, which is how a phone reaches a session the bridge started
let (events, _sharing) =
super::share::share(events, handle.actions.clone(), &settings, &handle.session_id.0);
let ready = Event::Ready {
protocol_version: luxe_core::PROTOCOL_VERSION,
luxe_version: env!("CARGO_PKG_VERSION").to_string(),
session_id: handle.session_id.0.clone(),
cwd: settings.work_root.to_string_lossy().into_owned(),
github_writes: policy.github_writes.allowed(),
};
if let Some(level) = settings.initial_thinking {
handle.actions.send(Action::SetThinkingLevel(level)).await.ok();
}
// Walk-away mode from launch, for a client driving a session nobody is watching. The same
// state `set_permission_auto_approve` reaches, so a client can turn it back off.
if settings.auto_approve {
handle.actions.send(Action::SetPermissionAutoApprove(true)).await.ok();
}
serve(
ready.into(),
events,
handle.actions,
tokio::fs::File::from_std(input),
tokio::io::stdout(),
std::sync::Arc::new(CatalogResolver { settings: settings.clone() }),
policy,
)
.await?;
super::tui::shutdown_workspace_services().await;
Ok(())
}
/// Drive one RPC session over an arbitrary duplex.
///
/// Generic over the streams so the protocol — handshake, framing, translation, refusal, shutdown —
/// is exercised end to end in tests without a real stdin, a real terminal, or a live provider.
/// `run_rpc` is this function with stdio and the real catalog plugged in.
///
/// A client that joined a terminal's session (`policy.joined`) never closes the engine: its
/// hangup or `close` ends its own connection, and the terminal carries on.
pub(super) async fn serve<R, W>(
opening: Opening,
mut events: mpsc::Receiver<Event>,
engine_tx: mpsc::Sender<Action>,
input: R,
mut output: W,
models: Models,
policy: Policy,
) -> anyhow::Result<()>
where
R: AsyncRead + Unpin + Send + 'static,
W: AsyncWrite + Unpin,
{
let joined = policy.joined;
if !emit_opening(&mut output, opening).await? {
close_unless_joined(&engine_tx, joined).await;
return Ok(());
}
let (local_tx, mut local_rx) = mpsc::channel::<Event>(LOCAL_FRAME_BUFFER);
let reader = tokio::spawn(read_actions(input, engine_tx.clone(), local_tx, models, policy));
// One writer, so a refusal can never interleave with an event mid-line.
//
// The engine's stream ending is what ends the session; the refusal channel merely runs dry
// when the reader stops, and must not take the session with it — the engine is usually still
// finishing a turn at that point.
//
// Refusals keep their order among themselves, and events keep theirs. The two are *not*
// ordered against each other: `select!` takes whichever is ready. Nothing needs them to be — a
// refusal is about the client's own input, not about engine state — and pretending otherwise
// would mean holding one stream up for the other.
//
// A joined client's reader ending *is* the end of its session, since the engine outlives it.
let mut refusals_open = true;
loop {
let frame = tokio::select! {
event = events.recv() => match event {
Some(event) => event,
None => break,
},
refusal = local_rx.recv(), if refusals_open => match refusal {
Some(refusal) => refusal,
None if joined => break,
None => {
refusals_open = false;
continue;
}
},
};
if !emit(&mut output, &frame).await? {
break;
}
}
// The engine's stream has ended, but the reader may have queued refusals the client has not
// been told about. Dropping them would leave someone debugging a frame that vanished without
// a word, so close the channel to stop new ones and write out what is already there.
local_rx.close();
while let Some(refusal) = local_rx.recv().await {
if !emit(&mut output, &refusal).await? {
break;
}
}
reader.abort();
// The engine may already be gone (the client sent `close`); saying so twice is harmless.
close_unless_joined(&engine_tx, joined).await;
Ok(())
}
/// Close the engine as a client leaves, unless the client only joined it.
async fn close_unless_joined(engine_tx: &mpsc::Sender<Action>, joined: bool) {
if !joined {
engine_tx.send(Action::Close).await.ok();
}
}
/// Read wire actions until EOF, forwarding what translates and refusing what does not.
///
/// EOF means the client is gone, so the engine is told to close rather than left running behind a
/// stream nobody is reading. A joined client's EOF or `close` only ends the read.
async fn read_actions<R>(
input: R,
engine_tx: mpsc::Sender<Action>,
local_tx: mpsc::Sender<Event>,
models: Models,
policy: Policy,
) where
R: AsyncRead + Unpin,
{
let mut lines = BufReader::new(input).lines();
loop {
let line = match lines.next_line().await {
Ok(Some(line)) => line,
Ok(None) => break,
Err(error) => {
tracing::warn!(%error, "rpc: input read failed");
break;
}
};
if line.trim().is_empty() {
continue;
}
let reply = match parse_action(&line, &*models, &policy) {
Ok(Inbound::Engine(action)) => Ok(*action),
Ok(Inbound::Answer(answer)) => Err(answer),
Err(rejected) => {
Err(Event::ActionRejected { kind: rejected.kind, reason: rejected.reason })
}
};
let action = match reply {
Ok(action) => action,
Err(reply) => {
if local_tx.send(reply).await.is_err() {
break;
}
continue;
}
};
let closing = matches!(action, Action::Close);
if closing && policy.joined {
break;
}
if engine_tx.send(action).await.is_err() {
break;
}
if closing {
break;
}
}
close_unless_joined(&engine_tx, policy.joined).await;
}
/// Parse and translate one inbound line.
///
/// Split out from the read loop so the whole inbound contract — framing, vocabulary, translation —
/// is testable without any IO at all.
fn parse_action(
line: &str,
models: &(dyn ModelResolver + Send + Sync),
policy: &Policy,
) -> Result<Inbound, Rejected> {
// Read the envelope before the payload, so a frame that names itself and then fails to
// deserialize is still refused *by name*. Reporting `kind: null` for a `steer_turn` missing its
// text sends the client looking through every frame it wrote instead of the one that was wrong.
let raw: serde_json::Value = serde_json::from_str(line)
.map_err(|error| Rejected { kind: None, reason: error.to_string() })?;
let kind = raw.get("kind").and_then(serde_json::Value::as_str).map(str::to_string);
let wire: WireAction = serde_json::from_value(raw)
.map_err(|error| Rejected { kind, reason: error.to_string() })?;
if let WireAction::ListModels { request_id } = wire {
return Ok(Inbound::Answer(Event::ModelsListed { request_id, models: models.choices() }));
}
to_engine_action(wire, models, policy).map(|action| Inbound::Engine(Box::new(action)))
}
/// What one inbound line comes to.
#[derive(Debug)]
enum Inbound {
/// An action for the engine
Engine(Box<Action>),
/// An answer for this client alone, which the engine has no part in
Answer(Event),
}
/// Write one frame, reporting `false` once the client has stopped reading.
///
/// A hangup is how a session ends when the other end is `head` or a closed editor pane, so it
/// resolves to a clean exit rather than an error written to a pipe nobody is holding.
/// Send `ready` and any transcript, saying whether the client is still there.
///
/// Takes the opening by value so the transcript is let go once sent: held for the connection, it
/// would pin a superseded copy of every message, and each commit would copy the snapshot's whole
/// list to append to it.
async fn emit_opening<W: AsyncWrite + Unpin>(
out: &mut W,
opening: Opening,
) -> anyhow::Result<bool> {
if !emit(out, &opening.ready).await? {
return Ok(false);
}
match opening.transcript {
Some(transcript) => emit(out, &transcript).await,
None => Ok(true),
}
}
async fn emit<W, F>(out: &mut W, frame: &F) -> anyhow::Result<bool>
where
W: AsyncWrite + Unpin,
F: serde::Serialize + ?Sized,
{
match write_frame(out, frame).await {
Ok(()) => Ok(true),
Err(error)
if matches!(
error.kind(),
std::io::ErrorKind::BrokenPipe | std::io::ErrorKind::ConnectionReset
) =>
{
tracing::info!("rpc: client closed the stream");
Ok(false)
}
Err(error) => Err(error.into()),
}
}
#[cfg(test)]
mod tests;