Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(agents): keep LoadTools-loaded tools callable across turns (#9210)

Wolf Mermelsteinb28f9a7614cf
diff --git a/crates/agent/AGENTS.md b/crates/agent/AGENTS.md
index 15df12297d..24389784f7 100644
--- a/crates/agent/AGENTS.md
+++ b/crates/agent/AGENTS.md
@@ -59,6 +59,10 @@ and usage metering.
## Gotchas
+- A `Session` lives for one turn. Before its first request it reloads the
+ catalog tools the history called or loaded, reading `SearchTools`/`LoadTools`
+ results through `ai_toolset::tool_search::tools_loaded_by`; change those
+ response types there, not in `ai_tools`.
- `rig-core`/`rig-agent` are pinned exact versions (not workspace deps);
bump both together and check `test-utils` feature compatibility.
- `AgentLoop::with_provider_api_key` rekeys only the loop's own model calls
diff --git a/crates/agent/src/agent_loop.rs b/crates/agent/src/agent_loop.rs
index 0ae32cdc29..b9ad0ee92b 100644
--- a/crates/agent/src/agent_loop.rs
+++ b/crates/agent/src/agent_loop.rs
@@ -10,11 +10,13 @@ use crate::stream::ChatCompletionStream;
use crate::telemetry::GenAiContext;
use crate::tool_adapter::DynToolSetAdapter;
use crate::tool_result_limit::ToolResultLimit;
+use ai_toolset::tool_search::tools_loaded_by;
use ai_toolset::{RequestContext, SearchableTool, ToolLoader, ToolSet as AiToolSet};
use ai_usage::{UsageContext, UsageRecorder};
use genai_telemetry::ContentPolicy;
use rig_agent::tool::server::{ToolServer, ToolServerHandle};
-use rig_core::message::{AssistantContent, Message};
+use rig_core::message::{AssistantContent, Message, ToolResultContent, UserContent};
+use std::collections::HashMap;
use std::future::Future;
use std::pin::Pin;
use std::sync::{Arc, Mutex, RwLock};
@@ -731,11 +733,15 @@ impl Session {
};
// A session lives for one turn, so whatever the conversation loaded
- // before is gone. Reload what it called, in the order it first did,
- // rather than have the model reload each tool every turn.
- let called = called_catalog_tools(history, &self.request_context.searchable_tools);
- if !called.is_empty() {
- (self.bridge_inputs.register_loaded)(called).await;
+ // before is gone. Reload what it loaded or called, in the order it
+ // first did, rather than have the model reload each tool every turn
+ // or call a tool it loaded that is no longer there.
+ let in_use = HistoryTools::of(history, &self.request_context.searchable_tools);
+ for (call_id, tools) in &in_use.loads {
+ self.bridge_inputs.tool_loads.record_call(call_id, tools);
+ }
+ if !in_use.tools.is_empty() {
+ (self.bridge_inputs.register_loaded)(in_use.tools).await;
}
let stream = self
@@ -762,25 +768,79 @@ impl Session {
}
}
-/// The catalog tools `history` called, in the order of their first call.
-fn called_catalog_tools(history: &[Message], catalog: &[SearchableTool]) -> Vec<SearchableTool> {
- let mut called: Vec<SearchableTool> = Vec::new();
- for message in history {
- let Message::Assistant { content, .. } = message else {
- continue;
- };
- for content in content.iter() {
- let AssistantContent::ToolCall(call) = content else {
- continue;
- };
- let name = &call.function.name;
- if called.iter().any(|tool| &tool.name == name) {
- continue;
- }
- if let Some(tool) = catalog.iter().find(|tool| &tool.name == name) {
- called.push(tool.clone());
+/// The catalog tools `history` loaded or called, in the order it first did.
+#[derive(Default)]
+struct HistoryTools {
+ /// Every such tool, once.
+ tools: Vec<SearchableTool>,
+ /// The tools each `SearchTools` or `LoadTools` call loaded, by the call's
+ /// provider id.
+ loads: Vec<(String, Vec<SearchableTool>)>,
+}
+
+impl HistoryTools {
+ fn of(history: &[Message], catalog: &[SearchableTool]) -> Self {
+ let mut found = Self::default();
+ let mut call_names: HashMap<&str, &str> = HashMap::new();
+ for message in history {
+ match message {
+ Message::Assistant { content, .. } => {
+ for content in content.iter() {
+ let AssistantContent::ToolCall(call) = content else {
+ continue;
+ };
+ call_names.insert(&call.id, &call.function.name);
+ if let Some(tool) =
+ catalog.iter().find(|tool| tool.name == call.function.name)
+ {
+ found.add(tool);
+ }
+ }
+ }
+ Message::User { content } => {
+ for content in content.iter() {
+ let UserContent::ToolResult(result) = content else {
+ continue;
+ };
+ let Some(tool_name) = call_names.get(result.id.as_str()) else {
+ continue;
+ };
+ let text: String = result
+ .content
+ .iter()
+ .filter_map(|content| match content {
+ ToolResultContent::Text(text) => Some(text.text.as_str()),
+ _ => None,
+ })
+ .collect();
+ // Every tool the call loaded, as the live turn
+ // recorded it, even one an earlier call loaded too.
+ let loaded: Vec<SearchableTool> = tools_loaded_by(tool_name, &text)
+ .iter()
+ .filter_map(|name| catalog.iter().find(|tool| &tool.name == name))
+ .cloned()
+ .collect();
+ for tool in &loaded {
+ found.add(tool);
+ }
+ if !loaded.is_empty() {
+ // Requests are laid out under the provider's call
+ // id (see `replay_provider_ids`).
+ let call_id = result.call_id.as_ref().unwrap_or(&result.id);
+ found.loads.push((call_id.clone(), loaded));
+ }
+ }
+ }
+ Message::System { .. } => {}
}
}
+ found
+ }
+
+ /// Adds `tool` unless it is already in.
+ fn add(&mut self, tool: &SearchableTool) {
+ if !self.tools.iter().any(|known| known.name == tool.name) {
+ self.tools.push(tool.clone());
+ }
}
- called
}
diff --git a/crates/agent/src/hook.rs b/crates/agent/src/hook.rs
index bc42089488..d250ffb3e1 100644
--- a/crates/agent/src/hook.rs
+++ b/crates/agent/src/hook.rs
@@ -105,6 +105,12 @@ impl ToolLoads {
});
}
+ /// Records that the call `call_id` loaded `tools`, as an earlier turn's
+ /// history shows it.
+ pub(crate) fn record_call(&self, call_id: &str, tools: &[SearchableTool]) {
+ self.record(LoadingCall::Id(call_id.to_owned()), tools);
+ }
+
/// The tools `call` loaded.
pub(crate) fn loaded_by(&self, call: &rig_core::message::ToolCall) -> Vec<String> {
self.0
diff --git a/crates/agent/src/test/agent_loop/test_prompt_cache.rs b/crates/agent/src/test/agent_loop/test_prompt_cache.rs
index f24bfbc52e..b0a63a20d6 100644
--- a/crates/agent/src/test/agent_loop/test_prompt_cache.rs
+++ b/crates/agent/src/test/agent_loop/test_prompt_cache.rs
@@ -12,6 +12,7 @@ use crate::model::anthropic_prompt_layout::AnthropicPromptLayout;
use crate::model::router::ModelRouter;
use crate::stream::ToolResponse;
use crate::types::{ChatMessage, ChatMessageContent, Role};
+use ai_toolset::tool_search::{LoadToolsResponse, ToolMatch};
use ai_toolset::{
AsyncTool, AsyncToolCollection, RequestContext, RequestSchema, SearchableTool, ServiceContext,
ToolAnnotated, ToolAnnotations, ToolResult, ToolSet as AiToolSet, ToolSetError,
@@ -136,7 +137,7 @@ impl ToolAnnotated for LoadToolsStandIn {
#[async_trait]
impl AsyncTool<()> for LoadToolsStandIn {
- type Output = Value;
+ type Output = LoadToolsResponse;
async fn call(
&self,
@@ -149,10 +150,14 @@ impl AsyncTool<()> for LoadToolsStandIn {
.filter(|tool| self.names.contains(&tool.name))
.cloned()
.collect();
+ let loaded = matched.iter().map(ToolMatch::of).collect();
if let Some(loader) = request_context.tool_loader.as_ref() {
loader.load(matched);
}
- Ok(json!({ "loaded": self.names }))
+ Ok(LoadToolsResponse {
+ loaded,
+ not_found: Vec::new(),
+ })
}
}
@@ -324,7 +329,7 @@ async fn loading_a_tool_keeps_every_request_prefix() {
{"type": "tool_result", "tool_use_id": "toolu_load", "content": [
{"type": "tool_reference", "tool_name": "EditPresentation"},
]},
- {"type": "text", "text": "<tool_result_text tool_use_id=\"toolu_load\">{\"loaded\":[\"EditPresentation\"]}</tool_result_text>"},
+ {"type": "text", "text": "<tool_result_text tool_use_id=\"toolu_load\">{\"loaded\":[{\"name\":\"EditPresentation\",\"description\":\"Edit a presentation.\"}],\"not_found\":[]}</tool_result_text>"},
]})
);
}
@@ -359,12 +364,17 @@ async fn sessions_with_different_instructions_share_the_shared_system_block() {
}
/// The next turn replays this one from its persisted parts. It must send the
-/// same bytes the live requests did, tool call ids included, or the cache
+/// same bytes the live requests did, tool call ids included and the tools a
+/// `LoadTools` call loaded still referenced from its result, or the cache
/// misses from the first tool call on.
#[tokio::test]
async fn a_replayed_turn_repeats_its_live_requests() {
let transport = ScriptedProvider::new([
- tool_use_response("toolu_load", "LoadTools", json!({"names": []})),
+ tool_use_response(
+ "toolu_load",
+ "LoadTools",
+ json!({"names": ["EditPresentation"]}),
+ ),
text_response("done"),
text_response("again"),
]);
@@ -372,7 +382,7 @@ async fn a_replayed_turn_repeats_its_live_requests() {
&transport,
"anthropic/claude-opus-4-8",
split_prompt("task A"),
- "load nothing",
+ "load the editor",
)
.await;
assert!(collected.error.is_none(), "{:?}", collected.error);
@@ -382,7 +392,7 @@ async fn a_replayed_turn_repeats_its_live_requests() {
}
let history = [
ChatMessage {
- content: ChatMessageContent::Text("load nothing".to_owned()),
+ content: ChatMessageContent::Text("load the editor".to_owned()),
role: Role::User,
attachments: None,
},
diff --git a/crates/agent/src/test/agent_loop/test_tool_search.rs b/crates/agent/src/test/agent_loop/test_tool_search.rs
index 2bcdaa8031..e81ab025d2 100644
--- a/crates/agent/src/test/agent_loop/test_tool_search.rs
+++ b/crates/agent/src/test/agent_loop/test_tool_search.rs
@@ -8,6 +8,9 @@
use super::util;
use crate::AgentError;
use crate::stream::ToolResponse;
+use ai_toolset::tool_search::{
+ LOAD_TOOLS, LoadToolsResponse, SEARCH_TOOLS, SearchToolsResponse, ToolMatch,
+};
use ai_toolset::{
AsyncTool, AsyncToolCollection, RequestContext, RequestSchema, SearchableTool, ServiceContext,
ToolResult, ToolSet as AiToolSet, ToolSetError,
@@ -27,7 +30,7 @@ use std::sync::Arc;
/// the top-ranked matches; with this test catalog everything fits the cap.)
#[derive(Deserialize, JsonSchema)]
#[schemars(
- title = "search_tools",
+ title = "SearchTools",
description = "Find and stage searchable tools."
)]
struct SearchToolsTest {}
@@ -38,7 +41,7 @@ impl ToolAnnotated for SearchToolsTest {
#[async_trait]
impl AsyncTool<()> for SearchToolsTest {
- type Output = serde_json::Value;
+ type Output = SearchToolsResponse;
async fn call(
&self,
@@ -47,18 +50,21 @@ impl AsyncTool<()> for SearchToolsTest {
) -> ToolResult<Self::Output> {
let matched: Vec<SearchableTool> =
request_context.searchable_tools.iter().cloned().collect();
- let results: Vec<String> = matched.iter().map(|t| t.name.clone()).collect();
+ let results = matched.iter().map(ToolMatch::of).collect();
if let Some(loader) = request_context.tool_loader.as_ref() {
loader.load(matched);
}
- Ok(serde_json::json!({ "results": results }))
+ Ok(SearchToolsResponse {
+ results,
+ additional_matches: Vec::new(),
+ })
}
}
/// Stand-in for `ai_tools::LoadTools`: looks names up in the request context's
/// searchable catalog and hands them to the loader.
#[derive(Deserialize, JsonSchema)]
-#[schemars(title = "load_tools", description = "Load searchable tools by name.")]
+#[schemars(title = "LoadTools", description = "Load searchable tools by name.")]
struct LoadToolsTest {
names: Vec<String>,
}
@@ -69,7 +75,7 @@ impl ToolAnnotated for LoadToolsTest {
#[async_trait]
impl AsyncTool<()> for LoadToolsTest {
- type Output = serde_json::Value;
+ type Output = LoadToolsResponse;
async fn call(
&self,
@@ -82,19 +88,22 @@ impl AsyncTool<()> for LoadToolsTest {
.filter(|t| self.names.contains(&t.name))
.cloned()
.collect();
- let loaded: Vec<String> = matched.iter().map(|t| t.name.clone()).collect();
+ let loaded = matched.iter().map(ToolMatch::of).collect();
if let Some(loader) = request_context.tool_loader.as_ref() {
loader.load(matched);
}
- Ok(serde_json::json!({ "loaded": loaded }))
+ Ok(LoadToolsResponse {
+ loaded,
+ not_found: Vec::new(),
+ })
}
}
-/// Fake `CombinedToolSet`: static tools + a searchable MCP catalog spanning
-/// two servers (`a` and `b`).
+/// Fake `CombinedToolSet`: static tools + a searchable catalog of a deferred
+/// Macro tool and MCP tools spanning two servers (`a` and `b`).
struct FakeCombined {
static_tools: Arc<AsyncToolCollection<()>>,
- mcp_tools: Vec<String>,
+ catalog_tools: Vec<String>,
}
impl FakeCombined {
@@ -105,7 +114,8 @@ impl FakeCombined {
.add_tool::<SearchToolsTest, ()>()
.add_tool::<LoadToolsTest, ()>(),
),
- mcp_tools: vec![
+ catalog_tools: vec![
+ "ReadInitiative".to_owned(),
"mcp__a__t1".to_owned(),
"mcp__b__t2".to_owned(),
"mcp__a__t3".to_owned(),
@@ -124,16 +134,9 @@ impl AiToolSet<()> for FakeCombined {
) -> Pin<
Box<dyn Future<Output = Result<ToolResult<serde_json::Value>, ToolSetError>> + 'a + Send>,
> {
- if tool_name.starts_with("mcp__") {
- let known = self.mcp_tools.iter().any(|t| t == tool_name);
+ if self.catalog_tools.iter().any(|t| t == tool_name) {
let name = tool_name.to_owned();
- return Box::pin(async move {
- if known {
- Ok(Ok(serde_json::json!({ "ok": name })))
- } else {
- Err(ToolSetError::NotFound(name))
- }
- });
+ return Box::pin(async move { Ok(Ok(serde_json::json!({ "ok": name }))) });
}
self.static_tools
.dispatch_tool_call(context, request_context, tool_name, json)
@@ -144,7 +147,7 @@ impl AiToolSet<()> for FakeCombined {
}
fn searchable_catalog(&self) -> Vec<SearchableTool> {
- self.mcp_tools
+ self.catalog_tools
.iter()
.map(|name| SearchableTool {
name: name.clone(),
@@ -180,7 +183,7 @@ async fn mcp_calls_from_two_providers_in_one_turn() {
vec![
MockStreamEvent::tool_call(
"call-load",
- "load_tools",
+ LOAD_TOOLS,
serde_json::json!({ "names": ["mcp__a__t1", "mcp__b__t2"] }),
),
MockStreamEvent::final_response_with_default_usage(),
@@ -212,7 +215,7 @@ async fn mcp_calls_from_two_providers_in_one_turn() {
async fn search_stages_tools_from_multiple_providers_for_the_next_turn() {
let model = MockCompletionModel::from_stream_turns([
vec![
- MockStreamEvent::tool_call("call-search", "search_tools", serde_json::json!({})),
+ MockStreamEvent::tool_call("call-search", SEARCH_TOOLS, serde_json::json!({})),
MockStreamEvent::final_response_with_default_usage(),
],
vec![
@@ -222,7 +225,7 @@ async fn search_stages_tools_from_multiple_providers_for_the_next_turn() {
// turn's normal allowed set and no invalid-call recovery is needed.
MockStreamEvent::tool_call(
"call-load-b",
- "load_tools",
+ LOAD_TOOLS,
serde_json::json!({ "names": ["mcp__b__t2"] }),
),
MockStreamEvent::tool_call("call-b", "mcp__b__t2", serde_json::json!({})),
@@ -401,7 +404,7 @@ async fn mcp_calls_from_two_providers_loaded_sequentially() {
vec![
MockStreamEvent::tool_call(
"call-load-a",
- "load_tools",
+ LOAD_TOOLS,
serde_json::json!({ "names": ["mcp__a__t1"] }),
),
MockStreamEvent::final_response_with_default_usage(),
@@ -413,7 +416,7 @@ async fn mcp_calls_from_two_providers_loaded_sequentially() {
vec![
MockStreamEvent::tool_call(
"call-load-b",
- "load_tools",
+ LOAD_TOOLS,
serde_json::json!({ "names": ["mcp__b__t2"] }),
),
MockStreamEvent::final_response_with_default_usage(),
@@ -482,3 +485,84 @@ async fn a_tool_called_earlier_in_the_conversation_is_loaded_upfront() {
assert!(advertised.contains(&"mcp__a__t1"), "{advertised:?}");
assert!(!advertised.contains(&"mcp__b__t2"), "{advertised:?}");
}
+
+/// A deferred tool loaded with `LoadTools` on one turn and never called there
+/// is still loaded on the next: the call goes through on the first request,
+/// with no invalid-call recovery.
+#[tokio::test]
+async fn a_tool_loaded_on_an_earlier_turn_is_callable_on_the_next() {
+ use rig_core::OneOrMany;
+ use rig_core::message::{AssistantContent, Message};
+
+ let first_model = MockCompletionModel::from_stream_turns([
+ vec![
+ MockStreamEvent::tool_call(
+ "call-load",
+ LOAD_TOOLS,
+ serde_json::json!({ "names": ["ReadInitiative"] }),
+ ),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ vec![
+ MockStreamEvent::text("I'm checking your access on that project."),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ ]);
+ let toolset: Arc<dyn AiToolSet<()> + Send + Sync> = Arc::new(FakeCombined::new());
+ let mut first = util::session(toolset.clone(), Arc::new(()), first_model).await;
+ let first_turn = util::drive(&mut first, "link these tasks to the Agents project").await;
+ assert!(first_turn.error.is_none(), "{:?}", first_turn.error);
+ let Some(loaded) =
+ first_turn
+ .tool_responses()
+ .into_iter()
+ .find_map(|response| match response {
+ ToolResponse::Json { name, json, .. } if name == LOAD_TOOLS => Some(json),
+ _ => None,
+ })
+ else {
+ panic!("expected the LoadTools result");
+ };
+
+ let second_model = MockCompletionModel::from_stream_turns([
+ vec![
+ MockStreamEvent::tool_call("call-read", "ReadInitiative", serde_json::json!({})),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ vec![
+ MockStreamEvent::text("You can view the project."),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ ]);
+ let mut second = util::session(toolset, Arc::new(()), second_model.clone()).await;
+ let stream = second
+ .send_message(vec![
+ Message::user("link these tasks to the Agents project"),
+ Message::Assistant {
+ id: None,
+ content: OneOrMany::one(AssistantContent::tool_call(
+ "call-load",
+ LOAD_TOOLS,
+ serde_json::json!({ "names": ["ReadInitiative"] }),
+ )),
+ },
+ Message::tool_result("call-load", loaded.to_string()),
+ Message::assistant("I'm checking your access on that project."),
+ Message::user("did it work?"),
+ ])
+ .await
+ .expect("send_message should start the stream");
+ let second_turn = util::collect(stream).await;
+
+ assert!(second_turn.error.is_none(), "{:?}", second_turn.error);
+ expect_json_ok(&second_turn, "ReadInitiative");
+ let requests = second_model.requests();
+ assert_eq!(requests.len(), 2, "the call needed no recovery");
+ assert!(
+ requests[0]
+ .tools
+ .iter()
+ .any(|tool| tool.name == "ReadInitiative"),
+ "ReadInitiative is advertised on the first request"
+ );
+}
diff --git a/crates/agent_inmem/src/domain/agent.rs b/crates/agent_inmem/src/domain/agent.rs
index 5900e55f81..4f557b112d 100644
--- a/crates/agent_inmem/src/domain/agent.rs
+++ b/crates/agent_inmem/src/domain/agent.rs
@@ -75,6 +75,10 @@ pub(crate) mod compaction;
/// a stop, or the connection going away.
const TURN_IDLE_TIMEOUT: Duration = Duration::from_secs(5 * 60);
+/// What a failed turn says to the person it answers, wherever its reply is
+/// read. The failure itself goes to the prompt's error, not to them.
+const TURN_FAILED_REPLY: &str = "I ran into an error and stopped before finishing.";
+
/// Whole milliseconds since `started`, saturating; a span field, not a clock.
fn elapsed_ms(started: Instant) -> u64 {
u64::try_from(started.elapsed().as_millis()).unwrap_or(u64::MAX)
@@ -1121,12 +1125,22 @@ async fn run_turn(
)),
));
}
- if let Some(failure) = &failure {
+ // The turn's text is the reply a channel thread reads, so it says the
+ // turn failed and leaves why to the prompt's error.
+ if failure.is_some() {
+ // Readers join a turn's text chunks, so set this apart from any
+ // text the turn already said.
+ let said_something = turn_parts
+ .iter()
+ .any(|part| matches!(part, AssistantMessagePart::Text { .. }));
+ let reply = if said_something {
+ format!("\n\n{TURN_FAILED_REPLY}")
+ } else {
+ TURN_FAILED_REPLY.to_owned()
+ };
let _ = connection.send_notification(SessionNotification::new(
acp_session_id.clone(),
- SessionUpdate::AgentMessageChunk(ContentChunk::new(
- format!("The agent stopped on an error: {failure}").into(),
- )),
+ SessionUpdate::AgentMessageChunk(ContentChunk::new(reply.into())),
));
}
state.push_turn(request_id, prompt, turn_parts);
diff --git a/crates/agent_inmem/src/domain/agent/test.rs b/crates/agent_inmem/src/domain/agent/test.rs
index 7a1401eaa7..9a55595e70 100644
--- a/crates/agent_inmem/src/domain/agent/test.rs
+++ b/crates/agent_inmem/src/domain/agent/test.rs
@@ -56,6 +56,41 @@ impl TurnEngine for CancelledEngine {
}
}
+/// A turn whose model spoke, thought, then called a tool the loop refused.
+struct UnknownToolEngine;
+
+impl TurnEngine for UnknownToolEngine {
+ fn supported_models(&self) -> &[&str] {
+ crate::testing::TEST_MODELS
+ }
+
+ fn run_turn(
+ &self,
+ _request: TurnRequest,
+ ) -> tokio::sync::mpsc::Receiver<Result<StreamPart, agent::AgentError>> {
+ let (parts, receiver) = tokio::sync::mpsc::channel(3);
+ tokio::spawn(async move {
+ let _ = parts
+ .send(Ok(StreamPart::Content(
+ "I'm checking your access on that project.".into(),
+ )))
+ .await;
+ let _ = parts
+ .send(Ok(StreamPart::Thinking("Read the project next.".into())))
+ .await;
+ let unknown = PromptError::UnknownToolCall {
+ tool_name: "ReadInitiative".to_owned(),
+ available_tools: vec!["LoadTools".to_owned()],
+ allowed_tools: vec!["LoadTools".to_owned()],
+ chat_history: Box::default(),
+ };
+ let error = agent::AgentError::Streaming(StreamingError::Prompt(Box::new(unknown)));
+ let _ = parts.send(Err(error)).await;
+ });
+ receiver
+ }
+}
+
/// Drive the served agent as a scripted ACP client: initialize, open a
/// session, then hand the connection to `scenario`.
async fn with_agent<Engine, Out>(
@@ -1705,6 +1740,30 @@ async fn engine_cancellation_is_not_rendered_as_an_error_message() {
);
}
+/// A failed turn's reply is what a channel thread posts, so it says the turn
+/// failed in words; the raw error is the prompt's.
+#[tokio::test]
+async fn a_failed_turn_says_so_without_the_raw_error() {
+ let (notifications, _config_options, response) =
+ with_agent(Arc::new(UnknownToolEngine), async |connection, session| {
+ connection
+ .send_request(text_prompt(&session, "link these tasks"))
+ .block_task()
+ .await
+ })
+ .await;
+
+ assert_eq!(
+ spoken(&notifications),
+ format!("I'm checking your access on that project.\n\n{TURN_FAILED_REPLY}")
+ );
+ let error = response.expect_err("the turn failed");
+ assert!(
+ format!("{error:?}").contains("UnknownToolCall"),
+ "{error:?}"
+ );
+}
+
#[tokio::test]
async fn a_prompt_for_an_unknown_session_is_refused() {
let engine = Arc::new(ScriptedEngine::new(vec![]));
@@ -2570,11 +2629,7 @@ async fn a_silent_turn_with_no_question_out_is_stopped_by_the_idle_timeout() {
|| format!("{error:?}").contains("produced nothing"),
"got {error:?}"
);
- assert!(
- spoken(&notifications).contains("produced nothing"),
- "got {:?}",
- spoken(&notifications)
- );
+ assert_eq!(spoken(&notifications), TURN_FAILED_REPLY);
}
/// An engine whose turn waits on a person for twice the idle timeout - the
diff --git a/crates/ai_tools/src/search_tools.rs b/crates/ai_tools/src/search_tools.rs
index 2c436c76e9..2328540af9 100644
--- a/crates/ai_tools/src/search_tools.rs
+++ b/crates/ai_tools/src/search_tools.rs
@@ -1,35 +1,17 @@
+use ai_toolset::tool_search::{LoadToolsResponse, SearchToolsResponse, ToolMatch};
use ai_toolset::{
AsyncTool, RequestContext, SearchableTool, ServiceContext, ToolLoader, ToolResult,
};
use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
-use serde::{Deserialize, Serialize};
+use serde::Deserialize;
use crate::ToolServiceContext;
#[cfg(test)]
mod test;
-/// A tool surfaced by [`SearchTools`] / [`LoadTools`] — just enough for the
-/// model to decide how to call it.
-#[derive(Debug, Serialize, JsonSchema)]
-pub struct ToolMatch {
- /// The exact name to call the tool by.
- pub name: String,
- /// What the tool does.
- pub description: String,
-}
-
-impl ToolMatch {
- fn of(tool: &SearchableTool) -> Self {
- Self {
- name: tool.name.clone(),
- description: tool.description.clone(),
- }
- }
-}
-
// ---------------------------------------------------------------------------
// SearchTools — discovery + auto-loading
// ---------------------------------------------------------------------------
@@ -44,19 +26,6 @@ impl ToolMatch {
/// be loaded explicitly with [`LoadTools`].
const MAX_AUTO_LOADED_MATCHES: usize = 8;
-/// Response from [`SearchTools`]: ranked matches, split into the top matches
-/// (auto-loaded, callable on the next model turn) and the remainder (loadable
-/// via [`LoadTools`]).
-#[derive(Debug, Serialize, JsonSchema)]
-pub struct SearchToolsResponse {
- /// Top matches, ranked by relevance. These are loaded: call them by exact
- /// name on the next step.
- pub results: Vec<ToolMatch>,
- /// Matches past the auto-load cap, ranked. Not callable yet — pass a name
- /// to `LoadTools` if one of these is the tool you need.
- pub additional_matches: Vec<ToolMatch>,
-}
-
/// `SearchTools` discovers tools from connected integrations (MCP servers such
/// as Slack, Gmail, Linear) that are not listed upfront, and auto-loads the top
/// matches so they are callable on the next model turn. This keeps the model
@@ -103,16 +72,6 @@ impl AsyncTool<ToolServiceContext> for SearchTools {
// LoadTools — load named tools so they become callable
// ---------------------------------------------------------------------------
-/// Response from [`LoadTools`]: which requested tools were loaded, and any names
-/// that weren't found.
-#[derive(Debug, Serialize, JsonSchema)]
-pub struct LoadToolsResponse {
- /// Tools that are now loaded and callable by name.
- pub loaded: Vec<ToolMatch>,
- /// Requested names that don't exist (call `SearchTools` to find valid names).
- pub not_found: Vec<String>,
-}
-
/// `LoadTools` loads tools discovered via `SearchTools` so they become callable.
/// Pass the exact names from the search results; after loading, call each tool
/// by its name as usual.
diff --git a/crates/ai_tools/src/search_tools/test.rs b/crates/ai_tools/src/search_tools/test.rs
index 935a42f124..5c1fa88a45 100644
--- a/crates/ai_tools/src/search_tools/test.rs
+++ b/crates/ai_tools/src/search_tools/test.rs
@@ -207,3 +207,23 @@ fn load_without_loader_still_reports() {
);
assert!(result.not_found.is_empty());
}
+
+// --- names the agent loop reads loads back by ---
+
+#[test]
+fn tools_are_named_as_the_agent_loop_reads_them() {
+ let tools = ai_toolset::AsyncToolCollection::<ToolServiceContext>::new()
+ .add_tool::<SearchTools, ToolServiceContext>()
+ .add_tool::<LoadTools, ToolServiceContext>();
+
+ assert!(
+ tools
+ .tools
+ .contains_key(ai_toolset::tool_search::SEARCH_TOOLS)
+ );
+ assert!(
+ tools
+ .tools
+ .contains_key(ai_toolset::tool_search::LOAD_TOOLS)
+ );
+}
diff --git a/crates/ai_toolset/AGENTS.md b/crates/ai_toolset/AGENTS.md
index a93369cb8e..ce234c4412 100644
--- a/crates/ai_toolset/AGENTS.md
+++ b/crates/ai_toolset/AGENTS.md
@@ -27,7 +27,9 @@ deliberately stable and widely depended on.
## Scope
-- Owns: the tool trait, schema generation, and collection mechanics.
+- Owns: the tool trait, schema generation, and collection mechanics, plus
+ the tool-search wire types (`tool_search.rs`: `SearchToolsResponse`,
+ `LoadToolsResponse`) the agent loop reads loads back from.
- Not here: any actual tool implementation — those live in domain crates
and are assembled in `ai_tools`.
diff --git a/crates/ai_toolset/src/tool_search.rs b/crates/ai_toolset/src/tool_search.rs
index cea7befe1a..e92b430fa6 100644
--- a/crates/ai_toolset/src/tool_search.rs
+++ b/crates/ai_toolset/src/tool_search.rs
@@ -10,9 +10,16 @@
//! catalog out of every request without depending on any provider's native
//! tool-search feature.
-use schemars::Schema;
+use schemars::{JsonSchema, Schema};
+use serde::{Deserialize, Serialize};
use std::sync::Arc;
+/// The name of the tool that finds catalog tools and loads the top matches.
+pub const SEARCH_TOOLS: &str = "SearchTools";
+
+/// The name of the tool that loads catalog tools by name.
+pub const LOAD_TOOLS: &str = "LoadTools";
+
/// A tool that is loaded on demand via tool search rather than sent on every
/// request. The catalog of these is returned by
/// [`ToolSet::searchable_catalog`](crate::ToolSet::searchable_catalog) and read
@@ -55,53 +62,64 @@ impl std::fmt::Debug for ToolLoader {
}
}
-#[cfg(test)]
-mod test {
- use super::*;
- use crate::RequestContext;
- use macro_user_id::user_id::MacroUserIdStr;
- use std::sync::Mutex;
+/// A tool surfaced by [`SearchTools`] / [`LoadTools`] — just enough for the
+/// model to decide how to call it.
+#[derive(Debug, Serialize, Deserialize, JsonSchema)]
+pub struct ToolMatch {
+ /// The exact name to call the tool by.
+ pub name: String,
+ /// What the tool does.
+ pub description: String,
+}
- fn tool(name: &str) -> SearchableTool {
- SearchableTool {
- name: name.to_string(),
- description: String::new(),
- schema: Schema::default(),
+impl ToolMatch {
+ /// The match for `tool`.
+ pub fn of(tool: &SearchableTool) -> Self {
+ Self {
+ name: tool.name.clone(),
+ description: tool.description.clone(),
}
}
+}
- #[test]
- fn tool_loader_forwards_to_its_closure() {
- let seen = Arc::new(Mutex::new(Vec::<String>::new()));
- let sink = seen.clone();
- let loader = ToolLoader::new(move |tools| {
- sink.lock()
- .unwrap()
- .extend(tools.into_iter().map(|t| t.name));
- });
-
- loader.load(vec![tool("a"), tool("b")]);
-
- assert_eq!(&*seen.lock().unwrap(), &["a".to_string(), "b".to_string()]);
- }
-
- #[test]
- fn request_context_new_has_no_tool_search() {
- let user = MacroUserIdStr::try_from_email("[email protected]").unwrap();
- let ctx = RequestContext::new(user);
- assert!(ctx.searchable_tools.is_empty());
- assert!(ctx.tool_loader.is_none());
- }
+/// Response from [`SearchTools`]: ranked matches, split into the top matches
+/// (auto-loaded, callable on the next model turn) and the remainder (loadable
+/// via [`LoadTools`]).
+#[derive(Debug, Serialize, Deserialize, JsonSchema)]
+pub struct SearchToolsResponse {
+ /// Top matches, ranked by relevance. These are loaded: call them by exact
+ /// name on the next step.
+ pub results: Vec<ToolMatch>,
+ /// Matches past the auto-load cap, ranked. Not callable yet — pass a name
+ /// to `LoadTools` if one of these is the tool you need.
+ pub additional_matches: Vec<ToolMatch>,
+}
- #[test]
- fn with_tool_search_wires_catalog_and_loader() {
- let user = MacroUserIdStr::try_from_email("[email protected]").unwrap();
- let catalog = Arc::new(vec![tool("mcp__x__y")]);
- let loader = ToolLoader::new(|_| {});
- let ctx = RequestContext::new(user).with_tool_search(catalog, loader);
+/// Response from [`LoadTools`]: which requested tools were loaded, and any names
+/// that weren't found.
+#[derive(Debug, Serialize, Deserialize, JsonSchema)]
+pub struct LoadToolsResponse {
+ /// Tools that are now loaded and callable by name.
+ pub loaded: Vec<ToolMatch>,
+ /// Requested names that don't exist (call `SearchTools` to find valid names).
+ pub not_found: Vec<String>,
+}
- assert_eq!(ctx.searchable_tools.len(), 1);
- assert_eq!(ctx.searchable_tools[0].name, "mcp__x__y");
- assert!(ctx.tool_loader.is_some());
- }
+/// The names of the catalog tools a `tool_name` call loaded, read from its
+/// `result`. Empty for any other tool, and for a result that is not the
+/// tool's response (an error, or a result cut for length).
+pub fn tools_loaded_by(tool_name: &str, result: &str) -> Vec<String> {
+ let matches = match tool_name {
+ SEARCH_TOOLS => serde_json::from_str::<SearchToolsResponse>(result)
+ .map(|response| response.results)
+ .unwrap_or_default(),
+ LOAD_TOOLS => serde_json::from_str::<LoadToolsResponse>(result)
+ .map(|response| response.loaded)
+ .unwrap_or_default(),
+ _ => Vec::new(),
+ };
+ matches.into_iter().map(|tool| tool.name).collect()
}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/ai_toolset/src/tool_search/test.rs b/crates/ai_toolset/src/tool_search/test.rs
new file mode 100644
index 0000000000..2cd4fea270
--- /dev/null
+++ b/crates/ai_toolset/src/tool_search/test.rs
@@ -0,0 +1,66 @@
+use super::*;
+use crate::RequestContext;
+use macro_user_id::user_id::MacroUserIdStr;
+use std::sync::Mutex;
+
+fn tool(name: &str) -> SearchableTool {
+ SearchableTool {
+ name: name.to_string(),
+ description: String::new(),
+ schema: Schema::default(),
+ }
+}
+
+#[test]
+fn tool_loader_forwards_to_its_closure() {
+ let seen = Arc::new(Mutex::new(Vec::<String>::new()));
+ let sink = seen.clone();
+ let loader = ToolLoader::new(move |tools| {
+ sink.lock()
+ .unwrap()
+ .extend(tools.into_iter().map(|t| t.name));
+ });
+
+ loader.load(vec![tool("a"), tool("b")]);
+
+ assert_eq!(&*seen.lock().unwrap(), &["a".to_string(), "b".to_string()]);
+}
+
+#[test]
+fn request_context_new_has_no_tool_search() {
+ let user = MacroUserIdStr::try_from_email("[email protected]").unwrap();
+ let ctx = RequestContext::new(user);
+ assert!(ctx.searchable_tools.is_empty());
+ assert!(ctx.tool_loader.is_none());
+}
+
+#[test]
+fn with_tool_search_wires_catalog_and_loader() {
+ let user = MacroUserIdStr::try_from_email("[email protected]").unwrap();
+ let catalog = Arc::new(vec![tool("mcp__x__y")]);
+ let loader = ToolLoader::new(|_| {});
+ let ctx = RequestContext::new(user).with_tool_search(catalog, loader);
+
+ assert_eq!(ctx.searchable_tools.len(), 1);
+ assert_eq!(ctx.searchable_tools[0].name, "mcp__x__y");
+ assert!(ctx.tool_loader.is_some());
+}
+
+#[test]
+fn tools_loaded_by_reads_search_and_load_results() {
+ let search = serde_json::json!({
+ "results": [{ "name": "ReadInitiative", "description": "Read a project" }],
+ "additional_matches": [{ "name": "ListInitiatives", "description": "List projects" }],
+ })
+ .to_string();
+ let load = serde_json::json!({
+ "loaded": [{ "name": "ReadInitiative", "description": "Read a project" }],
+ "not_found": ["ReadInitiatives"],
+ })
+ .to_string();
+
+ assert_eq!(tools_loaded_by(SEARCH_TOOLS, &search), ["ReadInitiative"]);
+ assert_eq!(tools_loaded_by(LOAD_TOOLS, &load), ["ReadInitiative"]);
+ assert!(tools_loaded_by("ReadInitiative", &load).is_empty());
+ assert!(tools_loaded_by(LOAD_TOOLS, "Tool call failed").is_empty());
+}