iris/ai-app
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Prune commentary and stale Rust port notes

Browse Source
This commit is contained in:
iris committed 2026-09-10 00:44:13 -04:00
1 parent 5428cd75c9
commit 25370731d0
193 files changed
+693 -16219
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

server/src/session/claude.rs
-361
View File
@@ -1,51 +1,3 @@
//! The Claude Code driver: `claude -p` speaking stream-json on stdio,
//! translated into the common event model.
//!
//! This half owns the process -- starting it, *adopting one this server
//! left running*, writing lines to it, and ending it. Where it runs is
//! `session::transport`'s business, not this file's: this one emits a
//! `Launch` and never learns whether it became a local child or an ssh
//! invocation.
//!
//! The process is meant to outlive the server, so that restarting the
//! backend does not end a turn: its stdio lives in the session directory
//! (a fifo it holds open itself, plus logs read from a byte offset) and
//! `session::process` records what it is. Everything comes through
//! [`ClaudeDriver::launch`], which adopts if it can and starts if it
//! cannot -- `--resume` is reachable only on the second path, because two
//! CLIs on one session file duplicate the conversation into it.
//! Turning a line into [`Event`]s is [`translate`], which changes when the
//! CLI's wire format does rather than when any of the above does.
//!
//! The probing record below stays here, since it is the provenance for
//! both halves: the flags are this file's, the message catalogue is what
//! `translate` implements.
//!
//! Wire format pinned against CLI 2.1.237 by probing (2026-08-24; scripts
//! summarized here since they live outside the repo):
//!
//! - Outbound: `system/init` (carries `session_id`, the `--resume` token),
//! `stream_event` (raw API deltas; `text_delta` is the streaming text),
//! consolidated `assistant` messages (their `tool_use` blocks have the
//! complete input), `user` messages with `tool_result` blocks, a `result`
//! per turn (usage + cost), `control_request` for anything needing a
//! human, `control_response` answering ours.
//! - Permission prompts require the hidden `--permission-prompt-tool stdio`
//! flag; they arrive as `control_request{subtype:can_use_tool}` and are
//! answered with `{behavior:"allow",updatedInput}` or
//! `{behavior:"deny",message}`. `AskUserQuestion` uses the same shape,
//! with the chosen labels added to `updatedInput` as
//! `answers:{<question text>:<label>}`.
//! - Inbound `user` messages sent mid-turn are queued and injected at the
//! next tool boundary (verified live: the model acknowledged a steer
//! between two Bash calls) -- the behavior this app exists for.
//! - `control_request{subtype:set_model}` answers success;
//! `{subtype:interrupt}` stops the turn.
//! - `control_request{subtype:set_permission_mode}` answers success and
//! echoes the mode back (`{"response":{"mode":"acceptEdits"}}`), so the
//! mode is changeable mid-session rather than only at spawn. Probed the
//! same way as the rest, against 2.1.237 on 2026-08-29.
use std::collections::VecDeque;
use std::os::unix::fs::OpenOptionsExt;
use std::path::{Path, PathBuf};
@@ -69,9 +21,6 @@ use translate::{AnswerOutcome, Setting, Translator, starts_a_model_call};
/// because this is held per session for the life of the process.
const STDERR_LINES_KEPT: usize = 50;
/// The kept stderr as one block, with blank lines trimmed off both ends. The
/// trailing trim is the point: a shell's error ends with a blank line, so
/// anything reporting "the last line" reports nothing at all.
fn tail_of(kept: &VecDeque<String>) -> String {
let lines: Vec<&str> = kept.iter().map(String::as_str).collect();
let start = lines
@@ -86,41 +35,14 @@ fn tail_of(kept: &VecDeque<String>) -> String {
lines[start..end].join("\n")
}
/// Where the driver remembers its CLI session id between backend runs -- the
/// whole crash-recovery story, since respawning with `--resume <id>` picks the
/// conversation back up. Kept in the session directory rather than config.ron
/// so the shared schema stays free of per-driver state.
pub(super) mod translate;
const RESUME_FILE: &str = "claude-session.json";
/// Messages handed to the CLI that it has not visibly acted on yet.
///
/// The CLI *does* take a message written mid-turn: it goes into the next model
/// call, which is the next tool boundary, and steering a running turn is the
/// point of this app. An earlier version held every mid-turn message until the
/// turn ended, so a steer sent after the second tool call sat unread until all
/// the work it was meant to redirect had finished.
///
/// What the CLI does not do is say on stdout that it has read one. So the line
/// goes out immediately and the *announcement* waits here, until the CLI opens
/// the next model call -- see [`translate::starts_a_model_call`].
///
/// The proof has to be the model call and not the output. Assistant text and a
/// tool call both keep arriving from a message that was *already in flight*
/// when the steer was written, and that message saw none of it: a steer sent
/// while an answer was streaming was recorded in the middle of it, above tool
/// calls the model had already committed to.
#[derive(Default)]
struct Queue {
/// A turn is in flight, so a message sent now is a steer into it.
running: bool,
/// Written, not yet announced, oldest first, each with the id of the
/// `MessageQueued` that told the phone it was waiting -- so the
/// announcement can name which bubble it resolves.
awaiting: VecDeque<(String, String, Vec<AttachmentRef>)>,
/// The process is gone, so nothing can be taken up any more.
///
/// Needed because every other way out of a turn is an `Idle` this driver
/// sees, and an exit is the one that is not. Without it a process that
/// died mid-turn left `running` true for good, and since a message is only
@@ -177,37 +99,18 @@ const STDIN_FIFO: &str = "stdin.fifo";
const STDOUT_LOG: &str = "stdout.log";
const STDERR_LOG: &str = "stderr.log";
/// How often a reader with nothing to read looks again. A poll rather than a
/// watch: the alternative is an inotify dependency for one file per session,
/// and at this interval the streaming text already arrives faster than a phone
/// renders it.
const POLL: std::time::Duration = std::time::Duration::from_millis(50);
pub struct ClaudeDriver {
sink: EventSink,
queue: Arc<Mutex<Queue>>,
/// Lines for the process's stdin. Not closeable, unlike the pipe this used
/// to be: stdin is a fifo the process holds open itself, so closing this
/// end says nothing to it. Ending the process is [`Driver::stop`]'s job.
to_child: mpsc::UnboundedSender<String>,
state: Arc<Mutex<Translator>>,
session_dir: PathBuf,
/// Cleared to stop the reader without touching the process -- which is
/// exactly what detaching is.
reading: Arc<AtomicBool>,
}
impl ClaudeDriver {
/// Takes charge of this session's process: the one already running if
/// there is one, otherwise a new one.
///
/// One entry point rather than two, because the choice is not the caller's
/// and getting it wrong is the expensive bug. A second `--resume` against
/// a session file that is already open duplicates the whole conversation
/// into it and bills the reattached copy for re-reading it -- measured at
/// 65 MB and 154 screenshots on 2026-08-29. So `--resume` is reachable
/// only through the spawn half below, under a check that nothing is
/// running.
pub fn launch(
meta: &SessionConfig,
provider: &ProviderConfig,
@@ -223,13 +126,6 @@ impl ClaudeDriver {
let queue = Arc::new(Mutex::new(Queue::default()));
let reading = Arc::new(AtomicBool::new(true));
// Adopting is only possible for a process this server left behind on
// this machine: an ssh session's child died with the connection.
// Nothing was ever recorded for one, so this answers "no" without
// needing to know that.
//
// `started_here` is whether this launch *started* a process or picked
// one up; the two owe the session different things.
let started_here;
let record = match process::recorded(session_dir) {
// Still running, and ours. Pick it up where it was left -- the one
@@ -244,9 +140,6 @@ impl ClaudeDriver {
started_here = false;
record
}
// Recorded, and the machine will not say whether it is still
// there. Starting one anyway is the mistake this module is for, so
// nothing is started; `follow` keeps asking.
Some((record, process::Liveness::Unknown)) => {
tracing::warn!(
"session {} recorded pid {} but this machine won't say whether it is running; \
@@ -280,19 +173,11 @@ impl ClaudeDriver {
state: SessionStatus::Idle,
});
}
// Where reading of its output had reached. A process just started has
// said nothing, so its record says zero.
let resuming_from = match record.detail {
process::Detail::Stdio { stdout_read } => stdout_read,
// A record of the wrong shape belongs to a different driver; read
// its output from the start rather than trusting an offset into a
// file that means something else.
_ => 0,
};
// The writer end of the fifo. Opened write-only here: the process holds
// its own read-write handle, so this side coming and going across a
// restart is invisible to it.
let stdin = std::fs::OpenOptions::new()
.write(true)
.open(session_dir.join(STDIN_FIFO))
@@ -331,9 +216,6 @@ impl ClaudeDriver {
})
}
/// Starts a new CLI for this session, with its streams in the session
/// directory so the next run of this server can find them. The only path
/// that passes `--resume`, and it is reached only when nothing is running.
fn start(
meta: &SessionConfig,
provider: &ProviderConfig,
@@ -347,8 +229,6 @@ impl ClaudeDriver {
};
push("--input-format", "stream-json");
push("--output-format", "stream-json");
// Hidden but load-bearing: without it the CLI resolves permissions
// itself and nothing ever reaches the phone.
push("--permission-prompt-tool", "stdio");
if let Some(model) = &meta.model {
push("--model", model);
@@ -356,39 +236,14 @@ impl ClaudeDriver {
if let Some(mode) = &meta.permission_mode {
push("--permission-mode", mode);
}
// Launch-only: see `SessionConfig::effort`. Omitted entirely when
// unset, so the CLI's own default is what an unchosen session gets
// rather than a level this app decided to call the default.
if let Some(effort) = &meta.effort {
push("--effort", effort);
}
// Named at birth, so this session is the same session in the CLI's own
// picker and in what other agents see.
//
// Only when we are creating it. A resume is a session that already
// existed -- an import, or this server starting again -- and it already
// has whatever name it was given, quite possibly by the person typing
// in it. `Driver::set_title` is how it changes after this point, and
// that one is asked for.
match read_resume_token(session_dir) {
Some(resume) => push("--resume", &resume),
None => push("--name", &meta.title),
}
args.push("--include-partial-messages".to_string());
// Makes `bypassPermissions` *reachable* without selecting it: the
// session still starts in whatever mode was asked for above.
//
// The CLI is asymmetric about that mode. It will *launch* in
// `bypassPermissions` on `--permission-mode` alone, but refuses to
// *switch* into it later ("the session was not launched with
// --dangerously-skip-permissions"), so the phone's mode picker offered
// a mode that could not be picked on every session not given it at
// birth. Since the mode is already reachable at spawn, this grants
// nothing that was being withheld.
//
// Measured against 2.1.237 both ways round. Note it is the `--allow-`
// form; `--dangerously-skip-permissions` turns it on for everything,
// which would take the choice away from whoever holds the phone.
args.push("--allow-dangerously-skip-permissions".to_string());
// Fresh logs, because the offsets that index them start at zero and
@@ -435,21 +290,12 @@ 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, 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.
///
/// Nothing is emitted about the command itself: the manager has already
/// said it was sent, and the CLI announces what it does.
fn local_command(&self, text: String) {
let mut queue = self.queue.lock().unwrap();
// The same check `send_user_message` makes: a line written into a fifo
// nothing is reading goes nowhere and looks exactly like one that
// arrived. What this catches is the process going away between
// `Commands::submit`'s check and this write.
if queue.closed {
drop(queue);
let _ = self.sink.send(Event::Error {
@@ -474,19 +320,9 @@ impl ClaudeDriver {
);
}
/// Sends a control request, remembering what it asked for.
///
/// `confirms` is the setting this request will have made if the CLI answers
/// success -- see [`Translator::expect_setting`]. `None` for the ones that
/// change no setting, like an interrupt.
///
/// The id is random rather than the clock it used to be: two requests in
/// the same second shared an id.
fn send_control(&self, request: Value, confirms: Option<Setting>) {
let id = format!("req-{}", super::random_hex());
if let Some(setting) = confirms {
// Before the line goes out: the reader thread is already running,
// and a fast answer to a slow lock arrives first.
self.state
.lock()
.unwrap()
@@ -531,9 +367,6 @@ impl Driver for ClaudeDriver {
let line =
json!({"type": "user", "message": {"role": "user", "content": content}}).to_string();
let mut queue = self.queue.lock().unwrap();
// Saying so beats writing into a fifo that nothing is reading, which is
// what this used to do -- the message went nowhere and looked exactly
// like one that had been delivered.
if queue.closed {
drop(queue);
let _ = self.sink.send(Event::Error {
@@ -543,13 +376,6 @@ impl Driver for ClaudeDriver {
return;
}
if queue.running {
// Into the running turn, now. Announced when the CLI shows it has
// been round the model again -- see `Queue`.
//
// The *waiting* is recorded here, which is the one thing that must
// not be left to the phone to remember: it drew the bubble from its
// own state, so leaving the session showed nothing pending while a
// message was still queued.
let id = super::random_hex();
queue
.awaiting
@@ -604,7 +430,6 @@ impl Driver for ClaudeDriver {
});
self.send_line(control_response.to_string());
}
// A multi-question AskUserQuestion still waiting on the rest.
AnswerOutcome::Pending => {}
AnswerOutcome::Unknown => {
let _ = self.sink.send(Event::Error {
@@ -618,8 +443,6 @@ impl Driver for ClaudeDriver {
/// deliberately, and dropping it would lose a message that never reached
/// the transcript.
fn interrupt(&self) {
// Recorded before the request goes out, so the result it produces reads
// as the stop somebody asked for rather than as a failure.
self.state.lock().unwrap().expect_interrupt();
self.send_control(json!({"subtype": "interrupt"}), None);
}
@@ -639,18 +462,10 @@ impl Driver for ClaudeDriver {
}
fn run_command(&self, text: &str) {
// Whatever the CLI's own vocabulary holds. It rides the same channel as
// `/compact` and starts a turn the same way, so the same bookkeeping
// applies; what it means is the CLI's business.
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 knows, measured by
// asking. It answers this the way it answers `/compact`. A name with a
// newline would be two lines and the second would be a message, so it
// is refused rather than sent.
if title.contains('\n') {
let _ = self.sink.send(Event::Error {
message: "a session name cannot contain a line break".to_string(),
@@ -665,11 +480,6 @@ impl Driver for ClaudeDriver {
}
fn clear(&self) {
// Nothing is emitted here on purpose: the transcript should record a
// clear that happened, not one that was asked for. The CLI announces it
// with `conversation_reset`, which `translate.rs` turns into
// `Event::Cleared`, and follows it with a fresh `init` whose new
// `session_id` the reader persists as the resume token.
self.local_command("/clear".to_string());
}
@@ -679,9 +489,6 @@ impl Driver for ClaudeDriver {
}
fn detach(&self) {
// Stop reading and leave everything else exactly as it is. The process
// keeps its fifo, keeps writing its log, and keeps its record -- which
// is how the next run of this server finds it.
self.reading.store(false, Ordering::SeqCst);
}
@@ -694,14 +501,6 @@ impl Driver for ClaudeDriver {
}
}
/// Follows the process's stdout log, turning it into events, and is also what
/// decides whether the session is still running.
///
/// One loop rather than a reader plus a monitor. After a restart there is no
/// `Child` to wait on -- the process was reparented away -- so liveness has to
/// be a question asked of the record either way, and asking it in two places is
/// how the two answers come to disagree.
///
/// Reading is resumable because the position is written down with the process:
/// everything before it is already in the transcript, so a server coming back
/// picks up exactly where the last one stopped.
@@ -718,9 +517,6 @@ async fn follow(
) {
let stdout_path = session_dir.join(STDOUT_LOG);
let stderr_path = session_dir.join(STDERR_LOG);
// Whatever is already in the stderr log was logged by whichever run of this
// server was watching, so a reattach starts at the end of it. The tail is
// still read from the file if the process dies, which is when it matters.
let mut stderr_at = process::size_of(&stderr_path);
let mut said_unknown = false;
@@ -751,16 +547,6 @@ async fn follow(
return;
}
};
// Only whole lines, and the offset stops at the last newline -- so a
// line the process is halfway through writing is read again next pass.
// Deliberately *not* held in memory between passes: the offset would
// then have to point behind the bytes being held. It is also what makes
// the position crash-safe.
//
// Counted in bytes rather than on a decoded string: a read can cut a
// multi-byte character in half, and the replacement character is a
// different length from what it replaced -- which would slide the offset
// out of step with the file for the rest of the session.
let complete = complete_lines(&bytes);
for line in String::from_utf8_lossy(&bytes[..complete]).lines() {
@@ -779,9 +565,6 @@ async fn follow(
process::write(&session_dir, &record);
}
// Diagnostics only, and the tail of it is what an exit report carries --
// so it is read from the file rather than kept in memory, which means a
// reattached session can still explain a failure it did not witness.
if let Ok((bytes, at)) = process::read_from(&stderr_path, stderr_at)
&& at != stderr_at
{
@@ -795,11 +578,6 @@ async fn follow(
match record.liveness() {
process::Liveness::Alive => said_unknown = false,
// Drain whatever it wrote on the way out before saying so.
//
// Progress, not "there were bytes": a process that died mid-line
// leaves a partial one that is re-read every pass and never
// completes, so waiting on a non-empty read would wait for ever.
process::Liveness::Dead if complete > 0 => {}
process::Liveness::Dead => {
queue.lock().unwrap().close(&sink, "the session ended");
@@ -815,10 +593,6 @@ async fn follow(
process::clear(&session_dir);
return;
}
// The record is there and the machine will not say whether the
// process behind it is. Reported rather than guessed: calling it
// exited would invite starting a second one against the same
// conversation. Kept polling, so it resolves itself.
process::Liveness::Unknown => {
if !said_unknown {
said_unknown = true;
@@ -832,10 +606,6 @@ async fn follow(
}
}
/// How many leading bytes of `bytes` form complete lines. The offset only ever
/// advances by this, which is what lets a read land anywhere -- mid-line,
/// mid-character -- without the reader losing its place.
///
/// A line ends at `\n` and at nothing else, deliberately: this stream is JSONL,
/// so something terminated by a bare `\r` is not a record and treating one as a
/// line would hand `serde_json` a fragment. The accepted consequence is that
@@ -850,8 +620,6 @@ fn complete_lines(bytes: &[u8]) -> usize {
.unwrap_or(0)
}
/// One line of the CLI's output as events on the sink. `false` when the
/// session has been torn down and there is nothing left to send to.
fn translate_line(
line: &str,
session_dir: &Path,
@@ -878,20 +646,6 @@ fn translate_line(
if let Some(session_id) = new_session_id {
write_resume_token(session_dir, &session_id);
}
// A turn the CLI began by itself, said one line earlier than anything else
// could say it.
//
// The CLI picks the conversation back up with nothing written to it --
// measured: a backgrounded `sleep` finished nine seconds after the turn's
// result and it started again unprompted. It announces that with an `init`,
// and the first assistant text follows about a second and a half later;
// until this, that read as idle, which is long enough to send a command into
// and have it read as text.
//
// `before.is_some()` separates this from the `init` at startup. Our own
// `/clear` also produces one, and is excluded by `running` already being
// true.
// `local_command` set it before the line went out.
if opens_a_turn_by_itself(&message, before.is_some()) {
let started = {
let mut queue = queue.lock().unwrap();
@@ -911,16 +665,10 @@ fn translate_line(
return false;
}
}
// The steer is announced where the CLI opens the model call that read it,
// and *before* that call's output, so the message sits above what it
// produced and below what it did not. This line carries no events of its
// own, which is what makes it the right place.
if opens_a_model_call && !announce_steers(queue, sink) {
return false;
}
for event in events {
// A turn nobody here started -- see `proves_a_turn`. Said before the
// event that proves it, for the same reason a steer is.
let started = {
let mut queue = queue.lock().unwrap();
let started = proves_a_turn(&event) && !queue.running && !queue.closed;
@@ -960,30 +708,12 @@ fn translate_line(
true
}
/// Whether this line is the CLI announcing work it started on its own.
///
/// `system/init` is how it says a conversation is beginning, and it sends one
/// at startup, after a `/clear`, and when it picks the conversation back up by
/// itself. Only the third is a turn nobody here asked for: `already_started`
/// rules out the first, and the caller's `running` check rules out the second.
fn opens_a_turn_by_itself(message: &Value, already_started: bool) -> bool {
already_started
&& message.get("type").and_then(Value::as_str) == Some("system")
&& message.get("subtype").and_then(Value::as_str) == Some("init")
}
/// Whether this event could only have come from a turn in flight.
///
/// The turn this side starts is announced where it is started, and that covers
/// the common case and nothing else. Everything below happens without a phone
/// asking: a compaction the CLI decided on itself, a session adopted mid-turn,
/// a message that reached the conversation by another route. In all of them the
/// CLI is plainly working and the only thing that would have said so is a
/// `Running` nobody sent, so the session reads as idle until the turn ends.
///
/// Deliberately a wider set than what announces a steer: any sign of work
/// proves a turn is running, while only a `message_start` proves a line written
/// a moment ago has been read.
fn proves_a_turn(event: &Event) -> bool {
matches!(
event,
@@ -999,12 +729,6 @@ fn proves_a_turn(event: &Event) -> bool {
)
}
/// Records every message written since the last announcement, in the order it
/// was written. False means the session has been torn down.
///
/// Called from the two places that prove the CLI has consumed them: the start
/// of a new model call, and the end of the turn. The pair is the whole of the
/// rule -- a steer announced anywhere else lands above output that predates it.
fn announce_steers(queue: &Arc<Mutex<Queue>>, sink: &EventSink) -> bool {
let taken: Vec<(String, String, Vec<AttachmentRef>)> = {
let mut queue = queue.lock().unwrap();
@@ -1045,13 +769,6 @@ fn stderr_tail(path: &Path) -> String {
tail_of(&kept)
}
/// Creates the stdin fifo if it is not already there, and opens it read-write
/// for the process to inherit.
///
/// Read-write is the whole trick: a fifo opened read-only delivers EOF as soon
/// as the last writer closes, so the process would exit the moment this server
/// did -- exactly what leaving it running has to prevent. Holding it open for
/// writing means the process is its own last writer.
fn make_fifo(path: &Path) -> Result<std::fs::File> {
if !path.exists() {
let c_path = std::ffi::CString::new(path.as_os_str().as_encoded_bytes())
@@ -1072,7 +789,6 @@ fn make_fifo(path: &Path) -> Result<std::fs::File> {
.with_context(|| format!("opening the fifo {}", path.display()))
}
/// A fresh, empty, owner-only log for one of the process's output streams.
fn create_log(path: &Path) -> Result<std::fs::File> {
std::fs::OpenOptions::new()
.create(true)
@@ -1099,8 +815,6 @@ pub(super) fn write_resume_token(session_dir: &Path, session_id: &str) {
}
}
/// Where an uploaded attachment is, as a path the CLI can be told.
///
/// Absolute, because the CLI's working directory is the session's and the
/// attachments are not in it. Refused rather than resolved when the id is not
/// one this server would have written, so a crafted id cannot name a file
@@ -1124,7 +838,6 @@ fn attachment_path(session_dir: &Path, id: &str) -> Result<PathBuf> {
std::fs::canonicalize(&path).with_context(|| format!("find {}", path.display()))
}
/// Reads an uploaded image into an API image content block.
fn attachment_block(session_dir: &Path, id: &str) -> Result<Value> {
let path = attachment_path(session_dir, id)?;
let bytes = std::fs::read(&path).with_context(|| format!("read {}", path.display()))?;
@@ -1133,8 +846,6 @@ fn attachment_block(session_dir: &Path, id: &str) -> Result<Value> {
"type": "image",
"source": {
"type": "base64",
// Ids carry the extension the upload was stored under, so an
// unrecognized one means a name this server didn't write.
"media_type": crate::media::media_type_for(id).unwrap_or("image/jpeg"),
"data": base64::engine::general_purpose::STANDARD.encode(bytes),
}
@@ -1155,7 +866,6 @@ mod tests {
attachment_path(dir.path(), "ab12-x.bin").unwrap(),
attachments.join("ab12-x.bin").canonicalize().unwrap()
);
// Shipped to the session's machine: the path there, not here.
std::fs::write(
attachments.join("ab12-x.bin.remote"),
"/home/t/in/ab12-x.bin\n",
@@ -1169,9 +879,6 @@ mod tests {
assert!(attachment_path(dir.path(), "missing.bin").is_err());
}
/// Drives real CLI output lines through the reader and collects what came
/// out, which is the only way to check the wiring between "the CLI said
/// this" and "the transcript records that".
fn events_from_lines(lines: &[&str]) -> Vec<Event> {
let dir = tempfile::tempdir().expect("temp dir");
let state = Arc::new(Mutex::new(Translator::new(
@@ -1191,10 +898,6 @@ mod tests {
events
}
/// Feeds lines through the reader, running `interject` between two of them,
/// and returns what came out. The hook is what makes a steer testable at
/// all: what matters is not which events a line produces but *where* a
/// message written part-way through the stream ends up among them.
fn events_with_interjection(
lines: &[&str],
after: usize,
@@ -1222,10 +925,6 @@ mod tests {
events
}
/// One assistant message, streamed: two text deltas, then the `tool_use` it
/// ends with, then that call's result. Written out rather than shortened
/// because the point of both tests below is the *order*, and the shape of a
/// real turn is what makes the order mean anything. Recorded from 2.1.237.
const STREAMED_CALL: &[&str] = &[
r#"{"type":"stream_event","event":{"type":"message_start"},"session_id":"s","parent_tool_use_id":null}"#,
r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Let me "}},"session_id":"s","parent_tool_use_id":null}"#,
@@ -1234,13 +933,6 @@ mod tests {
r#"{"type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01","type":"tool_result","content":"one","is_error":false}]},"parent_tool_use_id":null}"#,
];
/// A steer typed while an answer is streaming is recorded below that
/// answer's tool call and its result, not among them.
///
/// The message reaches the CLI immediately; what waits is saying so.
/// Everything emitted after it was typed still belongs to a model call that
/// had not read it. `message_start` is the first line that proves the next
/// call has it, so that is where the announcement goes.
#[test]
fn a_steer_is_recorded_below_the_call_that_had_not_read_it() {
let mut lines = STREAMED_CALL.to_vec();
@@ -1250,7 +942,6 @@ mod tests {
lines.push(
r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Doing that instead."}},"session_id":"s","parent_tool_use_id":null}"#,
);
// Typed after the first delta, with the answer still arriving.
let events = events_with_interjection(&lines, 1, |queue| {
queue.lock().unwrap().awaiting.push_back((
"q1".into(),
@@ -1266,9 +957,6 @@ mod tests {
.unwrap_or_else(|| panic!("nothing matched in {events:?}"))
};
let taken = at(|e| matches!(e, Event::MessageTaken { .. }));
// Named, not just announced: the phone has a waiting bubble for this
// message and clears the one with this id. Matching on the text would
// clear the wrong bubble whenever the same thing was sent twice.
assert!(
matches!(
&events[taken],
@@ -1294,17 +982,12 @@ mod tests {
);
}
/// A steer written after the turn's last model call is still recorded.
/// Nothing further is coming, so no `message_start` will ever prove it was
/// read -- and a message only recorded when announced would vanish, leaving
/// a phone drawing it as waiting forever.
#[test]
fn a_steer_with_no_model_call_left_is_recorded_at_the_end_of_the_turn() {
let mut lines = STREAMED_CALL.to_vec();
lines.push(
r#"{"type":"result","subtype":"success","usage":{"input_tokens":1,"output_tokens":1}}"#,
);
// Typed after the tool result, with only the turn's end to come.
let events = events_with_interjection(&lines, 4, |queue| {
queue
.lock()
@@ -1334,12 +1017,6 @@ mod tests {
);
}
/// The divider comes from the CLI announcing the reset, not from an `init`
/// arriving. Measured against 2.1.237: `/clear` emits `conversation_reset`,
/// then a fresh `init` carrying a new session id. Watching the id be
/// replaced would work, but it reads the event through a side effect; the
/// announcement says so directly and arrives first, so the divider lands
/// above the new conversation.
#[test]
fn a_conversation_reset_is_what_records_a_clear() {
let events = events_from_lines(&[
@@ -1354,11 +1031,6 @@ mod tests {
);
}
/// An `init` on its own never records a clear, whatever id it carries.
/// Three ways one arrives and none is a cleared conversation: the first
/// init of a session, the one a compaction re-announces carrying the *same*
/// id, and the one that follows a resume. Reading any as a clear would tell
/// the reader a conversation had been dropped when it had been summarised.
#[test]
fn an_init_alone_is_never_a_clear() {
for ids in [["first", "first"], ["first", "second"]] {
@@ -1376,9 +1048,6 @@ mod tests {
}
}
/// The failure this exists for: a shell's complaint ends with a blank line,
/// so reporting "the last line of stderr" reported nothing, and the phone
/// showed a bare exit status while the reason sat in the server's log.
#[test]
fn the_report_keeps_the_message_and_not_the_blank_line_after_it() {
let fish_cd_failure = [
@@ -1401,12 +1070,9 @@ mod tests {
report.ends_with("'~/repos/ai-app'"),
"the trailing blank is trimmed: {report:?}",
);
// The blank *between* lines is part of the message and stays.
assert!(report.contains("does not exist\n\nembedded:"), "{report:?}");
}
/// Nothing to say is said as nothing, so the caller can tell the two
/// apart and print just the exit status.
#[test]
fn stderr_that_is_only_blank_lines_reports_as_empty() {
let kept: VecDeque<String> = ["", " ", ""].iter().map(|l| l.to_string()).collect();
@@ -1416,10 +1082,6 @@ mod tests {
#[test]
fn a_stream_read_in_arbitrary_chunks_yields_each_line_once() {
// The property the reading position has to have: however a write is
// split -- mid-line, or mid-character -- every line comes out exactly
// once and in order. Chunked at every prime-ish size so the cuts land in
// different places, including inside the multi-byte character.
let stream = "{\"a\":1}\n{\"b\":\"caf\u{e9}\"}\n{\"c\":3}\n";
for chunk in [1usize, 2, 3, 5, 7, 11, 1000] {
let mut offset = 0usize;
@@ -1428,8 +1090,6 @@ mod tests {
let mut available = 0usize;
while available < bytes.len() {
available = (available + chunk).min(bytes.len());
// What a read from the recorded offset returns: the file as far
// as it has been written, from where we left off.
let unread = &bytes[offset..available];
let complete = complete_lines(unread);
for line in String::from_utf8_lossy(&unread[..complete]).lines() {
@@ -1448,12 +1108,8 @@ mod tests {
#[test]
fn an_incomplete_line_advances_nothing() {
// Nothing to do yet, and crucially the position does not move -- so a
// crash here re-reads the line rather than skipping it.
assert_eq!(complete_lines(b"{\"partial\": tru"), 0);
assert_eq!(complete_lines(b""), 0);
// And a complete line followed by a partial one advances only past
// the complete one.
assert_eq!(complete_lines(b"done\nhalf"), 5);
}
@@ -1472,8 +1128,6 @@ mod tests {
.push_back(("q2".into(), "second".into(), Vec::new()));
queue.close(&sink, "the session ended");
// Named rather than counted, because these never reached the transcript:
// this message is the only record they existed.
let Some(Event::Error { message }) = received.try_recv().ok() else {
panic!("closing a queue holding messages must report them");
};
@@ -1484,18 +1138,12 @@ mod tests {
"{message}"
);
// And the flag is cleared, so a later message is refused with a reason
// rather than queued behind a turn that will never end.
assert!(!queue.running);
assert!(queue.closed);
}
#[test]
fn a_turn_this_side_did_not_start_still_reports_as_running() {
// The case: a session picked up while it was already working, or one
// another agent wrote to. Nothing called `send_user_message`, so the
// only thing that can say the session is busy is what it is observed
// doing.
let dir = tempfile::tempdir().expect("tempdir");
let (sink, mut received) = mpsc::unbounded_channel();
let state = Arc::new(Mutex::new(Translator::new(
@@ -1518,16 +1166,12 @@ mod tests {
Some(Event::AssistantText { .. })
));
// Once only: the turn is known to be running now, and a status per delta
// would be a status per word.
assert!(translate_line(text, dir.path(), &state, &sink, &queue));
assert!(matches!(
received.try_recv().ok(),
Some(Event::AssistantText { .. })
));
// And the end of the turn puts it back, so the next one is
// reported the same way.
let done = r#"{"type":"result","subtype":"success","is_error":false,"usage":{}}"#;
assert!(translate_line(done, dir.path(), &state, &sink, &queue));
assert_eq!(
@@ -1541,9 +1185,6 @@ mod tests {
#[test]
fn output_from_a_process_that_has_gone_does_not_revive_the_turn() {
// `close` is what says the process is gone and reports the messages that
// died with it. Anything still in the pipe after that must not put the
// session back to work.
let dir = tempfile::tempdir().expect("tempdir");
let (sink, mut received) = mpsc::unbounded_channel();
let state = Arc::new(Mutex::new(Translator::new(
@@ -1567,8 +1208,6 @@ mod tests {
let (sink, mut received) = mpsc::unbounded_channel();
let mut queue = Queue::default();
queue.close(&sink, "the session ended");
// A session that exits with nothing held has lost nothing, and an error
// saying so would be noise on every ordinary exit.
assert!(received.try_recv().is_err());
assert!(queue.closed);
}
server/src/session/claude/translate.rs
-322
View File
@@ -1,14 +1,3 @@
//! The stream-json dialect: CLI lines in, common [`Event`]s out.
//!
//! Split from the driver beside it because the two change for unrelated
//! reasons. This half moves when the CLI's wire format does, which is what the
//! tests at the bottom pin by replaying recorded lines; the driver half moves
//! when spawning, resuming or shutting down changes.
//!
//! The one side effect here is saving images a tool result carries into the
//! session directory; everything else is pure, which is what makes the mapping
//! testable without a process.
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};
@@ -18,8 +7,6 @@ use serde_json::{Value, json};
use super::super::driver::{Event, QuestionOption, SessionStatus, context_tokens};
use super::super::subagent::Subagents;
/// Whether this line is the CLI opening a fresh model call.
///
/// `message_start` begins one assistant message, and the CLI sends the previous
/// call's tool results back before opening the next -- so this is the first
/// moment at which anything written since the last one can have been read.
@@ -33,71 +20,31 @@ pub(super) fn starts_a_model_call(message: &Value) -> bool {
&& message["event"].get("type").and_then(Value::as_str) == Some("message_start")
}
/// What answering a question produced.
pub(super) enum AnswerOutcome {
/// Send this control_response line to the CLI.
Respond(Value),
/// Part of a multi-question request; more answers still needed.
Pending,
Unknown,
}
/// A setting a control request asked for, held until the CLI says whether it
/// took. The CLI answers `set_model` with a bare success -- no value -- so the
/// only way to report what was accepted is to remember what was asked.
/// `set_permission_mode` does echo its mode back.
pub(super) enum Setting {
Model(String),
PermissionMode(String),
}
/// A `can_use_tool` request we've surfaced to the phone and not yet answered.
/// For plain permissions there is one implicit question (Allow/Deny); for
/// AskUserQuestion, one per entry in `questions`.
struct PendingRequest {
request_id: String,
input: Value,
/// Question text per sub-question, in order -- the keys the answers map
/// uses. Empty for a plain permission request.
questions: Vec<String>,
answers: HashMap<String, String>,
}
/// Translation state: stream-json lines in, common events out.
pub(super) struct Translator {
pub(super) session_id: Option<String>,
pending: HashMap<String, PendingRequest>,
/// Settings asked for and not yet answered, by request id. Its path out is
/// the response: every entry is removed when one arrives, whether it
/// succeeded or failed.
asked: HashMap<String, Setting>,
/// Whether this side asked the turn to stop.
///
/// The CLI reports an interrupted turn the same way it reports one that
/// broke -- a `result` with `is_error` set -- so the line cannot tell them
/// apart, and somebody who pressed Stop was shown "the turn ended with an
/// error". What separates them is that *we* asked.
///
/// Its path out is that result, so a genuine failure in a later turn is
/// still reported.
interrupting: bool,
/// The input side of the newest assistant message, waiting for the `result`
/// that ends the turn to carry it out.
///
/// Read from the assistant message rather than the result's own usage,
/// which is the whole turn added up: measured on 2026-08-30 against 2.1.237,
/// a two-message turn reported `cache_read_input_tokens` of 40,211, being
/// 14,259 and 25,952 -- the same conversation counted twice. The model held
/// 26,131. A turn with ten tool calls would overstate it tenfold.
///
/// Its path out is that result, so a turn whose messages carried no usage
/// reports none rather than repeating the previous turn's.
context: Option<u64>,
session_dir: PathBuf,
/// This session's subagents, shared with every child translator below --
/// see `SUBAGENTS.md`. One registry per session, so a subagent started
/// through this translator or any of its children lands in the same
/// place a route reads it back from.
subagents: Arc<Subagents>,
/// One translator per subagent id, holding *its* streaming and
/// tool-tracking state -- separate from the parent's because tool ids
@@ -120,51 +67,27 @@ impl Translator {
}
}
/// Remembers what a control request was for, so its answer can say so.
/// Called before the request goes out: the reader thread is already running
/// and a fast CLI can answer before this side gets back to it.
pub(super) fn expect_setting(&mut self, request_id: String, setting: Setting) {
self.asked.insert(request_id, setting);
}
/// Says that the turn about to end was stopped on purpose. Called before
/// the request goes out, for the reason [`Translator::expect_setting`]
/// gives.
pub(super) fn expect_interrupt(&mut self) {
self.interrupting = true;
}
pub(super) fn translate(&mut self, message: &Value) -> Vec<Event> {
// Events from subagents (Task tool internals) carry a
// parent_tool_use_id; the transcript shows the Task tool's own
// start/end instead of every nested step. Routed into that
// subagent's own transcript rather than dropped -- see
// `SUBAGENTS.md`.
if let Some(parent_id) = message.get("parent_tool_use_id").and_then(Value::as_str) {
return self.translate_child(parent_id, message);
}
self.dispatch(message)
}
/// A line belonging to a subagent rather than to this translator's own
/// session. Always returns nothing to the *caller*: everything it
/// produces goes into the subagent's own transcript instead.
fn translate_child(&mut self, id: &str, message: &Value) -> Vec<Event> {
match self.subagents.get(id) {
Some(subagent) if !subagent.is_open() => {
// Not stale: the Task tool runs in the background by
// default, so a finished subagent can still be sent another
// message later (SendMessage) and start working again. A
// line arriving after `finish` means exactly that, not a
// conversation that is over -- see `SUBAGENTS.md`.
self.subagents.reopen(id);
}
Some(_) => {}
None => {
// Nobody has heard of this id yet: the Task call itself
// either has not been seen or never will be. Started here
// with the best title available -- the tool name of this
// first line -- since SUBAGENTS.md's real title only
// arrives with the Task call.
self.subagents.start(id, &fallback_title(message), None);
}
}
@@ -196,10 +119,6 @@ impl Translator {
self.subagents.record(id, event);
}
}
// What actually ends a subagent's turn: not the parent's
// `tool_result`, which for a background Task arrives at launch
// ("Async agent launched...") long before the work is done -- see
// `SUBAGENTS.md`.
if ends_a_turn(message) {
self.subagents.finish(id);
}
@@ -209,11 +128,6 @@ impl Translator {
fn dispatch(&mut self, message: &Value) -> Vec<Event> {
match message.get("type").and_then(Value::as_str) {
Some("system") => self.translate_system(message),
// The CLI's own announcement that `/clear` took effect, sent just
// before the fresh `init` carrying the new session_id. Measured
// against 2.1.237: this used to watch for the id being *replaced*,
// which is the same event seen through a side effect. The
// announcement lands before the new init rather than after it.
Some("conversation_reset") => vec![Event::Cleared],
Some("stream_event") => self.translate_stream_event(&message["event"]),
Some("assistant") => self.translate_assistant(&message["message"]),
@@ -221,9 +135,6 @@ impl Translator {
Some("control_request") => self.translate_control_request(message),
Some("control_response") => {
let response = &message["response"];
// Answered either way, so the request stops being pending
// either way -- a rejected setting that stayed here would be
// applied by the next request that reused its id.
let asked = response
.get("request_id")
.and_then(Value::as_str)
@@ -237,9 +148,6 @@ impl Translator {
message: format!("claude rejected a request: {error}"),
}];
}
// Success, so the setting this request asked for is now the
// session's, and this is the only place that says so: the
// response carries no value of its own for a model.
match asked {
Some(Setting::Model(model)) => vec![Event::Settings {
model: Some(model),
@@ -247,10 +155,6 @@ impl Translator {
}],
Some(Setting::PermissionMode(mode)) => vec![Event::Settings {
model: None,
// The CLI echoes this one, and its answer wins: `auto`
// and `manual` are names it accepts on the way in and
// reports back under another name, so repeating the
// request would show a mode the session is not in.
permission_mode: Some(
response["response"]["mode"]
.as_str()
@@ -272,29 +176,14 @@ impl Translator {
.and_then(Value::as_u64)
.unwrap_or(0);
let mut events = Vec::new();
// A turn another agent started, which is only knowable here.
//
// Measured against 2.1.237 (2026-08-31) by sending a real
// cross-session message to a real stream-json session: the CLI
// emits no `user` record for it and nothing in the
// partial-message stream mentions it. The whole of it arrives as
// an `origin` object on the turn's `result`, in the same shape
// the session file records -- so this is `import::peer_message`
// reading a different record.
//
// The cost is the position: the note lands after the reply it
// caused, because at no earlier point does the CLI say why the
// turn started. Taken deliberately over a second reader tailing
// the CLI's own session file, which is two sources of truth for
// one conversation and a poll per live session.
//
// Only peer-caused turns carry it: four ordinary results over a
// real session's stdout had no `origin` between them.
if let Some(peer) = crate::session::import::peer_message(message) {
events.push(peer);
}
// Whichever way this result went, the interrupt it may have
// been answering is now spent.
let asked_to_stop = std::mem::take(&mut self.interrupting);
if !asked_to_stop
&& message
@@ -323,35 +212,12 @@ impl Translator {
}
}
/// The CLI's own notices: which session this is, and what it is doing that
/// is not a turn.
///
/// Compaction is the whole of that second kind, and it is announced rather
/// than inferred. Measured against 2.1.237 (2026-08-29) by driving a session
/// through `/compact`, one produces in order:
///
/// - `{"subtype":"status","status":"compacting"}` -- the start;
/// - `{"subtype":"status","status":null,"compact_result":"success"}`, or
/// `"failed"` with a `compact_error` -- the end;
/// - a fresh `init` carrying the same `session_id`;
/// - `{"subtype":"compact_boundary","compact_metadata":{…}}` with the token
/// counts, and only when it succeeded;
/// - the turn's ordinary `result`, which returns it to idle.
///
/// The keys are snake_case here and camelCase in the CLI's own transcript
/// file, which records the same events -- so reading the shape off that
/// file, the obvious place to look, gets every field name wrong and
/// silently yields a compaction with no numbers in it.
fn translate_system(&mut self, message: &Value) -> Vec<Event> {
match message.get("subtype").and_then(Value::as_str) {
Some("init") => {
if let Some(id) = message.get("session_id").and_then(Value::as_str) {
self.session_id = Some(id.to_string());
}
// The CLI's own account of what it is set to, and the only one
// that resolves an alias: a session launched with
// `--model haiku` reports `claude-haiku-4-5-20251001` here. It
// arrives again after a compaction, which is free.
vec![Event::Settings {
model: message
.get("model")
@@ -379,19 +245,7 @@ impl Translator {
}
}
/// A `system/status` line: the CLI entering or leaving a state that is not
/// a turn.
///
/// A null `status` is the leaving edge, and it carries how the thing went.
/// The turn it happened inside is still going when it ends -- the `result`
/// has not arrived -- so leaving says `Running`. A state this build does
/// not recognise is left alone rather than mapped onto the nearest one.
fn translate_status(&self, message: &Value) -> Vec<Event> {
// A mode change the CLI has made, announced a moment after it answers
// the request. Measured on 2.1.237:
// `{"subtype":"status","status":null,"permissionMode":"plan"}`, which
// is a leaving edge carrying no compaction result -- so it is checked
// before the compaction reading below.
if let Some(mode) = message.get("permissionMode").and_then(Value::as_str) {
return vec![Event::Settings {
model: None,
@@ -426,9 +280,6 @@ impl Translator {
events
}
/// Raw API streaming: only text deltas become events. Consolidated blocks
/// arriving later re-carry the same text, so those are skipped in
/// `translate_assistant` -- one source per fact.
fn translate_stream_event(&mut self, event: &Value) -> Vec<Event> {
if event.get("type").and_then(Value::as_str) == Some("content_block_delta")
&& let Some(delta) = event["delta"].get("text")
@@ -469,9 +320,6 @@ impl Translator {
.unwrap_or_default()
.to_string();
let input = block.get("input").cloned().unwrap_or(Value::Null);
// A subagent this call is about to start -- see
// `SUBAGENTS.md`'s lifecycle #1. The parent's own transcript
// still shows only the Task call itself, below.
if tool == "Task" || tool == "Agent" {
self.start_subagent_from_task(&id, &input);
}
@@ -480,10 +328,6 @@ impl Translator {
.collect()
}
/// Starts the subagent a Task call names, with the title and prompt
/// SUBAGENTS.md describes: the call's `description`, then
/// `(<subagent_type>)` when one is given, falling back to the tool's own
/// name when there is no description to build one from.
fn start_subagent_from_task(&self, id: &str, input: &Value) {
let description = text_field(input, "description");
let subagent_type = text_field(input, "subagent_type");
@@ -535,10 +379,6 @@ impl Translator {
.and_then(Value::as_str)
.unwrap_or("(question)")
.to_string();
// Everything the reader decides on, carried in the event. The
// alternative -- and what this was -- is the phone reaching into
// the tool call's input for the parts the event dropped, which
// puts this dialect's schema where no other dialect can reach it.
let options = question
.get("options")
.and_then(Value::as_array)
@@ -576,8 +416,6 @@ impl Translator {
events.push(Event::Question {
id: request_id.clone(),
prompt: format!("Allow {tool_name}?\n{summary}"),
// No header: the question is about the call it names, and the
// phone draws it on that call's own row.
header: None,
options: vec![
QuestionOption::plain("Allow"),
@@ -602,13 +440,7 @@ impl Translator {
events
}
/// Applies one answer from the phone. Question ids are the control request
/// id, suffixed `#i` for AskUserQuestion sub-questions.
pub(super) fn answer(&mut self, question_id: &str, answers: &[String]) -> AnswerOutcome {
// Where this dialect's shape is put on: the CLI's `answers` map is
// string-valued whatever the question, so several choices become one
// line here rather than everything upstream pretending a question can
// only ever have one answer.
let answer = answers.join(", ");
let answer = answer.as_str();
let (request_id, sub) = match question_id.split_once('#') {
@@ -644,10 +476,6 @@ impl Translator {
}))
}
/// `user` messages: tool results become ToolEnd, with any image parts saved
/// into the session dir and referenced by an Image event. Replayed and
/// synthetic user text is skipped -- the manager already recorded the
/// user's side.
fn translate_user(&self, message: &Value) -> Vec<Event> {
// Only tool results are here. The CLI never echoes a person's own
// message back on stdout -- measured, because the obvious way to learn
@@ -662,8 +490,6 @@ impl Translator {
continue;
}
let mut texts = Vec::new();
// Held until the call's id is in hand a few lines below: an image is
// drawn under the call that produced it, so it has to carry that id.
let mut images = Vec::new();
match block.get("content") {
Some(Value::String(text)) => texts.push(text.clone()),
@@ -702,21 +528,11 @@ impl Translator {
output: texts.join("\n"),
is_error: crate::session::import::tool_result_is_error(block),
});
// Deliberately does *not* finish a subagent `about` might name:
// the Task tool runs in the background by default, so this
// `tool_result` -- "Async agent launched..." -- arrives at
// launch, long before the subagent's own work is done. What
// ends it is its own turn ending, handled in `translate_child`.
}
events
}
}
/// The title to start a subagent under when its own first line arrives
/// before (or without) its Task call ever being seen: the tool name of that
/// first line, which is the only thing known about it yet. `"subagent"` for
/// a line this cannot even find a tool name in, such as one that opens with
/// something other than a tool call.
fn fallback_title(message: &Value) -> String {
message["message"]["content"]
.as_array()
@@ -729,20 +545,10 @@ fn fallback_title(message: &Value) -> String {
.to_string()
}
/// Whether this line is a subagent's *own* turn ending -- the only thing
/// that does, per `SUBAGENTS.md`: not the parent's `tool_result`, which for
/// a background Task arrives at launch rather than at completion.
///
/// Checked on the raw line rather than on what `dispatch` returns, so this
/// never has to touch the shared `translate_stream_event`/`dispatch` code a
/// top-level session's own turn-ending also goes through -- a subagent's
/// idea of "ended" must not change when a real session's does.
///
/// `message_delta` is the raw API's own signal, carrying the stop reason:
/// `end_turn` is genuinely done, `tool_use` means the model is about to call
/// one and there is more coming. A `result` line is the CLI's own shape for
/// a top-level turn; a subagent has not been observed to send one, but
/// SUBAGENTS.md counts it too in case a future CLI version does.
fn ends_a_turn(message: &Value) -> bool {
match message.get("type").and_then(Value::as_str) {
Some("stream_event") => {
@@ -769,10 +575,6 @@ fn ends_a_turn(message: &Value) -> bool {
/// not say until when" -- which is not a reason to invent a time: `crate::resume`
/// asks the usage endpoint before sending anything, and that answer is the one
/// that decides.
///
/// Milliseconds are accepted as well as seconds and told apart by magnitude,
/// since a wrong guess would schedule a resume tens of thousands of years out
/// and look exactly like auto-resume being broken.
fn usage_limit(result: &str) -> Option<Option<f64>> {
if !result.to_ascii_lowercase().contains("usage limit reached") {
return None;
@@ -786,9 +588,6 @@ fn usage_limit(result: &str) -> Option<Option<f64>> {
Some(stamp)
}
/// A string field that is there and not empty, or `None`. The CLI omits these
/// rather than sending them empty, but a caller that sends `""` means the same
/// thing and should not produce a description that draws as a blank line.
fn text_field(value: &Value, name: &str) -> Option<String> {
value
.get(name)
@@ -797,8 +596,6 @@ fn text_field(value: &Value, name: &str) -> Option<String> {
.map(str::to_string)
}
/// Decodes one base64 image block into `files/` and returns its ref.
///
/// A free function rather than a method because the import replay needs exactly
/// this too: a session's history carries the same image blocks as its live
/// output. Two copies would be two naming schemes for one directory.
@@ -809,8 +606,6 @@ pub(in crate::session) fn save_image(session_dir: &Path, part: &Value) -> Option
let bytes = base64::engine::general_purpose::STANDARD
.decode(data)
.ok()?;
// Screenshots are the overwhelming case and they are PNG; an unrecognized
// type is more likely a dialect change than a JPEG.
let extension = source
.get("media_type")
.and_then(Value::as_str)
@@ -832,7 +627,6 @@ pub(in crate::session) fn save_image(session_dir: &Path, part: &Value) -> Option
mod tests {
use super::*;
/// What a phone sends back: everything chosen, even when that is one.
fn chose(answer: &str) -> Vec<String> {
vec![answer.to_string()]
}
@@ -848,10 +642,6 @@ mod tests {
.collect()
}
/// A fresh, empty subagent registry over the same temp dir a test's
/// translator writes into -- every test here is about the parent's own
/// events, so what a registry does with a subagent is `subagent.rs`'s
/// tests to make, not these.
fn test_subagents(dir: &tempfile::TempDir) -> Arc<Subagents> {
Arc::new(Subagents::new(dir.path().to_path_buf()))
}
@@ -867,8 +657,6 @@ mod tests {
],
);
assert_eq!(translator.session_id.as_deref(), Some("5ecf21da-d53f"));
// The resolved model, which is the point: a session launched with
// `--model haiku` is reported by its full name here.
assert_eq!(
events,
vec![Event::Settings {
@@ -883,15 +671,12 @@ mod tests {
let dir = tempfile::tempdir().expect("tempdir");
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
// What `set_model` does: remember, send, and say nothing yet.
translator.expect_setting("req-a".to_string(), Setting::Model("sonnet".to_string()));
translator.expect_setting(
"req-b".to_string(),
Setting::PermissionMode("plan".to_string()),
);
// Success carries no model of its own -- measured on 2.1.237 -- so what
// was asked for is the only answer available.
let events = translate_lines(
&mut translator,
&[
@@ -906,8 +691,6 @@ mod tests {
}]
);
// A mode the CLI answers with a value of its own is taken from that
// value: `auto` on the way in is `default` coming back.
translator.expect_setting(
"req-c".to_string(),
Setting::PermissionMode("auto".to_string()),
@@ -926,8 +709,6 @@ mod tests {
}]
);
// A refusal changes nothing, and says why rather than claiming a
// setting that was rejected.
let events = translate_lines(
&mut translator,
&[
@@ -941,8 +722,6 @@ mod tests {
}]
);
// And neither request is still waiting: a second answer to either id
// reports nothing at all.
let events = translate_lines(
&mut translator,
&[
@@ -955,8 +734,6 @@ mod tests {
#[test]
fn a_mode_the_cli_announces_is_taken_from_the_announcement() {
// The line it sends just after answering `set_permission_mode`, which is
// also how a mode changed from the terminal arrives.
let dir = tempfile::tempdir().expect("tempdir");
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
let events = translate_lines(
@@ -976,7 +753,6 @@ mod tests {
#[test]
fn streams_text_deltas_and_skips_the_consolidated_copy() {
// Real lines (trimmed) from the 2.1.237 probe.
let dir = tempfile::tempdir().expect("tempdir");
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
let events = translate_lines(
@@ -1023,11 +799,6 @@ mod tests {
);
}
/// The other half of the test above, and the one it cannot stand in
/// for: a call the tool itself reported as failed. Both lines are
/// `tool_result`s and both carry output, so nothing but `is_error`
/// tells them apart -- which is why dropping the field made a broken
/// call draw exactly like one that worked.
#[test]
fn a_failed_tool_result_says_so() {
let dir = tempfile::tempdir().expect("tempdir");
@@ -1036,9 +807,6 @@ mod tests {
&mut translator,
&[
r#"{"type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_02","type":"tool_result","content":"No such file or directory","is_error":true}]},"parent_tool_use_id":null}"#,
// No `is_error` at all: every transcript written before
// the field was read looks like this, and it means the
// call was not reported to have failed.
r#"{"type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_03","type":"tool_result","content":"fine"}]},"parent_tool_use_id":null}"#,
],
);
@@ -1072,9 +840,6 @@ mod tests {
assert!(events.is_empty());
}
/// A child line does not just vanish from the parent -- it lands in its
/// own subagent's transcript, with that transcript's own sequence
/// numbers, starting at 1 like any other.
#[test]
fn a_child_line_lands_in_its_own_subagents_transcript() {
let dir = tempfile::tempdir().expect("tempdir");
@@ -1103,8 +868,6 @@ mod tests {
);
}
/// The title and prompt shown for a subagent come from the Task call
/// that started it, not from anything guessed at its first line.
#[test]
fn the_subagent_takes_its_title_and_prompt_from_the_task_call() {
let dir = tempfile::tempdir().expect("tempdir");
@@ -1127,16 +890,8 @@ mod tests {
));
}
/// The parent's `tool_result` for the Task id is what ends the
/// subagent -- SUBAGENTS.md's lifecycle #3 -- and nothing else does.
#[test]
fn the_parents_tool_result_does_not_finish_the_subagent() {
// The Task tool runs in the background by default: this
// `tool_result` is "Async agent launched...", arriving the moment
// the subagent *starts*, while it goes on working for however long
// its own turn takes. Finishing it here was the bug -- a running
// background agent read as "finished" with its transcript truncated
// at launch.
let dir = tempfile::tempdir().expect("tempdir");
let subagents = test_subagents(&dir);
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
@@ -1157,10 +912,6 @@ mod tests {
assert!(subagent.is_open());
}
/// What actually ends a subagent: the raw API's own `message_delta`
/// saying its turn stopped with `end_turn`. Never written into the
/// subagent's own transcript as `Idle` -- its vocabulary has no such
/// state.
#[test]
fn the_subagents_own_end_turn_finishes_it() {
let dir = tempfile::tempdir().expect("tempdir");
@@ -1191,8 +942,6 @@ mod tests {
);
}
/// `stop_reason: "tool_use"` is the model about to call a tool, with
/// more of the turn still coming -- not an end.
#[test]
fn a_stop_reason_of_tool_use_does_not_finish_the_subagent() {
let dir = tempfile::tempdir().expect("tempdir");
@@ -1213,9 +962,6 @@ mod tests {
);
}
/// A background Task can be sent another message long after its first
/// turn ended -- a further child line for it reopens rather than being
/// dropped, and the same transcript and child translator carry on.
#[test]
fn a_line_after_finish_reopens_the_subagent_rather_than_being_dropped() {
let dir = tempfile::tempdir().expect("tempdir");
@@ -1240,8 +986,6 @@ mod tests {
assert!(subagent.is_open());
let lines = crate::session::transcript::read_after(&subagent.transcript_path(), 0)
.expect("read subagent transcript");
// Running, [prompt], Exited, Running (reopened), then the new line's
// own ToolStart -- the same transcript throughout, not a new one.
assert!(
lines.iter().any(
|entry| matches!(&entry.event, Event::ToolStart { tool, .. } if tool == "Bash")
@@ -1262,9 +1006,6 @@ mod tests {
);
}
/// Two subagents running at once keep two separate transcripts: tool ids
/// are unique but a `stream_event`'s content-block index is not, so
/// sharing translation state between them would cross their streams.
#[test]
fn two_parallel_subagents_keep_separate_transcripts() {
let dir = tempfile::tempdir().expect("tempdir");
@@ -1326,8 +1067,6 @@ mod tests {
panic!("expected a question, got {events:?}");
};
assert_eq!(id, "req-1");
// The call being asked about, so the phone draws the ask on that tool's
// row instead of as a second card repeating its input.
assert_eq!(about.as_deref(), Some("toolu_03"));
assert!(prompt.contains("Bash") && prompt.contains("rm -rf /tmp/x"));
assert_eq!(labels(options), ["Allow", "Deny"]);
@@ -1338,7 +1077,6 @@ mod tests {
}
);
// Allowing echoes the input back; the request is then gone.
let AnswerOutcome::Respond(response) = translator.answer("req-1", &chose("Allow")) else {
panic!("expected a control response");
};
@@ -1372,8 +1110,6 @@ mod tests {
#[test]
fn ask_user_question_rides_the_same_flow_with_answers_keyed_by_question() {
// The real 2.1.237 shape, verified live: answers go back inside
// updatedInput, keyed by the question text.
let dir = tempfile::tempdir().expect("tempdir");
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
let events = translate_lines(
@@ -1397,7 +1133,6 @@ mod tests {
.collect();
assert_eq!(questions.len(), 2);
assert_eq!(questions[0].0, "req-3#0");
// Both belong to the call that asked, so a phone draws them on it.
assert!(events.iter().all(|event| match event {
Event::Question { about, .. } => about.as_deref() == Some("toolu_04"),
_ => true,
@@ -1405,8 +1140,6 @@ mod tests {
assert_eq!(questions[0].1, "Which color?");
assert_eq!(labels(&questions[0].2), ["Red", "Blue"]);
// First answer alone isn't enough; the response goes out when the
// last sub-question is answered, with all answers aboard.
assert!(matches!(
translator.answer("req-3#0", &chose("Blue")),
AnswerOutcome::Pending
@@ -1422,10 +1155,6 @@ mod tests {
#[test]
fn a_question_carries_what_it_takes_to_answer_it() {
// Descriptions and previews are what the reader decides on, and a
// multi-select is how many answers the question takes. All of it travels
// in the event: a phone that had to read this dialect's tool input to
// find them would be the only place that knew how.
let dir = tempfile::tempdir().expect("tempdir");
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
let events = translate_lines(
@@ -1458,8 +1187,6 @@ mod tests {
.contains("dev-updater")
);
// Two choices, one answer: the joining is this dialect's shape, done
// where it is spoken. The CLI's answers map holds strings.
let AnswerOutcome::Respond(response) = translator.answer(
"req-9#0",
&["Tool calls".to_string(), "Peer messages".to_string()],
@@ -1476,7 +1203,6 @@ mod tests {
fn images_in_tool_results_are_saved_and_referenced() {
let dir = tempfile::tempdir().expect("tempdir");
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
// A 1x1 PNG, the smallest real payload worth round-tripping.
let png = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
let line = format!(
r#"{{"type":"user","message":{{"role":"user","content":[{{"type":"tool_result","tool_use_id":"toolu_05","content":[{{"type":"text","text":"took a screenshot"}},{{"type":"image","source":{{"type":"base64","media_type":"image/png","data":"{png}"}}}}]}}]}},"parent_tool_use_id":null}}"#
@@ -1487,8 +1213,6 @@ mod tests {
panic!("expected an image event, got {events:?}");
};
assert!(image.ends_with(".png"));
// Named as belonging to the call that produced it, so a phone draws it
// under that row rather than beside it.
assert_eq!(about.as_deref(), Some("toolu_05"));
let saved = dir.path().join("files").join(image);
assert!(saved.is_file(), "image not saved at {}", saved.display());
@@ -1526,17 +1250,6 @@ mod tests {
);
}
/// A turn another agent started says so, on the record that carries it.
///
/// The line is the real shape, taken from a real cross-session message sent
/// to a real stream-json session on 2.1.237 (2026-08-31) -- including the
/// `from` socket path, which is deliberately *not* what a reader is shown:
/// the sending session's `name` is what they recognise it by. The `body` is
/// the message as written; the content the model is given wraps the same
/// text in a preamble written for the model rather than for a person.
///
/// The note comes before the usage and the idle, so it sits as close to the
/// turn it explains as the wire allows.
#[test]
fn a_turn_started_by_another_agent_records_who_and_what() {
let dir = tempfile::tempdir().expect("tempdir");
@@ -1553,8 +1266,6 @@ mod tests {
Event::PeerMessage {
from: "ai-app-2-fb".to_string(),
text: "Reply with just the word ACK.".to_string(),
// Stamped by the pump, which is the only place that knows
// what seq the turn started at.
turn_start: None,
},
Event::UsageDelta {
@@ -1568,9 +1279,6 @@ mod tests {
);
}
/// And an ordinary turn does not, which is the half that decides whether
/// the check above is a check or a rubber stamp. Measured over a real
/// session's stdout: four results, no `origin` between them.
#[test]
fn an_ordinary_turn_carries_no_peer_note() {
let dir = tempfile::tempdir().expect("tempdir");
@@ -1589,13 +1297,6 @@ mod tests {
);
}
/// The context is the last assistant message's, not the result's.
///
/// Real figures from a two-message haiku turn on 2.1.237, captured
/// 2026-08-30. The result adds the turn up -- its `cache_read_input_tokens`
/// of 40,211 is 14,259 and 25,952, the same conversation counted twice -- so
/// reading the context off it would report a size the model never held, by
/// more the more tool calls a turn makes.
#[test]
fn the_context_is_what_the_last_message_held_not_the_turn_added_up() {
let dir = tempfile::tempdir().expect("tempdir");
@@ -1616,8 +1317,6 @@ mod tests {
})
);
// Taken by that result, so a following turn whose messages carry no
// usage reports none rather than repeating this one's.
let events = translate_lines(
&mut translator,
&[
@@ -1635,9 +1334,6 @@ mod tests {
#[test]
fn a_compaction_reports_its_start_and_what_it_recovered() {
// Real lines (trimmed) from a 2.1.237 session driven through `/compact`.
// Note the snake_case keys -- the CLI's transcript file writes the same
// records in camelCase.
let dir = tempfile::tempdir().expect("tempdir");
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
let events = translate_lines(
@@ -1737,12 +1433,6 @@ mod tests {
);
}
/// Running out of quota is a state, not a failure of the work.
///
/// The naive reading -- an error result like any other -- is what shipped
/// before this: the transcript said "Claude AI usage limit reached|…" in
/// red, which is neither readable nor actionable, and nothing above the
/// driver could tell it apart from a broken tool call.
#[test]
fn a_turn_stopped_by_the_usage_limit_says_so_and_carries_the_reset() {
let dir = tempfile::tempdir().expect("tempdir");
@@ -1771,8 +1461,6 @@ mod tests {
r#"{"type":"result","subtype":"error_during_execution","is_error":true,"result":"Claude AI usage limit reached","usage":{}}"#,
],
);
// Not a time this side invented: the meter is asked before anything is
// sent, and a made-up reset would only decide when to ask.
assert_eq!(events[0], Event::LimitReached { resets_at: None });
}
@@ -1782,18 +1470,9 @@ mod tests {
usage_limit("Claude AI usage limit reached|1788546972000"),
Some(Some(1_788_546_972.0))
);
// And anything that is not the limit stays an ordinary failure.
assert_eq!(usage_limit("something broke"), None);
}
/// Pressing Stop is not a failure, and the CLI cannot tell you which it was.
///
/// An interrupted turn arrives as exactly the same shape a broken one does,
/// so somebody who pressed the button was shown "the turn ended with an
/// error". What separates the two is that this side asked. The second half
/// of this test is the one that matters, because the naive fix -- never
/// reporting an error result -- passes the first half and silences every
/// genuine failure afterwards.
#[test]
fn a_turn_stopped_on_purpose_is_not_an_error() {
let dir = tempfile::tempdir().expect("tempdir");
@@ -1816,7 +1495,6 @@ mod tests {
"an interrupted turn still has to end the turn"
);
// The interrupt is spent, so the next failure is a failure again.
let later = translate_lines(&mut translator, &[stopped_result]);
assert!(
later
server/src/session/driver.rs
-96
View File
@@ -1,26 +1,9 @@
//! The common event model and the `Driver` trait -- the one abstraction
//! everything hangs off (see PLAN.md).
//!
//! A driver translates its child process's JSONL dialect into [`Event`]s
//! and accepts the small inbound vocabulary below. The transcript, the SSE
//! stream, and the phone UI work purely in this model; nothing downstream
//! of a driver may branch on the session kind.
//!
//! The event model itself -- [`Event`], [`QuestionOption`], [`SessionStatus`],
//! [`AttachmentRef`], `ImageRef`, [`context_tokens`] and [`context_after`] --
//! moved to the `event-model` crate on 2026-09-04, so `client-core` can share
//! one definition with this server instead of a hand-kept Kotlin mirror.
//! Re-exported here so nothing downstream of this module had to change; what
//! stayed behind is the *driver* abstraction, which is how this server runs
//! a session rather than part of what a client reads off the wire.
pub use event_model::{
AttachmentRef, Event, QuestionOption, SessionStatus, context_after, context_tokens,
};
use tokio::sync::mpsc;
/// 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`
@@ -35,8 +18,6 @@ pub enum SessionCommand {
}
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(),
@@ -46,7 +27,6 @@ impl SessionCommand {
}
}
/// Runs it. Called only at a boundary -- see [`Event::CommandQueued`].
pub fn apply(&self, driver: &dyn Driver) {
match self {
Self::Compact => driver.compact(),
@@ -57,8 +37,6 @@ impl SessionCommand {
}
}
/// What became of a request to take a queued message back.
///
/// Three states rather than a bool because the two failures are not the same
/// fact. A driver that writes into its session the moment a message arrives
/// -- which is what `ClaudeDriver` does, so a steer reaches the model at the
@@ -68,9 +46,7 @@ impl SessionCommand {
pub enum Unqueued {
/// Out of the queue; the session will never read it.
Dropped,
/// Already handed to the session, so there is nothing left to take back.
AlreadySent,
/// Nothing is waiting under that id.
Unknown,
}
@@ -79,23 +55,12 @@ pub enum Unqueued {
/// is the backpressure-free buffer of record.
pub type EventSink = mpsc::UnboundedSender<Event>;
/// The inbound half of a session. Deliberately small; see PLAN.md for the
/// per-driver mapping of each method onto its dialect.
///
/// `send_user_message` during a run is the point of the whole app: both
/// real dialects queue it for injection at the next tool boundary rather
/// than the end of the turn.
pub trait Driver: Send + Sync {
/// Takes a message, now or once the session is free for it.
///
/// Every driver owes exactly one `MessageTaken` per message, at the moment
/// it actually starts reading it: that event is what puts the message in
/// the transcript, so a driver that never sends it drops the message from
/// the conversation entirely.
fn send_user_message(&self, text: String, attachments: Vec<AttachmentRef>);
/// Takes back a message that is still waiting, named by the id its
/// [`Event::MessageQueued`] carried.
///
/// Answering is the whole of the contract: a driver that drops the message
/// owes an [`Event::MessageDropped`], and one that cannot must say which
/// of the two reasons it is -- "the session has already been told" is
@@ -105,55 +70,15 @@ pub trait Driver: Send + Sync {
fn unqueue(&self, _id: &str) -> Unqueued {
Unqueued::Unknown
}
/// Answers one question with everything that was chosen, in the order it
/// was offered. A driver whose dialect takes a single value joins them
/// where it writes it.
fn answer_question(&self, id: &str, answers: &[String]);
/// Stop mid-run; the session survives.
fn interrupt(&self);
fn set_model(&self, model: &str);
/// How much the session asks about before acting. Live rather than
/// spawn-only: the answer changes with what is being done, and a phone is
/// the worst place to answer "may I run this?" forty times.
fn set_permission_mode(&self, mode: &str);
// Both of the above are requests, and neither reports the outcome by
// returning. A driver that changes the setting owes an [`Event::Settings`]
// once it has -- that event, not the request, is what the manager and the
// phone read. One that cannot owes an [`Event::Error`] saying why.
/// Tells the process what this conversation is called, when it has
/// somewhere to put it.
///
/// Unlike the two above, this is not a request that can fail: the rename
/// has already happened in this server's config, which is what a phone
/// lists. So a driver whose process has no notion of a name does nothing
/// and says nothing. Claude Code has one: `--name` at creation and
/// `/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 --
/// `/context`, `/usage`, anything a CLI adds next month. A driver with 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.
///
/// Called only when the session is between turns; the waiting is done
/// above, once, for every driver.
fn run_command(&self, text: &str);
/// llama: not built, and refused; claude: `/compact`.
fn compact(&self);
/// Drops the conversation so far without ending the session.
///
/// The cheap half of managing a long session, and why it is a driver
/// operation rather than a manager one: compaction *reads* the whole
/// conversation in order to summarise it, so on a large context it is
/// itself one of the most expensive requests the session will make --
/// measured at 1.7 million tokens for one automatic compaction on
/// 2026-08-29. Clearing costs nothing, because nothing is sent.
///
/// Every implementation emits [`Event::Cleared`] so the transcript carries
/// the divider whatever the dialect did behind it.
fn clear(&self);
/// Stop attending to the process but leave it running, because this
/// server is going away and means to adopt it again.
@@ -162,12 +87,6 @@ pub trait Driver: Send + Sync {
/// is in flight, so a session's process outlives the server that started
/// it and is found again through `session::process`.
///
/// Its counterpart is [`Driver::stop`]. Every driver owes exactly one of
/// the two on the way out, and which one is the difference between "back
/// shortly" and "this conversation is over".
/// Whether a line written *now* would start a turn of its own, rather than
/// landing inside one already in flight.
///
/// Asked of the driver because the driver is the only thing that knows: it
/// updates this the instant it writes rather than when output returns. The
/// manager's `SessionStatus` is built from what has been *recorded*, so
@@ -175,8 +94,6 @@ pub trait Driver: Send + Sync {
/// and a second line sent in that gap lands inside the turn the first one
/// started. For a command that is the difference between being executed
/// and being read to the model as text, which is silent both ways.
///
/// Defaults to true for a driver with no turn of its own to be inside.
fn between_turns(&self) -> bool {
true
}
@@ -195,10 +112,6 @@ pub trait Driver: Send + Sync {
mod tests {
use super::*;
/// A tripwire for the wire format, not for serde. The app reads these
/// names, and getting one wrong does not fail loudly: a field the app
/// cannot find reads as a field the server chose not to send, which
/// several of them are allowed to be.
#[test]
fn multi_word_fields_go_out_in_camel_case() {
let json = serde_json::to_value(Event::Compacted {
@@ -218,10 +131,6 @@ mod tests {
);
}
/// The two events that take the context *down* are the point of the fold:
/// a figure measured before a compaction or a clear stopped being true at
/// that moment, and carrying it forward is how a session that had just
/// been cleared went on reporting the context it no longer had.
#[test]
fn a_compaction_and_a_clear_move_the_context_a_turn_cannot() {
let after = |current, event| context_after(current, &event);
@@ -249,8 +158,6 @@ mod tests {
);
assert_eq!(after(Some(9_617), Event::Cleared), None);
// A compaction that did not say how much it recovered leaves the
// context unknown rather than stale: it definitely moved.
assert_eq!(
after(
Some(128_402),
@@ -263,8 +170,6 @@ mod tests {
None
);
// A turn the dialect reported no context for is stale by a turn,
// which every context figure is, rather than unknown.
assert_eq!(
after(
Some(30_100),
@@ -276,7 +181,6 @@ mod tests {
Some(30_100)
);
// Everything else leaves it alone.
assert_eq!(
after(
Some(30_100),
server/src/session/echo.rs
-213
View File
@@ -1,63 +1,3 @@
//! The fake driver: no child process, just events. It proves the whole pipe --
//! spawn, transcript, SSE cursors, questions, interrupts, compaction -- and
//! stays useful afterwards as a connectivity check that costs no tokens. It
//! produces exactly the event vocabulary the real drivers do, so a UI that
//! renders echo sessions correctly renders the real thing.
//!
//! Every message is echoed back as a few streamed text deltas. A leading word
//! asks for something more specific:
//!
//! - `/tool [input]` -- a full tool run, start through end.
//! - `/bash [command]` -- a Bash call carrying that command, for what the
//! phone's shell highlighting does to a particular line.
//! - `/tools [n] [gap]` -- n calls back to back. `gap` is seconds between one
//! call and the next, which is what makes a run *grow* while somebody is
//! looking at it -- the only way to reach the state where a call opened on
//! its own gains a neighbour. The first call carries a screenshot, so that
//! state is also reachable with an image open full screen.
//! - `/question [text]` -- a question, exercising the answer path.
//! - `/ask` -- an AskUserQuestion call: two questions on one tool call, with
//! descriptions, a preview and a multi-select, which is the shape that is
//! awkward to get a real model to produce on demand. Wrapped in a run of
//! ordinary calls on each side, because being asked something happens in the
//! middle of work.
//! - `/slow [seconds]` -- a turn that stays running (default 30), so states
//! that only exist *while* something is happening can be looked at.
//! - `/error [text]` -- a failure, which is otherwise awkward to cause.
//! - `/peer [text]`, `/peer-turn` -- a message from another agent, in the
//! in-place and the live shapes.
//! - `/usage [what]` -- an invented rate-limit answer, or `/usage off` to take
//! it away. An echo session meters nothing, so it draws no usage bar until
//! this is set; what it exists for is the states that bar can be in, which
//! otherwise cost real quota to reach. `/usage 42`, `/usage 95 20`,
//! `/usage 42 never`, `/usage notloggedin`, `/usage unreachable`,
//! `/usage failed`. The vocabulary is `usage::Fixture`'s, where the states
//! live.
//! - `/limit [minutes]` -- a turn that stops because the account is out of
//! quota, saying the limit lifts in `minutes` (default 5, and `never` for a
//! limit with no stated reset). What it exists for is auto-resume, which is
//! otherwise reachable only by actually exhausting somebody's account: pair
//! it with `/usage 100 5` for a meter that agrees, and then `/usage 20` for
//! the moment the limit lifts. The wait itself is decided by the meter, so
//! those two commands are the whole rig.
//! - `/compact` -- a compaction, start to finish.
//! - `/stream N` -- one long answer in N small pieces, 50ms apart: the shape a
//! real model's reply arrives in, and the one where the row a reader is
//! anchored to is the row that keeps changing height.
//! - `/mixed N` -- N beats of an interleaved transcript: rows of every shape
//! and height the app draws, in one session, which is what a scrolling
//! problem needs in order to be reproduced twice the same way.
//! - `/table [columns]` -- a markdown table with cells too long for one line.
//! - `/subagent [n]` -- n subagents at once (default 1), each named
//! "helper k", its prompt recorded as its own first user message: a
//! streamed reply, one Bash call, then it finishes about three seconds
//! later, the same lifecycle a real Task call has -- see `SUBAGENTS.md`.
//!
//! `/slow` earns its place: a queued message, a Stop button and a spinner are
//! states that only exist mid-turn, and the obvious way to get one -- ask a
//! real model to sleep -- does not work. It declines and answers instantly, so
//! the state never arrives and the attempt still costs a turn.
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::{Arc, Mutex};
@@ -68,19 +8,10 @@ use super::driver::{
};
use super::subagent::Subagents;
/// Delay between streamed deltas -- long enough that streaming is visibly
/// streaming, short enough that tests waiting on a full turn stay fast.
const DELTA_DELAY: Duration = Duration::from_millis(50);
/// How long a fake compaction takes. A measured one, near enough: driving a
/// real session through `/compact` on 2026-08-29 took 13 seconds for a small
/// conversation. Three seconds -- what this was -- is too short to look at the
/// row that only exists while a compaction is running.
const COMPACT_TIME: Duration = Duration::from_secs(13);
/// A question echo is waiting on, and the tool call it belongs to. `call` is
/// `None` for `/question`, which asks on its own the way a permission does;
/// `Some` for `/ask`, where several questions share one call.
struct PendingQuestion {
id: String,
call: Option<String>,
@@ -88,34 +19,15 @@ struct PendingQuestion {
pub struct EchoDriver {
sink: EventSink,
/// Whether a turn is in flight, and what arrived during it.
///
/// A real CLI holds a message sent mid-turn and injects it at the next tool
/// boundary; echo used to answer it on the spot, which made it the wrong
/// shape for testing anything about queueing.
busy: Arc<AtomicBool>,
/// Held messages with the id of the `MessageQueued` each one announced, so
/// the announcement can say which waiting bubble it resolves.
queued: Arc<Mutex<Vec<Held>>>,
/// Where `/mixed` writes the attachments it references, which is the same
/// directory the files route serves them from.
session_dir: PathBuf,
/// Ids of the questions awaiting an answer, in the order asked. A list
/// because `/ask` puts up to four on one tool call, and the turn resumes
/// when the last is answered rather than the first.
pending_questions: Mutex<Vec<PendingQuestion>>,
/// The invented rate-limit answer `/usage` sets, shared with the usage
/// monitor that serves it. An echo session meters nothing, so this is unset
/// until a test asks for something -- see [`crate::usage::Fixture`].
usage: crate::usage::Fixture,
/// A pretend context, so the status row has something that behaves the way
/// a real one does: it grows with each turn, drops to what the compaction
/// says it recovered, and a clear leaves it unmeasured. What is real is
/// which way the numbers move.
context: Arc<AtomicU64>,
/// This session's subagents -- see `SUBAGENTS.md`. `/subagent` is the
/// test rig for the same registry the claude driver routes real Task
/// calls into.
subagents: Arc<Subagents>,
}
@@ -139,17 +51,7 @@ impl EchoDriver {
}
}
/// An AskUserQuestion call, in the shape the CLI sends one.
///
/// Two questions on one call, because that is where the display is hardest
/// and where it was wrong. Written out in full rather than generated so it
/// carries the parts that are easy to leave out of a fixture -- a header, an
/// option with a description, an option with a preview block, and a
/// multi-select.
fn ask_user_question(&self) {
// Written once, in the shape the events carry, and turned into the tool
// call's own input below -- the CLI sends both, and two hand-written
// copies of one question would drift.
let asked = [
(
"Theme",
@@ -239,7 +141,6 @@ impl EchoDriver {
header: Some(header.to_string()),
options,
multi_select: multi,
// The call that asked, so all of it draws as one thing.
about: Some(call.clone()),
});
}
@@ -248,23 +149,10 @@ impl EchoDriver {
});
}
/// One typed line, whether it arrived as a message or as a command.
///
/// `announce` is the whole difference: 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, attachments: Vec<AttachmentRef>, announce: bool) {
let sink = self.sink.clone();
// Mid-turn messages are held rather than answered, the way a real CLI
// holds them until the next tool boundary. Without this the session went
// idle the instant one arrived, and every state that only exists while
// something is queued was untestable.
if self.busy.load(Ordering::SeqCst) {
// The waiting is recorded, exactly as the real driver records it:
// the phone draws its pending bubbles from the server, so an echo
// session has to produce the same events.
let id = super::random_hex();
self.queued
.lock()
@@ -307,7 +195,6 @@ impl EchoDriver {
} else {
rest.trim().to_string()
},
// Stamped by the manager, exactly as a real one is.
turn_start: None,
});
self.emit(Event::Status {
@@ -361,12 +248,6 @@ impl EchoDriver {
return;
}
// A turn that ends the way a real one does when the account runs out:
// the same event a real driver reports, so what acts on it -- the
// transcript row and `crate::resume` -- is exercised rather than
// imitated. The meter it should agree with is `/usage`'s fixture,
// deliberately separate: the two disagreeing is a state worth being
// able to produce, since it is what a stale reset time looks like.
if let Some(rest) = text.strip_prefix("/limit") {
if announce {
self.emit(Event::MessageTaken {
@@ -394,11 +275,6 @@ impl EchoDriver {
return;
}
// `n` subagents at once, each with its own transcript in the
// registry a real Task call routes into -- see `SUBAGENTS.md`. The
// parent's own Task calls end when their subagent does, three
// seconds later, which is long enough to see the running state on
// the phone before it finishes.
if let Some(rest) = text.strip_prefix("/subagent") {
let n = rest.trim().parse::<usize>().unwrap_or(1).clamp(1, 8);
if announce {
@@ -443,9 +319,6 @@ impl EchoDriver {
return;
}
// The same word the real CLI takes, so a phone drives both the same way.
// `Driver::compact` is what the manager's route calls; this is the typed
// path onto it.
if text.trim() == "/compact" {
if announce {
self.emit(Event::MessageTaken {
@@ -501,8 +374,6 @@ impl EchoDriver {
return;
}
// Checked before `/tool`, which is a prefix of it: matching the shorter
// one first would read "/tools 4" as a single tool whose input is "s 4".
let many_tools = text.strip_prefix("/tools").map(|rest| {
let mut words = rest.split_whitespace();
// At least two, because one call is not a run of them.
@@ -565,9 +436,6 @@ impl EchoDriver {
let _ = sink.send(event);
};
let finish = || finish_turn(&sink, &queued, &busy);
// Echo takes a message the instant it gets one, but says so anyway:
// a driver that skips this leaves the phone holding a message it
// thinks is still queued.
if announce {
send(Event::MessageTaken {
id: None,
@@ -580,7 +448,6 @@ impl EchoDriver {
});
if let Some(linger) = linger {
// A delta a second: visibly alive rather than merely slow.
let seconds = linger.as_secs();
for remaining in (1..=seconds).rev() {
send(Event::AssistantText {
@@ -623,14 +490,6 @@ impl EchoDriver {
"timeout": 5000,
}),
});
// The first call carries a screenshot, and only the first.
// That is what makes this rig cover the case a growing run
// is about: an image opened full screen from a call that is
// alone, and then a second call turning that row into a
// group. The dialog used to be inside the row, so the reader
// was thrown back to the transcript by the session making
// another tool call. The first call is the one that is on
// its own for a whole `gap`.
if i == 1 {
let part = serde_json::json!({
"source": {"media_type": "image/png", "data": SAMPLE_PNG}
@@ -653,11 +512,6 @@ impl EchoDriver {
return;
}
// One long answer arriving in small pieces, which is what a real
// model does and what `/slow` does not: `/slow` emits a line a
// second, so its message grows in steps a reader can watch one at a
// time. A jump caused by the *anchor row itself* changing height
// needs growth that is continuous.
if let Some(pieces) = stream {
for i in 0..pieces {
let len = 3 + (i * 7) % 14;
@@ -730,8 +584,6 @@ impl EchoDriver {
});
tokio::time::sleep(DELTA_DELAY).await;
}
// A conversation gets bigger, so the pretend context does too:
// roughly a hundred tokens a turn plus the words themselves.
let spent = text.split_whitespace().count() as u64;
send(Event::UsageDelta {
tokens: spent,
@@ -763,8 +615,6 @@ impl EchoDriver {
driver
}
/// Sends are infallible from the driver's point of view: a closed sink
/// means the session is being torn down.
fn emit(&self, event: Event) {
let _ = self.sink.send(event);
}
@@ -776,13 +626,6 @@ impl EchoDriver {
/// that it occupies an image's worth of space.
const SAMPLE_PNG: &str = "iVBORw0KGgoAAAANSUhEUgAAABAAAAAKCAIAAAAy3EnLAAAAIklEQVR42mPo3PILiOTk9ICIGDYDyRqIVwphk65h1A9EsAGCYdJRj+JH4wAAAABJRU5ErkJggg==";
/// One beat of `/mixed`: a row shape chosen by position, so the same N always
/// produces the same transcript.
///
/// Repeatable on purpose. A scrolling fault is judged by watching the same
/// content behave differently, and a rig that produced a different transcript
/// each run would make every comparison an argument about whether the content
/// changed.
async fn write_beat(sink: &EventSink, session_dir: &Path, beat: usize) {
let send = |event: Event| {
let _ = sink.send(event);
@@ -796,10 +639,6 @@ async fn write_beat(sink: &EventSink, session_dir: &Path, beat: usize) {
1 => 60,
_ => 220,
};
// Deliberately ragged: each word's length is a function of its
// position, so no two lines wrap the same way. A paragraph of
// uniform tokens looks identical at every offset, which makes it
// impossible to tell a scroll of one line from a scroll of ten.
let body: String = (0..words)
.map(|w| {
let len = 3 + (w * 7 + beat * 3) % 14;
@@ -810,7 +649,6 @@ async fn write_beat(sink: &EventSink, session_dir: &Path, beat: usize) {
delta: format!("\n\nParagraph at beat {beat}:\n{body}"),
});
}
// One call on its own -- drawn as a card rather than a group.
2 => {
let id = format!("t-{}", super::random_hex());
send(Event::ToolStart {
@@ -824,8 +662,6 @@ async fn write_beat(sink: &EventSink, session_dir: &Path, beat: usize) {
is_error: false,
});
}
// A run of three, which the app folds into one collapsed group -- the
// row whose identity depends on what is next to it.
3 => {
for i in 1..=3 {
let id = format!("t-{}", super::random_hex());
@@ -851,8 +687,6 @@ async fn write_beat(sink: &EventSink, session_dir: &Path, beat: usize) {
});
}
}
// An image, under the call that produced it, which is where a real
// screenshot lands.
4 => {
let id = format!("t-{}", super::random_hex());
send(Event::ToolStart {
@@ -875,7 +709,6 @@ async fn write_beat(sink: &EventSink, session_dir: &Path, beat: usize) {
is_error: false,
});
}
// Somebody else's voice, which is its own row shape.
_ => {
send(Event::PeerMessage {
from: format!("beat-{beat}-peer"),
@@ -884,17 +717,9 @@ async fn write_beat(sink: &EventSink, session_dir: &Path, beat: usize) {
});
}
}
// Slow enough that the phone renders each beat as it arrives rather than
// composing the whole run in one frame -- which is the condition a scrolling
// fault actually happens under.
tokio::time::sleep(Duration::from_millis(120)).await;
}
/// One `/subagent` helper: a few streamed words, one Bash call, then
/// `Status::Exited` about three seconds after it started -- long enough that
/// its `Running` state can be seen on the phone before it finishes. The
/// parent's own Task call for it ends at the same moment, the same way a
/// real Task's `tool_result` ends it.
async fn run_helper(id: String, sink: EventSink, subagents: Arc<Subagents>) {
let start = tokio::time::Instant::now();
for word in "Working on it now.".split_inclusive(' ') {
@@ -942,13 +767,6 @@ async fn run_helper(id: String, sink: EventSink, subagents: Arc<Subagents>) {
/// three, because all three are what the `MessageTaken` at the other end owes.
type Held = (String, String, Vec<AttachmentRef>);
/// A markdown table [columns] wide, with cells too long for one line.
///
/// Both halves matter. Long cells are what the renderer used to cut off with an
/// ellipsis, and a cut cell looks exactly like a short one, so a fixture of
/// tidy one-word values would have rendered perfectly while the defect was
/// still there. The column count decides whether the table fits the screen.
///
/// Written out as markdown rather than assembled from a grid type because what
/// is being tested is the renderer's parse of the syntax a model actually
/// writes, pipes and alignment row included.
@@ -1033,10 +851,6 @@ impl Driver for EchoDriver {
!self.busy.load(Ordering::SeqCst)
}
/// Really droppable, which is what makes this the rig for the phone's side
/// of it: the held message is this driver's own and nothing has been written
/// anywhere, so a tap here exercises the whole path through to the bubble
/// disappearing on every device. The Claude driver can only ever refuse.
fn unqueue(&self, id: &str) -> Unqueued {
let mut queued = self.queued.lock().unwrap();
let Some(at) = queued.iter().position(|(waiting, ..)| waiting == id) else {
@@ -1055,9 +869,6 @@ impl Driver for EchoDriver {
self.handle(text, attachments, 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);
}
@@ -1073,8 +884,6 @@ impl Driver for EchoDriver {
return;
};
let answered = pending.remove(at);
// Whether anything on the same call is still unanswered: a tool that
// asked four questions ends once, not four times.
let waiting = answered
.call
.as_ref()
@@ -1090,9 +899,6 @@ impl Driver for EchoDriver {
output: format!("answered: {answer}"),
is_error: false,
});
// The work carries on where it left off, which is what makes the
// asked-here row a boundary with a group on each side rather than
// the last thing in the turn.
self.some_calls("after");
} else {
self.emit(Event::AssistantText {
@@ -1105,16 +911,12 @@ impl Driver for EchoDriver {
}
fn interrupt(&self) {
// Nothing real to stop; a pending question is abandoned so the session
// isn't stuck awaiting input forever.
self.pending_questions.lock().unwrap().clear();
self.emit(Event::Status {
state: SessionStatus::Idle,
});
}
// Nothing to forward: this process has no notion of what the conversation
// is called, and the rename has already happened where the name lives.
fn set_title(&self, _title: &str) {}
fn set_permission_mode(&self, mode: &str) {
@@ -1129,11 +931,6 @@ impl Driver for EchoDriver {
});
}
/// A compaction with nothing to compact. The counts are invented, like
/// everything else this driver says -- what is real is the shape and the
/// order: busy, a pause long enough to see, then the result. The only other
/// way to reach those states is to fill a real session's context and spend
/// two minutes of somebody's account getting it back.
fn compact(&self) {
let sink = self.sink.clone();
let queued = Arc::clone(&self.queued);
@@ -1145,10 +942,6 @@ impl Driver for EchoDriver {
state: SessionStatus::Compacting,
});
tokio::time::sleep(COMPACT_TIME).await;
// What it says it recovered is what the pretend context becomes, so
// the figure on the status row and the one on the divider agree --
// two numbers about the same moment disagreeing is the thing this
// rig exists to catch.
context.store(9_617, Ordering::SeqCst);
let _ = sink.send(Event::Compacted {
pre_tokens: Some(128_402),
@@ -1159,17 +952,11 @@ impl Driver for EchoDriver {
});
}
/// The same marker a real driver leaves, and nothing else -- there is
/// no context here to drop. It exists so the phone's divider, its
/// scroll behaviour and the transcript's shape can be exercised
/// without spending a real session's context to produce one.
fn clear(&self) {
self.context.store(0, Ordering::SeqCst);
let _ = self.sink.send(Event::Cleared);
}
/// Nothing to detach from and nothing to stop: the echo driver has no
/// process, so both halves of the way out are already done.
fn detach(&self) {}
fn stop(&self) {}
server/src/session/import.rs
-294
View File
@@ -1,22 +1,3 @@
//! Adopting a Claude Code session that already exists on a machine.
//!
//! Claude Code keeps every session as JSONL under
//! `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl`, and the CLI can
//! be told to continue one with `--resume <id>`. This module is the two
//! halves of putting that behind the phone: asking a machine what it has,
//! and turning one of those files into the transcript a phone reads.
//!
//! **Continuing is not this module's job.** `claude.rs` already resumes
//! whenever a session directory holds a resume token, for crash recovery,
//! so an import is that same path with the token written up front. There
//! is deliberately no second way to start a session.
//!
//! **The phone never names a file.** It picks an id out of what this
//! module enumerated, and the path is looked up again on the server -- the
//! same rule the setups model follows for providers, and for the same
//! reason: an enrolled token must not be able to turn into "read me this
//! arbitrary path".
use std::collections::HashMap;
use anyhow::{Context, Result};
@@ -26,77 +7,34 @@ use serde_json::Value;
use super::driver::{self, Event};
use super::transport::{Launch, Transport};
/// How much of a transcript's tail is replayed into the phone's view.
///
/// The imported conversation is for reading; *continuing* it is the CLI's job
/// through `--resume`, and it reads the whole file itself. So this is a
/// display budget, and it needs to be one: these files reach tens of megabytes
/// and every line would otherwise cross a WireGuard link to a phone.
const REPLAY_LINES: usize = 2000;
/// Whether a session is open in a CLI somewhere. Three answers, because
/// "nobody could check" is not "nobody is using it" -- collapsing them puts
/// the dangerous case behind the safe word.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum InUse {
/// Checked, and nothing is running it.
No,
/// Checked, and a live CLI has it open.
Yes,
/// The machine does not keep the record this is read from, so there is no
/// answer to be had -- not an answer of "no".
Unknown,
}
/// One Claude Code session found on a machine.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Importable {
/// The CLI's own session id, which is both the file name and the
/// `--resume` token.
pub id: String,
/// Where that session was working, offered as the imported session's cwd
/// so it resumes pointing at the same tree.
pub cwd: String,
/// The first thing a person said in it, for recognising it in a list.
pub title: String,
/// Epoch seconds, for ordering by "what I was last doing".
pub modified: f64,
pub lines: usize,
/// How many tokens the model was holding at the last turn: the input side
/// of the most recent assistant message's usage, which is the closest thing
/// to "what continuing this costs" and is a number the CLI recorded rather
/// than one inferred from the file.
///
/// Size and this disagree in the direction that matters. Most of a big
/// transcript is usually history from before a compaction, which the model
/// is no longer given: of the 133 MB session behind the 2026-08-29
/// incident, 99% of the bytes sat before its last compaction summary.
///
/// `None` when no assistant turn has recorded usage yet -- which is not
/// zero, and is why this is an option.
pub context_tokens: Option<u64>,
/// Size of the file, in bytes. Reported because it predicts what
/// continuing the session will cost and lines do not: these transcripts
/// embed screenshots as base64, so one line can be a megabyte. The session
/// behind the 2026-08-29 incident was 65 MB across 13,000 lines.
///
/// Shown rather than warned about: importing a large session is a choice
/// somebody is entitled to make.
pub bytes: u64,
/// Whether [`title`](Self::title) is a name somebody chose rather than
/// something read out of the conversation. Worth the reader knowing: a name
/// is a claim about what a session *is*, and a last message is only the
/// last thing that happened in it.
pub named: bool,
/// Whether a CLI is running this session right now.
///
/// The load-bearing field on this struct. Importing a session already open
/// puts a second `--resume` on one file: the conversation gets duplicated
/// into it, both copies read each other's writes as work done elsewhere,
/// and the adopted one is billed for re-reading everything -- measured on
/// 2026-08-29 at 65 MB and 154 screenshots.
pub in_use: InUse,
/// Where it lives. Not serialized: the phone chooses by id and the server
/// resolves the path, so a path never crosses the wire either direction.
@@ -104,14 +42,7 @@ pub struct Importable {
pub path: String,
}
/// Asks `transport`'s machine which Claude Code sessions it has.
///
/// One command rather than one per file: over ssh each would be its own
/// connection and handshake. `stat -c` is GNU-specific, which is the thing to
/// change first if this ever meets a BSD.
pub async fn list(transport: &Transport) -> Result<Vec<Importable>> {
// Which sessions are open right now, before the files themselves.
//
// Claude Code writes a descriptor per live session at
// `~/.claude/sessions/<pid>.json`, and records `procStart` -- the kernel's
// start time for that pid -- for the same reason `session::process` does: a
@@ -119,35 +50,17 @@ pub async fn list(transport: &Transport) -> Result<Vec<Importable>> {
// otherwise mark a session as open for as long as something else held its
// number. Checking both is what makes this a measurement.
//
// The `LIVEKNOWN` line says the directory was there to be read at all.
// Without it an old CLI that keeps no descriptors would look exactly like a
// machine with nothing running.
//
// Then two questions per file, both answered from the end of it. A rename
// if there was one, grepped over the whole file rather than its tail
// because a session can be named early and talked in for hours after. Then
// the last several things a person said -- the *last*, because the question
// this answers is "which one was I just in", and several because the final
// ones are often the CLI's own.
//
// Tool results are excluded rather than typed messages included, and the
// difference matters: a tool result is *also* a user record, so grepping
// the type alone gave a session that ended mid-tool a tail of empty records.
// But matching only a string `content` was worse -- a message carrying an
// attachment stores its text in a list, so that reading lost twenty rows
// rather than two. Excluding `tool_use_id` keeps both shapes of a real
// message and drops the one that is not.
let script = listing_script(r#""$HOME"/.claude/projects/*/*.jsonl"#);
let launch = Launch::new("sh", vec!["-c".to_string(), script], None);
parse_listing(&transport.capture(&launch).await?)
}
/// The same listing, for one session named by id.
///
/// Importing needs everything a row holds, and used to get it by listing
/// *every* session and searching the result -- a full read of every transcript
/// on the machine, seconds of it, to answer a question about one file, paid
/// once per import in a batch. Same script, same parsing, one glob narrower.
pub async fn find(transport: &Transport, id: &str) -> Result<Option<Importable>> {
if !is_session_id(id) {
return Ok(None);
@@ -163,12 +76,6 @@ pub async fn find(transport: &Transport, id: &str) -> Result<Option<Importable>>
.find(|candidate| candidate.id == id))
}
/// What the machine is asked, over whichever set of files `glob` names.
///
/// One script with the glob substituted rather than two that drift: a row has
/// to mean the same thing whether it came from a listing or a lookup. The glob
/// is this module's own text; the only thing that crosses from outside is the
/// id, which stays an argument and is checked by [`is_session_id`] first.
fn listing_script(glob: &str) -> String {
// `replace` rather than `format!`: this is shell, so it is full of braces,
// and every one would have to be doubled to survive a format string --
@@ -201,7 +108,6 @@ for f in {glob}; do
done
"#;
/// Rows out of what [`listing_script`] printed, with `in_use` filled in.
fn parse_listing(found: &str) -> Result<Vec<Importable>> {
let mut live = std::collections::HashSet::new();
let mut checkable = false;
@@ -225,15 +131,6 @@ fn parse_listing(found: &str) -> Result<Vec<Importable>> {
// addresses: `--resume` takes it, deleting globs for it, the in-flight
// registry is keyed on it, and the phone keys its list on it -- which
// turned two rows sharing an id into a crash rather than a confusion.
//
// It is a real state of the machine, not corruption: resuming from a
// different working directory makes the CLI write a second file under that
// directory's project folder with the same id. One is then usually a stub
// of a few hundred bytes.
//
// So the copy with the most in it wins, and the row's `cwd` comes from that
// same copy. Ties go to the more recent, and the *stub* is often the more
// recent, so size has to be the first key rather than the tie-break.
sessions.sort_by(|a, b| {
b.lines
.cmp(&a.lines)
@@ -242,15 +139,10 @@ fn parse_listing(found: &str) -> Result<Vec<Importable>> {
let mut seen = std::collections::HashSet::new();
sessions.retain(|session| seen.insert(session.id.clone()));
// Most recent first, and only that. Naming was tried as the first key and
// is a worse list: it buries what somebody was just doing under everything
// they ever named. A name still shows, as the row's title and as a word
// beside it.
sessions.sort_by(|a, b| b.modified.total_cmp(&a.modified));
Ok(sessions)
}
/// One line of [`list`]'s output, or nothing if it is not one.
fn parse_row(line: &str) -> Option<Importable> {
let mut fields = line.splitn(6, '\t');
let modified: f64 = fields.next()?.trim().parse().ok()?;
@@ -279,17 +171,12 @@ fn parse_row(line: &str) -> Option<Importable> {
if !is_hidden(&record)
&& let Some(text) = first_line_of(&record)
{
// Kept rather than broken out of: these arrive oldest first, so the
// last to survive the filter is the most recent thing said.
said = Some(text);
}
}
Some(Importable {
id,
// Filled in by `list`, which is the only thing that knows: it takes one
// command to ask a machine, and asking per row would be one ssh
// connection each.
in_use: InUse::Unknown,
cwd: cwd.unwrap_or_default(),
// A name somebody typed outranks anything read out of the conversation,
@@ -318,9 +205,6 @@ fn context_tokens(usage: &str) -> Option<u64> {
if usage.trim().is_empty() {
return None;
}
// The leading quote matters: without it `"input_tokens"` also matches
// inside `"cache_read_input_tokens"`, and the same number is counted three
// times.
let field = |name: &str| -> u64 {
usage
.split_once(&format!("\"{name}\":"))
@@ -338,12 +222,6 @@ fn context_tokens(usage: &str) -> Option<u64> {
))
}
/// The first line of what a person typed, short enough for a list row.
///
/// None for the CLI's own plumbing. A slash command, the caveat wrapped around
/// a local command's output, and an injected reminder are all stored as
/// ordinary user records without `isMeta` -- so titling by "first user record"
/// gave a list where most rows read `<command-name>/clear</command-name>`.
fn first_line_of(record: &Value) -> Option<String> {
let text = text_of(record.get("message")?.get("content")?);
let first = text.lines().find(|line| !line.trim().is_empty())?.trim();
@@ -354,17 +232,11 @@ fn first_line_of(record: &Value) -> Option<String> {
(!trimmed.is_empty()).then_some(trimmed)
}
/// Records the transcript should not show: a subagent's private conversation,
/// and the CLI's own injected notes. The same rule the live translator applies
/// -- a sidechain is another agent talking to itself, and duplicating it would
/// show the reader two conversations interleaved as one.
fn is_hidden(record: &Value) -> bool {
record.get("isSidechain").and_then(Value::as_bool) == Some(true)
|| record.get("isMeta").and_then(Value::as_bool) == Some(true)
}
/// Whether a `tool_result` block says the call itself failed.
///
/// One reader for the field rather than one per caller: the live
/// translator (`translate.rs`) and this replay of the CLI's own file look
/// at the same block shape, and a call drawn as failed in one and as
@@ -392,12 +264,6 @@ fn text_of(content: &Value) -> String {
}
}
/// Whether a directory the machine recorded is still there.
///
/// A session's recorded cwd can outlive the directory: these files go back
/// months, and a checkout that moved leaves every session from before it
/// pointing at a path that is gone. Resuming into one fails at `cd` before the
/// CLI starts.
pub async fn directory_exists(transport: &Transport, path: &str) -> bool {
if path.is_empty() {
return false;
@@ -411,8 +277,6 @@ pub async fn directory_exists(transport: &Transport, path: &str) -> bool {
transport.capture(&launch).await.is_ok()
}
/// Reads the tail of one session's file, as the raw JSONL.
///
/// `tail` rather than the whole file, and as [`Launch`] arguments rather than a
/// shell string, so the path is an argument and never syntax.
///
@@ -431,15 +295,6 @@ pub async fn read_tail(transport: &Transport, path: &str) -> Result<String> {
.with_context(|| format!("reading {path}"))
}
/// Claude Code's stored JSONL as this project's events.
///
/// A partial first line is expected and ignored: `tail -n` cuts at a line
/// boundary, but the *file* may have been appended to since.
///
/// `session_dir` is where images found along the way are written, the same
/// place and by the same function the live translator uses -- so a screenshot
/// looks identical whether it was watched happening or replayed afterwards.
/// Only the *reference* reaches the phone.
pub fn events_from(text: &str, session_dir: &std::path::Path) -> Vec<Event> {
let mut events = Vec::new();
// What the newest record that had an opinion says the session is doing.
@@ -482,14 +337,6 @@ pub fn events_from(text: &str, session_dir: &std::path::Path) -> Vec<Event> {
events
}
/// A message from another agent, as the CLI reports one.
///
/// Measured from a real session file (2026-08-29): the record is a `user` one
/// marked `isMeta`, and its `origin` carries `kind: "peer"`, the sending
/// session's `name`, and the message as `body`. The message content beside it
/// is the same text wrapped in a preamble written for the model rather than for
/// a person, so the body is what a reader is shown.
///
/// Shared with the live driver, which finds the same `origin` object on a
/// different record -- so this reads the object and not the record around it.
/// One function because it is one wire format: two copies would drift the first
@@ -508,27 +355,10 @@ pub(in crate::session) fn peer_message(record: &Value) -> Option<Event> {
.unwrap_or("another session")
.to_string(),
text: origin.get("body").and_then(Value::as_str)?.to_string(),
// The session file has it in the right place already.
turn_start: None,
})
}
/// Whether this record means the session is working, as far as the file can
/// say.
///
/// The one thing a session file does not contain is the CLI saying "this turn
/// is over": there is no `result` record. What there is instead is why the last
/// assistant message stopped -- `tool_use` means a call is being made and more
/// is coming, anything else means the model has finished talking. Anything on
/// the user's side means the session has something to answer.
///
/// `None` is the third answer and it matters: a record that says nothing about
/// the turn leaves the status alone rather than voting for idle.
///
/// What this cannot see is a session that stopped existing mid-turn -- its
/// file's last record still says `tool_use`, so it reads as working forever.
/// Nothing in the file distinguishes that from a model thinking, and inventing
/// a timeout would replace a stale reading with a confident wrong one.
fn turn_state(record: &Value) -> Option<super::driver::SessionStatus> {
use super::driver::SessionStatus;
match record.get("type").and_then(Value::as_str)? {
@@ -551,14 +381,10 @@ fn push_user(events: &mut Vec<Event>, content: &Value, session_dir: &std::path::
// same voice.
if let Value::Array(blocks) = content {
for block in blocks {
// A picture the person attached to their own message rather than
// one a tool produced. Same block shape, one level up.
push_images(events, std::slice::from_ref(block), session_dir, None);
if block.get("type").and_then(Value::as_str) == Some("tool_result")
&& let Some(id) = block.get("tool_use_id").and_then(Value::as_str)
{
// Before the tool's own row, matching the live translator: a
// screenshot belongs to the call that took it.
if let Some(Value::Array(parts)) = block.get("content") {
push_images(events, parts, session_dir, Some(id));
}
@@ -584,10 +410,6 @@ fn push_user(events: &mut Vec<Event>, content: &Value, session_dir: &std::path::
}
}
/// Saves every image block in `parts` and references each one. `about` is the
/// call the images came out of, or `None` for one a person attached to their
/// own message -- the same distinction the live translator makes, so replayed
/// history draws a screenshot under the call that took it.
fn push_images(
events: &mut Vec<Event>,
parts: &[Value],
@@ -638,20 +460,6 @@ fn push_assistant(events: &mut Vec<Event>, content: &Value) {
}
}
/// Removes each id it is given and prints one `<id>\t<state>` line per id.
///
/// The three states are every way removing one id can end: `deleted` if at
/// least one file went, `missing` if the glob matched nothing, `failed` if an
/// `rm` refused. "Not there" is deliberately kept apart from "it broke" --
/// only one of them is worth retrying.
///
/// Every copy of each id, not the first. The same id can name a file under two
/// project directories, and stopping at the first left the other behind, so the
/// row came back on the next listing after a delete that reported success.
/// `failed` therefore sticks once set.
///
/// Ids arrive as arguments rather than in the script text; `is_session_id` is
/// what keeps one from globbing its way out of the projects directory.
const DELETE_SCRIPT: &str = r#"
for id do
state=missing
@@ -667,8 +475,6 @@ for id do
done
"#;
/// Deletes sessions [`list`] reported, and says what happened to each.
///
/// By id, resolved on the machine against what it actually has, so the caller
/// never names a file -- the same rule importing follows, and it matters more
/// here: this one removes something.
@@ -690,9 +496,6 @@ pub async fn delete(
transport: &Transport,
ids: &[String],
) -> Result<HashMap<String, Result<(), String>>> {
// Refused here rather than on the machine: `is_session_id` is what keeps an
// id from walking out of the projects directory. It fails only itself --
// one malformed id is not a reason to leave the other five in place.
let (safe, mut outcomes): (Vec<&String>, HashMap<String, Result<(), String>>) =
ids.iter().fold(
(Vec::new(), HashMap::new()),
@@ -712,16 +515,6 @@ pub async fn delete(
return Ok(outcomes);
}
// The file name *is* the id, so the machine can find it by name. This used
// to call `list` and search its output, which is correct and costs a full
// read of every transcript on the machine -- around four seconds against a
// gigabyte of them, per delete.
//
// Every copy of each id, not the first: the same id can name a file under
// two project directories, and stopping at the first left the other behind.
//
// Each id prints its own verdict rather than the loop exiting on the first
// failure, which would leave every id after it unexplained.
let mut args = vec![
"-c".to_string(),
DELETE_SCRIPT.to_string(),
@@ -730,8 +523,6 @@ pub async fn delete(
args.extend(safe.iter().map(|id| (*id).clone()));
let launch = Launch::new("sh", args, None);
// A failure to run the script at all is the machine being unreachable,
// which is true of every id in the batch rather than of any one of them.
let reported = transport
.capture(&launch)
.await
@@ -765,22 +556,10 @@ pub async fn delete(
Ok(outcomes)
}
/// Whether an id is one of ours to put in a shell glob.
///
/// Both places that resolve an id interpolate it into
/// `$HOME/.claude/projects/*/"$1".jsonl`. That is an argument rather than
/// script text, so a shell cannot be talked into running something -- but a `/`
/// or a `..` inside it still walks the glob out of the directory the id is
/// supposed to name, and [`delete`] removes whatever it lands on.
///
/// Claude Code names each transcript with a uuid, so hex and dashes is the
/// whole alphabet. Refused rather than escaped.
fn is_session_id(id: &str) -> bool {
!id.is_empty() && id.len() <= 64 && id.bytes().all(|b| b.is_ascii_hexdigit() || b == b'-')
}
/// How often an imported session checks whether its source file grew.
///
/// A poll rather than a watch, because the file may be on another machine and
/// there is no portable way to be told. Ten seconds is chosen against the cost
/// of an ssh round trip rather than against how fast a person types.
@@ -793,8 +572,6 @@ pub const SYNC_INTERVAL: std::time::Duration = std::time::Duration::from_secs(10
#[derive(Debug, Clone, Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Cursor {
/// Server-side only, resolved once at import. Nothing accepts a path from
/// the phone; this is the path *we* found.
pub path: String,
/// Lines of that file already accounted for -- whether replayed into
/// the transcript or skipped because this session wrote them itself.
@@ -823,7 +600,6 @@ pub fn write_cursor(session_dir: &std::path::Path, cursor: &Cursor) {
}
}
/// How many lines the source file has now.
pub async fn line_count(transport: &Transport, path: &str) -> Result<usize> {
let launch = Launch::new("wc", vec!["-l".to_string(), path.to_string()], None);
let out = transport.capture(&launch).await?;
@@ -833,17 +609,6 @@ pub async fn line_count(transport: &Transport, path: &str) -> Result<usize> {
.with_context(|| format!("couldn't read a line count out of {out:?}"))
}
/// What the CLI's own file says a session is holding, for a session this
/// server has no measurement of.
///
/// A restarting server has been told nothing, and a session that has not
/// taken a turn since will not tell it -- so a conversation that is nearly
/// full reads as one nobody has counted until somebody sends a message to
/// it. The CLI records the figure on every assistant message, so it is
/// there to be read rather than waited for, and reading it is a
/// measurement rather than a guess: the same three fields, from the same
/// file, that the import list reports.
///
/// A clear needs no special case here even though it makes the last usage
/// in a file stale. Clearing gives the CLI a *new* session id, which the
/// reader persists as the resume token, so this looks in a file that has
@@ -854,9 +619,6 @@ pub async fn line_count(transport: &Transport, path: &str) -> Result<usize> {
/// Not knowing is a state the status row draws, so there is nothing to be
/// gained by inventing a number here.
pub async fn context_of(transport: &Transport, session_id: &str) -> Option<u64> {
// The same guard `delete` explains, applied to the other member of the
// set: this one only reads, but a glob that can leave the directory is
// worth closing in both places rather than in the dangerous one only.
if !is_session_id(session_id) {
return None;
}
@@ -883,8 +645,6 @@ done
context_tokens(&transport.capture(&launch).await.ok()?)
}
/// Events from the lines after `after`, which is a 0-based count of lines
/// already accounted for.
pub async fn replay_after(
transport: &Transport,
path: &str,
@@ -907,17 +667,6 @@ pub async fn replay_after(
mod tests {
use super::*;
/// One session id, two files, one row.
///
/// Resuming a session from a different working directory makes the CLI
/// write a second file with the same id under that directory's project
/// folder, so this is an ordinary state of a machine rather than a
/// corrupt one. Everything downstream addresses a session by id, and
/// the phone keys its list on it, so two rows sharing one was a crash.
///
/// The stub is deliberately the *newer* of the two here, because that
/// is how the real case looked: ordering by recency alone picks the
/// near-empty copy and describes the session by the wrong cwd.
#[test]
fn a_session_recorded_under_two_projects_is_offered_once() {
let id = "3114dee1-2f95-4de0-9c04-3d6fcc594afe";
@@ -933,17 +682,9 @@ mod tests {
assert_eq!(rows.len(), 1, "one id is one row: {rows:#?}");
assert_eq!(rows[0].lines, 412, "the conversation, not the stub");
// The cwd has to come from the copy that was kept, because that is
// the directory `--resume` will find those 412 lines under.
assert_eq!(rows[0].cwd, "/home/bob/repos/survey");
}
/// The guard on the only thing this module ever puts in a glob.
///
/// Worth a test of its own because what it protects is a `rm`: `delete`
/// resolves an id straight to `$HOME/.claude/projects/*/"$1".jsonl`, so
/// an id that can contain a slash or a `..` is an id that can name a
/// file outside the directory and have it removed.
#[test]
fn a_session_id_cannot_walk_out_of_the_projects_directory() {
assert!(is_session_id("5ecf21da-d53f-4a11-9c0d-000000000100"));
@@ -955,19 +696,10 @@ mod tests {
assert!(!is_session_id("a.b"));
assert!(!is_session_id("a*"));
assert!(!is_session_id("a b"));
// Empty would glob to the directory itself, and a long one is not a
// uuid whatever else it is.
assert!(!is_session_id(""));
assert!(!is_session_id(&"a".repeat(65)));
}
/// One batch, one invocation, one verdict per id -- including for the
/// two cases a single-id delete never had to keep apart from the rest:
/// an id recorded under two project directories (both copies must go,
/// and it still reports once) and an id that is not there at all.
///
/// Runs the real script against a temporary `$HOME`, because what is
/// being checked is the shell, not the Rust around it.
#[test]
fn a_batch_deletes_every_copy_and_reports_each_id_once() {
let home = tempfile::tempdir().expect("tempdir");
@@ -992,21 +724,17 @@ mod tests {
String::from_utf8_lossy(&output.stdout),
format!("{one}\tdeleted\n{twice}\tdeleted\n{absent}\tmissing\n"),
);
// The second copy is the one a per-id delete used to leave behind.
assert!(!projects.join("b").join(format!("{twice}.jsonl")).exists());
assert!(!projects.join("a").join(format!("{twice}.jsonl")).exists());
assert!(!projects.join("a").join(format!("{one}.jsonl")).exists());
}
/// A 1x1 PNG, base64 -- the smallest thing with a real header.
const PNG: &str = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk\
YPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
#[test]
fn replayed_screenshots_are_saved_and_referenced() {
let dir = tempfile::tempdir().expect("tempdir");
// The shape a screenshot actually has in these files: an image
// part inside a tool result, beside its text.
let line = format!(
r#"{{"type":"user","message":{{"role":"user","content":[{{"type":"tool_result","tool_use_id":"toolu_1","content":[{{"type":"text","text":"took a screenshot"}},{{"type":"image","source":{{"type":"base64","media_type":"image/png","data":"{PNG}"}}}}]}}]}}}}"#
);
@@ -1016,12 +744,8 @@ mod tests {
panic!("a replayed screenshot must become an image event: {events:?}");
};
assert!(image.ends_with(".png"));
// On disk, where the files route serves it from -- the phone
// fetches it only when something draws it.
assert!(dir.path().join("files").join(image).is_file());
// And it comes before the tool row it belongs to, so it does not
// read as belonging to whatever happened next.
assert!(
matches!(events.get(1), Some(Event::ToolEnd { .. })),
"{events:?}"
@@ -1030,19 +754,12 @@ mod tests {
#[test]
fn context_tokens_add_the_input_side_only() {
// The shape the CLI records, as captured from a real transcript.
let usage = r#""usage":{"input_tokens":2,"cache_creation_input_tokens":703,"cache_read_input_tokens":142228,"output_tokens":587,"output_tokens_details":{"thinking_tokens":0"#;
// 2 + 703 + 142228. Output is not context to carry forward, so it
// is not in the total; if it were, this would read 143520.
assert_eq!(context_tokens(usage), Some(142_933));
// The leading quote is load-bearing: without it "input_tokens"
// matches inside both cache field names and the prompt figure gets
// counted three times.
let only_cache = r#""usage":{"cache_read_input_tokens":100,"output_tokens":9"#;
assert_eq!(context_tokens(only_cache), Some(100));
// No assistant turn yet is not a context of zero.
assert_eq!(context_tokens(""), None);
assert_eq!(context_tokens(" "), None);
}
@@ -1052,8 +769,6 @@ mod tests {
let dir = tempfile::tempdir().expect("tempdir");
let line = r#"{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_1","content":"plain output"}]}}"#;
let events = events_from(line, dir.path());
// The result, and the turn state it implies: a tool has answered,
// so the model is about to be asked again.
assert_eq!(events.len(), 2, "{events:?}");
assert_eq!(
events[1],
@@ -1061,14 +776,11 @@ mod tests {
state: super::super::driver::SessionStatus::Running
}
);
// No stray directory for a session that never produced one.
assert!(!dir.path().join("files").exists());
}
#[test]
fn a_message_from_another_agent_is_kept_and_named() {
// The real shape, from a session file: the CLI marks these meta,
// and everything a reader needs is in `origin`.
let dir = tempfile::tempdir().expect("tempdir");
let line = r#"{"type":"user","isMeta":true,"origin":{"kind":"peer","from":"uds:/run/user/1000/cc-socks/605.sock","verifiedPeerPid":605,"name":"dev-updater-f5","fromMode":"prompting","body":"Pull before you touch AGENTS.md."},"message":{"role":"user","content":"Another Claude session sent a message:\n<cross-session-message from-name=\"dev-updater-f5\">\nPull before you touch AGENTS.md.\n</cross-session-message>"}}"#;
let events = events_from(line, dir.path());
@@ -1076,13 +788,11 @@ mod tests {
events[0],
Event::PeerMessage {
from: "dev-updater-f5".to_string(),
// The body, not the wrapper the model is given.
text: "Pull before you touch AGENTS.md.".to_string(),
turn_start: None,
},
"{events:?}"
);
// And it counts as the session having been given something.
assert_eq!(
events[1],
Event::Status {
@@ -1119,9 +829,6 @@ mod tests {
"a turn that has finished talking is over"
);
// A subagent's own messages are not the session's turn, and a
// record with no stop reason is not an answer -- neither may
// overrule what the conversation itself last said.
let sidechain = r#"{"type":"assistant","isSidechain":true,"message":{"role":"assistant","stop_reason":"end_turn","content":[{"type":"text","text":"sub"}]}}"#;
let unknown = r#"{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"?"}]}}"#;
assert_eq!(
@@ -1129,7 +836,6 @@ mod tests {
Some(SessionStatus::Running)
);
// And nothing at all to go on says nothing, rather than idle.
assert_eq!(state(r#"{"type":"summary","summary":"x"}"#), None);
}
}
server/src/session/llama.rs
+1 -137
View File
@@ -1,33 +1,3 @@
//! The llama.cpp driver: a `llama-server` process per session, spoken to over
//! its OpenAI-compatible HTTP API and translated into the common event model.
//!
//! Two things make this shaped differently from the Claude driver.
//!
//! **It is spawned but not spoken to over stdio.** The process is started
//! through the same [`Transport`] as any other and then reached over HTTP on a
//! loopback port. That is the second half of what a transport is -- "run this"
//! plus "reach this port" -- and it is what lets a session run on another
//! machine: [`Transport::reserve_port`] hands back a port the server binds
//! *there* and one that reaches it *here*, and the ssh connection carrying the
//! command carries the tunnel between them. The far `llama-server` binds
//! loopback only, so a model is never served to that machine's network.
//!
//! **The model file is the far machine's, not this one's.** A remote setup
//! names its own models directory (`SshConfig::models_dir`, defaulting to where
//! this backend keeps its downloads), and the file is looked for *there* -- so
//! a session naming a model that machine does not have says so, instead of
//! starting a server that will never load one. Downloading to another machine
//! is not built; the model gets there however anything else does.
//!
//! **The server is stateless between requests**, so the whole conversation goes
//! with every one. It is rebuilt from the session's transcript rather than kept
//! in this struct, which is not tidiness: a copy in driver memory is invisible
//! to a second device and gone when this process restarts.
//!
//! That leaves the Claude driver as the odd one out rather than this one -- the
//! CLI's own memory of a conversation is a cache in front of the same
//! transcript. Resolve any inconsistency in this direction.
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
@@ -46,7 +16,6 @@ use crate::config::{ProviderConfig, SessionConfig};
/// is generous -- the failure it exists for is a server that will never answer.
const READY_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(300);
/// One turn in the conversation this driver keeps on the server's behalf.
#[derive(Debug, Clone, Serialize, Deserialize)]
struct Message {
role: String,
@@ -55,28 +24,16 @@ struct Message {
pub struct LlamaDriver {
sink: EventSink,
/// Where this session's own llama-server answers.
endpoint: String,
/// Where the conversation is read back from, one line per event.
transcript: PathBuf,
/// Sampling settings chosen at spawn, sent with every request.
sampling: serde_json::Map<String, serde_json::Value>,
/// Set by [`Driver::interrupt`]; the streaming loop checks it between
/// chunks and stops, leaving what was generated in the transcript.
cancel: Arc<AtomicBool>,
/// Where this session's process record lives, so [`Driver::stop`] can find
/// the server it has to end.
session_dir: PathBuf,
}
impl LlamaDriver {
/// Takes charge of this session's `llama-server`: the one already loaded if
/// there is one, otherwise a new one.
///
/// One entry point, for the reason `ClaudeDriver::launch` gives, expensive
/// in a different currency: two servers holding the same model is twice the
/// memory, and the second would bind a different port while the phone kept
/// talking to the first.
#[allow(clippy::too_many_arguments)]
pub fn launch(
meta: &SessionConfig,
@@ -86,9 +43,6 @@ impl LlamaDriver {
transcript: &Path,
session_dir: &Path,
sink: EventSink,
// llama.cpp has no notion of a Task call, so this is accepted only
// to keep one shape across every driver's launch -- see
// `SUBAGENTS.md`'s "Server layout".
_subagents: Arc<super::subagent::Subagents>,
) -> Result<Self> {
let model = meta.model.as_deref().context(
@@ -120,17 +74,12 @@ impl LlamaDriver {
));
}
// Where it listens on its own machine, and where that is reached
// from here -- the same number when that machine is this one.
let forward = transport
.reserve_port()
.context("finding a port for llama-server")?;
let mut args: Vec<String> = vec![
"-m".into(),
path.clone(),
// Loopback there, whichever machine there is: what reaches it
// from outside that machine is the ssh tunnel and nothing
// else.
"--host".into(),
"127.0.0.1".into(),
"--port".into(),
@@ -152,10 +101,6 @@ impl LlamaDriver {
let program = provider.program();
let launch = Launch::new(program, args, meta.cwd.as_deref()).reaching(forward);
// Its output goes to files, not pipes. Not only so the process can
// outlive this server: nothing ever read those pipes, so a chatty
// llama-server filled the 64 KB buffer and blocked mid-load with no sign
// of why.
let child = transport.spawn(
&launch,
Streams::Detached {
@@ -203,8 +148,6 @@ impl LlamaDriver {
))
}
/// The driver for a `llama-server` at `endpoint`, however it got there.
///
/// Shared by starting one and adopting one, because everything after "there
/// is a server at this address" is identical -- including waiting for it to
/// answer, which an adopted one still owes: a recorded pid says a process
@@ -217,9 +160,6 @@ impl LlamaDriver {
session_dir: &Path,
sink: EventSink,
) -> Self {
// Loading is slow enough to be worth saying so: the session shows as
// running until the model is in memory, rather than looking ready and
// refusing the first message.
let _ = sink.send(Event::Status {
state: SessionStatus::Running,
});
@@ -273,9 +213,6 @@ impl LlamaDriver {
}
}
/// Where llama-server's own output goes. One file for both streams: it is
/// diagnostics nobody parses, and interleaving them is how it reads in a
/// terminal anyway.
const SERVER_LOG: &str = "llama-server.log";
/// How often a loaded server is checked for still being there. Slower than the
@@ -283,8 +220,6 @@ const SERVER_LOG: &str = "llama-server.log";
/// to notice a server that has gone.
const WATCH_INTERVAL: std::time::Duration = std::time::Duration::from_secs(2);
/// An owner-only log opened for appending, so the two streams pointed at
/// it do not overwrite each other and a reattach keeps what came before.
fn log_file(path: &Path) -> Result<std::fs::File> {
use std::os::unix::fs::OpenOptionsExt;
std::fs::OpenOptions::new()
@@ -295,21 +230,12 @@ fn log_file(path: &Path) -> Result<std::fs::File> {
.with_context(|| format!("opening {}", path.display()))
}
/// Reports the server going away, for as long as the session is there to report
/// it to.
///
/// Polled rather than waited on, for the reason the Claude driver gives: after a
/// restart this server is not the process's parent, so liveness has to be a
/// question asked of the record -- and asking it two different ways is how the
/// two answers come to disagree.
fn watch(session_dir: PathBuf, sink: EventSink) {
std::thread::spawn(move || {
loop {
std::thread::sleep(WATCH_INTERVAL);
match process::recorded(&session_dir) {
Some((_, process::Liveness::Alive)) => {}
// Nothing recorded means the session was stopped or deleted
// deliberately, and whoever did that has already said so.
None => return,
Some((_, process::Liveness::Dead)) => {
let _ = sink.send(Event::Error {
@@ -348,8 +274,6 @@ impl Driver for LlamaDriver {
let cancel = Arc::clone(&self.cancel);
cancel.store(false, Ordering::Relaxed);
// Its own thread: the request blocks for as long as the model takes to
// generate, which is the whole point of streaming it.
std::thread::spawn(move || {
// Nothing is ever held back here -- there is no queue to wait in --
// so the message is taken the moment it arrives. Said anyway,
@@ -372,9 +296,6 @@ impl Driver for LlamaDriver {
role: "user".into(),
content: text,
});
// The reply is not stored: the deltas below are the durable record,
// so the next turn reads back exactly what the phone was shown --
// including a partial one that was interrupted.
if let Err(err) = generate(&endpoint, &messages, &sampling, &cancel, &sink) {
let _ = sink.send(Event::Error {
message: format!("{err:#}"),
@@ -386,16 +307,12 @@ impl Driver for LlamaDriver {
});
}
fn answer_question(&self, _id: &str, _answers: &[String]) {
// Nothing here asks questions: this driver has no tools.
}
fn answer_question(&self, _id: &str, _answers: &[String]) {}
fn interrupt(&self) {
self.cancel.store(true, Ordering::Relaxed);
}
// Nothing to forward: this process has no notion of what the conversation
// is called, and the rename has already happened where the name lives.
fn set_title(&self, _title: &str) {}
fn set_permission_mode(&self, _mode: &str) {
@@ -430,15 +347,9 @@ impl Driver for LlamaDriver {
}
fn clear(&self) {
// All of it. `conversation` folds from the last of these, so recording
// the marker *is* the reset -- there is no driver state to keep in step
// with it, which is the same property that makes a second device see the
// same conversation this one does.
let _ = self.sink.send(Event::Cleared);
}
/// Stops generating and leaves the server loaded.
///
/// Worth being deliberate about, because the cost points the other way from
/// the Claude driver's: a `llama-server` holds its whole model in memory, so
/// a leaked one is gigabytes nobody is using. It is left anyway, because the
@@ -458,12 +369,6 @@ impl Driver for LlamaDriver {
}
}
/// The conversation so far, folded out of the transcript.
///
/// Consecutive `AssistantText` deltas are one assistant turn, closed by the next
/// user message -- which is also what makes an interrupted reply come back as
/// the partial text the phone actually saw.
///
/// This must stay a pure function of the transcript and must never re-render
/// earlier turns. llama.cpp caches the prompt prefix, so a growing conversation
/// reprocesses almost nothing -- but only while every turn is byte-identical to
@@ -475,9 +380,6 @@ fn conversation(path: &Path) -> Vec<Message> {
};
let mut messages: Vec<Message> = Vec::new();
let mut pending = String::new();
// Everything before the last clear is still in the transcript and is
// deliberately not in the conversation. Folding from zero would put it back,
// which is the whole of what clearing had to undo.
let events = match events.iter().rposition(|e| e.event == Event::Cleared) {
Some(at) => &events[at + 1..],
None => &events[..],
@@ -509,8 +411,6 @@ fn conversation(path: &Path) -> Vec<Message> {
messages
}
/// Where a model key resolves to on disk, refusing anything that climbs
/// out of the models directory -- the key arrives from a phone.
fn model_path(models_dir: &Path, key: &str) -> Result<PathBuf> {
let mut path = models_dir.to_path_buf();
for part in key.split('/') {
@@ -525,29 +425,16 @@ fn model_path(models_dir: &Path, key: &str) -> Result<PathBuf> {
Ok(path)
}
/// The model file's path **on the machine that will serve it**, confirmed to be
/// there.
///
/// One function rather than a local check and hope for the other case: the same
/// question has to be asked of two filesystems. The remote answer is measured
/// for the reason the local one is -- a missing file otherwise becomes a
/// `llama-server` that starts, fails to load, and reports as a session that
/// never became ready, which reads as the machine being slow.
///
/// One blocking round trip on a remote spawn, which is what the spawn is
/// already paying to start ssh. The alternative is a path built here from a `~`
/// this machine cannot expand.
fn model_on(transport: &Transport, models_dir: &Path, key: &str) -> Result<String> {
let Transport::Ssh { name, .. } = transport else {
return Ok(model_path(models_dir, key)?.to_string_lossy().into_owned());
};
// The same directory the spawn screen listed for this machine, and one
// function for the same reason: a list from one place and a load from
// another is a model that appears and then fails.
let dir = crate::models::dir_on(transport, models_dir);
// Checked here rather than in the script: `..` in a key would walk out of
// the models directory on a machine this server can start processes on,
// and the phone is where the key comes from.
for part in key.split('/') {
if part.is_empty() || part == "." || part == ".." {
bail!("\"{key}\" is not a model key this can resolve");
@@ -580,8 +467,6 @@ fn model_on(transport: &Transport, models_dir: &Path, key: &str) -> Result<Strin
}
}
/// Polls until the server says it is ready, or gives up.
///
/// Watches the process as well as the port, because the two failures need
/// different words and one of them is common: a model that will not load,
/// a port already taken on the far machine, a `llama-server` too old for
@@ -616,8 +501,6 @@ fn wait_until_ready(endpoint: &str, session_dir: &Path) -> Result<()> {
}
}
/// The end of `llama-server`'s own log, for a failure message.
///
/// Its account of what went wrong is the useful half -- "failed to load
/// model", "bind: Address already in use" -- and on a remote session it
/// is the only half, since nobody reading the phone can open a file on
@@ -636,7 +519,6 @@ fn log_tail(session_dir: &Path) -> String {
)
}
/// How much of that log to carry into a message somebody reads on a phone.
const LOG_TAIL_LINES: usize = 6;
/// One streamed completion: posts the conversation, emits each delta as it
@@ -666,16 +548,12 @@ fn generate(
let reader = std::io::BufReader::new(response.body_mut().as_reader());
let mut tokens = 0u64;
// The prompt side only, which is what the model is holding -- the same
// definition the other dialects report, so one word on the phone means one
// thing whichever kind of session it is.
let mut context = None;
for line in std::io::BufRead::lines(reader) {
if cancel.load(Ordering::Relaxed) {
break;
}
let line = line.context("reading the generation stream")?;
// Server-sent events: the payload lines are the ones that matter.
let Some(payload) = line.strip_prefix("data: ") else {
continue;
};
@@ -723,8 +601,6 @@ mod tests {
use super::*;
use crate::session::transcript::Transcript;
/// Writes a transcript the way the pump does, so the fold is tested against
/// the real file format rather than a hand-built vector.
fn transcript_with(events: &[Event]) -> (tempfile::TempDir, PathBuf) {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("transcript.jsonl");
@@ -777,10 +653,6 @@ mod tests {
}
#[test]
/// The interrupted case, which decides what a resumed conversation is built
/// from: whatever the phone was shown. The deltas that arrived before the
/// stop are in the transcript, so they are in the prompt -- the model is
/// never told it said something the user did not see.
fn an_interrupted_reply_stays_in_the_conversation() {
let (_dir, path) = transcript_with(&[
Event::UserMessage {
@@ -801,9 +673,6 @@ mod tests {
}
#[test]
/// Events this driver does not produce must not disturb the fold: a
/// transcript can carry errors and status changes from a session that
/// was, say, relaunched.
fn other_events_are_not_part_of_the_conversation() {
let (_dir, path) = transcript_with(&[
Event::Status {
@@ -832,9 +701,6 @@ mod tests {
}
#[test]
/// Clearing decides what the *model* is given, not just what the phone
/// draws. Everything above the marker stays in the transcript and none of it
/// is sent.
fn the_conversation_starts_after_the_last_clear() {
let (_dir, path) = transcript_with(&[
Event::UserMessage {
@@ -862,8 +728,6 @@ mod tests {
}
#[test]
/// The *last* one, so clearing twice does not resurrect what the
/// first clear dropped.
fn only_the_newest_clear_counts() {
let (_dir, path) = transcript_with(&[
Event::UserMessage {
server/src/session/mod.rs
-996
View File
File diff suppressed because it is too large. Load diff
server/src/session/pending.rs
-46
View File
@@ -1,26 +1,9 @@
//! What is being done to a machine's Claude Code sessions right now.
//!
//! Importing and deleting used to be whatever the phone was in the middle of:
//! the request was the work, so leaving the screen cancelled it and coming back
//! showed no sign it had ever started. Sessions half-imported that way are the
//! expensive kind of missing -- the row is back in the list looking untouched,
//! and taking it again is the second `--resume` the import path exists to
//! prevent.
//!
//! So the work runs here, on the server, and this is the record of it. The
//! phone reads that record two ways and needs both: every row of the importable
//! listing carries what is happening to it, which is what a phone that was
//! asleep has to go on; and [`Registry::subscribe`] is the live stream, which is
//! what makes a screen change by itself. A broadcast has no memory, and a
//! listing is only true when it was fetched.
use std::collections::HashMap;
use std::sync::{Arc, Mutex};
use serde::Serialize;
use tokio::sync::broadcast;
/// What is being done to an importable session.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum Operation {
@@ -29,8 +12,6 @@ pub enum Operation {
}
impl Operation {
/// The word a row shows while this runs. Fixed here rather than in the app
/// so the two ends cannot disagree about what a state is called.
pub fn label(self) -> &'static str {
match self {
Self::Importing => "importing",
@@ -39,11 +20,6 @@ impl Operation {
}
}
/// One change to what is in flight, as it goes out on the stream.
///
/// The three states are every way an operation ends, including the two easy to
/// leave out: still running, finished, and failed. There is deliberately no
/// "unknown" -- this is the server's own work, so not knowing would be a bug.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase", tag = "state")]
pub enum Change {
@@ -64,8 +40,6 @@ pub enum Change {
}
impl Change {
/// Which machine this is about, so a stream scoped to one can drop the rest.
/// Every variant carries it; matching here keeps that fact in one place.
pub fn setup(&self) -> &str {
match self {
Self::Started { setup, .. }
@@ -75,7 +49,6 @@ impl Change {
}
}
/// Everything in flight, and the last failure against each session.
#[derive(Debug)]
pub struct Registry {
running: Mutex<HashMap<(String, String), Operation>>,
@@ -92,16 +65,12 @@ impl Default for Registry {
Self {
running: Mutex::new(HashMap::new()),
failures: Mutex::new(HashMap::new()),
// Enough that a phone watching one screen cannot lag behind a batch
// of any size somebody would start by hand.
changes: broadcast::channel(256).0,
}
}
}
impl Registry {
/// Marks an operation as running and announces it.
///
/// The returned guard is how it stops being marked: settle it with
/// [`InFlight::succeeded`] or [`InFlight::failed`], or drop it and it reports
/// a failure. Dropping without settling means the task was cancelled or
@@ -122,20 +91,16 @@ impl Registry {
}
}
/// What is happening to this session, if anything is.
pub fn running(&self, setup: &str, session: &str) -> Option<Operation> {
let key = (setup.to_string(), session.to_string());
self.running.lock().unwrap().get(&key).copied()
}
/// How the last operation on this session failed, if it did.
pub fn failure(&self, setup: &str, session: &str) -> Option<String> {
let key = (setup.to_string(), session.to_string());
self.failures.lock().unwrap().get(&key).cloned()
}
/// Forgets failures against sessions the machine no longer has. Called from
/// the listing, which is the only place that knows what is still there.
pub fn prune(&self, setup: &str, present: &[String]) {
self.failures
.lock()
@@ -145,14 +110,11 @@ impl Registry {
});
}
/// Every change as it happens. See the module note on why this is not the
/// only way the phone finds out.
pub fn subscribe(&self) -> broadcast::Receiver<Change> {
self.changes.subscribe()
}
}
/// An operation that is running, and its way back out of the registry.
pub struct InFlight {
registry: Arc<Registry>,
key: (String, String),
@@ -219,8 +181,6 @@ mod tests {
assert!(matches!(changes.try_recv(), Ok(Change::Finished { .. })));
}
/// A failure outlives the operation, because the phone that needs it may not
/// have been listening when it happened.
#[test]
fn a_failure_is_kept_until_something_replaces_or_prunes_it() {
let registry = Arc::new(Registry::default());
@@ -234,11 +194,9 @@ mod tests {
Some("no such session")
);
// Still on the machine, so the failure is still about something.
registry.prune("local", &["abc".to_string()]);
assert!(registry.failure("local", "abc").is_some());
// Another machine's listing says nothing about this one's.
registry.prune("other", &[]);
assert!(registry.failure("local", "abc").is_some());
@@ -246,8 +204,6 @@ mod tests {
assert!(registry.failure("local", "abc").is_none());
}
/// Trying again clears the last failure, so a row cannot show an error from
/// before the attempt somebody is currently watching.
#[test]
fn starting_again_clears_the_previous_failure() {
let registry = Arc::new(Registry::default());
@@ -260,8 +216,6 @@ mod tests {
second.succeeded();
}
/// A task that is cancelled or panics must not leave a row saying something
/// is still happening to it.
#[test]
fn dropping_an_unsettled_operation_reports_a_failure() {
let registry = Arc::new(Registry::default());
server/src/session/process.rs
-97
View File
@@ -1,28 +1,3 @@
//! What a session's process is, and how far this server has read it --
//! written down so a *later* run of this server can find the same process
//! rather than start a second one.
//!
//! Stopping the backend must not kill a turn that is in flight, so session
//! processes are left running and adopted again on the way back up. That only
//! works if "is this still mine?" has an answer, which is what this module is.
//!
//! **A pid is not an identity.** Pids are reused, so adopting one by number
//! alone eventually means treating a stranger's process as a session -- never
//! resuming the real conversation, and signalling something unrelated when the
//! session is deleted. The kernel's start time for that pid is recorded beside
//! it; the pair is unique for as long as the machine has been up.
//!
//! **How to reach it again belongs here too**, in the same record and the same
//! write, because it answers the other half of the same question. Splitting
//! them would be two files that can disagree about one process. What it takes
//! differs by driver, so it is a typed [`Detail`] rather than a union of every
//! driver's fields.
//!
//! The record is rewritten in place as reading advances. A crash during that
//! write leaves a record that does not parse, which is read as "no live
//! process" -- so the failure is the old behaviour rather than a wrong
//! adoption.
use std::os::unix::fs::OpenOptionsExt;
use std::path::{Path, PathBuf};
@@ -31,34 +6,21 @@ use serde::{Deserialize, Serialize};
const RECORD_FILE: &str = "process.json";
/// A process this server started and expects to outlive it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Record {
pub pid: u32,
/// The kernel's start time for `pid`, in clock ticks since boot. See the
/// module comment: this is what makes the pid an identity.
pub started: u64,
/// What the driver needs in order to pick this process back up.
#[serde(flatten)]
pub detail: Detail,
}
/// How a reattaching driver reaches a process it did not start.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum Detail {
/// Spoken to over stdio, which outlives the server as files in the session
/// directory. `stdout_read` is how many bytes of the stdout log have
/// already become events: everything after it is what a reattaching server
/// owes the conversation.
Stdio { stdout_read: u64 },
/// Spoken to over HTTP on a loopback port, which is all it takes to find
/// it again -- there is no stream to be partway through.
Http { port: u16 },
}
/// Whether a recorded process is still there.
///
/// Three answers rather than a boolean, because "I could not find out" is a
/// real one and is not the same as "no". Treating it as "no" is what would
/// start a second process against a conversation that already has one.
@@ -83,7 +45,6 @@ impl Record {
pub fn liveness(&self) -> Liveness {
match stat_of(self.pid) {
// A different start time is a reused pid, so definitely not ours.
Ok(Some(stat)) if stat.started == self.started => {
if stat.exited {
Liveness::Dead
@@ -122,20 +83,6 @@ pub fn live(session_dir: &Path) -> Option<Record> {
}
}
/// Writes `record` where [`live`] will find it, atomically -- to a neighbouring
/// file, renamed over the real name, so a reader sees either the whole old
/// record or the whole new one.
///
/// Writing in place would not be, and the consequence is severe rather than
/// untidy. `fs::write` truncates before it fills, so a crash inside that window
/// leaves no readable record -- and a missing record reads as "nothing is
/// running", which is the single answer that makes the next launch start a
/// *second* process against a conversation that already has one. The window is
/// not rare: this runs on every read that makes progress, so many times a
/// second while a turn is producing output.
///
/// Errors are logged rather than returned: this runs on the reading path, and a
/// session that cannot save its position is still worth having.
pub fn write(session_dir: &Path, record: &Record) {
let path = path(session_dir);
let text = match serde_json::to_string(record) {
@@ -145,14 +92,11 @@ pub fn write(session_dir: &Path, record: &Record) {
return;
}
};
// Beside the real file so the rename stays within one filesystem, which is
// what makes it atomic.
let temp = path.with_extension("json.new");
let written = std::fs::OpenOptions::new()
.create(true)
.write(true)
.truncate(true)
// Owner-only, like everything else in a session directory.
.mode(0o600)
.open(&temp)
.and_then(|mut file| {
@@ -176,8 +120,6 @@ pub fn size_of(path: &Path) -> u64 {
std::fs::metadata(path).map(|meta| meta.len()).unwrap_or(0)
}
/// Forgets the recorded process -- for one confirmed dead, or a session
/// being deleted. The path out for [`write`].
pub fn clear(session_dir: &Path) {
let path = path(session_dir);
if let Err(err) = std::fs::remove_file(&path)
@@ -222,8 +164,6 @@ pub fn stop(record: &Record, grace: std::time::Duration) {
/// One deadline for all of them rather than one each: they were signalled
/// together, so waiting is bounded by the grace period however many there are.
pub fn wait_gone(records: &[Record], grace: std::time::Duration) {
/// How often to look. Short enough that a process that goes at once costs
/// nothing noticeable, and long enough not to spin.
const LOOK: std::time::Duration = std::time::Duration::from_millis(20);
let deadline = std::time::Instant::now() + grace;
@@ -260,14 +200,8 @@ fn signal(pid: u32, signal: libc::c_int) {
}
}
/// What `/proc` says about a pid.
struct Stat {
/// The kernel's start time in clock ticks since boot -- see
/// [`Record::started`].
started: u64,
/// State `Z`: the process has ended, and the kernel is keeping its entry
/// only until somebody collects the exit status.
///
/// Read rather than ignored, because that entry has the same pid *and* the
/// same start time, so a finished process goes on answering "still there"
/// for as long as nothing reaps it -- which makes `Exited` unsayable: the
@@ -276,31 +210,15 @@ struct Stat {
exited: bool,
}
/// The kernel's start time for `pid`, in clock ticks since boot.
///
/// Field 22 of `/proc/<pid>/stat`, counted from the closing parenthesis of
/// field 2 rather than from the start of the line: a process's name is field 2,
/// it is wrapped in parentheses, and it may itself contain spaces and
/// parentheses. Splitting the whole line on whitespace reads the wrong field
/// for anything with a space in its name.
///
/// Three outcomes, and they are not the same: `Ok(None)` is "no such process",
/// `Err` is "could not find out". Collapsing the second into the first is what
/// would let a machine without a readable `/proc` look like a machine with
/// nothing running on it. Linux-specific, like `import`'s use of GNU `stat`.
fn stat_of(pid: u32) -> std::io::Result<Option<Stat>> {
let stat = match std::fs::read_to_string(format!("/proc/{pid}/stat")) {
Ok(stat) => stat,
Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(err) => return Err(err),
};
// A `/proc` entry that exists but does not have the shape this reads is not
// a process that has gone away; it is a reading this code cannot make.
let unreadable =
|| std::io::Error::new(std::io::ErrorKind::InvalidData, "unreadable /proc stat");
let after_name = stat.rsplit_once(')').ok_or_else(unreadable)?.1;
// Field 3 is the first after the name, so the state is the first here and
// field 22 is the 20th.
let mut fields = after_name.split_whitespace();
let exited = fields.next().ok_or_else(unreadable)? == "Z";
let started = fields
@@ -311,9 +229,6 @@ fn stat_of(pid: u32) -> std::io::Result<Option<Stat>> {
Ok(Some(Stat { started, exited }))
}
/// Reads `path` from `from`, returning what is there and where reading reached.
/// A file truncated or replaced under us reads from the start, since the offset
/// no longer means anything in it.
pub fn read_from(path: &Path, from: u64) -> Result<(Vec<u8>, u64)> {
use std::io::{Read, Seek, SeekFrom};
let mut file = match std::fs::File::open(path) {
@@ -345,8 +260,6 @@ mod tests {
.expect("this process has a start time");
assert_eq!(mine.liveness(), Liveness::Alive);
// The same pid with a different start time is a different process --
// which is the whole reason the start time is recorded.
let recycled = Record {
started: mine.started + 1,
..mine.clone()
@@ -362,12 +275,10 @@ mod tests {
write(dir.path(), &record);
assert_eq!(live(dir.path()), Some(record.clone()));
// A shorter value must not leave a readable tail of the longer one.
record.detail = Detail::Stdio { stdout_read: 1 };
write(dir.path(), &record);
assert_eq!(live(dir.path()), Some(record.clone()));
// And the other shape round trips through the same file.
record.detail = Detail::Http { port: 8080 };
write(dir.path(), &record);
assert_eq!(live(dir.path()), Some(record));
@@ -381,8 +292,6 @@ mod tests {
let dir = tempfile::tempdir().expect("tempdir");
let mut record =
Record::of(std::process::id(), Detail::Stdio { stdout_read: 0 }).expect("start time");
// Rewritten the way the reader rewrites it: constantly, as the position
// advances. Each one must land whole.
for read in [1u64, 4096, 2, 999_999] {
record.detail = Detail::Stdio { stdout_read: read };
write(dir.path(), &record);
@@ -392,8 +301,6 @@ mod tests {
"after offset {read}"
);
}
// The rename is what makes it atomic; a leftover neighbour would mean it
// had not happened.
let stray: Vec<_> = std::fs::read_dir(dir.path())
.expect("read dir")
.filter_map(Result::ok)
@@ -408,7 +315,6 @@ mod tests {
let dir = tempfile::tempdir().expect("tempdir");
assert_eq!(live(dir.path()), None);
// Pid 0 is never a process we started.
write(
dir.path(),
&Record {
@@ -433,14 +339,11 @@ mod tests {
assert_eq!(bytes, b"world");
assert_eq!(read, 11);
// An offset past the end means the file was replaced, so the offset
// describes a file that no longer exists.
std::fs::write(&path, b"new").expect("truncate");
let (bytes, read) = read_from(&path, 11).expect("read");
assert_eq!(bytes, b"new");
assert_eq!(read, 3);
// A missing file is not an error: the process has said nothing.
let (bytes, read) = read_from(&dir.path().join("nope"), 7).expect("read");
assert!(bytes.is_empty());
assert_eq!(read, 7);
server/src/session/subagent.rs
-60
View File
@@ -1,16 +1,3 @@
//! A session's subagents -- see `SUBAGENTS.md`.
//!
//! **A subagent is a second transcript owned by a session, in the same event
//! model, with no process and no controls.** It shares the transcript file
//! format, the paging routes, and the SSE stream with a session by
//! addressing, not by copying: `Transcript`, `read_window` and `catch_up`
//! work on a subagent's file unchanged.
//!
//! Storage is `<session dir>/subagents/<id>/{meta.json,transcript.jsonl}`,
//! where `<id>` is the Task tool_use id that started it -- unique, stable
//! across a backend restart, and already the key the parent side uses. Only
//! ids matching [`is_subagent_id`] are ever turned into a path.
use std::collections::HashMap;
use std::fs;
use std::path::{Path, PathBuf};
@@ -23,9 +10,6 @@ use tokio::sync::broadcast;
use super::driver::{Event, SessionStatus};
use super::transcript::{SeqEvent, Transcript};
/// Fan-out buffer for one subagent's SSE subscribers. Smaller than a
/// session's: a subagent's whole conversation is usually a handful of tool
/// calls, not an hours-long session.
const EVENT_BUFFER: usize = 64;
/// Whether `id` is safe to become a path segment under a session's
@@ -52,7 +36,6 @@ struct Meta {
created: f64,
}
/// One row of `GET /sessions/{id}/subagents`.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SubagentInfo {
@@ -63,8 +46,6 @@ pub struct SubagentInfo {
pub last_activity: f64,
}
/// One subagent: its own transcript and broadcast, same shape as a
/// session's but with no driver behind it.
pub struct Subagent {
dir: PathBuf,
transcript: Mutex<Transcript>,
@@ -88,10 +69,6 @@ impl Subagent {
self.events.subscribe()
}
/// Whether this subagent's last recorded status is not `Exited` --
/// what decides whether a further child line reopens it (see
/// `Subagents::reopen`) rather than continuing straight through. See
/// `SUBAGENTS.md`'s lifecycle.
pub fn is_open(&self) -> bool {
*self.status.lock().unwrap() != SessionStatus::Exited
}
@@ -103,8 +80,6 @@ impl Subagent {
if let Event::Status { state } = &entry.event {
*self.status.lock().unwrap() = *state;
}
// No subscribers is fine; the transcript already has it,
// same as a session's pump.
let _ = self.events.send(entry);
}
Err(err) => tracing::error!("subagent transcript append failed: {err:#}"),
@@ -112,16 +87,7 @@ impl Subagent {
}
}
/// Every subagent one session has started, keyed by the Task tool_use id
/// that names it.
///
/// Lives beside a session's driver rather than inside it: a claude driver
/// holds an `Arc` to this and routes child lines into it; echo uses it for
/// its `/subagent` rig; llama ignores it, since it has no notion of a Task
/// call. One instance per live session, built at launch and handed to
/// whichever driver replaces it across a stop/start.
pub struct Subagents {
/// The session's own directory; subagents live under `<dir>/subagents`.
dir: PathBuf,
live: Mutex<HashMap<String, Arc<Subagent>>>,
}
@@ -188,10 +154,6 @@ impl Subagents {
)?;
}
}
// A freshly created subagent is running by construction (its only
// lines so far are `Status::Running` and maybe its prompt); a
// reopened one takes whatever the file last said, since this
// `Transcript` has not been appended to yet in this process.
let status = if existed {
transcript.last_status().unwrap_or(SessionStatus::Running)
} else {
@@ -206,10 +168,6 @@ impl Subagents {
}))
}
/// Starts a subagent unless one is already known by this id -- see
/// `SUBAGENTS.md`'s lifecycle: created at the Task call or at the first
/// child line, whichever comes first, and never twice. A bad id is
/// refused rather than turned into a path.
pub fn start(&self, id: &str, title: &str, prompt: Option<&str>) {
if !is_subagent_id(id) {
tracing::debug!("refusing to start a subagent with a bad id {id:?}");
@@ -241,8 +199,6 @@ impl Subagents {
if !self.subagents_dir().join(id).join("meta.json").is_file() {
return None;
}
// Title and prompt are ignored: the directory already exists, so
// `open_or_create` reads its own meta rather than using either.
match self.open_or_create(id, "", None) {
Ok(subagent) => {
self.live
@@ -300,8 +256,6 @@ impl Subagents {
}
}
/// The parent session's process is gone, so nothing still open here has
/// a process behind it either -- see `SUBAGENTS.md`'s lifecycle #4.
pub fn finish_all(&self) {
let subagents: Vec<Arc<Subagent>> = self.live.lock().unwrap().values().cloned().collect();
for subagent in subagents {
@@ -313,12 +267,6 @@ impl Subagents {
}
}
/// Every subagent under this session's directory, oldest first --
/// `GET /sessions/{id}/subagents`. Read straight from disk rather than
/// from `live`, so a subagent from before this process started (or one
/// this run has not yet touched) still shows up; one file read per
/// subagent, which is fine at the handful a session usually has.
///
/// `session_running` is what turns a subagent whose last status is
/// `Running` into `Unknown`: its process was the session's, and the
/// session has none.
@@ -328,7 +276,6 @@ impl Subagents {
.filter_map(Result::ok)
.filter_map(|entry| info_of(&entry.path(), session_running))
.collect(),
// No directory is no subagents, not a fault worth reporting.
Err(_) => Vec::new(),
};
rows.sort_by(|a, b| {
@@ -366,9 +313,6 @@ fn info_of(subagent_dir: &Path, session_running: bool) -> Option<SubagentInfo> {
})
}
/// How many subagents a session has, for `SessionInfo::subagents`: a
/// directory listing, so the session list stays cheap and only the
/// dedicated route pays for reading a status out of each one.
pub fn count(session_dir: &Path) -> usize {
fs::read_dir(session_dir.join("subagents"))
.map(|entries| entries.filter_map(Result::ok).count())
@@ -426,7 +370,6 @@ mod tests {
},
);
}
// A fresh registry, the way a backend restart builds one.
let subagents = Subagents::new(dir.path().to_path_buf());
let subagent = subagents.get("toolu_2").expect("reopened");
assert!(subagent.is_open());
@@ -438,7 +381,6 @@ mod tests {
);
let events =
crate::session::transcript::read_after(&subagent.transcript_path(), 0).expect("read");
// Status, UserMessage, two AssistantText deltas, seq continuing.
assert_eq!(events.len(), 4);
assert_eq!(events.last().unwrap().seq, 4);
}
@@ -451,7 +393,6 @@ mod tests {
subagents.finish("toolu_3");
let subagent = subagents.get("toolu_3").unwrap();
assert!(!subagent.is_open());
// On disk too, not only in the live cache `is_open` reads.
assert_eq!(
Transcript::open(&subagent.transcript_path())
.expect("reopen")
@@ -459,7 +400,6 @@ mod tests {
Some(SessionStatus::Exited)
);
// Finishing an id that was never a subagent is a no-op, not a panic.
subagents.finish("never-started");
}
server/src/session/transcript.rs
-157
View File
@@ -1,11 +1,3 @@
//! Append-only JSONL event log, one per session, with monotonically
//! increasing sequence numbers -- the phone's resume cursor.
//!
//! One line per event: `{"seq":N,"ts":...,"type":...,...}`. The writer
//! assigns sequence numbers; readers replay everything after a cursor.
//! Reopening an existing file continues the numbering, which is what makes
//! a backend restart invisible to a phone holding a cursor.
use std::fs::{File, OpenOptions};
use std::io::Write;
use std::ops::Range;
@@ -17,9 +9,6 @@ use serde::Deserialize;
use super::driver::{Event, SessionStatus, context_after};
// `SeqEvent` moved to `event-model` on 2026-09-04 along with the rest of the
// event model, so `client-core` can read the same wire shape; re-exported
// here since every caller in this crate reaches it through this module.
pub use event_model::SeqEvent;
pub struct Transcript {
@@ -31,8 +20,6 @@ pub struct Transcript {
}
impl Transcript {
/// Opens (or creates) the log at `path`, continuing the sequence from
/// the last line if one exists.
pub fn open(path: &Path) -> Result<Self> {
// One pass for all three answers. They are wanted at the same moment
// by the same caller, and reading the file again for each doubled the
@@ -43,8 +30,6 @@ impl Transcript {
Event::Status { state } => Some(state),
_ => None,
});
// Owner-only: a transcript is the whole conversation, including
// whatever the session read, wrote, or was told.
let file = OpenOptions::new()
.create(true)
.append(true)
@@ -56,17 +41,12 @@ impl Transcript {
next_seq: last_seq + 1,
last_status,
last_activity: existing.last().map(|entry| entry.ts),
// Folded rather than read off the newest usage entry: a clear or
// a compaction after it is what the answer is, and those events
// carry no usage of their own.
context_tokens: existing
.iter()
.fold(None, |current, entry| context_after(current, &entry.event)),
})
}
/// The state the session was last reported to be in, as of opening.
///
/// Read from the file rather than assumed, because a server that has just
/// restarted has been told nothing. Assuming idle claimed a session was
/// waiting for you when it had exited hours earlier.
@@ -76,14 +56,6 @@ impl Transcript {
self.last_status
}
/// When this session last did anything, as of opening.
///
/// Read from the file for the reason [`Transcript::last_status`] is, and it
/// is the same mistake in the other direction: taking the clock instead
/// said every session it relaunched had been active this second. On the
/// phone that is every row reading "just now" and the list -- sorted by
/// this -- in an order that means nothing.
///
/// `None` for a transcript with no lines, which is a session that genuinely
/// has not done anything. Its caller answers with when the session was
/// created, not with the clock.
@@ -91,8 +63,6 @@ impl Transcript {
self.last_activity
}
/// How much context the session was holding, as of opening.
///
/// `None` for a transcript nothing has been measured in. That is not zero:
/// a server that has just restarted has been told nothing, and answering
/// zero would draw an empty context for a conversation that may be nearly
@@ -120,16 +90,6 @@ impl Transcript {
}
}
/// A window of the transcript ending just before `before`, newest-biased.
///
/// The screen opens on the end of a conversation, and the end is all it can
/// show at once. Replaying the whole file to get there costs one network frame
/// per event -- on an 863-event import that was several seconds of messages
/// arriving oldest-first, which reads as the app loading top-down.
///
/// `before` pages backwards for history somebody actually scrolls to. Only the
/// window is parsed; see [`Indexed`] for why that is the whole cost.
///
/// `after` is a floor: nothing at or below it is returned, and the page stops
/// there rather than at `limit`. A phone holding a cached run passes the end of
/// what it already has, so the page is exactly the gap and never overlaps its
@@ -153,13 +113,7 @@ pub fn read_window(
Some(after) => indexed.first_at_or_after(after.saturating_add(1))?,
None => 0,
};
// A floor above the window is an empty page, not a walk backwards past it.
let start = start.min(end);
// Coalescing counts *rows*, not events, and would misread the newest
// window: a message still streaming there would fold to one event whose seq
// is its first delta, and the phone resumes its live stream from the newest
// seq it applied -- so the deltas the coalesced event hid would replay and
// double. Only settled history (`before` set) is safe.
if coalesce && before.is_some() {
indexed.parse_coalesced(start, end, limit)
} else {
@@ -167,37 +121,18 @@ pub fn read_window(
}
}
/// How far behind a reconnecting subscriber can be and still be handed the
/// backlog one event at a time.
///
/// Past this it is served better by rebuilding from the newest window. The
/// events are the same either way; what differs is that one arrives as a single
/// window and the other as thousands of frames a screen renders one by one. Set
/// well above a screenful so an ordinary blip still streams continuously.
pub const CATCH_UP_LIMIT: usize = 200;
/// What a subscriber asking for "everything after my cursor" gets back.
///
/// Two answers rather than one list, because they mean different things to the
/// screen holding the cursor: one continues what it has, the other replaces it.
/// Collapsing them would leave the client splicing a window onto rows it has no
/// way to know are no longer adjacent -- a seam that looks like ordinary output.
#[derive(Debug, Clone, PartialEq)]
pub enum CatchUp {
/// The events after the cursor, continuing what the subscriber holds.
Continue(Vec<SeqEvent>),
/// The subscriber was further behind than [`CATCH_UP_LIMIT`]: the newest
/// window, replacing whatever it holds. Earlier history is still there to be
/// paged backwards through.
Restart(Vec<SeqEvent>),
}
/// Everything after `after`, or the newest `limit` when that is more.
///
/// The window is chosen before anything is parsed, which matters most in the
/// case that looks least interesting: a subscriber with no cursor asks for the
/// whole conversation and is handed the last [`CATCH_UP_LIMIT`] events of it,
/// so parsing the discarded prefix is the whole file's work for a screenful.
pub fn catch_up(path: &Path, after: u64, limit: usize) -> Result<CatchUp> {
let Some(indexed) = Indexed::read(path)? else {
return Ok(CatchUp::Continue(Vec::new()));
@@ -210,9 +145,6 @@ pub fn catch_up(path: &Path, after: u64, limit: usize) -> Result<CatchUp> {
Ok(CatchUp::Continue(indexed.parse(start..end)?))
}
/// Replays every event with `seq > after`, oldest first. A missing file is
/// an empty transcript, not an error -- the session just hasn't produced an
/// event yet.
pub fn read_after(path: &Path, after: u64) -> Result<Vec<SeqEvent>> {
let Some(indexed) = Indexed::read(path)? else {
return Ok(Vec::new());
@@ -221,32 +153,13 @@ pub fn read_after(path: &Path, after: u64) -> Result<Vec<SeqEvent>> {
indexed.parse(start..indexed.lines.len())
}
/// The transcript's lines located but not read, so a reader can find the range
/// it wants and parse only that.
///
/// Both readers above want a *range* of the file, and both used to reach it by
/// parsing every line and discarding the ones outside it -- the cost that grows
/// with the conversation rather than with the answer. Measured on a 21 MB,
/// 24,000-event transcript, one page took **500 ms of server time to return
/// 600 KB**, and the same 500 ms whichever page was asked for. A phone paging
/// back pays it per page, and every stream reconnect pays it again to discover
/// there is nothing new.
///
/// Sequence numbers only ever increase, so the boundary of a range is a
/// bisection: this parses one line per halving, and the caller parses only what
/// it returns. The file is still read whole, which is a deliberate stop --
/// going further means a chunked backwards reader, and locating a line is not
/// what the half-second was going to.
struct Indexed<'a> {
path: &'a Path,
text: String,
/// Byte range of each non-blank line, in the order they were written.
lines: Vec<Range<usize>>,
}
impl<'a> Indexed<'a> {
/// `None` for a file that isn't there, which is a session that has not
/// produced an event yet rather than a failure.
fn read(path: &'a Path) -> Result<Option<Self>> {
let text = match std::fs::read_to_string(path) {
Ok(text) => text,
@@ -270,9 +183,6 @@ impl<'a> Indexed<'a> {
Ok(Some(Self { path, text, lines }))
}
/// The index of the first line numbered `seq` or higher, or the end when
/// every line is older than that.
///
/// A bisection, which is only correct because the file is in sequence order.
/// A line that cannot be read is reported here rather than silently treated
/// as out of range, because the answer would be a window off by however much
@@ -290,7 +200,6 @@ impl<'a> Indexed<'a> {
Ok(low)
}
/// One line's sequence number, without building the event on it.
fn seq_at(&self, index: usize) -> Result<u64> {
#[derive(Deserialize)]
struct JustSeq {
@@ -317,24 +226,8 @@ impl<'a> Indexed<'a> {
.with_context(|| format!("bad transcript line in {}", self.path.display()))
}
/// The newest `limit` *rows* ending at line `end`, with each run of
/// consecutive [`Event::AssistantText`] deltas concatenated into one.
///
/// A reply is stored a token at a time, so a window counted in events is a
/// fraction of a row for a reply and a whole row for a tool call, and the
/// phone can neither predict how much a page will show nor fill a screen
/// without folding a page of near-duplicate events. Counted in rows, a page
/// is a page.
///
/// A run takes the seq and time of its *oldest* delta, matching the phone's
/// own rule -- so anchors and the `before` cursor land where they always
/// did. A run cut by the `limit` is emitted as the partial it is, and the
/// phone's `healSplitMessage` welds it to the next page. `start` is the same
/// kind of cut from the other end.
fn parse_coalesced(&self, start: usize, end: usize, limit: usize) -> Result<Vec<SeqEvent>> {
// Newest first while walking back, reversed to transcript order at the end.
let mut out: Vec<SeqEvent> = Vec::new();
// The run currently being gathered: its oldest seq/ts so far, and its deltas newest-first.
let mut run: Option<(u64, f64, Vec<String>)> = None;
let flush = |run: &mut Option<(u64, f64, Vec<String>)>, out: &mut Vec<SeqEvent>| {
if let Some((seq, ts, mut deltas)) = run.take() {
@@ -350,9 +243,6 @@ impl<'a> Indexed<'a> {
};
let mut index = end;
while index > start {
// A row is counted when it lands in `out`; an open run is the row
// being gathered, so stopping while one is open would drop the
// deltas already read. Break only between rows.
if out.len() >= limit && run.is_none() {
break;
}
@@ -368,7 +258,6 @@ impl<'a> Indexed<'a> {
None => run = Some((entry.seq, entry.ts, vec![delta])),
}
} else {
// The run above this event (newer) is complete: it is a row, and so is this event.
flush(&mut run, &mut out);
out.push(entry);
}
@@ -406,7 +295,6 @@ mod tests {
assert_eq!(replay[0].event, text("b"));
assert_eq!(replay[1].seq, 3);
// A cursor at or past the end replays nothing.
assert!(read_after(&path, 3).expect("read").is_empty());
}
@@ -435,15 +323,12 @@ mod tests {
.expect("append");
}
// Within the limit the subscriber keeps what it has.
let CatchUp::Continue(events) = catch_up(&path, 7, 5).expect("catch up") else {
panic!("a backlog of 3 should continue");
};
assert_eq!(events.len(), 3);
assert_eq!(events[0].seq, 8);
// Past it, the newest window replaces what it has -- and it is the
// newest, not the oldest, that survives the trim.
let CatchUp::Restart(events) = catch_up(&path, 0, 5).expect("catch up") else {
panic!("a backlog of 10 should restart");
};
@@ -451,9 +336,6 @@ mod tests {
assert_eq!(events[0].seq, 6);
assert_eq!(events[4].seq, 10);
// Exactly at the limit is still a continuation: the boundary belongs to
// the cheaper answer, so a client is not reset for being one event
// behind the threshold.
assert!(matches!(
catch_up(&path, 5, 5).expect("catch up"),
CatchUp::Continue(_)
@@ -465,8 +347,6 @@ mod tests {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("transcript.jsonl");
// Nothing recorded yet: no prior state to report, which is not the same
// as reporting idle.
assert_eq!(Transcript::open(&path).expect("open").last_status(), None);
let mut transcript = Transcript::open(&path).expect("open");
@@ -486,13 +366,11 @@ mod tests {
2.0,
)
.expect("append");
// Events after the last status must not hide it.
transcript.append(text("trailing"), 3.0).expect("append");
drop(transcript);
let reopened = Transcript::open(&path).expect("reopen");
assert_eq!(reopened.last_status(), Some(SessionStatus::Exited));
// And the same pass still continues the numbering.
assert_eq!(reopened.next_seq, 4);
}
@@ -507,22 +385,18 @@ mod tests {
.expect("append");
}
// No cursor is the newest page, which is what opening a session asks for.
let newest = read_window(&path, None, None, 3, false).expect("window");
assert_eq!(
newest.iter().map(|entry| entry.seq).collect::<Vec<_>>(),
[8, 9, 10]
);
// Then backwards from the oldest of those, exclusive: the page a phone
// scrolling up asks for must not repeat the row it is scrolling from.
let older = read_window(&path, Some(8), None, 3, false).expect("window");
assert_eq!(
older.iter().map(|entry| entry.seq).collect::<Vec<_>>(),
[5, 6, 7]
);
// Asking for more than there is gives what there is, rather than failing.
assert_eq!(
read_window(&path, None, None, 100, false)
.expect("window")
@@ -530,8 +404,6 @@ mod tests {
10
);
// Nothing before the first event, which is how the phone learns to stop
// paging. An empty answer here is the end of the history, not a fault.
assert!(
read_window(&path, Some(1), None, 3, false)
.expect("window")
@@ -555,24 +427,18 @@ mod tests {
.expect("append");
}
// The floor is exclusive, like the SSE route's `after`, and it -- not the
// limit -- is what the page stops at. This is the gap between a phone's
// cached run and the window on its screen, fetched exactly.
let page = read_window(&path, Some(9), Some(5), 100, false).expect("window");
assert_eq!(
page.iter().map(|entry| entry.seq).collect::<Vec<_>>(),
[6, 7, 8]
);
// A limit smaller than the gap still bites; the floor is a bound, not a
// replacement for one.
let page = read_window(&path, Some(9), Some(2), 3, false).expect("window");
assert_eq!(
page.iter().map(|entry| entry.seq).collect::<Vec<_>>(),
[6, 7, 8]
);
// A floor at or above the window is an empty page, not a walk past it.
assert!(
read_window(&path, Some(4), Some(9), 10, false)
.expect("window")
@@ -599,9 +465,6 @@ mod tests {
)
.expect("append"); // seq 5
// Cut inside the run: what comes back is the deltas above the floor, seq'd
// at the first of them -- the partial the phone's `healSplitMessage` welds
// onto the rest, the same as a run cut by the limit.
let rows = read_window(&path, Some(6), Some(2), 10, true).expect("window");
assert_eq!(rows.len(), 2);
assert!(matches!(
@@ -617,7 +480,6 @@ mod tests {
}
));
// And with no floor the whole run is one row, as before.
let rows = read_window(&path, Some(6), None, 10, true).expect("window");
assert_eq!(rows.len(), 2);
assert!(matches!(
@@ -631,8 +493,6 @@ mod tests {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("transcript.jsonl");
let mut transcript = Transcript::open(&path).expect("open");
// Two replies of three deltas each, split by a tool call: the shape a turn writes, and
// the one an event-counted page cannot see a row of.
for d in ["a", "b", "c"] {
transcript.append(text(d), 0.0).expect("append"); // seq 1..3
}
@@ -650,12 +510,8 @@ mod tests {
transcript.append(text(d), 0.0).expect("append"); // seq 5..7
}
// Three rows asked for, three rows returned -- each delta run one event -- where a raw
// window of three would have shown one and a half tokens of the newer reply.
let rows = read_window(&path, Some(8), None, 3, true).expect("window");
assert_eq!(rows.len(), 3);
// A run keeps its oldest delta's seq, so the phone anchors and pages from where it always
// did.
assert!(matches!(
&rows[0],
SeqEvent { seq: 1, event: Event::AssistantText { delta }, .. } if delta == "abc"
@@ -673,11 +529,9 @@ mod tests {
SeqEvent { seq: 5, event: Event::AssistantText { delta }, .. } if delta == "def"
));
// The next page pages from the oldest row's seq and returns the rest, no repeat, no gap.
let older = read_window(&path, Some(1), None, 3, true).expect("window");
assert!(older.is_empty());
// The newest window never coalesces even when asked: the live cursor depends on real seqs.
let newest = read_window(&path, None, None, 2, true).expect("window");
assert_eq!(newest.iter().map(|e| e.seq).collect::<Vec<_>>(), [6, 7]);
}
@@ -686,17 +540,6 @@ mod tests {
fn a_line_read_back_is_the_line_that_was_written() {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("transcript.jsonl");
// A timestamp with enough digits to be lost: the clock produces these all day, and this
// one is real (2026-09-04). serde_json's default float parser is not correctly rounded,
// so it read this back as ...0755 and every reader got a line one bit different from the
// one in the file -- while the SSE stream, which serializes the same struct, had already
// sent the original. Two answers to "what is line 1", indistinguishable by eye.
//
// Nothing on screen showed it: a `ts` is drawn as a relative time. What found it was the
// phone's transcript cache, which keeps the line it was sent and checks it against the
// server's own answer before resuming a stream from it -- so the mismatch turned into a
// cache thrown away and a transcript downloaded again, silently and only sometimes. The
// `float_roundtrip` feature in Cargo.toml is the fix; this is what keeps it.
let mut transcript = Transcript::open(&path).expect("open");
transcript
.append(text("hello"), 1788546972.6030757)
server/src/session/transport.rs
-76
View File
@@ -1,24 +1,3 @@
//! Where a session's process runs, and the only place that knows how.
//!
//! A driver says *what* to run -- a [`Launch`] -- and hands it here. Whether
//! that becomes a child of this process or an `ssh host …` invocation is
//! settled in this module, so a driver carries no transport knowledge and a
//! second one cannot forget to handle the remote case. It also means the
//! wrapping is honest about drivers that run nothing at all: `EchoDriver`
//! builds no [`Launch`], so there is no host for it to appear to honour.
//!
//! The quoting, the forced ssh options and the remote script are
//! `crate::ssh`'s: this module decides *which* transport, that one knows what a
//! correct ssh invocation is.
//!
//! A transport is therefore two operations rather than one: **run this** and
//! **reach this port**. The second is what a managed `llama-server` needs -- it
//! is spawned as a process and then spoken to over HTTP -- and it is a no-op
//! locally, where the port a program binds is already one this machine can
//! dial. Over ssh it is an `-L` tunnel on the same connection that runs the
//! command, so the model server binds loopback on the far machine and is never
//! exposed to its network. See [`Transport::reserve_port`].
use std::path::{Path, PathBuf};
use std::process::Stdio;
@@ -36,10 +15,6 @@ pub struct Launch {
pub program: String,
pub args: Vec<String>,
pub cwd: Option<PathBuf>,
/// A port this program will listen on, and the port that reaches it
/// from here -- see [`Transport::reserve_port`], which is the only
/// thing that should produce one.
///
/// On the launch rather than in [`Transport::spawn`]'s signature
/// because it is part of what is being run: a caller that needs to
/// reach the process it is starting says so once, where it says
@@ -66,23 +41,9 @@ impl Launch {
}
}
/// How a launched process's standard streams are connected.
///
/// The choice is not the transport's and not the driver's dialect: it is
/// whether the process is expected to outlive this server. A probe answers
/// within one call, so pipes this server drains are right. A session is a
/// conversation somebody is having, so its streams live in the session
/// directory where a later run of this server can pick them up.
pub enum Streams {
/// Pipes owned by this server; the child is killed when they drop.
Piped,
/// The same, except that stdin is already open on something this server
/// holds -- the file being copied to another machine. Bytes this process has
/// in memory do not need this: [`Streams::Piped`] gives a pipe to write them
/// into as the child reads.
PipedFrom(Stdio),
/// Files -- and, for stdin, a fifo the child itself holds open so it never
/// reads EOF -- that outlast this process.
Detached {
stdin: Stdio,
stdout: Stdio,
@@ -90,18 +51,12 @@ pub enum Streams {
},
}
/// The machine a session's process runs on.
pub enum Transport {
/// The machine this server is running on.
Here,
/// Reached with the system `ssh` client. Owns its entry rather than
/// borrowing it, so a session keeps working against the config it was
/// spawned with even if the setup is edited afterwards.
Ssh { name: String, ssh: SshConfig },
}
impl Transport {
/// The transport a setup describes; a setup with no `ssh` is here.
pub fn for_setup(setup: &crate::config::SetupConfig) -> Self {
match &setup.ssh {
Some(ssh) => Self::Ssh {
@@ -112,10 +67,6 @@ impl Transport {
}
}
/// Starts `launch` with its streams connected as `streams` says. The failure
/// names what to check, and the two transports fail for genuinely different
/// reasons -- a missing ssh client here versus a program not on the remote
/// PATH -- so each says its own thing.
pub fn spawn(&self, launch: &Launch, streams: Streams) -> Result<Child> {
let host = match self {
Self::Here => None,
@@ -149,9 +100,6 @@ impl Transport {
stderr,
} => {
command.stdin(stdin).stdout(stdout).stderr(stderr);
// No `kill_on_drop`: outliving this server is the point. Its own
// process group as well, so a signal sent to the server's group
// does not travel to a session meant to survive being stopped.
command.process_group(0);
}
}
@@ -198,9 +146,6 @@ impl Transport {
Ok(String::from_utf8_lossy(&output.stdout).into_owned())
}
/// Runs `launch` with `input` on its stdin and reports everything it
/// produced -- stdout as bytes, stderr as text, and the exit status.
///
/// The one description of "run this there, with this on stdin", so that
/// shipping an attachment and writing a file through the explorer are the
/// same operation rather than two. It is also the only capture that hands
@@ -211,9 +156,6 @@ impl Transport {
/// Bytes rather than a `String`, because a file's contents are not text
/// until something has checked, and lossy decoding would replace the
/// evidence that they are not.
///
/// `Err` means the process could not be started at all; a process that ran
/// and failed is a [`Captured`] with a status saying so.
pub async fn capture_with_input(&self, launch: &Launch, input: Input) -> Result<Captured> {
let (streams, to_write) = match input {
Input::None => (Streams::Piped, None),
@@ -245,13 +187,6 @@ impl Transport {
})
}
/// Picks a port for a launched program to serve on, and the port that
/// reaches it from here.
///
/// The "reach this port" half of what a transport is. Locally there is
/// one port and the OS chooses it, by binding and letting go -- racy
/// in principle, and nothing on this machine is hunting for ports.
///
/// Over ssh the near end is chosen the same way and the far end is a
/// guess, because there is no portable way to ask a machine for a free
/// port that does not race with binding it anyway. It is taken from
@@ -273,7 +208,6 @@ impl Transport {
})
}
/// How to say where this runs, for a log line a person reads.
pub fn describe(&self) -> String {
match self {
Self::Here => "on this machine".to_string(),
@@ -282,13 +216,8 @@ impl Transport {
}
}
/// Where a port on another machine is guessed from: high enough to be out
/// of the way of services, and below the 32768-60999 Linux hands out to
/// outgoing connections, which is where a guess would most often collide.
const FAR_PORTS: std::ops::Range<u16> = 20000..30000;
/// What a command is given on its standard input.
///
/// Three cases rather than an `Option<Stdio>` because they are three genuinely
/// different arrangements and only this knows which: nothing to say, bytes this
/// process is holding, or a file it has open. The last is how a
@@ -300,18 +229,13 @@ pub enum Input {
File(std::fs::File),
}
/// Everything a finished command produced, including the status.
pub struct Captured {
pub status: std::process::ExitStatus,
pub stdout: Vec<u8>,
/// Trimmed, and what a failure is reported as: ssh's own refusals and a
/// tool's own message about the file it could not open are both the useful
/// half of why something did not work.
pub stderr: String,
}
impl Captured {
/// The stdout of a command that succeeded, or the machine's own words.
pub fn ok(self) -> Result<Vec<u8>> {
if self.status.success() {
return Ok(self.stdout);