Make a command a thing the app knows, and hold it until it can run

Typing "/" now suggests what this app understands -- `/compact` and
`/rename <name>` -- with a line each about what they do, and anything
else beginning with a slash is passed to whatever runs the session,
because a dialect's own vocabulary grows without this list.

None of them are messages, and that is the substance of the change. A
line written into a running turn is read by the *model*, so a command
sent mid-turn either does nothing or arrives as text somebody has to
puzzle over. They now wait for the turn to end. The waiting is done once
for every provider, in the pump that already watches every event for the
boundary, rather than in each driver where a new provider could get it
wrong by leaving it out.

Waiting is a state, so it is on screen: the command sits at the reader's
end of the conversation in blue, with a spinner and "waiting for this
turn to end", and becomes an ordinary blue row when it goes. Blue
because these are about the session rather than about the task -- the
same blue a compaction already used, which is now one colour with one
name rather than two.

Renaming from the settings screen sends exactly this, so it waits and
draws the same way. The name itself is not held: it is this server's own
datum, so the list and the header change at once and only telling the
session waits.

Echo grew the same split, which is where the bug in it showed: its
commands are its messages, so running one announced a `MessageTaken` as
well, and the same line drew twice -- once blue, once purple. A command
owes no announcement; the manager has already recorded that it was sent.

Watched rather than reasoned about: `/compact` during a 25 second turn
held with its bubble up, went out when the turn ended, and the
compaction that followed reported what it recovered.
This commit is contained in:
iris committed 2026-08-29 17:10:21 -04:00
1 parent bebaae7a94
commit 749b2db287
13 files changed
+678 -93

No files matched your search

+34 -23
View File
@@ -398,6 +398,29 @@ impl ClaudeDriver {
let _ = self.to_child.send(line);
}
/// Writes one of the CLI's own commands into the session.
///
/// Slash commands ride the normal user-message channel -- there is no
/// control request for them; `set_session_name` is not a subtype the
/// CLI knows, measured by asking. The turn they start is marked here
/// because they produce a `result` like any other, so a message sent
/// meanwhile belongs in the queue's "written, announce when read"
/// path rather than being reported as read the moment it is typed.
///
/// Nothing is emitted about the command itself: the manager has
/// already said it was sent, and the CLI announces what it does --
/// saying so here would be this side's guess standing in for its
/// measurement.
fn local_command(&self, text: String) {
self.queue.lock().unwrap().running = true;
self.send_line(
json!({"type": "user", "message": {"role": "user", "content": [
{"type": "text", "text": text}
]}})
.to_string(),
);
}
/// Sends a control request, remembering what it asked for.
///
/// `confirms` is the setting this request will have made if the CLI
@@ -516,6 +539,15 @@ impl Driver for ClaudeDriver {
);
}
fn run_command(&self, text: &str) {
// Whatever the CLI's own vocabulary holds -- `/context`, `/usage`,
// a command added after this was written. It rides the same
// channel as `/compact` and `/rename` and starts a turn the same
// way, so the same bookkeeping applies; what it means is the
// CLI's business, not this file's.
self.local_command(text.to_string());
}
fn set_title(&self, title: &str) {
// The CLI's own mechanism, and a local command rather than a
// control request -- `set_session_name` is not a subtype it
@@ -530,32 +562,11 @@ impl Driver for ClaudeDriver {
});
return;
}
self.queue.lock().unwrap().running = true;
self.send_line(
json!({"type": "user", "message": {"role": "user", "content": [
{"type": "text", "text": format!("/rename {title}")}
]}})
.to_string(),
);
self.local_command(format!("/rename {title}"));
}
fn compact(&self) {
// A turn is in flight from here. The CLI answers `/compact` like
// any other message -- a status line, a boundary, then a `result`
// -- so a message sent meanwhile belongs in the queue's "written,
// announce when it has been read" path rather than being reported
// as read the moment it is typed.
self.queue.lock().unwrap().running = true;
// Slash commands ride the normal user-message channel. Nothing is
// emitted here: the CLI announces the compaction itself, and
// saying so first would be this side's guess standing in for its
// measurement.
self.send_line(
json!({"type": "user", "message": {"role": "user", "content": [
{"type": "text", "text": "/compact"}
]}})
.to_string(),
);
self.local_command("/compact".to_string());
}
fn detach(&self) {
+69
View File
@@ -223,11 +223,68 @@ pub enum Event {
#[serde(default, skip_serializing_if = "Option::is_none")]
trigger: Option<String>,
},
/// A command the session was asked to run on itself, held because it
/// cannot run yet.
///
/// These are not messages: `/compact` and `/rename` are instructions
/// to the session about itself, and a session in the middle of a turn
/// reads a line written to it as something the model should see. So
/// they wait for the turn to end, and this is what a phone draws
/// while they do -- otherwise pressing Compact during a long turn
/// does nothing visible for minutes and looks like it was missed.
CommandQueued {
id: String,
/// What to show for it: the command as a person would type it.
text: String,
},
/// The same command, now handed to the session. Its [`CommandQueued`]
/// stops being pending when this arrives, matched by `id`; a command
/// that ran immediately has only this.
CommandSent {
id: String,
text: String,
},
Error {
message: String,
},
}
/// Something a session can be asked to do to itself.
///
/// A closed set rather than a string, because the two that are not
/// dialect-specific have to reach every provider: compaction is a
/// capability an llama session may one day have, and a name is this
/// server's own. `Raw` is the escape for a dialect's own commands --
/// `/context`, `/usage` -- which only the thing running the session can
/// interpret.
#[derive(Debug, Clone, PartialEq)]
pub enum SessionCommand {
Compact,
SetTitle(String),
Raw(String),
}
impl SessionCommand {
/// What a person would have typed to ask for this, which is what a
/// phone shows while it waits.
pub fn label(&self) -> String {
match self {
Self::Compact => "/compact".to_string(),
Self::SetTitle(title) => format!("/rename {title}"),
Self::Raw(text) => text.clone(),
}
}
/// Runs it. Called only at a boundary -- see [`Event::CommandQueued`].
pub fn apply(&self, driver: &dyn Driver) {
match self {
Self::Compact => driver.compact(),
Self::SetTitle(title) => driver.set_title(title),
Self::Raw(text) => driver.run_command(text),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum SessionStatus {
@@ -300,6 +357,18 @@ pub trait Driver: Send + Sync {
/// `/rename` afterwards, which is what puts the same name in its own
/// session picker and in what other agents see.
fn set_title(&self, title: &str);
/// Runs a command this session's own dialect understands, verbatim.
///
/// For the ones this app has no opinion about -- `/context`, `/usage`,
/// anything a CLI adds next month. A driver whose process has no such
/// vocabulary says so with an [`Event::Error`] rather than sending it
/// as a message, which would put a line meant for the session in front
/// of the model instead.
///
/// Like [`Driver::compact`] and [`Driver::set_title`], this is called
/// only when the session is between turns; the waiting is done above,
/// once, for every driver.
fn run_command(&self, text: &str);
/// pi: native compaction; claude: `/compact`.
fn compact(&self);
/// Stop attending to the process but leave it running, because this
+81 -49
View File
@@ -192,51 +192,14 @@ impl EchoDriver {
});
}
pub fn new(sink: EventSink) -> Self {
let driver = Self {
sink,
pending_questions: Mutex::new(Vec::new()),
busy: Arc::new(AtomicBool::new(false)),
queued: Arc::new(Mutex::new(Vec::new())),
};
driver.emit(Event::Status {
state: SessionStatus::Idle,
});
driver
}
/// Sends are infallible from the driver's point of view: a closed sink
/// means the session is being torn down, and there is nobody left to
/// report to.
fn emit(&self, event: Event) {
let _ = self.sink.send(event);
}
}
/// Ending a turn is also when anything held during it is taken up -- the
/// moment a real CLI would have injected it. One place, because a turn has
/// several ways to end (a reply, an interrupt, a compaction) and every one
/// of them owes the same answer.
fn finish_turn(sink: &EventSink, queued: &Mutex<Vec<String>>, busy: &AtomicBool) {
let held = std::mem::take(&mut *queued.lock().unwrap());
for text in held {
// Announced before it is answered, in that order: a phone showing
// the message as pending needs the signal that it has been read,
// and the answer is meaningless above a message still drawn as
// waiting.
let _ = sink.send(Event::MessageTaken { text: text.clone() });
let _ = sink.send(Event::AssistantText {
delta: format!("\n(taken from the queue) You said: {text}"),
});
}
busy.store(false, Ordering::SeqCst);
let _ = sink.send(Event::Status {
state: SessionStatus::Idle,
});
}
impl Driver for EchoDriver {
fn send_user_message(&self, text: String, _images: Vec<ImageRef>) {
/// One typed line, whether it arrived as a message or as a command.
///
/// `announce` is the difference and it is the whole of it: a message
/// is announced with `MessageTaken`, which is what puts it in the
/// transcript, and a command is not -- the manager has already
/// recorded that one was sent, and saying so twice drew the same
/// line in both colours.
fn handle(&self, text: String, _images: Vec<ImageRef>, announce: bool) {
let sink = self.sink.clone();
// Mid-turn messages are held rather than answered, the way a real
@@ -255,7 +218,9 @@ impl Driver for EchoDriver {
// `MessageTaken` per message, and a command that quietly vanishes
// from the transcript is the one thing echo must not model.
if let Some(rest) = text.strip_prefix("/peer") {
self.emit(Event::MessageTaken { text: text.clone() });
if announce {
self.emit(Event::MessageTaken { text: text.clone() });
}
self.emit(Event::PeerMessage {
from: "dev-updater-f5".to_string(),
text: if rest.trim().is_empty() {
@@ -274,13 +239,17 @@ impl Driver for EchoDriver {
// way. `Driver::compact` is what the manager's own route calls;
// this is the typed path onto it.
if text.trim() == "/compact" {
self.emit(Event::MessageTaken { text });
if announce {
self.emit(Event::MessageTaken { text });
}
self.compact();
return;
}
if text.trim() == "/ask" {
self.emit(Event::MessageTaken { text });
if announce {
self.emit(Event::MessageTaken { text });
}
self.ask_user_question();
return;
}
@@ -352,7 +321,9 @@ impl Driver for EchoDriver {
// anyway: a driver that skips this leaves the phone holding a
// message it thinks is still queued, and the point of an echo
// provider is that it behaves like the real ones.
send(Event::MessageTaken { text: text.clone() });
if announce {
send(Event::MessageTaken { text: text.clone() });
}
send(Event::Status {
state: SessionStatus::Running,
});
@@ -442,6 +413,67 @@ impl Driver for EchoDriver {
});
}
pub fn new(sink: EventSink) -> Self {
let driver = Self {
sink,
pending_questions: Mutex::new(Vec::new()),
busy: Arc::new(AtomicBool::new(false)),
queued: Arc::new(Mutex::new(Vec::new())),
};
driver.emit(Event::Status {
state: SessionStatus::Idle,
});
driver
}
/// Sends are infallible from the driver's point of view: a closed sink
/// means the session is being torn down, and there is nobody left to
/// report to.
fn emit(&self, event: Event) {
let _ = self.sink.send(event);
}
}
/// Ending a turn is also when anything held during it is taken up -- the
/// moment a real CLI would have injected it. One place, because a turn has
/// several ways to end (a reply, an interrupt, a compaction) and every one
/// of them owes the same answer.
fn finish_turn(sink: &EventSink, queued: &Mutex<Vec<String>>, busy: &AtomicBool) {
let held = std::mem::take(&mut *queued.lock().unwrap());
for text in held {
// Announced before it is answered, in that order: a phone showing
// the message as pending needs the signal that it has been read,
// and the answer is meaningless above a message still drawn as
// waiting.
let _ = sink.send(Event::MessageTaken { text: text.clone() });
let _ = sink.send(Event::AssistantText {
delta: format!("\n(taken from the queue) You said: {text}"),
});
}
busy.store(false, Ordering::SeqCst);
let _ = sink.send(Event::Status {
state: SessionStatus::Idle,
});
}
impl Driver for EchoDriver {
fn send_user_message(&self, text: String, images: Vec<ImageRef>) {
// Announced, because this is a message: every driver owes exactly
// one `MessageTaken` per message, and one that quietly vanishes
// from the transcript is the thing echo must not model. A command
// owes none -- the manager has already recorded that it was sent,
// and announcing it again drew the same line twice, once in each
// colour.
self.handle(text, images, true);
}
/// Echo's commands *are* its messages -- `/tool`, `/slow`, `/ask` --
/// so this is the same path with the same parsing, and the fixture
/// behaves like a real session driven the same way.
fn run_command(&self, text: &str) {
self.handle(text.to_string(), Vec::new(), false);
}
fn answer_question(&self, id: &str, answers: &[String]) {
let answer = answers.join(", ");
let (answered, waiting) = {
+8
View File
@@ -401,6 +401,14 @@ impl Driver for LlamaDriver {
});
}
fn run_command(&self, text: &str) {
let _ = self.sink.send(Event::Error {
message: format!(
"a llama.cpp session has no commands of its own, so {text} means nothing to it."
),
});
}
fn compact(&self) {
let _ = self.sink.send(Event::Error {
message: "llama.cpp has no compaction. When the context fills, start a new session."
+202 -9
View File
@@ -18,7 +18,7 @@ pub mod process;
pub mod transcript;
pub mod transport;
use std::collections::HashMap;
use std::collections::{HashMap, VecDeque};
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex, RwLock};
use std::time::{SystemTime, UNIX_EPOCH};
@@ -31,7 +31,7 @@ use crate::config::{
Config, DriverKind, ProviderConfig, SessionConfig, SetupConfig, SshConfig, TokenEntry,
};
use claude::ClaudeDriver;
use driver::{Driver, Event, EventSink, ImageRef, SessionStatus};
use driver::{Driver, Event, EventSink, ImageRef, SessionCommand, SessionStatus};
use echo::EchoDriver;
use llama::LlamaDriver;
use transcript::{SeqEvent, Transcript};
@@ -103,7 +103,11 @@ pub struct SessionInfo {
/// keeps current. Cheap to clone-by-`Arc` into request handlers.
pub struct LiveSession {
meta: SessionConfig,
driver: Box<dyn Driver>,
driver: Arc<dyn Driver>,
/// Commands asked for and not yet run, oldest first, with the pump
/// that will run them. Shared with that pump, which is what notices
/// the boundary.
commands: Arc<Commands>,
/// The same channel the driver reports into; the manager injects
/// `UserMessage`/`Answered` here so they take a sequence number in
/// order with everything else.
@@ -113,6 +117,73 @@ pub struct LiveSession {
shared: Arc<Shared>,
}
/// Commands waiting for the session to be between turns.
///
/// One implementation for every provider, because the rule is about
/// sessions rather than about a dialect: a line written into a running
/// turn is read by the model, so anything meant for the *session* waits
/// for the turn to end. Drivers therefore never have to think about it,
/// and a new provider cannot get it wrong by omission.
struct Commands {
driver: Arc<dyn Driver>,
sink: EventSink,
waiting: Mutex<VecDeque<(String, SessionCommand)>>,
}
impl Commands {
/// Runs `command` now if the session is between turns, and otherwise
/// holds it until it is. Either way the phone is told which happened.
fn submit(&self, command: SessionCommand, status: SessionStatus) {
let id = random_hex();
let text = command.label();
if status == SessionStatus::Idle {
let _ = self.sink.send(Event::CommandSent { id, text });
command.apply(self.driver.as_ref());
return;
}
let _ = self.sink.send(Event::CommandQueued {
id: id.clone(),
text,
});
self.waiting.lock().unwrap().push_back((id, command));
}
/// The turn ended, so the oldest waiting command can go. One, not all
/// of them: running a command starts a turn of its own, and the next
/// boundary is where the one after it belongs.
fn take_one(&self) {
let Some((id, command)) = self.waiting.lock().unwrap().pop_front() else {
return;
};
let _ = self.sink.send(Event::CommandSent {
id,
text: command.label(),
});
command.apply(self.driver.as_ref());
}
/// Gives up on everything held, because the session cannot run them.
///
/// Reported rather than dropped, for the reason the message queue in
/// `claude.rs` reports its own: somebody asked for these and nothing
/// else would ever say they did not happen.
fn abandon(&self, why: &str) {
let lost: Vec<String> = self
.waiting
.lock()
.unwrap()
.drain(..)
.map(|(_, command)| command.label())
.collect();
if lost.is_empty() {
return;
}
let _ = self.sink.send(Event::Error {
message: format!("{why}, so {} never ran", lost.join(" and ")),
});
}
}
/// The pump-maintained view of a session, read by the list endpoint.
/// `model` also lives here (not in the immutable meta) because it can
/// change mid-session via `set_model`.
@@ -171,6 +242,13 @@ impl LiveSession {
self.driver.answer_question(question_id, answers);
}
/// Asks the session to run a command on itself, now or at the next
/// boundary. See [`Commands`] for why it may not be now.
pub fn run_command(&self, command: SessionCommand) {
self.commands
.submit(command, *self.shared.status.lock().unwrap());
}
pub fn interrupt(&self) {
self.driver.interrupt();
}
@@ -182,8 +260,11 @@ impl LiveSession {
self.driver.detach();
}
/// Compacts at the next boundary. Through the command queue like
/// every other instruction to the session, so pressing it during a
/// turn holds rather than writing into that turn.
pub fn compact(&self) {
self.driver.compact();
self.run_command(SessionCommand::Compact);
}
pub fn subscribe(&self) -> broadcast::Receiver<SeqEvent> {
@@ -720,8 +801,12 @@ impl SessionManager {
candidate.save(&self.config_path)?;
inner.config = candidate;
if let Some(session) = inner.live.get(id) {
// The name is this server's and changes now. Telling whatever
// runs the session is a command, and commands wait for the
// turn to end -- so the list shows the new name immediately
// and the CLI is told at the next boundary.
*session.shared.title.lock().unwrap() = title.to_string();
session.driver.set_title(title);
session.run_command(SessionCommand::SetTitle(title.to_string()));
}
Ok(())
}
@@ -999,9 +1084,9 @@ fn launch(
);
}
let driver: Box<dyn Driver> = match provider.kind {
DriverKind::Echo => Box::new(EchoDriver::new(sink.clone())),
DriverKind::LlamaCpp => Box::new(LlamaDriver::launch(
let driver: Arc<dyn Driver> = match provider.kind {
DriverKind::Echo => Arc::new(EchoDriver::new(sink.clone())),
DriverKind::LlamaCpp => Arc::new(LlamaDriver::launch(
&meta,
provider,
&Transport::for_setup(setup),
@@ -1010,7 +1095,7 @@ fn launch(
&dir,
sink.clone(),
)?),
DriverKind::ClaudeCli => Box::new(ClaudeDriver::launch(
DriverKind::ClaudeCli => Arc::new(ClaudeDriver::launch(
&meta,
provider,
&Transport::for_setup(setup),
@@ -1019,16 +1104,24 @@ fn launch(
)?),
};
let commands = Arc::new(Commands {
driver: Arc::clone(&driver),
sink: sink.clone(),
waiting: Mutex::new(VecDeque::new()),
});
tokio::spawn(pump(
transcript,
source,
Arc::clone(&shared),
events.clone(),
Arc::clone(&commands),
));
Ok(Arc::new(LiveSession {
meta,
driver,
commands,
sink,
events,
transcript_path,
@@ -1072,6 +1165,7 @@ async fn pump(
mut source: mpsc::UnboundedReceiver<Event>,
shared: Arc<Shared>,
events: broadcast::Sender<SeqEvent>,
commands: Arc<Commands>,
) {
while let Some(event) = source.recv().await {
let ts = now();
@@ -1116,6 +1210,19 @@ async fn pump(
}
*shared.last_activity.lock().unwrap() = ts;
*shared.written.lock().unwrap() += 1;
// The boundary a held command was waiting for, and the one
// place that sees every driver's. Done after the status is
// recorded, so the command that runs next sees an idle
// session and goes out rather than queueing behind itself.
match &entry.event {
Event::Status {
state: SessionStatus::Idle,
} => commands.take_one(),
Event::Status {
state: SessionStatus::Exited,
} => commands.abandon("this session's process has exited"),
_ => {}
}
// No subscribers is fine; the transcript already has it.
let _ = events.send(entry);
}
@@ -1328,6 +1435,92 @@ mod tests {
assert_eq!(manager.sessions()[0].title, "the one about paging");
}
#[tokio::test]
async fn a_command_waits_for_the_turn_to_end() {
let dir = tempfile::tempdir().expect("tempdir");
seed_echo_only(&dir.path().join("config.ron"));
let manager = SessionManager::new(
dir.path().join("config.ron"),
dir.path().join("sessions"),
dir.path().join("models"),
)
.expect("manager");
let info = manager.spawn_session(echo_spec()).expect("spawn");
let session = manager.session(&info.id).expect("live session");
let mut rx = session.subscribe();
// A turn that will still be going when the command arrives.
session.send_message("/slow 1".to_string(), Vec::new());
collect_until(&mut rx, |event| {
matches!(
event,
Event::Status {
state: SessionStatus::Running
}
)
})
.await;
session.run_command(SessionCommand::Raw("/tool held".to_string()));
let seen = collect_until(&mut rx, |event| {
matches!(event, Event::CommandQueued { .. })
})
.await;
let Some(Event::CommandQueued { id, text }) =
seen.iter().map(|entry| entry.event.clone()).next_back()
else {
panic!("expected the command to be held: {seen:?}");
};
assert_eq!(text, "/tool held");
// Held, not run: nothing of the command has reached the session.
assert!(
!seen
.iter()
.any(|entry| matches!(entry.event, Event::ToolStart { .. })),
"a held command must not have run yet"
);
// The turn ends, and it goes.
let seen = collect_until(&mut rx, |event| matches!(event, Event::ToolStart { .. })).await;
assert!(
seen.iter().any(|entry| matches!(
&entry.event,
Event::CommandSent { id: sent, .. } if *sent == id
)),
"the same command has to be reported as sent: {seen:?}"
);
}
#[tokio::test]
async fn a_command_on_an_idle_session_goes_straight_out() {
let dir = tempfile::tempdir().expect("tempdir");
seed_echo_only(&dir.path().join("config.ron"));
let manager = SessionManager::new(
dir.path().join("config.ron"),
dir.path().join("sessions"),
dir.path().join("models"),
)
.expect("manager");
let info = manager.spawn_session(echo_spec()).expect("spawn");
let session = manager.session(&info.id).expect("live session");
let mut rx = session.subscribe();
session.run_command(SessionCommand::Raw("/tool now".to_string()));
let seen = collect_until(&mut rx, |event| matches!(event, Event::ToolStart { .. })).await;
// Sent, and never queued: a session between turns has nothing to
// wait for, and a phone should not draw a bubble that resolves in
// the same frame.
assert!(
seen.iter()
.any(|entry| matches!(entry.event, Event::CommandSent { .. }))
);
assert!(
!seen
.iter()
.any(|entry| matches!(entry.event, Event::CommandQueued { .. }))
);
}
#[tokio::test]
async fn questions_round_trip_through_answer() {
let dir = tempfile::tempdir().expect("tempdir");