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};
use crate::log::{self, SpecialistLog};
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 },
}
#[allow(clippy::too_many_arguments)]
pub async fn run_specialist(
client: &Client,
registry: &Registry,
specialist: &Specialist,
prompt: &str,
tools: &[ToolDef],
opts: &CompleteOptions,
observer: &mut dyn FnMut(RunEvent<'_>),
log: Option<&SpecialistLog<'_>>,
) -> Result<(), String> {
let model = registry.resolve_model(specialist)?;
let mut ctx = build_context(specialist, prompt, tools);
let agentic = specialist.constraint.is_none();
let constrained_active = opts.constrained_decoding && opts.tool_choice.is_some();
let stream = specialist.stream && !constrained_active;
if let Some(log) = log {
log.emit(log::specialist_start(
log.wf,
log.stmt,
&specialist.name,
&specialist.model,
prompt,
));
}
let started = std::time::Instant::now();
let mut turns = 0u32;
let mut input_tokens = 0u32;
let mut output_tokens = 0u32;
let mut last_stop = StopReason::Stop;
let mut settled = false;
for _ in 0..MAX_TURNS {
let (message, usage, stop_reason) =
one_turn(client, &model, &ctx, opts, stream, observer).await?;
turns += 1;
input_tokens += usage.input;
output_tokens += usage.output;
last_stop = stop_reason;
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() {
settled = true;
break;
}
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,
log,
&specialist.name,
));
}
if !agentic {
settled = true;
break;
}
ctx.messages.push(message);
ctx.messages.push(Message {
role: Role::User,
content: results,
});
}
if settled {
if let Some(log) = log {
log.emit(log::specialist_done(
log.wf,
log.stmt,
&specialist.name,
last_stop,
turns,
input_tokens,
output_tokens,
started.elapsed().as_millis() as u64,
));
}
return Ok(());
}
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<'_>),
log: Option<&SpecialistLog<'_>>,
specialist: &str,
) -> ContentBlock {
if let Some(log) = log {
log.emit(log::tool_call(
log.wf,
log.stmt,
Some(specialist),
tool_name,
arguments,
));
}
let started = std::time::Instant::now();
let done = |log: Option<&SpecialistLog<'_>>, success: bool, exit_code: Option<i32>| {
if let Some(log) = log {
log.emit(log::tool_done(
log.wf,
log.stmt,
Some(specialist),
tool_name,
success,
exit_code,
started.elapsed().as_millis() as u64,
));
}
};
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,
});
done(log, false, None);
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,
});
done(log, run.success, run.code);
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,
});
done(log, false, None);
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)]
#[path = "run_tests.rs"]
mod tests;