Luxe 0.1.3: your sessions on your phone, joinable sessions, and nested AGENTS.md

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

The CHANGELOG has the full list.
This commit is contained in:
Evan Whittaker
2026-10-20 02:40:13 -05:00
parent 99e30d6d0f
commit d2129a886f
423 changed files with 31666 additions and 1669 deletions

View File

@@ -0,0 +1,107 @@
//! Session claims — one Luxe process writes a session's log at a time.
//!
//! Two processes appending to one log interleave entries that each parent on their own leaf, so a
//! resume walks one branch and silently drops the other's turns. A claim is an OS lock on a
//! `.lock` file beside the log: the system lets go of it when the process ends, however it ends,
//! so a crash never leaves a session stuck. Within one process the claim is counted instead,
//! since the TUI starts the next engine on a session before the last one has let go of it.
use std::collections::HashMap;
use std::fs::{File, OpenOptions, TryLockError};
use std::io;
use std::path::{Path, PathBuf};
use std::sync::{Mutex, MutexGuard, OnceLock};
/// This process's claim on one session, released when the last one for that session drops.
#[derive(Debug)]
pub struct SessionClaim {
lock_path: PathBuf,
}
/// The locks this process holds, by lock file, with how many claims share each.
struct Held {
_file: File,
claims: usize,
}
fn held() -> MutexGuard<'static, HashMap<PathBuf, Held>> {
static HELD: OnceLock<Mutex<HashMap<PathBuf, Held>>> = OnceLock::new();
// A panic mid-update leaves a count off by one at worst, which a restart clears
HELD.get_or_init(Default::default).lock().unwrap_or_else(std::sync::PoisonError::into_inner)
}
/// Claim the session whose lock file is `lock_path`. `None` when another process holds it.
pub(crate) fn claim(lock_path: &Path) -> io::Result<Option<SessionClaim>> {
let mut held = held();
if let Some(shared) = held.get_mut(lock_path) {
shared.claims += 1;
return Ok(Some(SessionClaim { lock_path: lock_path.to_path_buf() }));
}
let file = OpenOptions::new().create(true).truncate(false).write(true).open(lock_path)?;
match file.try_lock() {
Ok(()) => {}
Err(TryLockError::WouldBlock) => return Ok(None),
Err(TryLockError::Error(error)) => return Err(error),
}
held.insert(lock_path.to_path_buf(), Held { _file: file, claims: 1 });
Ok(Some(SessionClaim { lock_path: lock_path.to_path_buf() }))
}
impl Drop for SessionClaim {
fn drop(&mut self) {
let mut held = held();
let Some(shared) = held.get_mut(&self.lock_path) else { return };
shared.claims -= 1;
if shared.claims == 0 {
// Closing the file is what releases the lock; the empty file stays, since removing it
// would race a process that just opened it to lock
held.remove(&self.lock_path);
}
}
}
#[cfg(test)]
mod tests {
use super::*;
/// Whether some other holder could take the lock right now, as another process would.
fn free_for_another(lock_path: &Path) -> bool {
let file = File::open(lock_path).expect("the lock file exists");
file.try_lock().is_ok()
}
/// The break this catches: a claim that takes no OS lock, so a second Luxe writes beside it.
#[test]
fn a_claim_keeps_other_holders_out_until_it_drops() {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("s.lock");
let claimed = claim(&path).expect("claim").expect("free");
assert!(!free_for_another(&path));
drop(claimed);
assert!(free_for_another(&path));
}
/// The break this catches: ignoring a lock someone else holds.
#[test]
fn a_session_held_elsewhere_is_refused() {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("s.lock");
let other = File::create(&path).expect("create");
other.try_lock().expect("the other holder locks first");
assert!(claim(&path).expect("claim").is_none());
}
/// The break this catches: releasing on the first drop, so the engine that's still running
/// loses its claim when the one it replaced shuts down.
#[test]
fn claims_within_one_process_are_counted() {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("s.lock");
let first = claim(&path).expect("claim").expect("free");
let second = claim(&path).expect("claim").expect("this process already holds it");
drop(first);
assert!(!free_for_another(&path), "still claimed by the second");
drop(second);
assert!(free_for_another(&path));
}
}

View File

@@ -2,6 +2,8 @@
use super::*;
mod cache;
/// In-memory index of sessions for fast lookup.
#[derive(Debug, Default)]
struct SessionIndex {
@@ -17,13 +19,20 @@ pub struct JsonlSessionStore {
index: SessionIndex,
/// Project hash for directory naming (derived from cwd).
project_hash: String,
/// The parsed entries of the session this store writes
cache: cache::SessionCache,
}
impl JsonlSessionStore {
/// Create a new store rooted at `root`, scanning for existing sessions.
pub fn new(root: impl Into<PathBuf>) -> Self {
let root = root.into();
let mut store = Self { root, index: SessionIndex::default(), project_hash: String::new() };
let mut store = Self {
root,
index: SessionIndex::default(),
project_hash: String::new(),
cache: cache::SessionCache::default(),
};
store.scan_for_sessions();
store
}
@@ -73,6 +82,13 @@ impl JsonlSessionStore {
self.index.sessions.keys().cloned().collect()
}
/// Path to a session's `.jsonl` file, or [`SessionError::NotFound`].
fn known_path(&self, session: &SessionId) -> Result<&PathBuf, SessionError> {
let (path, _) =
self.index.sessions.get(session).ok_or(SessionError::NotFound(session.clone()))?;
Ok(path)
}
/// Path to a session's `.jsonl` file, if the store knows the session.
pub fn session_path(&self, session: &SessionId) -> Option<PathBuf> {
self.index.sessions.get(session).map(|(path, _)| path.clone())
@@ -120,6 +136,7 @@ impl SessionStore for JsonlSessionStore {
writer.flush()?;
self.index.sessions.insert(session_id.clone(), (dir, Some(header.id.clone())));
self.cache.writing(&session_id);
Ok(session_id)
}
@@ -152,43 +169,28 @@ impl SessionStore for JsonlSessionStore {
}
fn load(&self, session: &SessionId) -> Result<Vec<Entry>, SessionError> {
let (path, _) =
self.index.sessions.get(session).ok_or(SessionError::NotFound(session.clone()))?;
let file = fs::File::open(path)?;
let reader = io::BufReader::new(file);
let mut entries = Vec::new();
for (line_num, line) in reader.lines().enumerate() {
let line = line?;
if line.is_empty() {
continue;
}
let entry: Entry = serde_json::from_str(&line)
.map_err(|e| SessionError::JsonParse { line: line_num + 1, error: e })?;
entries.push(entry);
}
Ok(entries)
let path = self.known_path(session)?;
self.cache.read(session, path, |entries| Ok(entries.to_vec()))
}
fn active_path(&self, session: &SessionId, leaf: &EntryId) -> Result<Vec<Entry>, SessionError> {
let entries = self.load(session)?;
let path = self.known_path(session)?;
self.cache.read(session, path, |entries| {
Ok(walk_to_root(entries, leaf)?.into_iter().cloned().collect())
})
}
let by_id: HashMap<&EntryId, &Entry> = entries.iter().map(|e| (&e.id, e)).collect();
let mut path = Vec::new();
let mut current_id: Option<&EntryId> = Some(leaf);
while let Some(id) = current_id {
let entry = by_id.get(id).ok_or(SessionError::EntryNotFound(id.clone()))?;
path.push((*entry).clone());
current_id = entry.parent_id.as_ref();
}
// Reverse to get root-to-leaf order.
path.reverse();
Ok(path)
fn visit_active_path(
&self,
session: &SessionId,
leaf: &EntryId,
visit: &mut dyn FnMut(&[&Entry]),
) -> Result<(), SessionError> {
let path = self.known_path(session)?;
self.cache.read(session, path, |entries| {
visit(&walk_to_root(entries, leaf)?);
Ok(())
})
}
fn list_sessions(&self) -> Vec<SessionId> {
@@ -205,4 +207,29 @@ impl SessionStore for JsonlSessionStore {
sorted.truncate(limit);
sorted
}
fn claim(&self, session: &SessionId) -> Result<Option<SessionClaim>, SessionError> {
let lock_path = self.session_dir(session).with_extension("lock");
match claim::claim(&lock_path)? {
Some(claimed) => {
self.cache.writing(session);
Ok(Some(claimed))
}
None => Err(SessionError::OpenElsewhere(session.clone())),
}
}
}
/// The entries from the root to `leaf`.
fn walk_to_root<'a>(entries: &'a [Entry], leaf: &EntryId) -> Result<Vec<&'a Entry>, SessionError> {
let by_id: HashMap<&EntryId, &Entry> = entries.iter().map(|e| (&e.id, e)).collect();
let mut path = Vec::new();
let mut current_id: Option<&EntryId> = Some(leaf);
while let Some(id) = current_id {
let entry = by_id.get(id).ok_or(SessionError::EntryNotFound(id.clone()))?;
path.push(*entry);
current_id = entry.parent_id.as_ref();
}
path.reverse();
Ok(path)
}

View File

@@ -0,0 +1,109 @@
//! Cache — the session a store writes, parsed once and then read on from where it left off.
//!
//! A long session's file runs to tens of megabytes, and the engine reads its active path on every
//! model call, so parsing it whole each time cost ~60ms a call on a 68 MB session. Only the session
//! this store writes is kept: the picker and the GitHub overview read every session, and keeping
//! those would hold all of them in memory.
use std::fs;
use std::io::{Read, Seek, SeekFrom};
use std::path::Path;
use std::sync::{Mutex, MutexGuard};
use super::super::{Entry, SessionError, SessionId};
/// The entries parsed so far and where in the file the parse stopped.
#[derive(Default)]
struct Parsed {
entries: Vec<Entry>,
bytes: u64,
lines: usize,
}
#[derive(Default)]
struct CacheState {
writing: Option<SessionId>,
parsed: Parsed,
}
/// The parsed entries of the session the store writes, refreshed from the file on each read.
#[derive(Default)]
pub(super) struct SessionCache {
state: Mutex<CacheState>,
}
impl SessionCache {
/// Marks `session` as the one this store writes, dropping another session's entries.
pub(super) fn writing(&self, session: &SessionId) {
let mut state = self.lock();
if state.writing.as_ref() != Some(session) {
*state = CacheState { writing: Some(session.clone()), parsed: Parsed::default() };
}
}
/// Calls `read` with every entry in `path`, parsing only what was added since the last call
/// when `session` is the one this store writes, and the whole file otherwise.
pub(super) fn read<T>(
&self,
session: &SessionId,
path: &Path,
read: impl FnOnce(&[Entry]) -> Result<T, SessionError>,
) -> Result<T, SessionError> {
let mut state = self.lock();
if state.writing.as_ref() != Some(session) {
drop(state);
let mut fresh = Parsed::default();
catch_up(&mut fresh, path)?;
return read(&fresh.entries);
}
catch_up(&mut state.parsed, path)?;
read(&state.parsed.entries)
}
fn lock(&self) -> MutexGuard<'_, CacheState> {
// the state is rebuilt from the file on the next read, so a panicked reader left nothing
// that matters
self.state.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
}
}
/// Parses whatever `path` gained since `parsed` last read it. A file shorter than what was read
/// was replaced, so it's read again from the start.
fn catch_up(parsed: &mut Parsed, path: &Path) -> Result<(), SessionError> {
let length = fs::metadata(path)?.len();
if length < parsed.bytes {
*parsed = Parsed::default();
}
if length == parsed.bytes {
return Ok(());
}
let mut file = fs::File::open(path)?;
file.seek(SeekFrom::Start(parsed.bytes))?;
let mut tail = String::new();
file.read_to_string(&mut tail)?;
let (entries, lines) = parse_lines(&tail, parsed.lines)?;
parsed.entries.extend(entries);
parsed.lines += lines;
parsed.bytes += tail.len() as u64;
Ok(())
}
/// The entries in `text`, numbering lines on from `before` so an error names the file's line.
/// Returns them with how many lines `text` held.
fn parse_lines(text: &str, before: usize) -> Result<(Vec<Entry>, usize), SessionError> {
let mut entries = Vec::new();
let mut lines = 0;
for line in text.lines() {
lines += 1;
if line.is_empty() {
continue;
}
let entry = serde_json::from_str(line)
.map_err(|error| SessionError::JsonParse { line: before + lines, error })?;
entries.push(entry);
}
Ok((entries, lines))
}
#[cfg(test)]
mod tests;

View File

@@ -0,0 +1,138 @@
#![allow(clippy::unwrap_used)]
use super::super::super::{
EntryKind, JsonlSessionStore, Message, SessionError, SessionId, SessionStore,
};
use std::fs;
use std::path::Path;
fn store_at(root: &Path) -> JsonlSessionStore {
let mut store = JsonlSessionStore::new(root);
store.set_project_hash("project");
store
}
fn say(store: &mut JsonlSessionStore, session: &SessionId, words: &str) {
store.append(session, None, EntryKind::Message(Message::user(words))).unwrap();
}
/// Breaks the file's first line in place, keeping its length, so a store that parses the file
/// again fails and one reading on from where it stopped doesn't notice.
fn break_first_line(path: &Path) {
let mut bytes = fs::read(path).unwrap();
bytes[0] = b'x';
fs::write(path, bytes).unwrap();
}
// The break this catches: a cache that never looks at the file again, so another Luxe's entries
// (or a write this store didn't make) never show up
#[test]
fn entries_another_store_appends_are_read_on() {
let root = tempfile::tempdir().unwrap();
let mut mine = store_at(root.path());
let session = mine.create("/tmp").unwrap();
assert_eq!(mine.load(&session).unwrap().len(), 1);
say(&mut store_at(root.path()), &session, "from elsewhere");
assert_eq!(mine.load(&session).unwrap().len(), 2);
}
// The break this catches: the session being parsed whole on every read, ~60ms a model call on a
// long session, which is what the cache is for
#[test]
fn what_was_read_is_not_parsed_again() {
let root = tempfile::tempdir().unwrap();
let mut store = store_at(root.path());
let session = store.create("/tmp").unwrap();
store.load(&session).unwrap();
break_first_line(&store.session_dir(&session));
say(&mut store, &session, "after");
assert_eq!(store.load(&session).unwrap().len(), 2, "read on from where it stopped");
let fresh = store_at(root.path());
assert!(matches!(fresh.load(&session), Err(SessionError::JsonParse { line: 1, .. })));
}
// The break this catches: a resumed session, which this store claims rather than creates, parsed
// whole on every read
#[test]
fn a_claimed_session_is_kept() {
let root = tempfile::tempdir().unwrap();
let session = store_at(root.path()).create("/tmp").unwrap();
let store = store_at(root.path());
let _claim = store.claim(&session).unwrap();
store.load(&session).unwrap();
break_first_line(&store.session_dir(&session));
assert_eq!(store.load(&session).unwrap().len(), 1);
}
// The break this catches: a switch to another session keeping the first one cached, so the
// session now being written is parsed whole on every read
#[test]
fn switching_sessions_keeps_the_new_one() {
let root = tempfile::tempdir().unwrap();
let mut store = store_at(root.path());
let first = store.create("/tmp").unwrap();
store.load(&first).unwrap();
let second = store.create("/tmp").unwrap();
store.load(&second).unwrap();
break_first_line(&store.session_dir(&second));
assert_eq!(store.load(&second).unwrap().len(), 1);
}
// The break this catches: a file replaced by a shorter one served from the old entries, or read
// on from an offset past its end
#[test]
fn a_shorter_file_is_read_again_from_the_start() {
let root = tempfile::tempdir().unwrap();
let mut store = store_at(root.path());
let session = store.create("/tmp").unwrap();
let path = store.session_dir(&session);
let header = fs::read_to_string(&path).unwrap();
say(&mut store, &session, "dropped");
assert_eq!(store.load(&session).unwrap().len(), 2);
fs::write(&path, header).unwrap();
assert_eq!(store.load(&session).unwrap().len(), 1);
}
// The break this catches: every session the picker reads kept in memory, or one served from
// the cache though this store doesn't write it
#[test]
fn a_session_this_store_does_not_write_is_read_fresh() {
let root = tempfile::tempdir().unwrap();
let other = store_at(root.path()).create("/tmp").unwrap();
let mut store = store_at(root.path());
store.create("/tmp").unwrap();
store.load(&other).unwrap();
break_first_line(&store.session_dir(&other));
assert!(matches!(store.load(&other), Err(SessionError::JsonParse { line: 1, .. })));
}
// The break this catches: a bad line found while reading on reported by its place in the new
// part rather than in the file, pointing at the wrong line
#[test]
fn a_bad_line_read_later_names_its_line_in_the_file() {
let root = tempfile::tempdir().unwrap();
let mut store = store_at(root.path());
let session = store.create("/tmp").unwrap();
say(&mut store, &session, "fine");
store.load(&session).unwrap();
let path = store.session_dir(&session);
let mut text = fs::read_to_string(&path).unwrap();
text.push_str("not json\n");
fs::write(&path, text).unwrap();
assert!(matches!(store.load(&session), Err(SessionError::JsonParse { line: 3, .. })));
}
// The break this catches: the walk from a leaf served from the cache going stale, so a request
// built after an append is missing the newest entry
#[test]
fn the_active_path_includes_what_was_just_appended() {
let root = tempfile::tempdir().unwrap();
let mut store = store_at(root.path());
let session = store.create("/tmp").unwrap();
let header = store.load(&session).unwrap()[0].id.clone();
let leaf =
store.append(&session, Some(header), EntryKind::Message(Message::user("now"))).unwrap();
let path = store.active_path(&session, &leaf).unwrap();
assert_eq!(path.last().map(|entry| &entry.id), Some(&leaf));
assert_eq!(path.len(), 2);
}

View File

@@ -119,6 +119,46 @@ fn active_path_reconstructs_conversation() {
fs::remove_dir_all(root).ok();
}
/// The break this catches: lending the whole log, or the walk unreversed, rather than the branch
/// from the root to the leaf, which a request built from it would send as the conversation.
#[test]
fn with_active_path_lends_only_the_branch_to_the_leaf() {
let root = temp_root();
let mut store = JsonlSessionStore::new(&root);
store.set_project_hash("test-project");
let session = store.create("/tmp/test").unwrap();
let header = store.load(&session).unwrap()[0].id.clone();
let question = Message::user("q");
let user = store.append(&session, Some(header.clone()), EntryKind::Message(question)).unwrap();
let other = EntryKind::Message(Message::assistant("other"));
store.append(&session, Some(user.clone()), other).unwrap();
let kept = EntryKind::Message(Message::assistant("kept"));
let leaf = store.append(&session, Some(user.clone()), kept).unwrap();
let lent = with_active_path(&store, &session, &leaf, |path| {
path.iter().map(|entry| entry.id.clone()).collect::<Vec<_>>()
});
assert_eq!(lent.unwrap(), vec![header, user, leaf]);
fs::remove_dir_all(root).ok();
}
/// The break this catches: a leaf the log lacks lending a shortened path instead of failing, so a
/// request would go out without the conversation behind it.
#[test]
fn with_active_path_refuses_a_leaf_the_log_lacks() {
let root = temp_root();
let mut store = JsonlSessionStore::new(&root);
store.set_project_hash("test-project");
let session = store.create("/tmp/test").unwrap();
let missing = EntryId::new();
let lent = with_active_path(&store, &session, &missing, |path| path.len());
assert!(matches!(&lent, Err(SessionError::EntryNotFound(id)) if *id == missing), "{lent:?}");
fs::remove_dir_all(root).ok();
}
#[test]
fn branching_two_children() {
let root = temp_root();