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,106 @@
//! Nested instructions — the `AGENTS.md` files off the launch chain, read when work reaches them.
//!
//! The system prompt carries the files from the top of the checkout down to where Luxe started,
//! and it's written once per session. A file in a folder off that chain (`web/AGENTS.md` when Luxe
//! started at the root) can't join it without rewriting the prompt every later request is cached
//! against. So it rides on the result of the first tool call that reaches its folder: an append,
//! like any other result. Whether the model already has one is read off the conversation by the
//! note that opens it, so a rewind or a compaction that took it away lets it be sent again.
use std::path::{Path, PathBuf};
/// Opens the block that carries a nested file. Its path follows, up to [`NOTE_REST`].
const NOTE_OPEN: &str = "[instructions: ";
/// What follows the path, which is also where reading one back stops: a path may hold a `]`.
const NOTE_REST: &str = "] Instructions for work in this folder, from the file there. They add \
to the project's.";
/// Whether nested files are read at all. `LUXE_NESTED_INSTRUCTIONS=0` turns them off.
pub(crate) fn enabled() -> bool {
std::env::var("LUXE_NESTED_INSTRUCTIONS").as_deref() != Ok("0")
}
/// The paths a call's arguments name: `path`, and each string in `paths`.
///
/// Those two keys cover the tools that open, write or search a place in the tree. A shell command
/// isn't parsed: guessing at the paths in one would load rules for folders the call never reached.
pub(crate) fn touched_paths(args: &serde_json::Value) -> Vec<&str> {
let single = args.get("path").and_then(serde_json::Value::as_str);
let many = args.get("paths").and_then(serde_json::Value::as_array).into_iter().flatten();
single
.into_iter()
.chain(many.filter_map(serde_json::Value::as_str))
.filter(|path| !path.trim().is_empty())
.collect()
}
/// One nested instruction file a call reached.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct NestedFile {
/// The file, canonical
pub(crate) path: PathBuf,
/// Its path from the top of the checkout, with forward slashes: what the note names
pub(crate) shown: String,
}
/// The instruction files that apply to `target` but weren't read at session start, top first.
///
/// Only folders inside the checkout `launch` sits in, off its chain, and not ignored: a file under
/// `node_modules` was written by a dependency's authors, not this project's. `target` may not exist
/// yet (a file about to be written), so the nearest folder that does stands in.
pub(crate) fn nested_files(launch: &Path, target: &Path) -> Vec<NestedFile> {
let chain: Vec<PathBuf> = crate::project::chain_from_top(launch)
.iter()
.filter_map(|folder| folder.canonicalize().ok())
.collect();
let (Some(top), Some(folder)) = (chain.first(), existing_folder(target)) else {
return Vec::new();
};
folders_below(top, &folder)
.into_iter()
.filter(|dir| !chain.iter().any(|on_chain| on_chain == dir))
.filter_map(|dir| Some((dir, instruction_file(dir)?)))
.filter(|(dir, _)| !crate::project_files::is_ignored(top, dir))
.filter_map(|(_, file)| nested_file(top, file))
.collect()
}
/// The folders from just below `top` down to `folder`, top first; none when `folder` is outside.
fn folders_below<'a>(top: &Path, folder: &'a Path) -> Vec<&'a Path> {
if !folder.starts_with(top) {
return Vec::new();
}
let mut below: Vec<&Path> = folder.ancestors().take_while(|dir| *dir != top).collect();
below.reverse();
below
}
/// The nearest folder at or above `target` that exists, canonical.
fn existing_folder(target: &Path) -> Option<PathBuf> {
target.ancestors().find(|path| path.is_dir())?.canonicalize().ok()
}
/// The instruction file `dir` holds, by the same names and order the launch chain uses.
fn instruction_file(dir: &Path) -> Option<PathBuf> {
super::INSTRUCTION_FILES.iter().map(|name| dir.join(name)).find(|path| path.is_file())
}
/// `file` as a [`NestedFile`], named from `top` by where it sits rather than where a link points.
fn nested_file(top: &Path, file: PathBuf) -> Option<NestedFile> {
let shown = crate::paths::display(file.strip_prefix(top).ok()?);
Some(NestedFile { path: file.canonicalize().ok()?, shown })
}
/// The block that carries `shown`'s text to the model.
pub(crate) fn note(shown: &str, text: &str) -> String {
format!("{NOTE_OPEN}{shown}{NOTE_REST}\n\n{text}")
}
/// The file a block carries, when `text` is one.
pub(crate) fn noted(text: &str) -> Option<&str> {
text.strip_prefix(NOTE_OPEN)?.split_once(NOTE_REST).map(|(shown, _)| shown)
}
#[cfg(test)]
mod tests;

View File

@@ -0,0 +1,101 @@
use super::*;
/// A checkout at a temp dir's root, with `files` written into it.
fn checkout(files: &[&str]) -> tempfile::TempDir {
let dir = tempfile::tempdir().expect("temp dir");
std::fs::create_dir_all(dir.path().join(".git")).expect("git marker");
for file in files {
let path = dir.path().join(file);
std::fs::create_dir_all(path.parent().expect("a parent")).expect("folders");
std::fs::write(&path, format!("- rules from {file}\n")).expect("write");
}
dir
}
/// What [`nested_files`] names for `target`, from Luxe launched at `launch`, both under `root`.
fn shown(root: &Path, launch: &str, target: &str) -> Vec<String> {
let files = nested_files(&root.join(launch), &root.join(target));
files.into_iter().map(|file| file.shown).collect()
}
/// The break this catches: reading only `path`, so a multi-file `read` loaded nothing.
#[test]
fn a_call_touches_its_path_and_each_of_its_paths() {
let args = serde_json::json!({ "path": "a.rs", "paths": ["web/b.ts", 7, "", "c.md"] });
assert_eq!(touched_paths(&args), ["a.rs", "web/b.ts", "c.md"]);
assert!(touched_paths(&serde_json::json!({ "command": "cat web/x" })).is_empty());
assert!(touched_paths(&serde_json::json!({ "path": 3 })).is_empty());
}
/// The break this catches: the walk started at the launch folder, so a file one folder over
/// from it was never found.
#[test]
fn a_folder_off_the_launch_chain_is_found() {
let root = checkout(&["AGENTS.md", "web/AGENTS.md", "web/src/app.ts"]);
assert_eq!(shown(root.path(), "", "web/src/app.ts"), ["web/AGENTS.md"]);
}
/// The break this catches: the walk ran nearest first, so the more general rules arrived last
/// and read as the ones that win.
#[test]
fn files_come_top_down() {
let root = checkout(&["web/AGENTS.md", "web/src/AGENTS.md", "web/src/app.ts"]);
let found = shown(root.path(), "", "web/src/app.ts");
assert_eq!(found, ["web/AGENTS.md", "web/src/AGENTS.md"]);
}
/// The break this catches: folders on the launch chain were offered again, sending a file the
/// system prompt already carries.
#[test]
fn the_launch_chain_is_left_to_the_system_prompt() {
let root = checkout(&["AGENTS.md", "web/AGENTS.md", "web/src/AGENTS.md", "web/src/app.ts"]);
assert_eq!(shown(root.path(), "web", "web/src/app.ts"), ["web/src/AGENTS.md"]);
assert!(shown(root.path(), "", "README.md").is_empty(), "the top is the prompt's");
}
/// The break this catches: no ignore check, so a dependency's own `AGENTS.md` under an ignored
/// folder instructed the model as if this project wrote it.
#[test]
fn an_ignored_folder_is_skipped_and_its_sibling_is_not() {
let root = checkout(&["vendor/lib/AGENTS.md", "app/AGENTS.md"]);
std::fs::write(root.path().join(".gitignore"), "vendor/\n").expect("gitignore");
assert!(shown(root.path(), "", "vendor/lib/x.rs").is_empty());
assert_eq!(shown(root.path(), "", "app/x.rs"), ["app/AGENTS.md"]);
}
/// The break this catches: no checkout boundary, so a path outside the project loaded the rules
/// of whoever owns that folder.
#[test]
fn a_path_outside_the_checkout_finds_nothing() {
let root = checkout(&[]);
let elsewhere = checkout(&["lib/AGENTS.md", "lib/x.rs"]);
let files = nested_files(root.path(), &elsewhere.path().join("lib/x.rs"));
assert!(files.is_empty(), "{files:?}");
}
/// The break this catches: a target that doesn't exist yet (a file about to be written) found
/// no folder and so no rules.
#[test]
fn a_file_not_written_yet_uses_the_nearest_folder() {
let root = checkout(&["web/AGENTS.md"]);
assert_eq!(shown(root.path(), "", "web/new/deep/page.ts"), ["web/AGENTS.md"]);
}
/// The break this catches: only `AGENTS.md` was looked for, so a folder that still carries a
/// `CLAUDE.md` was silent here while the launch chain read it.
#[test]
fn a_claude_md_counts_like_it_does_on_the_chain() {
let root = checkout(&["web/CLAUDE.md"]);
assert_eq!(shown(root.path(), "", "web/x.ts"), ["web/CLAUDE.md"]);
}
/// The break this catches: reading a note back stopped at the first `]`, so a path holding one
/// read as a different file and was sent again.
#[test]
fn a_note_reads_back_as_its_file() {
let block = note("web/[id]/AGENTS.md", "- rules");
assert_eq!(noted(&block), Some("web/[id]/AGENTS.md"));
assert!(block.ends_with("\n\n- rules"), "{block}");
assert_eq!(noted("[instructions: web/AGENTS.md"), None, "a fragment isn't a note");
assert_eq!(noted("12: [instructions: x] y"), None, "nor is a line of a file that quotes one");
}