Initial public release

Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
This commit is contained in:
Evan Whittaker
2026-10-17 12:08:30 -05:00
commit 09a7de2520
1730 changed files with 412952 additions and 0 deletions

View File

@@ -0,0 +1,74 @@
//! Live smoke test for the keyless search endpoint.
//!
//! Skipped unless `LUXE_TEST_LIVE_WEB=1`, so the suite stays offline. Run it when the endpoint's
//! response shape is in question — this is the test that would have caught the advanced tool
//! answering with a JSON envelope while the parser expected prose, which silently turned working
//! searches into "No results".
//!
//! ```bash
//! LUXE_TEST_LIVE_WEB=1 cargo test -p luxe-tools --test live_exa_mcp -- --nocapture
//! ```
use luxe_tools::exa_mcp::ExaMcpBackend;
use luxe_tools::web::SearchOptions;
fn enabled() -> bool {
std::env::var("LUXE_TEST_LIVE_WEB").is_ok_and(|value| value == "1")
}
#[tokio::test]
async fn the_keyless_endpoint_returns_usable_results_with_content() {
if !enabled() {
eprintln!("skipped: set LUXE_TEST_LIVE_WEB=1 to run");
return;
}
let hits = ExaMcpBackend::new()
.search_with(
"tokio select cancellation safety",
3,
&SearchOptions { include_content: true, ..Default::default() },
)
.await
.expect("the keyless endpoint answers with no credential of any kind");
assert!(!hits.is_empty(), "a mainstream query must return something");
for hit in &hits {
assert!(hit.url.starts_with("http"), "every hit carries a usable url: {hit:?}");
assert!(!hit.title.trim().is_empty(), "and a title: {hit:?}");
}
// The whole point of the tool: enough content to answer from, without a follow-up fetch.
assert!(
hits.iter().any(|hit| hit.snippet.chars().count() > 200),
"at least one result must carry a real passage, not a bare snippet: {hits:#?}"
);
eprintln!("{} hits · first: {} ({})", hits.len(), hits[0].title, hits[0].url);
}
#[tokio::test]
async fn domain_and_multi_query_filters_reach_the_endpoint() {
if !enabled() {
eprintln!("skipped: set LUXE_TEST_LIVE_WEB=1 to run");
return;
}
let hits = ExaMcpBackend::new()
.search_with(
"async runtime",
5,
&SearchOptions {
also: vec!["tokio runtime internals".to_string()],
include_domains: vec!["docs.rs".to_string()],
include_content: true,
..Default::default()
},
)
.await
.expect("filters are accepted");
assert!(!hits.is_empty(), "the domain filter must not empty the result set");
assert!(
hits.iter().all(|hit| hit.url.contains("docs.rs")),
"includeDomains is honored server-side: {hits:#?}"
);
}

View File

@@ -0,0 +1,200 @@
//! Live smoke tests for every `web_search` backend, run against the real vendors.
//!
//! Skipped unless `LUXE_TEST_LIVE_WEB=1`, so the suite stays offline; each keyed backend is
//! skipped again unless its key is in the environment. Unit tests pin the *request* each backend
//! builds, which is where the silent bugs live — a filter serialized under a name the vendor does
//! not read is accepted, ignored, and answered 200. These pin the other half: that the vendor
//! agrees, and that what comes back is shaped like an answer.
//!
//! Every backend here shipped once without this. Brave interpolated the query straight into a URL,
//! so `tokio select! & cancellation` reached it as `tokio select!`; Exa asked for `num_results`,
//! which it does not read, and never requested page text at all. Both returned confident results
//! for a question nobody asked.
//!
//! ```bash
//! LUXE_TEST_LIVE_WEB=1 cargo test -p luxe-tools --test live_web_search -- --nocapture
//! ```
use luxe_tools::brave::BraveBackend;
use luxe_tools::exa::ExaBackend;
use luxe_tools::firecrawl::FirecrawlBackend;
use luxe_tools::tavily::TavilyBackend;
use luxe_tools::web::{Recency, SearchBackend, SearchHit, SearchOptions};
fn enabled() -> bool {
std::env::var("LUXE_TEST_LIVE_WEB").is_ok_and(|value| value == "1")
}
/// The key for `var`, or `None` with a note saying which test was skipped and why.
fn key(var: &str) -> Option<String> {
if !enabled() {
eprintln!("skipped: set LUXE_TEST_LIVE_WEB=1 to run");
return None;
}
match std::env::var(var).ok().filter(|value| !value.trim().is_empty()) {
Some(key) => Some(key),
None => {
eprintln!("skipped: {var} is not set");
None
}
}
}
/// Every backend owes the caller the same three things, whatever it costs to get them.
fn assert_usable(hits: &[SearchHit], what: &str) {
assert!(!hits.is_empty(), "{what}: a mainstream query must return something");
for hit in hits {
assert!(hit.url.starts_with("http"), "{what}: every hit carries a usable url: {hit:?}");
assert!(!hit.title.trim().is_empty(), "{what}: and a title: {hit:?}");
}
assert!(
hits.iter().any(|hit| hit.snippet.chars().count() > 80),
"{what}: a result with no text to read is a link the model has to spend a fetch on: \
{hits:#?}"
);
eprintln!("{what}: {} hits · first: {} ({})", hits.len(), hits[0].title, hits[0].url);
}
#[tokio::test]
async fn brave_searches_the_query_it_was_given() {
let Some(api_key) = key("BRAVE_API_KEY") else { return };
let backend = BraveBackend::new(api_key);
let hits = backend
.search("tokio cancellation safety", 3, &SearchOptions::default())
.await
.expect("Brave answers");
assert_usable(&hits, "brave");
// The punctuation that used to truncate the query. Brave answers 200 either way, so the only
// observable difference is whether the results are about the right thing.
let punctuated = backend
.search("rust #[tokio::main] macro & async fn", 3, &SearchOptions::default())
.await
.expect("Brave accepts a punctuated query");
assert!(!punctuated.is_empty(), "a punctuated query must still search");
let filtered = backend
.search(
"cancellation",
5,
&SearchOptions {
include_domains: vec!["docs.rs".to_string()],
recency: Some(Recency::Year),
..Default::default()
},
)
.await
.expect("Brave accepts site: operators and a freshness code");
assert!(
filtered.iter().all(|hit| hit.url.contains("docs.rs")),
"site: operators are the domain filter Brave actually reads: {filtered:#?}"
);
// Above 20 Brave answers 422 rather than clamping, so the clamp has to be ours.
assert!(backend.search("rust", 50, &SearchOptions::default()).await.is_ok());
}
#[tokio::test]
async fn tavily_applies_every_filter_the_schema_advertises() {
let Some(api_key) = key("TAVILY_API_KEY") else { return };
let backend = TavilyBackend::new(api_key);
let hits = backend
.search(
"tokio cancellation safety",
3,
&SearchOptions { include_content: true, ..Default::default() },
)
.await
.expect("Tavily answers a bearer-authenticated request");
assert_usable(&hits, "tavily");
let filtered = backend
.search(
"tokio",
5,
&SearchOptions {
include_domains: vec!["docs.rs".to_string()],
recency: Some(Recency::Year),
..Default::default()
},
)
.await
.expect("Tavily accepts the filters");
assert!(
filtered.iter().all(|hit| hit.url.contains("docs.rs")),
"include_domains is honored server-side: {filtered:#?}"
);
}
#[tokio::test]
async fn exa_returns_the_count_asked_for_and_the_page_text() {
let Some(api_key) = key("EXA_API_KEY") else { return };
let backend = ExaBackend::new(api_key);
let hits = backend
.search(
"tokio cancellation safety",
3,
&SearchOptions { include_content: true, ..Default::default() },
)
.await
.expect("Exa answers");
assert_usable(&hits, "exa");
// `num_results` was accepted and ignored, so this came back as Exa's default page size.
assert!(hits.len() <= 3, "numResults is the field Exa reads: {} hits", hits.len());
assert!(
hits.iter().any(|hit| hit.snippet.chars().count() > 200),
"contents.text is what makes a hit answerable without a fetch: {hits:#?}"
);
}
#[tokio::test]
async fn firecrawl_searches_and_renders_a_page_a_plain_get_cannot_read() {
let Some(api_key) = key("FIRECRAWL_API_KEY") else { return };
let backend = FirecrawlBackend::new(api_key);
let hits = backend
.search(
"tokio cancellation safety",
3,
&SearchOptions { include_content: true, ..Default::default() },
)
.await
.expect("Firecrawl answers");
assert_usable(&hits, "firecrawl");
let filtered = backend
.search(
"cancellation",
5,
&SearchOptions {
include_domains: vec!["docs.rs".to_string()],
recency: Some(Recency::Year),
..Default::default()
},
)
.await
.expect("Firecrawl accepts the filters");
assert!(
filtered.iter().all(|hit| hit.url.contains("docs.rs")),
"includeDomains is honored server-side: {filtered:#?}"
);
// The reason this backend earns its place in `web_fetch`: a rendered page, as markdown.
let page = backend
.scrape("https://openrouter.ai/docs/features/prompt-caching")
.await
.expect("Firecrawl renders a JavaScript-built docs page");
assert!(page.len() > 2_000, "a rendered page is a page, not a shell: {} chars", page.len());
assert!(page.contains("cach"), "and it is the page that was asked for");
eprintln!("firecrawl scrape: {} chars", page.len());
// Firecrawl answers 200 with a stub for an upstream 404; reporting that as content would hand
// the model a "Not Found" page as though it were the article. (A *soft* 404 — a 200 whose body
// says the page is missing, which is what docs.rs serves — is indistinguishable from content
// and is not what this checks.)
let missing = backend.scrape("https://www.rust-lang.org/no-such-page-luxe-xyz").await;
assert!(missing.is_err(), "an upstream 404 is a failure, not a page: {missing:?}");
}

View File

@@ -0,0 +1,191 @@
//! Read-before-edit + staleness + blind-write guards, exercised with a shared `ReadTracker`.
#![allow(clippy::unwrap_used)]
use luxe_core::read_tracker::ReadTracker;
use luxe_core::{ContentBlock, Tool, ToolContext, ToolResultData};
use luxe_tools::edit::EditTool;
use luxe_tools::read::ReadTool;
use luxe_tools::write::WriteTool;
use serde_json::json;
use std::sync::Arc;
use tokio::sync::{mpsc, watch};
fn ctx(cwd: &std::path::Path) -> ToolContext {
let (event_tx, _rx) = mpsc::channel(16);
let (_cancel_tx, cancel_rx) = watch::channel(false);
ToolContext {
cwd: cwd.to_path_buf(),
session_id: "session".to_string(),
cancelled: Arc::new(cancel_rx),
event_tx,
hook_ctx: None,
question_broker: None,
}
}
fn text(result: &ToolResultData) -> String {
result
.content
.iter()
.filter_map(|block| match block {
ContentBlock::Text(t) => Some(t.clone()),
_ => None,
})
.collect::<Vec<_>>()
.join("\n")
}
#[tokio::test]
async fn edit_requires_a_prior_read_then_allows_follow_up_edits() {
let tmp = tempfile::tempdir().unwrap();
std::fs::write(tmp.path().join("f.txt"), "hello world").unwrap();
let tracker = Arc::new(ReadTracker::new());
let read = ReadTool::new().with_tracker(tracker.clone());
let edit = EditTool::new().with_tracker(tracker.clone());
let cx = ctx(tmp.path());
// Editing an unread file is rejected (read-before-edit).
let r = edit
.run(json!({ "path": "f.txt", "edits": [{ "oldText": "world", "newText": "there" }] }), &cx)
.await;
assert!(r.is_error, "unread edit must be rejected: {}", text(&r));
assert!(text(&r).contains("read-before-edit"), "message: {}", text(&r));
// After a read, the edit applies.
read.run(json!({ "path": "f.txt" }), &cx).await;
let r = edit
.run(json!({ "path": "f.txt", "edits": [{ "oldText": "world", "newText": "there" }] }), &cx)
.await;
assert!(!r.is_error, "read+edit should succeed: {}", text(&r));
assert_eq!(std::fs::read_to_string(tmp.path().join("f.txt")).unwrap(), "hello there");
// A follow-up edit works without re-reading: the tool refreshed the fingerprint on write.
let r = edit
.run(
json!({ "path": "f.txt", "edits": [{ "oldText": "there", "newText": "everyone" }] }),
&cx,
)
.await;
assert!(!r.is_error, "follow-up edit should succeed: {}", text(&r));
assert_eq!(std::fs::read_to_string(tmp.path().join("f.txt")).unwrap(), "hello everyone");
}
#[tokio::test]
async fn edit_rejects_a_file_changed_on_disk_since_read() {
let tmp = tempfile::tempdir().unwrap();
std::fs::write(tmp.path().join("f.txt"), "one").unwrap();
let tracker = Arc::new(ReadTracker::new());
let read = ReadTool::new().with_tracker(tracker.clone());
let edit = EditTool::new().with_tracker(tracker.clone());
let cx = ctx(tmp.path());
read.run(json!({ "path": "f.txt" }), &cx).await;
// Something else changes the file (different size ⇒ different fingerprint).
std::fs::write(tmp.path().join("f.txt"), "one-two-three").unwrap();
let r = edit
.run(json!({ "path": "f.txt", "edits": [{ "oldText": "one", "newText": "1" }] }), &cx)
.await;
assert!(r.is_error, "stale edit must be rejected: {}", text(&r));
assert!(text(&r).contains("changed on disk"), "message: {}", text(&r));
}
#[tokio::test]
async fn write_guards_blind_overwrite_but_allows_new_files() {
let tmp = tempfile::tempdir().unwrap();
std::fs::write(tmp.path().join("exists.txt"), "old content").unwrap();
let tracker = Arc::new(ReadTracker::new());
let read = ReadTool::new().with_tracker(tracker.clone());
let write = WriteTool::new().with_tracker(tracker.clone());
let cx = ctx(tmp.path());
// A brand-new file writes freely (create, no guard).
let r = write.run(json!({ "path": "new.txt", "content": "fresh" }), &cx).await;
assert!(!r.is_error, "new file write should succeed: {}", text(&r));
// Overwriting an existing, unread file is rejected (blind-write).
let r = write.run(json!({ "path": "exists.txt", "content": "clobbered" }), &cx).await;
assert!(r.is_error, "blind overwrite must be rejected: {}", text(&r));
assert_eq!(std::fs::read_to_string(tmp.path().join("exists.txt")).unwrap(), "old content");
// After reading it, the overwrite is allowed.
read.run(json!({ "path": "exists.txt" }), &cx).await;
let r = write.run(json!({ "path": "exists.txt", "content": "intentional" }), &cx).await;
assert!(!r.is_error, "read+overwrite should succeed: {}", text(&r));
assert_eq!(std::fs::read_to_string(tmp.path().join("exists.txt")).unwrap(), "intentional");
}
/// The read record lives in the process, not in the transcript, so a resumed session legitimately
/// starts with none. The rejection has to say that: a model told only "you haven't read this" while
/// looking at its own earlier read concludes the tool is broken and starts hand-editing around it.
#[tokio::test]
async fn a_rejection_explains_that_the_read_record_is_per_process() {
let tmp = tempfile::tempdir().unwrap();
std::fs::write(tmp.path().join("f.txt"), "hello").unwrap();
let cx = ctx(tmp.path());
// A fresh tracker is exactly the state a resumed session starts in.
let tracker = Arc::new(ReadTracker::new());
let edit = EditTool::new().with_tracker(tracker.clone());
let write = WriteTool::new().with_tracker(tracker.clone());
let rejected = edit
.run(json!({ "path": "f.txt", "edits": [{ "oldText": "hello", "newText": "hi" }] }), &cx)
.await;
let message = text(&rejected);
assert!(message.contains("this Luxe run"), "names the scope: {message}");
assert!(message.contains("resumed session"), "names the resume case: {message}");
assert!(message.contains("nothing was written"), "says the file is untouched: {message}");
let rejected = write.run(json!({ "path": "f.txt", "content": "clobber" }), &cx).await;
let message = text(&rejected);
assert!(message.contains("read-before-write guard"), "names the guard: {message}");
assert!(message.contains("resumed session"), "names the resume case: {message}");
assert_eq!(std::fs::read_to_string(tmp.path().join("f.txt")).unwrap(), "hello");
}
#[tokio::test]
async fn guards_are_skipped_without_a_tracker() {
// Default tools (no tracker) preserve the old permissive behavior — edit an unread file.
let tmp = tempfile::tempdir().unwrap();
std::fs::write(tmp.path().join("f.txt"), "hello").unwrap();
let edit = EditTool::new();
let cx = ctx(tmp.path());
let r = edit
.run(json!({ "path": "f.txt", "edits": [{ "oldText": "hello", "newText": "hi" }] }), &cx)
.await;
assert!(!r.is_error, "no-tracker edit should be permissive: {}", text(&r));
}
/// A file the model printed with `cat` has been looked at, so it may be edited; one it only piped
/// somewhere, or one a failed command named, has not.
#[cfg(unix)]
#[tokio::test]
async fn a_file_printed_by_cat_counts_as_read() {
use luxe_tools::bash::BashTool;
let tmp = tempfile::tempdir().unwrap();
for name in ["a.txt", "b.txt", "c.txt"] {
std::fs::write(tmp.path().join(name), "hello world").unwrap();
}
let tracker = Arc::new(ReadTracker::new());
let bash = BashTool::new().with_tracker(tracker.clone());
let edit = EditTool::new().with_tracker(tracker.clone());
let cx = ctx(tmp.path());
let change =
|path: &str| json!({ "path": path, "edits": [{ "oldText": "world", "newText": "there" }] });
bash.run(json!({ "command": "cat a.txt; cat b.txt | wc -c" }), &cx).await;
let r = edit.run(change("a.txt"), &cx).await;
assert!(!r.is_error, "printed, so seen: {}", text(&r));
let r = edit.run(change("b.txt"), &cx).await;
assert!(r.is_error, "piped into wc, so never shown: {}", text(&r));
bash.run(json!({ "command": "cat c.txt missing.txt" }), &cx).await;
let r = edit.run(change("c.txt"), &cx).await;
assert!(r.is_error, "the command failed, so nothing counts: {}", text(&r));
}

View File

@@ -0,0 +1,492 @@
//! Every parameter a tool advertises has to change what the tool does.
//!
//! A tool's schema is a promise to the model, and the model reads it on every request. A parameter
//! that is declared and then dropped somewhere down the call chain does not fail — it answers a
//! different question, confidently, and neither the model nor the person reading the transcript
//! can tell. `web_search` shipped that way: it advertised `queries`, `domains`, `recency` and
//! `content` while passing only the query and a count to any keyed backend, so configuring an API
//! key silently *downgraded* the tool.
//!
//! The check is behavioral rather than structural, because the structural version passes. Every one
//! of those four names appeared in `web_search`'s own module; they just never reached the vendor. So
//! each case here runs the tool twice against the same fixture — once with the parameter, once
//! without — and asserts the two answers differ. Nothing else can tell the difference between a
//! parameter that is read and one that is honored.
//!
//! Not exhaustive by construction: a parameter needs an input where its presence is observable, and
//! writing that input is the work. What it does guarantee is that no *covered* parameter can quietly
//! stop mattering.
#![allow(clippy::unwrap_used)]
use luxe_core::tool::{Tool, ToolContext, ToolResultData};
use luxe_tools::{edit, glob, grep, read, todo, write};
use std::sync::Arc;
use tempfile::TempDir;
use tokio::sync::{mpsc, watch};
fn context(cwd: &std::path::Path) -> ToolContext {
let (event_tx, _event_rx) = mpsc::channel(64);
let (_cancel_tx, cancel_rx) = watch::channel(false);
ToolContext {
cwd: cwd.to_path_buf(),
session_id: "schema-audit".to_string(),
cancelled: Arc::new(cancel_rx),
event_tx,
hook_ctx: None,
question_broker: None,
}
}
/// The text a tool returned, so two runs can be compared.
fn text(result: &ToolResultData) -> String {
result
.content
.iter()
.filter_map(|block| match block {
luxe_core::ContentBlock::Text(text) => Some(text.clone()),
_ => None,
})
.collect::<Vec<_>>()
.join("\n")
}
/// A small tree with enough shape for a filter to have something to remove.
fn fixture() -> TempDir {
let dir = TempDir::new().unwrap();
let root = dir.path();
std::fs::create_dir_all(root.join("src")).unwrap();
std::fs::create_dir_all(root.join("docs")).unwrap();
std::fs::create_dir_all(root.join("nested/deep")).unwrap();
std::fs::write(root.join("src/alpha.rs"), "fn alpha() {}\n// needle here\nfn beta() {}\n")
.unwrap();
std::fs::write(root.join("src/beta.rs"), "fn gamma() {}\n// needle again\n").unwrap();
std::fs::write(root.join("docs/notes.md"), "needle in prose\n").unwrap();
std::fs::write(root.join("nested/deep/buried.rs"), "// needle buried\n").unwrap();
std::fs::write(root.join(".gitignore"), "ignored/\n").unwrap();
std::fs::create_dir_all(root.join("ignored")).unwrap();
std::fs::write(root.join("ignored/hidden.rs"), "// needle hidden\n").unwrap();
let numbered: String = (1..=40).map(|n| format!("line {n}\n")).collect();
std::fs::write(root.join("numbered.txt"), numbered).unwrap();
dir
}
/// Run `tool` with `args` and return its text.
async fn run(tool: &dyn Tool, cwd: &std::path::Path, args: serde_json::Value) -> String {
text(&tool.run(args, &context(cwd)).await)
}
/// `read`: `offset` and `limit` each have to move the window.
#[tokio::test]
async fn read_honors_its_window() {
let dir = fixture();
let root = dir.path();
let tool = read::ReadTool::new();
let whole = run(&tool, root, serde_json::json!({"path": "numbered.txt"})).await;
let from_ten =
run(&tool, root, serde_json::json!({"path": "numbered.txt", "offset": 10})).await;
let first_three =
run(&tool, root, serde_json::json!({"path": "numbered.txt", "limit": 3})).await;
assert!(whole.contains("line 1\n") || whole.contains("line 1"), "{whole}");
assert_ne!(whole, from_ten, "offset must move the window");
assert_ne!(whole, first_three, "limit must bound the window");
assert!(!from_ten.contains("line 1\n"), "offset 10 must not start at line 1: {from_ten}");
assert!(first_three.contains("line 3"), "{first_three}");
assert!(!first_three.contains("line 4"), "limit 3 must stop at three lines: {first_three}");
}
/// `grep`: `path`, `glob`, `context` and `all` each have to change the result.
#[tokio::test]
async fn grep_honors_every_filter_it_advertises() {
let dir = fixture();
let root = dir.path();
let tool = grep::GrepTool::new();
let everywhere = run(&tool, root, serde_json::json!({"pattern": "needle"})).await;
let scoped = run(&tool, root, serde_json::json!({"pattern": "needle", "path": "docs"})).await;
let globbed = run(&tool, root, serde_json::json!({"pattern": "needle", "glob": "*.md"})).await;
let with_context =
run(&tool, root, serde_json::json!({"pattern": "needle", "context": 2})).await;
assert!(everywhere.contains("alpha.rs"), "the unfiltered search finds the tree: {everywhere}");
assert!(!scoped.contains("alpha.rs"), "`path` must scope the search: {scoped}");
assert!(scoped.contains("notes.md"), "{scoped}");
assert!(!globbed.contains("alpha.rs"), "`glob` must filter by name: {globbed}");
assert!(globbed.contains("notes.md"), "{globbed}");
assert_ne!(everywhere, with_context, "`context` must add surrounding lines");
assert!(with_context.contains("fn alpha"), "context 2 reaches the line above: {with_context}");
}
/// `grep` and `glob`'s `all`: the ignore rules are the default, and turning them off has to show.
#[tokio::test]
async fn the_all_flag_reaches_past_the_ignore_rules() {
let dir = fixture();
let root = dir.path();
let respected =
run(&grep::GrepTool::new(), root, serde_json::json!({"pattern": "needle"})).await;
let everything =
run(&grep::GrepTool::new(), root, serde_json::json!({"pattern": "needle", "all": true}))
.await;
assert!(!respected.contains("hidden.rs"), "gitignore is honored by default: {respected}");
assert!(everything.contains("hidden.rs"), "`all` must reach an ignored file: {everything}");
let globbed = run(&glob::GlobTool, root, serde_json::json!({"pattern": "**/*.rs"})).await;
let globbed_all =
run(&glob::GlobTool, root, serde_json::json!({"pattern": "**/*.rs", "all": true})).await;
assert!(!globbed.contains("hidden.rs"), "{globbed}");
assert!(globbed_all.contains("hidden.rs"), "{globbed_all}");
}
/// `glob`: `pattern` selects and `path` scopes.
#[tokio::test]
async fn glob_honors_its_pattern_and_root() {
let dir = fixture();
let root = dir.path();
let tool = glob::GlobTool;
let rust = run(&tool, root, serde_json::json!({"pattern": "**/*.rs"})).await;
let markdown = run(&tool, root, serde_json::json!({"pattern": "**/*.md"})).await;
let scoped = run(&tool, root, serde_json::json!({"pattern": "**/*.rs", "path": "src"})).await;
assert!(rust.contains("alpha.rs"), "{rust}");
assert!(!rust.contains("notes.md"), "the pattern must select: {rust}");
assert!(markdown.contains("notes.md"), "{markdown}");
assert!(scoped.contains("alpha.rs"), "{scoped}");
assert!(!scoped.contains("buried.rs"), "`path` must scope the walk: {scoped}");
}
/// `edit`: `replaceAll` is the difference between changing one occurrence and every one, and the
/// tool *refuses* an ambiguous edit without it — so a dropped flag is a refusal, not a wrong answer.
#[tokio::test]
async fn edit_honors_replace_all() {
let dir = TempDir::new().unwrap();
let root = dir.path();
let tool = edit::EditTool::new();
let body = "let x = old;\nlet y = old;\nlet z = old;\n";
// Without the flag, three occurrences are ambiguous and the edit is refused.
std::fs::write(root.join("a.rs"), body).unwrap();
let refused = run(
&tool,
root,
serde_json::json!({
"path": "a.rs",
"edits": [{"oldText": "old", "newText": "new"}],
}),
)
.await;
assert_eq!(std::fs::read_to_string(root.join("a.rs")).unwrap(), body, "{refused}");
// With it, all three change.
run(
&tool,
root,
serde_json::json!({
"path": "a.rs",
"edits": [{"oldText": "old", "newText": "new", "replaceAll": true}],
}),
)
.await;
let after = std::fs::read_to_string(root.join("a.rs")).unwrap();
assert_eq!(after.matches("new").count(), 3, "replaceAll must change every occurrence: {after}");
assert!(!after.contains("old"), "{after}");
}
/// `write`: both of its arguments, and the round trip through `read`.
#[tokio::test]
async fn write_puts_the_content_at_the_path() {
let dir = TempDir::new().unwrap();
let root = dir.path();
run(
&write::WriteTool::new(),
root,
serde_json::json!({"path": "nested/made.txt", "content": "first\nsecond\n"}),
)
.await;
assert_eq!(
std::fs::read_to_string(root.join("nested/made.txt")).unwrap(),
"first\nsecond\n",
"`content` must reach the file, at the `path` given"
);
let back =
run(&read::ReadTool::new(), root, serde_json::json!({"path": "nested/made.txt"})).await;
assert!(back.contains("second"), "{back}");
}
/// `todo`: the control plane's arguments are the ones a model gets wrong most, so each has to land.
#[tokio::test]
async fn todo_honors_the_fields_it_advertises() {
let dir = TempDir::new().unwrap();
let tool = todo::TodoTool::new(dir.path().join("todos"));
let root = dir.path();
run(&tool, root, serde_json::json!({"action": "add", "subject": "first"})).await;
run(&tool, root, serde_json::json!({"action": "add", "subject": "second"})).await;
let listed = run(&tool, root, serde_json::json!({"action": "list"})).await;
assert!(listed.contains("first") && listed.contains("second"), "{listed}");
// `status` has to move the task, and `list` has to reflect it.
run(&tool, root, serde_json::json!({"action": "update", "id": 1, "status": "completed"})).await;
let after = run(&tool, root, serde_json::json!({"action": "list"})).await;
assert_ne!(listed, after, "a status update must be visible in the list");
// `subjects` is the batch spelling of `subject`.
let batch =
run(&tool, root, serde_json::json!({"action": "add", "subjects": ["third", "fourth"]}))
.await;
let listed = run(&tool, root, serde_json::json!({"action": "list"})).await;
assert!(listed.contains("third") && listed.contains("fourth"), "{batch}\n{listed}");
// `complete` is in the schema's own `enum`, so the model will send it.
let completed = run(&tool, root, serde_json::json!({"action": "complete", "id": 2})).await;
let listed = run(&tool, root, serde_json::json!({"action": "list"})).await;
assert!(
!completed.starts_with("Unknown action"),
"an action the schema advertises must exist: {completed}"
);
assert!(listed.contains("[x] #2"), "`complete` must complete the task: {listed}");
}
/// A truncation hint has to name something the caller can actually do.
///
/// `design-tool-surface.md` states the check: take the hint literally, as a caller with no other
/// context would, and ask whether it can be followed for *every* input that can trigger it. Both
/// tools that drop output promise an artifact file, and both wrote that promise before knowing
/// whether the file existed — `tee_artifact` returns `None` on a read-only tree or a full disk.
///
/// A directory that cannot be written to is how that is reproduced, so this runs on unix only:
/// the mode bits are the mechanism.
#[cfg(unix)]
#[tokio::test]
async fn a_dropped_output_never_promises_an_artifact_it_could_not_write() {
use std::os::unix::fs::PermissionsExt;
let dir = TempDir::new().unwrap();
let root = dir.path();
// Read-only, so `.luxe/artifacts/` cannot be created.
let mut mode = std::fs::metadata(root).unwrap().permissions();
mode.set_mode(0o555);
std::fs::set_permissions(root, mode).unwrap();
// Enough lines that the cap fires and the hint is reached.
let noisy = "for i in $(seq 1 400); do echo \"line $i\"; done";
let out =
run(&luxe_tools::bash::BashTool::new(), root, serde_json::json!({"command": noisy})).await;
// Restore before the tempdir is cleaned up, or the drop leaks the directory.
let mut mode = std::fs::metadata(root).unwrap().permissions();
mode.set_mode(0o755);
std::fs::set_permissions(root, mode).unwrap();
assert!(!out.contains("Full output: "), "no artifact was written, so none may be named: {out}");
if out.contains("not shown") || out.contains("compressed") {
assert!(
out.contains("could not be saved"),
"output was dropped with no artifact and no explanation: {out}"
);
}
}
/// `screenshot`: the parameters that change the pixels have to change the pixels.
///
/// The least-covered tool in the tree by parameter count, and the one whose output nobody can
/// eyeball in CI. Skipped without a display, and `mode=url` skipped without a browser — but where
/// they exist, the image itself is the assertion: a `width`/`height` that does not reach the
/// browser produces a differently-sized PNG, and a `region` that does not reach the compositor
/// produces a full screen.
#[tokio::test]
async fn screenshot_honors_the_geometry_it_is_given() {
let display =
std::env::var_os("WAYLAND_DISPLAY").is_some() || std::env::var_os("DISPLAY").is_some();
if !display {
eprintln!("skipped: no display");
return;
}
let dir = TempDir::new().unwrap();
let tool = luxe_tools::screenshot::ScreenshotTool;
// `mode=url` is the one that runs everywhere a browser does, and carries three of the nine
// parameters. The PNG's own dimensions are the evidence.
let browser = ["chromium", "google-chrome", "chrome", "microsoft-edge", "chromium-browser"]
.iter()
.any(|name| luxe_core::program::resolve(name).is_some());
if !browser {
eprintln!("skipped: no headless browser");
return;
}
// Over loopback, not `file://`: the tool refuses a local path on purpose (a browser given one
// can read anything this user can), and loopback is the origin it explicitly allows.
let (port, _server) = serve_one_page("<html><body style='background:#0af'>hi</body></html>");
let url = format!("http://127.0.0.1:{port}/");
for (width, height) in [(400u32, 300u32), (900u32, 600u32)] {
let result = tool
.run(
serde_json::json!({
"mode": "url", "url": url, "width": width, "height": height, "waitMs": 200
}),
&context(dir.path()),
)
.await;
let png = result
.content
.iter()
.find_map(|block| match block {
luxe_core::ContentBlock::Image { data, .. } => Some(data.clone()),
_ => None,
})
.unwrap_or_else(|| panic!("a capture returns an image: {}", text(&result)));
let (got_w, got_h) = png_size(&png);
assert_eq!(
(got_w, got_h),
(width, height),
"width/height must reach the browser, not just the schema"
);
}
}
/// Serve one tiny page on a loopback port until the returned guard is dropped.
fn serve_one_page(body: &'static str) -> (u16, std::thread::JoinHandle<()>) {
use std::io::{Read, Write};
let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind");
let port = listener.local_addr().expect("addr").port();
let handle = std::thread::spawn(move || {
for stream in listener.incoming().take(8) {
let Ok(mut stream) = stream else { continue };
let mut scratch = [0u8; 1024];
let _ = stream.read(&mut scratch);
let response = format!(
"HTTP/1.1 200 OK\r\nContent-Type: text/html\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
body.len()
);
let _ = stream.write_all(response.as_bytes());
}
});
(port, handle)
}
#[cfg(unix)]
/// A word from the title of some window the compositor currently has, if it will say.
///
/// Hyprland only; elsewhere `window` mode resolves its target differently and there is nothing
/// portable to ask.
fn a_listed_window() -> Option<String> {
let output = std::process::Command::new("hyprctl").args(["clients", "-j"]).output().ok()?;
let clients: serde_json::Value = serde_json::from_slice(&output.stdout).ok()?;
clients
.as_array()?
.iter()
.filter_map(|client| client.get("title")?.as_str())
.find_map(|title| title.split_whitespace().find(|word| word.len() > 4).map(str::to_string))
}
/// A base64 PNG's pixel dimensions, read straight out of the IHDR chunk.
fn png_size(base64_data: &str) -> (u32, u32) {
use base64::Engine as _;
let bytes = base64::engine::general_purpose::STANDARD
.decode(base64_data)
.expect("the tool returns base64 PNG");
assert_eq!(&bytes[1..4], b"PNG", "not a PNG");
let at = |i: usize| u32::from_be_bytes([bytes[i], bytes[i + 1], bytes[i + 2], bytes[i + 3]]);
(at(16), at(20))
}
/// `screenshot`'s compositor-backed modes, against the real display.
///
/// `fullscreen`, `region` and `window` all go through the OS's own capture tool, and none of them
/// had ever run in a test — the browser path was the only one reachable without a display. Each is
/// checked by the one thing that cannot be faked: the dimensions of the PNG that comes back.
#[cfg(unix)]
#[tokio::test]
async fn screenshot_captures_the_screen_the_way_each_mode_says() {
if std::env::var_os("WAYLAND_DISPLAY").is_none() && std::env::var_os("DISPLAY").is_none() {
eprintln!("skipped: no display");
return;
}
// The capture programs themselves; without one, this mode cannot run at all.
let have_capture = ["grim", "maim", "scrot", "import", "screencapture"]
.iter()
.any(|name| luxe_core::program::resolve(name).is_some());
if !have_capture {
eprintln!("skipped: no screen-capture program");
return;
}
let dir = TempDir::new().unwrap();
let tool = luxe_tools::screenshot::ScreenshotTool;
// A *desktop* capture runs only with somebody at the keyboard, and a broker is what says there
// is one. This test stands in for an interactive session, which is the only place the
// fullscreen/region/window modes are offered at all.
let interactive = {
let mut cx = context(dir.path());
cx.question_broker = Some(Arc::new(luxe_core::question::QuestionBroker::new()));
cx
};
let capture = |args: serde_json::Value| {
let tool = &tool;
let interactive = &interactive;
async move {
let result = tool.run(args, interactive).await;
let image = result.content.iter().find_map(|block| match block {
luxe_core::ContentBlock::Image { data, .. } => Some(data.clone()),
_ => None,
});
(image, text(&result), result.is_error)
}
};
let (full, summary, failed) = capture(serde_json::json!({"mode": "fullscreen"})).await;
// A locked or sleeping screen draws no frames, so there is nothing to measure — the machine's
// state, not the tool's. The tool saying so in its own words is the part this still checks.
if failed && summary.contains("locked or asleep") {
eprintln!("skipped: the screen is not drawing ({summary})");
return;
}
assert!(!failed, "fullscreen: {summary}");
let full = full.expect("fullscreen returns an image");
let (screen_w, screen_h) = png_size(&full);
assert!(screen_w > 0 && screen_h > 0, "a screen has size: {screen_w}x{screen_h}");
eprintln!("fullscreen: {screen_w}x{screen_h}");
// A region has to be *that* region, not the screen — the assertion the geometry exists for.
let (width, height) = (200u32, 120u32);
let (region, summary, failed) =
capture(serde_json::json!({"mode": "region", "region": format!("0,0 {width}x{height}")}))
.await;
assert!(!failed, "region: {summary}");
let region = region.expect("region returns an image");
let (got_w, got_h) = png_size(&region);
assert_eq!(
(got_w, got_h),
(width, height),
"the region geometry must reach the compositor (screen is {screen_w}x{screen_h})"
);
// `window` needs a window to exist, so it is checked only where the compositor lists one.
// Its geometry comes from the compositor rather than the arguments, so the assertion is that
// it captured *a* window and not the whole screen.
if let Some(title) = a_listed_window() {
let (window, summary, failed) =
capture(serde_json::json!({"mode": "window", "window": title})).await;
if failed {
eprintln!("window mode unavailable here: {summary}");
} else {
let window = window.expect("window mode returns an image");
let (w, h) = png_size(&window);
assert!(w > 0 && h > 0, "a window has size: {w}x{h}");
eprintln!("window: {w}x{h}");
}
}
// `note` is echoed back, and is the only parameter whose whole job is to come back out.
let (_, summary, failed) =
capture(serde_json::json!({"mode": "region", "region": "0,0 64x64", "note": "audit mark"}))
.await;
assert!(!failed, "note: {summary}");
assert!(summary.contains("audit mark"), "`note` is echoed back: {summary}");
}

View File

@@ -0,0 +1,109 @@
//! Every tool subprocess decides what its stdin is, and dies when the turn does.
//!
//! Source scans, because both guard a *default* — and a default cannot be caught by testing the
//! code that takes it.
use std::path::Path;
/// Every `Command::new` in this crate sets `stdin` explicitly.
///
/// The break this catches, and it shipped: `grep` let `Command::output()` supply the default, which
/// is an empty pipe. ripgrep handed a pattern, no path and a readable stdin searches *that pipe*, so
/// every default search returned "No matches found" — a wrong answer reported as a success. Every
/// other launch site in the crate already chose `Stdio::null()`; `grep` was the one that inherited.
///
/// The rule is "choose", not "choose null": an MCP transport or a formatter that is fed on stdin
/// wants a pipe. What is banned is saying nothing and taking whatever the runtime hands over.
#[test]
fn every_tool_subprocess_chooses_its_own_stdin() {
let src = Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
let mut inherited = Vec::new();
for file in walk(&src) {
let text = std::fs::read_to_string(&file).expect("a readable source file");
// Trim the test module: fixtures spawn helpers whose stdin is not a tool's concern.
let body = text.split("\n#[cfg(test)]\nmod tests {").next().unwrap_or(&text);
for (number, line) in body.lines().enumerate() {
if !line.contains("Command::new(") {
continue;
}
// A builder is often configured over the following lines rather than in one chain, so
// the window is generous: this guards a convention, and a near miss that reads as a
// pass is cheaper than a rule people learn to work around.
let window: String = body.lines().skip(number).take(16).collect::<Vec<_>>().join("\n");
if !window.contains(".stdin(") {
let name = file.strip_prefix(&src).unwrap_or(&file).display();
inherited.push(format!("{name}:{}: {}", number + 1, line.trim()));
}
}
}
assert!(
inherited.is_empty(),
"these launch a subprocess without choosing its stdin, and the default is an empty pipe \
a search tool will happily search:\n {}",
inherited.join("\n ")
);
}
/// Every `Command::new` in this crate is `kill_on_drop`, or kills its own process group.
///
/// The engine cancels a tool by **dropping its future** — that is the whole mechanism, and the
/// obligation it buys is on the tool side. A spawn that opts out of neither outlives the turn that
/// was waiting on it: `grep`, `glob` and `ast_grep` all did, so cancelling a search on a large tree
/// left ripgrep, `fd` or ast-grep running with nothing left to receive their output.
///
/// `bash` is the exception the rule needs: it owns a process group and reaps it through a drop
/// guard, because `kill_on_drop` reaps the shell and orphans everything the shell started.
#[test]
fn every_tool_subprocess_dies_with_the_turn_that_started_it() {
let src = Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
let mut survivors = Vec::new();
for file in walk(&src) {
let text = std::fs::read_to_string(&file).expect("a readable source file");
let body = text.split("\n#[cfg(test)]\nmod ").next().unwrap_or(&text);
for (number, line) in body.lines().enumerate() {
// `std::process::Command` is synchronous: it cannot be dropped mid-wait, so there is no
// future to cancel and nothing to reap.
if !line.contains("Command::new(") || line.contains("std::process::Command::new(") {
continue;
}
let window: String = body.lines().skip(number).take(16).collect::<Vec<_>>().join("\n");
let reaped = window.contains(".kill_on_drop(")
|| window.contains("kill_on_drop(true)")
|| window.contains("detach_from_terminal(");
if !reaped {
let name = file.strip_prefix(&src).unwrap_or(&file).display();
survivors.push(format!("{name}:{}: {}", number + 1, line.trim()));
}
}
}
assert!(
survivors.is_empty(),
"these spawn a process that outlives a cancelled turn — add `.kill_on_drop(true)`, or own \
the process group and reap it:\n {}",
survivors.join("\n ")
);
}
/// Every `.rs` file under a directory.
fn walk(dir: &Path) -> Vec<std::path::PathBuf> {
let mut found = Vec::new();
let Ok(entries) = std::fs::read_dir(dir) else { return found };
for entry in entries.flatten() {
let path = entry.path();
if path.is_dir() {
found.extend(walk(&path));
} else if path.extension().is_some_and(|ext| ext == "rs")
&& path.file_name().is_some_and(|name| name != "tests.rs")
{
// a sibling `tests.rs` is the test module, whose fixtures are not a tool's concern
found.push(path);
}
}
found
}

View File

@@ -0,0 +1,93 @@
// Integration tests for web tools.
//
// These tests verify the full pipeline from tool invocation to result formatting.
use luxe_core::tool::{Tool, ToolContext};
use luxe_tools::web::{SearchHit, WebConfig, WebTools};
use std::sync::Arc;
use tempfile::TempDir;
use tokio::sync::{mpsc, watch};
fn test_context(tmp_dir: &std::path::Path) -> ToolContext {
let (event_tx, _event_rx) = mpsc::channel(64);
let (_cancel_tx, cancel_rx) = watch::channel(false);
ToolContext {
cwd: tmp_dir.to_path_buf(),
session_id: "test-session".to_string(),
cancelled: Arc::new(cancel_rx),
event_tx,
hook_ctx: None,
question_broker: None,
}
}
#[tokio::test]
async fn test_web_search_integration_no_query() {
let tools = WebTools::new(WebConfig::default());
let tool = tools.web_search();
let tmp_dir = TempDir::new().unwrap();
let ctx = test_context(tmp_dir.path());
let result = tool.run(serde_json::json!({}), &ctx).await;
assert!(result.is_error);
}
/// Search with no key is a working capability, not an error — it falls back to the keyless
/// endpoint. Asserted through backend selection rather than by running a search, because a suite
/// that reaches the internet is a suite that fails on a plane.
#[tokio::test]
async fn search_without_a_key_resolves_a_backend_instead_of_failing() {
let config = WebConfig::default();
assert!(!config.has_search_key(), "nothing configured");
assert!(
luxe_tools::web::create_backend(&config).await.is_ok(),
"a fresh install still gets web search"
);
}
#[tokio::test]
async fn test_web_fetch_integration_no_url() {
let tools = WebTools::new(WebConfig::default());
let tool = tools.web_fetch();
let tmp_dir = TempDir::new().unwrap();
let ctx = test_context(tmp_dir.path());
let result = tool.run(serde_json::json!({}), &ctx).await;
assert!(result.is_error);
}
#[tokio::test]
async fn test_web_fetch_integration_no_api_key() {
let tools = WebTools::new(WebConfig::default());
let tool = tools.web_fetch();
let tmp_dir = TempDir::new().unwrap();
let ctx = test_context(tmp_dir.path());
let result = tool.run(serde_json::json!({"url": "https://example.com"}), &ctx).await;
// web_fetch returns a placeholder result without checking API keys
assert!(!result.is_error);
}
#[tokio::test]
async fn test_search_hit_serialization() {
let hits = vec![SearchHit {
title: "Test Title".to_string(),
url: "https://example.com".to_string(),
snippet: "Test Snippet".to_string(),
}];
let json_str = serde_json::to_string_pretty(&hits).unwrap();
assert!(json_str.contains("Test Title"));
assert!(json_str.contains("https://example.com"));
assert!(json_str.contains("Test Snippet"));
}
#[tokio::test]
async fn test_search_hit_deserialization() {
let json = r#"[{"title":"Test","url":"https://example.com","snippet":"Snippet"}]"#;
let hits: Vec<SearchHit> = serde_json::from_str(json).unwrap();
assert_eq!(hits.len(), 1);
assert_eq!(hits[0].title, "Test");
assert_eq!(hits[0].url, "https://example.com");
assert_eq!(hits[0].snippet, "Snippet");
}