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

@@ -6,11 +6,10 @@
//! `EXA_API_KEY` still wins, since an explicit choice outranks the fallback, but having none does
//! not mean having no web search.
//!
//! The endpoint also carries the whole feature set worth having: several query variations in one
//! call, domain include/exclude, a published-after date, and extracted highlights. That last one is
//! the point. Returning titles and snippets forces the model into one `web_fetch` per result — a
//! research question becomes six round-trips. Returning the passages *with* the results answers it
//! in one.
//! The endpoint also carries the whole feature set worth having: domain include/exclude, a
//! published-after date, and extracted highlights. That last one is the point. Returning titles
//! and snippets forces the model into one `web_fetch` per result — a research question becomes six
//! round-trips. Returning the passages *with* the results answers it in one.
use serde::Deserialize;
@@ -98,9 +97,8 @@ impl SearchBackend for ExaMcpBackend {
self.search_with(query, n, options).await
}
/// Exa's advanced tool takes every phrasing as one call, which is the whole reason it is the
/// default: one round-trip covers the angles a caller would otherwise pay for separately.
fn batches_queries(&self) -> bool {
/// The keyless endpoint turns away even two searches at once.
fn one_phrasing_at_a_time(&self) -> bool {
true
}
}
@@ -113,9 +111,6 @@ fn build_arguments(query: &str, n: usize, options: &SearchOptions) -> serde_json
"type": "auto",
});
let map = arguments.as_object_mut().expect("object literal");
if !options.also.is_empty() {
map.insert("additionalQueries".into(), serde_json::json!(options.also));
}
if !options.include_domains.is_empty() {
map.insert("includeDomains".into(), serde_json::json!(options.include_domains));
}
@@ -147,6 +142,16 @@ struct RpcResult {
content: Vec<RpcContent>,
#[serde(default, rename = "isError")]
is_error: bool,
#[serde(default, rename = "_meta")]
meta: RpcMeta,
}
/// Flags the endpoint sets beside a result.
#[derive(Debug, Default, Deserialize)]
struct RpcMeta {
/// Set on the reply to a search over the keyless limit, which carries a notice, not results
#[serde(default, rename = "ai.exa/rateLimited")]
rate_limited: bool,
}
#[derive(Debug, Deserialize)]
@@ -173,6 +178,11 @@ fn parse_response(body: &str, n: usize) -> Result<Vec<SearchHit>, WebError> {
let result = envelope
.result
.ok_or_else(|| WebError::Backend("exa mcp returned no result".to_string()))?;
if result.meta.rate_limited {
return Err(WebError::Backend(
"exa's free search is rate limited; try again shortly, or set EXA_API_KEY".to_string(),
));
}
if result.is_error {
let detail = result.content.first().map(|c| c.text.as_str()).unwrap_or("unknown error");
return Err(WebError::Backend(format!("exa mcp: {detail}")));
@@ -291,150 +301,4 @@ fn flush(hits: &mut [SearchHit], snippet: &mut String) {
}
#[cfg(test)]
mod tests {
use super::*;
/// The exact shape the live endpoint returned during development.
const SAMPLE: &str = "event: message\n\
data: {\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"Title: select in tokio - Rust\\nURL: https://docs.rs/tokio/latest/tokio/macro.select.html\\nPublished: N/A\\nAuthor: N/A\\nHighlights:\\n## Cancellation safety\\n...\\nCancellation safety describes what happens when a future is dropped.\\nTitle: Second Result\\nURL: https://example.com/two\\nHighlights:\\nSomething else entirely.\"}]}}\n";
#[test]
fn an_sse_framed_response_parses_into_hits_with_content() {
let hits = parse_response(SAMPLE, 10).expect("parses");
assert_eq!(hits.len(), 2);
assert_eq!(hits[0].title, "select in tokio - Rust");
assert_eq!(hits[0].url, "https://docs.rs/tokio/latest/tokio/macro.select.html");
assert!(
hits[0].snippet.contains("Cancellation safety describes"),
"the extracted passage rides along, so no follow-up fetch is needed: {:?}",
hits[0].snippet
);
assert!(!hits[0].snippet.contains("N/A"), "metadata noise is dropped");
assert_eq!(hits[1].url, "https://example.com/two");
}
#[test]
fn the_result_count_is_honored() {
assert_eq!(parse_response(SAMPLE, 1).expect("parses").len(), 1);
}
#[test]
fn a_bare_json_body_parses_too() {
let bare =
r#"{"result":{"content":[{"type":"text","text":"Title: A\nURL: https://a.test"}]}}"#;
assert_eq!(parse_response(bare, 5).expect("parses")[0].url, "https://a.test");
}
#[test]
fn an_rpc_error_surfaces_instead_of_an_empty_result() {
let body = r#"{"error":{"code":-32602,"message":"bad arguments"}}"#;
let error = parse_response(body, 5).expect_err("must not look like zero results");
assert!(error.to_string().contains("bad arguments"), "{error}");
}
#[test]
fn a_tool_level_error_surfaces_too() {
let body =
r#"{"result":{"isError":true,"content":[{"type":"text","text":"rate limited"}]}}"#;
let error = parse_response(body, 5).expect_err("isError must not be silently empty");
assert!(error.to_string().contains("rate limited"), "{error}");
}
#[test]
fn garbage_is_an_error_not_a_panic() {
assert!(parse_response("not json at all", 5).is_err());
assert!(parse_response("", 5).is_err());
}
#[test]
fn options_map_onto_exas_argument_names() {
let options = SearchOptions {
also: vec!["second phrasing".into()],
include_domains: vec!["arxiv.org".into()],
exclude_domains: vec!["spam.example".into()],
recency: Some(crate::web::Recency::Month),
include_content: true,
};
let args = build_arguments("tokio cancellation", 7, &options);
assert_eq!(args["query"], "tokio cancellation");
assert_eq!(args["numResults"], 7);
assert_eq!(args["additionalQueries"][0], "second phrasing");
assert_eq!(args["includeDomains"][0], "arxiv.org");
assert_eq!(args["excludeDomains"][0], "spam.example");
assert_eq!(args["startPublishedDate"].as_str().expect("a date").len(), 10);
assert_eq!(args["enableHighlights"], true);
}
#[test]
fn defaults_stay_off_the_wire_and_the_count_is_clamped() {
let args = build_arguments("q", 999, &SearchOptions::default());
assert_eq!(args["numResults"], 25, "clamped to Exa's practical ceiling");
for absent in [
"additionalQueries",
"includeDomains",
"excludeDomains",
"startPublishedDate",
"enableHighlights",
] {
assert!(args.get(absent).is_none(), "{absent} must not be sent by default");
}
}
/// The advanced tool answers with a JSON envelope, not the basic tool's prose. Parsing only the
/// prose form meant every advanced search reported "No results" while the endpoint was
/// returning perfectly good ones.
#[test]
fn the_advanced_tools_json_envelope_parses() {
let inner = serde_json::json!({
"requestId": "abc",
"results": [
{
"id": "https://tokio.rs/x",
"url": "https://tokio.rs/x",
"title": "Select | Tokio",
"text": "Select | Tokio\n\n# Select\n\nSo far...",
"highlights": ["Futures can implement Drop to clean up.", "oneshot is cancel safe."],
"publishedDate": "2026-03-18T00:00:00.000Z"
},
{ "url": "", "title": "dropped: no url" }
]
})
.to_string();
let body = serde_json::json!({
"result": { "content": [{ "type": "text", "text": inner }] }
})
.to_string();
let hits = parse_response(&body, 10).expect("parses");
assert_eq!(hits.len(), 1, "a result with no url is not a result");
assert_eq!(hits[0].title, "Select | Tokio");
assert_eq!(hits[0].url, "https://tokio.rs/x");
assert!(hits[0].snippet.contains("cancel safe"), "highlights lead: {:?}", hits[0].snippet);
assert!(!hits[0].snippet.contains('\n'), "whitespace is collapsed");
}
#[test]
fn a_result_without_highlights_falls_back_to_its_text() {
let inner = serde_json::json!({
"results": [{ "url": "https://a.test", "title": "A", "text": " body text here " }]
})
.to_string();
let body = serde_json::json!({ "result": { "content": [{ "text": inner }] } }).to_string();
let hits = parse_response(&body, 5).expect("parses");
assert_eq!(hits[0].snippet, "body text here");
}
#[test]
fn a_long_snippet_is_clipped() {
let long = "word ".repeat(400);
let inner = serde_json::json!({
"results": [{ "url": "https://a.test", "title": "A", "text": long }]
})
.to_string();
let body = serde_json::json!({ "result": { "content": [{ "text": inner }] } }).to_string();
let hits = parse_response(&body, 5).expect("parses");
assert!(hits[0].snippet.chars().count() <= SNIPPET_CHARS + 1, "clipped");
assert!(hits[0].snippet.ends_with('…'));
}
}
mod tests;

View File

@@ -0,0 +1,152 @@
use super::*;
/// The exact shape the live endpoint returned during development.
const SAMPLE: &str = "event: message\n\
data: {\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"Title: select in tokio - Rust\\nURL: https://docs.rs/tokio/latest/tokio/macro.select.html\\nPublished: N/A\\nAuthor: N/A\\nHighlights:\\n## Cancellation safety\\n...\\nCancellation safety describes what happens when a future is dropped.\\nTitle: Second Result\\nURL: https://example.com/two\\nHighlights:\\nSomething else entirely.\"}]}}\n";
/// A burst of searches crossed the keyless limit; this is the reply, copied from the endpoint.
const RATE_LIMITED: &str = "event: message\ndata: {\"result\":{\"_meta\":{\"ai.exa/rateLimited\":true},\"content\":[{\"type\":\"text\",\"text\":\"You've hit Exa's free MCP rate limit. To continue using without limits, create your own Exa API key.\\n\\nFix: Create API key at https://dashboard.exa.ai/api-keys , and then update Exa MCP URL to this https://mcp.exa.ai/mcp?exaApiKey=YOUR_EXA_API_KEY\"}]},\"jsonrpc\":\"2.0\",\"id\":1}\n";
#[test]
fn an_sse_framed_response_parses_into_hits_with_content() {
let hits = parse_response(SAMPLE, 10).expect("parses");
assert_eq!(hits.len(), 2);
assert_eq!(hits[0].title, "select in tokio - Rust");
assert_eq!(hits[0].url, "https://docs.rs/tokio/latest/tokio/macro.select.html");
assert!(
hits[0].snippet.contains("Cancellation safety describes"),
"the extracted passage rides along, so no follow-up fetch is needed: {:?}",
hits[0].snippet
);
assert!(!hits[0].snippet.contains("N/A"), "metadata noise is dropped");
assert_eq!(hits[1].url, "https://example.com/two");
}
#[test]
fn the_result_count_is_honored() {
assert_eq!(parse_response(SAMPLE, 1).expect("parses").len(), 1);
}
#[test]
fn a_bare_json_body_parses_too() {
let bare = r#"{"result":{"content":[{"type":"text","text":"Title: A\nURL: https://a.test"}]}}"#;
assert_eq!(parse_response(bare, 5).expect("parses")[0].url, "https://a.test");
}
#[test]
fn an_rpc_error_surfaces_instead_of_an_empty_result() {
let body = r#"{"error":{"code":-32602,"message":"bad arguments"}}"#;
let error = parse_response(body, 5).expect_err("must not look like zero results");
assert!(error.to_string().contains("bad arguments"), "{error}");
}
#[test]
fn a_tool_level_error_surfaces_too() {
let body = r#"{"result":{"isError":true,"content":[{"type":"text","text":"rate limited"}]}}"#;
let error = parse_response(body, 5).expect_err("isError must not be silently empty");
assert!(error.to_string().contains("rate limited"), "{error}");
}
/// The break this catches: a rate-limited reply, which isn't flagged as an error, reading as a
/// search that found nothing, so the model gave up on a question the web could answer.
#[test]
fn a_rate_limited_reply_is_an_error_not_zero_results() {
let error = parse_response(RATE_LIMITED, 5).expect_err("rate limited is not empty");
assert!(error.to_string().contains("rate limit"), "{error}");
assert!(error.to_string().contains("EXA_API_KEY"), "says how to lift it: {error}");
}
/// The break this catches: the keyless endpoint getting a search's phrasings all at once, which
/// crosses its limit and turns all but one of them away.
#[test]
fn the_keyless_endpoint_gets_one_phrasing_at_a_time() {
assert!(ExaMcpBackend::new().one_phrasing_at_a_time());
}
#[test]
fn garbage_is_an_error_not_a_panic() {
assert!(parse_response("not json at all", 5).is_err());
assert!(parse_response("", 5).is_err());
}
#[test]
fn options_map_onto_exas_argument_names() {
let options = SearchOptions {
include_domains: vec!["arxiv.org".into()],
exclude_domains: vec!["spam.example".into()],
recency: Some(crate::web::Recency::Month),
include_content: true,
};
let args = build_arguments("tokio cancellation", 7, &options);
assert_eq!(args["query"], "tokio cancellation");
assert_eq!(args["numResults"], 7);
assert_eq!(args["highlightsQuery"], "tokio cancellation", "passages for this phrasing");
assert_eq!(args["includeDomains"][0], "arxiv.org");
assert_eq!(args["excludeDomains"][0], "spam.example");
assert_eq!(args["startPublishedDate"].as_str().expect("a date").len(), 10);
assert_eq!(args["enableHighlights"], true);
}
#[test]
fn defaults_stay_off_the_wire_and_the_count_is_clamped() {
let args = build_arguments("q", 999, &SearchOptions::default());
assert_eq!(args["numResults"], 25, "clamped to Exa's practical ceiling");
for absent in ["includeDomains", "excludeDomains", "startPublishedDate", "enableHighlights"] {
assert!(args.get(absent).is_none(), "{absent} must not be sent by default");
}
}
/// The advanced tool answers with a JSON envelope, not the basic tool's prose. Parsing only the
/// prose form meant every advanced search reported "No results" while the endpoint was returning
/// perfectly good ones.
#[test]
fn the_advanced_tools_json_envelope_parses() {
let inner = serde_json::json!({
"requestId": "abc",
"results": [
{
"id": "https://tokio.rs/x",
"url": "https://tokio.rs/x",
"title": "Select | Tokio",
"text": "Select | Tokio\n\n# Select\n\nSo far...",
"highlights": ["Futures can implement Drop to clean up.", "oneshot is cancel safe."],
"publishedDate": "2026-03-18T00:00:00.000Z"
},
{ "url": "", "title": "dropped: no url" }
]
})
.to_string();
let body = serde_json::json!({ "result": { "content": [{ "type": "text", "text": inner }] } })
.to_string();
let hits = parse_response(&body, 10).expect("parses");
assert_eq!(hits.len(), 1, "a result with no url is not a result");
assert_eq!(hits[0].title, "Select | Tokio");
assert_eq!(hits[0].url, "https://tokio.rs/x");
assert!(hits[0].snippet.contains("cancel safe"), "highlights lead: {:?}", hits[0].snippet);
assert!(!hits[0].snippet.contains('\n'), "whitespace is collapsed");
}
#[test]
fn a_result_without_highlights_falls_back_to_its_text() {
let inner = serde_json::json!({
"results": [{ "url": "https://a.test", "title": "A", "text": " body text here " }]
})
.to_string();
let body = serde_json::json!({ "result": { "content": [{ "text": inner }] } }).to_string();
let hits = parse_response(&body, 5).expect("parses");
assert_eq!(hits[0].snippet, "body text here");
}
#[test]
fn a_long_snippet_is_clipped() {
let long = "word ".repeat(400);
let inner =
serde_json::json!({ "results": [{ "url": "https://a.test", "title": "A", "text": long }] })
.to_string();
let body = serde_json::json!({ "result": { "content": [{ "text": inner }] } }).to_string();
let hits = parse_response(&body, 5).expect("parses");
assert!(hits[0].snippet.chars().count() <= SNIPPET_CHARS + 1, "clipped");
assert!(hits[0].snippet.ends_with('…'));
}

View File

@@ -52,7 +52,7 @@ fn grep_schema() -> ToolSchema {
},
"glob": {
"type": "string",
"description": "Glob pattern to filter files (e.g., '*.rs')"
"description": "Glob pattern to filter files (e.g., '*.rs'); a leading '!' excludes (e.g., '!tests/**')"
},
"outputMode": {
"type": "string",

View File

@@ -76,6 +76,18 @@ fn the_native_search_honors_ignores_and_reports_ripgrep_shaped_rows() {
assert!(native_search(cwd, &search("no_such_text")).expect("valid").is_empty());
}
/// A glob that starts with `!` leaves out what it names and searches the rest.
///
/// The break this catches: `!` taken literally, so an exclude glob matched no file and the
/// search came back empty.
#[test]
fn an_exclude_glob_searches_everything_else() {
let dir = repo_with_build_output();
let excluding = Search { glob: Some("!target/**"), all: true, ..search("needle") };
let rows = native_search(dir.path(), &excluding).expect("a valid regex");
assert_eq!(rows, vec!["src/main.rs:1:let needle = 1;"]);
}
/// Context lines use `-` where a match uses `:`, the way ripgrep prints them, so a reader (and
/// the model) can tell the answer from its surroundings.
#[test]

View File

@@ -174,6 +174,7 @@ impl Tool for QuestionTool {
QuestionReply::Cancelled
}
};
let _ = cx.event_tx.send(Event::PromptClosed { id: id.as_str().to_string() }).await;
let outcome = match reply {
QuestionReply::Answered(answers) => QuestionOutcome::Answered(answers),

View File

@@ -89,6 +89,9 @@ async fn interactive_question_emits_event_and_awaits_the_brokered_answer() {
assert!(!result.is_error);
let ContentBlock::Text(text) = &result.content[0] else { panic!("expected text") };
assert!(text.contains("The user answered: Rust"), "got: {text}");
// Any other front-end showing the question is told to take it down
let closed = event_rx.recv().await;
assert_eq!(closed, Some(Event::PromptClosed { id: id.as_str().to_string() }));
}
/// A multi-select answer reaches the model as a list, and comes back off the text as the same

View File

@@ -129,7 +129,6 @@ mod tests {
exclude_domains: vec!["reddit.com".to_string()],
recency: Some(crate::web::Recency::Year),
include_content: true,
..Default::default()
});
assert_eq!(body["query"], "tokio");
assert_eq!(body["max_results"], 3);

View File

@@ -26,9 +26,9 @@ pub trait SearchBackend: Send + Sync {
Vec::new()
}
/// Whether one call covers every phrasing in [`SearchOptions::also`]. A plain search API does
/// not, so the caller runs them itself and merges.
fn batches_queries(&self) -> bool {
/// Whether a search's phrasings must run one after another. A rate-limited endpoint turns a
/// burst away, so its phrasings wait their turn instead of failing together.
fn one_phrasing_at_a_time(&self) -> bool {
false
}
}
@@ -112,8 +112,6 @@ impl Recency {
/// exposed all of them would cost more context than the answers it fetches.
#[derive(Debug, Clone, Default)]
pub struct SearchOptions {
/// Extra query phrasings run alongside the main one, widening coverage in a single call.
pub also: Vec<String>,
/// Only these domains.
pub include_domains: Vec<String>,
/// Never these domains.
@@ -170,48 +168,82 @@ pub async fn create_backend(config: &WebConfig) -> Result<Box<dyn SearchBackend>
}
}
/// What a search found, and a note for each phrasing that failed.
#[derive(Debug)]
pub(super) struct Searched {
pub(super) hits: Vec<SearchHit>,
pub(super) skipped: Vec<String>,
}
/// Run every phrasing the caller asked for and merge the results.
///
/// One call per query for a backend that takes one query, first-seen order preserved and duplicate
/// URLs dropped — the same page found by two phrasings is one result, and the earlier phrasing is
/// the one that ranked it. A phrasing that errors is skipped rather than sinking the whole search;
/// the error only surfaces when *nothing* answered.
/// Each phrasing is its own search, so each gets its own ranking and its own passages; one call
/// carrying the extras ranks everything against the first. A phrasing that errors is skipped and
/// named rather than sinking the whole search; the error only fails it when *nothing* answered.
pub(super) async fn run_search(
backend: &dyn SearchBackend,
queries: &[String],
n: usize,
options: &SearchOptions,
) -> Result<Vec<SearchHit>, WebError> {
let Some((query, also)) = queries.split_first() else {
return Ok(Vec::new());
};
if backend.batches_queries() || also.is_empty() {
return backend.search(query, n, options).await;
}
// The extras are already in `queries`; passing them again would double a backend that reads
// both. One phrasing at a time, and the option set minus the fan-out it has already served.
let single = SearchOptions { also: Vec::new(), ..options.clone() };
let mut merged: Vec<SearchHit> = Vec::new();
) -> Result<Searched, WebError> {
let mut lists = Vec::new();
let mut skipped = Vec::new();
let mut last_error = None;
for query in queries {
match backend.search(query, n, &single).await {
Ok(hits) => {
for hit in hits {
if !merged.iter().any(|seen| seen.url == hit.url) {
merged.push(hit);
}
}
for (query, answer) in queries.iter().zip(search_each(backend, queries, n, options).await) {
match answer {
Ok(hits) => lists.push(hits),
Err(error) => {
skipped.push(format!("\"{query}\" wasn't searched: {error}"));
last_error = Some(error);
}
Err(error) => last_error = Some(error),
}
}
match (merged.is_empty(), last_error) {
let hits = interleave(lists, n);
match (hits.is_empty(), last_error) {
(true, Some(error)) => Err(error),
_ => Ok(merged),
_ => Ok(Searched { hits, skipped }),
}
}
/// Each phrasing's answer, in order: all at once, or in turn where the backend needs that.
async fn search_each(
backend: &dyn SearchBackend,
queries: &[String],
n: usize,
options: &SearchOptions,
) -> Vec<Result<Vec<SearchHit>, WebError>> {
if !backend.one_phrasing_at_a_time() {
let searches = queries.iter().map(|query| backend.search(query, n, options));
return futures::future::join_all(searches).await;
}
let mut answers = Vec::with_capacity(queries.len());
for query in queries {
answers.push(backend.search(query, n, options).await);
}
answers
}
/// Up to `n` hits, rank by rank: the top of each list, then the next of each.
///
/// So every phrasing is represented. A page two phrasings found is one result, at its first
/// position, and its second slot goes to the next page.
fn interleave(lists: Vec<Vec<SearchHit>>, n: usize) -> Vec<SearchHit> {
let mut lists: Vec<_> = lists.into_iter().map(Vec::into_iter).collect();
let mut merged: Vec<SearchHit> = Vec::new();
while merged.len() < n {
let rank: Vec<SearchHit> = lists.iter_mut().filter_map(Iterator::next).collect();
if rank.is_empty() {
break;
}
for hit in rank {
if merged.len() < n && !merged.iter().any(|seen| seen.url == hit.url) {
merged.push(hit);
}
}
}
merged
}
/// web_search tool — pluggable search backend.
pub struct WebSearchTool {
pub(super) config: Arc<RwLock<WebConfig>>,
@@ -272,14 +304,13 @@ impl Tool for WebSearchTool {
async fn run(&self, args: serde_json::Value, _cx: &ToolContext) -> ToolResultData {
let queries = search_queries(&args);
let Some((_, also)) = queries.split_first() else {
if queries.is_empty() {
return ToolResultData::error("Error: 'query' (or 'queries') is required");
};
}
let n = (args.get("n").and_then(serde_json::Value::as_u64).unwrap_or(5) as usize)
.clamp(1, MAX_RESULTS);
let options = SearchOptions {
also: also.to_vec(),
include_content: args
.get("content")
.and_then(serde_json::Value::as_bool)
@@ -297,8 +328,10 @@ impl Tool for WebSearchTool {
Err(e) => return ToolResultData::error(format!("Backend error: {e}")),
};
match run_search(backend.as_ref(), &queries, n, &options).await {
Ok(hits) => {
ToolResultData::text(render_hits(&queries, &hits, &backend.honors(&options)))
Ok(searched) => {
let mut caveats = backend.honors(&options);
caveats.extend(searched.skipped);
ToolResultData::text(render_hits(&queries, &searched.hits, &caveats))
}
Err(e) => ToolResultData::error(format!("Search failed: {e}")),
}
@@ -336,3 +369,6 @@ pub(super) fn domain_filters(args: &serde_json::Value) -> SearchOptions {
}
options
}
#[cfg(test)]
mod tests;

View File

@@ -0,0 +1,142 @@
use super::*;
use std::collections::HashMap;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Mutex;
/// A backend with a result list per phrasing, which fails the phrasings it has no list for and
/// keeps what it was asked and how many searches it ran at once.
struct ByPhrasing {
lists: HashMap<&'static str, Vec<&'static str>>,
asked: Mutex<Vec<(String, usize)>>,
in_turn: bool,
running: AtomicUsize,
most_at_once: AtomicUsize,
}
impl ByPhrasing {
fn new(lists: &[(&'static str, &[&'static str])]) -> Self {
let lists = lists.iter().map(|(query, urls)| (*query, urls.to_vec())).collect();
let (running, most_at_once) = (AtomicUsize::new(0), AtomicUsize::new(0));
Self { lists, asked: Mutex::new(Vec::new()), in_turn: false, running, most_at_once }
}
fn in_turn(self) -> Self {
Self { in_turn: true, ..self }
}
/// Holds a search open long enough for another to start beside it, if one is going to.
async fn overlap(&self) {
let now = self.running.fetch_add(1, Ordering::SeqCst) + 1;
self.most_at_once.fetch_max(now, Ordering::SeqCst);
tokio::time::sleep(std::time::Duration::from_millis(20)).await;
self.running.fetch_sub(1, Ordering::SeqCst);
}
}
#[async_trait]
impl SearchBackend for ByPhrasing {
async fn search(
&self,
query: &str,
n: usize,
_options: &SearchOptions,
) -> Result<Vec<SearchHit>, WebError> {
self.asked.lock().expect("no panic holds this lock").push((query.to_string(), n));
self.overlap().await;
let Some(urls) = self.lists.get(query) else {
return Err(WebError::Backend(format!("no answer for {query}")));
};
Ok(urls.iter().take(n).map(|url| hit(url)).collect())
}
fn one_phrasing_at_a_time(&self) -> bool {
self.in_turn
}
}
fn hit(url: &str) -> SearchHit {
SearchHit { title: url.to_string(), url: url.to_string(), snippet: String::new() }
}
fn queries(list: &[&str]) -> Vec<String> {
list.iter().map(|query| query.to_string()).collect()
}
async fn searched(backend: &ByPhrasing, asked: &[&str], n: usize) -> Searched {
let answer = run_search(backend, &queries(asked), n, &SearchOptions::default()).await;
answer.expect("a phrasing answered")
}
async fn urls(backend: &ByPhrasing, asked: &[&str], n: usize) -> Vec<String> {
searched(backend, asked, n).await.hits.into_iter().map(|hit| hit.url).collect()
}
/// Every phrasing gets its share of the results: the top of each, then the next of each.
///
/// The break this catches: the first phrasing's results filling every slot, so the other
/// phrasings were searched and then thrown away.
#[tokio::test]
async fn each_phrasing_gets_its_share_of_the_results() {
let backend = ByPhrasing::new(&[("one", &["a1", "a2", "a3"]), ("two", &["b1", "b2", "b3"])]);
assert_eq!(urls(&backend, &["one", "two"], 4).await, ["a1", "b1", "a2", "b2"]);
// An odd count stops partway through a rank
assert_eq!(urls(&backend, &["one", "two"], 3).await, ["a1", "b1", "a2"]);
}
/// Each phrasing is searched on its own and asked for the full count, so its own ranking and
/// passages come back.
///
/// The break this catches: the extra phrasings riding along on the first one's search, which
/// ranks and extracts passages against the first phrasing alone.
#[tokio::test]
async fn each_phrasing_is_searched_on_its_own() {
let backend = ByPhrasing::new(&[("one", &["a1"]), ("two", &["b1"])]);
urls(&backend, &["one", "two"], 5).await;
let mut asked = backend.asked.lock().expect("no panic holds this lock").clone();
asked.sort();
assert_eq!(asked, [("one".to_string(), 5), ("two".to_string(), 5)]);
}
/// Phrasings run together unless the backend needs them in turn, and then never overlap.
///
/// The break this catches: a burst at a rate-limited endpoint, which turned all but one phrasing
/// away; or phrasings waiting on each other where nothing needed them to.
#[tokio::test]
async fn phrasings_wait_their_turn_only_where_the_backend_needs_it() {
let lists: &[(&str, &[&str])] = &[("one", &["a1"]), ("two", &["b1"]), ("three", &["c1"])];
let together = ByPhrasing::new(lists);
urls(&together, &["one", "two", "three"], 5).await;
assert_eq!(together.most_at_once.load(Ordering::SeqCst), 3, "all at once");
let in_turn = ByPhrasing::new(lists).in_turn();
assert_eq!(urls(&in_turn, &["one", "two", "three"], 5).await, ["a1", "b1", "c1"]);
assert_eq!(in_turn.most_at_once.load(Ordering::SeqCst), 1, "one at a time");
}
/// A page two phrasings found is one result, and its slot goes to the next page.
///
/// The break this catches: the same URL listed twice, spending a result on a repeat.
#[tokio::test]
async fn a_page_found_twice_is_one_result() {
let backend = ByPhrasing::new(&[("one", &["same", "a2"]), ("two", &["same", "b2"])]);
assert_eq!(urls(&backend, &["one", "two"], 3).await, ["same", "a2", "b2"]);
}
/// A phrasing that fails is skipped and named while another answers; the error only fails the
/// search when none did.
///
/// The break this catches: one failed phrasing sinking a search the others answered, a failure
/// the model is never told about, or every phrasing failing and the reply reading as no results.
#[tokio::test]
async fn a_failed_phrasing_is_named_and_skipped_until_none_answer() {
let backend = ByPhrasing::new(&[("works", &["a1"])]);
let partial = searched(&backend, &["broken", "works"], 5).await;
assert_eq!(partial.hits.len(), 1);
assert_eq!(
partial.skipped,
["\"broken\" wasn't searched: backend error: no answer for broken"]
);
let broken = queries(&["broken"]);
let all_failed = run_search(&backend, &broken, 5, &SearchOptions::default()).await;
let error = all_failed.expect_err("nothing answered");
assert!(error.to_string().contains("no answer for broken"), "{error}");
}