use std::collections::HashMap;
use futures::StreamExt;
use crate::ai::{
Client, CompleteOptions, ContentBlock, Context, Message, Model, Role, StopReason, StreamEvent,
Usage,
};
use crate::domain::{Registry, Specialist, ToolDef};
const MAX_TURNS: usize = 16;
#[derive(Debug, Clone, PartialEq)]
pub enum RunEvent<'a> {
TextDelta(&'a str),
Text(&'a str),
ThinkingDelta(&'a str),
Thinking(&'a str),
TurnDone { stop_reason: StopReason },
Usage(Usage),
ToolRan {
name: &'a str,
output: &'a str,
success: bool,
},
ToolFailed { name: &'a str, message: &'a str },
}
pub async fn run_specialist(
client: &Client,
registry: &Registry,
specialist: &Specialist,
prompt: &str,
tools: &[ToolDef],
opts: &CompleteOptions,
observer: &mut dyn FnMut(RunEvent<'_>),
) -> Result<(), String> {
let model = registry.resolve_model(specialist)?;
let mut ctx = build_context(specialist, prompt, tools);
let agentic = specialist.constraint.is_none();
let stream = specialist.stream && !opts.constrained_decoding;
for _ in 0..MAX_TURNS {
let (message, usage, stop_reason) =
one_turn(client, &model, &ctx, opts, stream, observer).await?;
observer(RunEvent::TurnDone { stop_reason });
observer(RunEvent::Usage(usage));
let calls: Vec<(String, String, serde_json::Value)> = message
.content
.iter()
.filter_map(|block| match block {
ContentBlock::ToolCall {
id,
name,
arguments,
} => Some((id.clone(), name.clone(), arguments.clone())),
_ => None,
})
.collect();
if calls.is_empty() {
return Ok(());
}
let mut results = Vec::with_capacity(calls.len());
for (id, tool_name, arguments) in &calls {
results.push(run_tool_call(tools, id, tool_name, arguments, observer));
}
if !agentic {
return Ok(());
}
ctx.messages.push(message);
ctx.messages.push(Message {
role: Role::User,
content: results,
});
}
Err(format!(
"specialist '{}' did not finish within {MAX_TURNS} turns.\n \
It kept calling tools without settling on an answer — inspect the tool \
outputs above, tighten its system prompt, or reduce the tools it can call.",
specialist.name
))
}
async fn one_turn(
client: &Client,
model: &Model,
ctx: &Context,
opts: &CompleteOptions,
stream: bool,
observer: &mut dyn FnMut(RunEvent<'_>),
) -> Result<(Message, Usage, StopReason), String> {
if stream {
let mut events = client
.stream(model, ctx, opts)
.await
.map_err(|e| e.to_string())?;
while let Some(event) = events.next().await {
match event.map_err(|e| e.to_string())? {
StreamEvent::TextDelta { delta, .. } => observer(RunEvent::TextDelta(&delta)),
StreamEvent::ThinkingDelta { delta, .. } => {
observer(RunEvent::ThinkingDelta(&delta))
}
StreamEvent::Done {
usage,
message,
stop_reason,
} => return Ok((message, usage, stop_reason)),
StreamEvent::ToolCallDelta { .. } => {}
}
}
Err("stream ended without a final event".to_string())
} else {
let completion = client
.complete(model, ctx, opts)
.await
.map_err(|e| e.to_string())?;
for block in &completion.message.content {
match block {
ContentBlock::Text { text } => observer(RunEvent::Text(text)),
ContentBlock::Thinking { thinking } => observer(RunEvent::Thinking(thinking)),
_ => {}
}
}
Ok((completion.message, completion.usage, completion.stop_reason))
}
}
fn build_context(specialist: &Specialist, prompt: &str, tools: &[ToolDef]) -> Context {
let mut ctx = Context::new(
Some(specialist.system_prompt.clone()),
vec![Message::user(prompt)],
);
ctx.tools = tools.iter().map(ToolDef::to_tool).collect();
ctx
}
fn run_tool_call(
tools: &[ToolDef],
id: &str,
tool_name: &str,
arguments: &serde_json::Value,
observer: &mut dyn FnMut(RunEvent<'_>),
) -> ContentBlock {
let tool = match tools.iter().find(|t| t.name == tool_name) {
Some(tool) => tool,
None => {
let message = format!("unknown tool: {tool_name}");
observer(RunEvent::ToolFailed {
name: tool_name,
message: &message,
});
return ContentBlock::tool_error(id, message);
}
};
let vars = args_to_vars(arguments);
match crate::run_script(&tool.script, &vars) {
Ok(run) => {
observer(RunEvent::ToolRan {
name: tool_name,
output: &run.output,
success: run.success,
});
if run.success {
ContentBlock::tool_result(id, run.output)
} else {
ContentBlock::tool_error(id, run.output)
}
}
Err(e) => {
let path = tool.script.display();
let message = format!(
"tool '{tool_name}' could not run its script {path}: {e}\n \
Ensure it exists, is executable (chmod +x {path}), and has a shebang (e.g. #!/bin/sh)."
);
observer(RunEvent::ToolFailed {
name: tool_name,
message: &message,
});
ContentBlock::tool_error(id, message)
}
}
}
fn args_to_vars(arguments: &serde_json::Value) -> HashMap<String, String> {
arguments
.as_object()
.into_iter()
.flatten()
.map(|(key, value)| {
let value = match value {
serde_json::Value::String(s) => s.clone(),
other => other.to_string(),
};
(key.clone(), value)
})
.collect()
}
#[cfg(test)]
mod tests {
use super::*;
use std::path::PathBuf;
fn write_script(body: &str) -> PathBuf {
use std::os::unix::fs::PermissionsExt;
let path = std::env::temp_dir().join(format!(
"sp_run_tool_{}_{}.sh",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
));
std::fs::write(&path, body).unwrap();
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap();
path
}
fn tool(name: &str, script: PathBuf) -> ToolDef {
ToolDef {
name: name.to_string(),
script,
description: String::new(),
params: vec![],
}
}
#[test]
fn build_context_carries_system_prompt_user_turn_and_tools() {
let specialist = Specialist {
name: "netop".to_string(),
provider: "anthropic".to_string(),
model: "claude-opus-4-8".to_string(),
system_prompt: "You ping hosts.".to_string(),
tools: vec!["ping".to_string()],
constraint: None,
reasoning: crate::ai::Reasoning::Off,
stream: false,
};
let tools = vec![ToolDef {
name: "ping".to_string(),
script: PathBuf::from("ping.sh"),
description: "Ping a host".to_string(),
params: vec!["host".to_string()],
}];
let ctx = build_context(&specialist, "ping example.com", &tools);
assert_eq!(ctx.system.as_deref(), Some("You ping hosts."));
assert_eq!(ctx.tools.len(), 1);
assert_eq!(ctx.tools[0].name, "ping");
assert_eq!(
ctx.messages[0].content,
vec![ContentBlock::text("ping example.com")]
);
}
#[test]
fn args_to_vars_stringifies_values_and_ignores_non_objects() {
let vars = args_to_vars(&serde_json::json!({ "env": "prod", "count": 3 }));
assert_eq!(vars.get("env"), Some(&"prod".to_string()));
assert_eq!(vars.get("count"), Some(&"3".to_string()));
assert!(args_to_vars(&serde_json::json!("oops")).is_empty());
}
#[test]
fn args_to_vars_handles_varied_json_value_types() {
let vars = args_to_vars(&serde_json::json!({
"s": "txt",
"n": 1.5,
"b": true,
"nil": null,
"arr": [1, 2],
"obj": { "k": "v" },
}));
assert_eq!(vars.get("s"), Some(&"txt".to_string()));
assert_eq!(vars.get("n"), Some(&"1.5".to_string()));
assert_eq!(vars.get("b"), Some(&"true".to_string()));
assert_eq!(vars.get("nil"), Some(&"null".to_string()));
assert_eq!(vars.get("arr"), Some(&"[1,2]".to_string()));
assert_eq!(vars.get("obj"), Some(&r#"{"k":"v"}"#.to_string()));
}
#[test]
fn run_tool_call_returns_result_on_success_and_reports_output() {
let script = write_script("#!/bin/sh\necho \"hi $NAME\"\n");
let tools = vec![tool("greet", script.clone())];
let mut events = Vec::new();
let block = run_tool_call(
&tools,
"id1",
"greet",
&serde_json::json!({ "NAME": "world" }),
&mut |e| events.push(format!("{e:?}")),
);
std::fs::remove_file(&script).ok();
match block {
ContentBlock::ToolResult {
tool_call_id,
content,
is_error,
} => {
assert_eq!(tool_call_id, "id1");
assert!(!is_error);
assert!(content.contains("hi world"));
}
other => panic!("expected ToolResult, got {other:?}"),
}
assert!(events
.iter()
.any(|e| e.contains("ToolRan") && e.contains("hi world")));
}
#[test]
fn run_tool_call_returns_error_on_nonzero_exit() {
let script = write_script("#!/bin/sh\necho boom >&2\nexit 1\n");
let tools = vec![tool("fail", script.clone())];
let block = run_tool_call(&tools, "id2", "fail", &serde_json::json!({}), &mut |_| {});
std::fs::remove_file(&script).ok();
match block {
ContentBlock::ToolResult {
content, is_error, ..
} => {
assert!(is_error);
assert!(content.contains("boom"));
}
other => panic!("expected ToolResult error, got {other:?}"),
}
}
#[test]
fn run_tool_call_reports_unknown_tool_as_error() {
let mut failed = false;
let block = run_tool_call(&[], "id3", "ghost", &serde_json::json!({}), &mut |e| {
if matches!(e, RunEvent::ToolFailed { .. }) {
failed = true;
}
});
match block {
ContentBlock::ToolResult {
tool_call_id,
content,
is_error,
} => {
assert_eq!(tool_call_id, "id3");
assert!(is_error);
assert!(content.contains("unknown tool"));
}
other => panic!("expected ToolResult error, got {other:?}"),
}
assert!(failed);
}
#[test]
fn run_tool_call_enriches_launch_failure_with_remediation() {
let tools = vec![tool(
"ghost_script",
PathBuf::from("/nonexistent/sp_tool_does_not_exist.sh"),
)];
let block = run_tool_call(
&tools,
"id",
"ghost_script",
&serde_json::json!({}),
&mut |_| {},
);
match block {
ContentBlock::ToolResult {
content, is_error, ..
} => {
assert!(is_error);
assert!(content.contains("could not run its script"));
assert!(content.contains("chmod +x"));
}
other => panic!("expected ToolResult error, got {other:?}"),
}
}
}