1use std::pin::Pin;
8use std::sync::Arc;
9
10use crate::protocol::{
11 AssistantBlock, BackgroundTask, InboundMessage, InboundUserMessage, ResultMessage, TurnErrorKind,
12 UserMessage,
13};
14use crate::session::{Session, SessionError};
15
16#[derive(Debug, Clone)]
19pub enum AgentEvent {
20 Text(String),
22 Thinking(String),
24 RedactedThinking(String),
26 ToolUse { id: String, name: String, input: serde_json::Value, server: bool },
29 ToolResult {
33 tool_use_id: String,
34 content: serde_json::Value,
35 is_error: bool,
36 structured: Option<serde_json::Value>,
37 },
38 Subagent { parent_tool_use_id: String, event: Box<AgentEvent> },
41 BackgroundTasks(Vec<BackgroundTask>),
43 ModelFallback { from: String, to: String, trigger: String },
45 Compacted { trigger: String, pre_tokens: Option<u64>, post_tokens: Option<u64> },
47 System { subtype: String, data: serde_json::Value },
50 Other { kind: String, data: serde_json::Value },
53 Done(TurnResult),
55 Error(TurnError),
57}
58
59#[derive(Debug, Clone)]
60pub struct TurnResult {
61 pub session_id: Option<String>,
62 pub result: Option<String>,
64 pub structured_output: Option<serde_json::Value>,
66 pub total_cost_usd: Option<f64>,
67 pub ttft_ms: Option<u64>,
68 pub duration_ms: Option<u64>,
69 pub duration_api_ms: Option<u64>,
70 pub num_turns: Option<u64>,
72 pub input_tokens: Option<u64>,
73 pub output_tokens: Option<u64>,
74 pub cache_read_input_tokens: Option<u64>,
75 pub cache_creation_input_tokens: Option<u64>,
76 pub model_usage: Option<serde_json::Value>,
78 pub stop_reason: Option<String>,
79 pub terminal_reason: Option<String>,
80 pub permission_denials: Vec<serde_json::Value>,
82 pub origin: Option<serde_json::Value>,
85}
86
87impl From<&ResultMessage> for TurnResult {
88 fn from(r: &ResultMessage) -> Self {
89 let usage = r.usage.as_ref();
90 TurnResult {
91 session_id: r.session_id.clone(),
92 result: r.result.clone(),
93 structured_output: r.structured_output.clone(),
94 total_cost_usd: r.total_cost_usd,
95 ttft_ms: r.ttft_ms,
96 duration_ms: r.duration_ms,
97 duration_api_ms: r.duration_api_ms,
98 num_turns: r.num_turns,
99 input_tokens: usage.map(|u| u.input_tokens),
100 output_tokens: usage.map(|u| u.output_tokens),
101 cache_read_input_tokens: usage.and_then(|u| u.cache_read_input_tokens),
102 cache_creation_input_tokens: usage.and_then(|u| u.cache_creation_input_tokens),
103 model_usage: r.model_usage.clone(),
104 stop_reason: r.stop_reason.clone(),
105 terminal_reason: r.terminal_reason.clone(),
106 permission_denials: r.permission_denials.clone(),
107 origin: r.origin.clone(),
108 }
109 }
110}
111
112#[derive(Debug, Clone, thiserror::Error)]
114#[error("{message}")]
115pub struct TurnError {
116 pub kind: TurnErrorKind,
117 pub message: String,
118 pub result: Option<TurnResult>,
119}
120
121impl From<&ResultMessage> for TurnError {
122 fn from(r: &ResultMessage) -> Self {
123 TurnError { kind: r.error_kind(), message: r.error_message(), result: Some(TurnResult::from(r)) }
124 }
125}
126
127impl TurnError {
128 fn cancelled() -> Self {
129 TurnError { kind: TurnErrorKind::Cancelled, message: "prompt cancelled before it ran".into(), result: None }
130 }
131
132 fn session_closed() -> Self {
133 TurnError {
134 kind: TurnErrorKind::SessionClosed,
135 message: "session closed before the turn finished".into(),
136 result: None,
137 }
138 }
139}
140
141#[derive(Debug, thiserror::Error)]
142pub enum AgentError {
143 #[error("session error: {0}")]
144 Session(#[from] SessionError),
145 #[error("json: {0}")]
146 Json(#[from] serde_json::Error),
147}
148
149pub type AgentStream = Pin<Box<dyn tokio_stream::Stream<Item = AgentEvent> + Send + 'static>>;
152
153pub struct Agent {
157 session: Session,
158}
159
160impl Agent {
161 pub fn new(session: Session) -> Self {
162 Self { session }
163 }
164
165 pub fn session(&self) -> &Session {
166 &self.session
167 }
168
169 pub async fn prompt(&self, text: impl Into<String>) -> Result<AgentStream, AgentError> {
173 self.prompt_message(UserMessage::text(text.into())).await
174 }
175
176 pub async fn prompt_message(&self, message: UserMessage) -> Result<AgentStream, AgentError> {
182 let mut rx = self.session.subscribe();
184 let uuid = message.uuid.clone();
185 self.session.send_prompt(&message).await?;
186 let partial = self.session.include_partial();
189 let span = tracing::info_span!(
191 "claude.turn",
192 session_id = self.session.session_id().unwrap_or_default(),
193 cost_usd = tracing::field::Empty,
194 input_tokens = tracing::field::Empty,
195 output_tokens = tracing::field::Empty,
196 ttft_ms = tracing::field::Empty,
197 error = tracing::field::Empty,
198 );
199
200 let mut guard = CancelOnDrop { session: self.session.clone(), uuid: uuid.clone(), armed: true };
204 let stream = async_stream::stream! {
205 let mut started = false;
213 let mut held: Vec<Arc<InboundMessage>> = vec![];
214 loop {
215 let Some(msg) = rx.recv().await else {
216 guard.disarm();
217 yield AgentEvent::Error(TurnError::session_closed());
218 break;
219 };
220 if let InboundMessage::Other(frame) = msg.as_ref()
223 && is_cancelled(frame, &uuid)
224 {
225 guard.disarm();
226 yield AgentEvent::Error(TurnError::cancelled());
227 break;
228 }
229
230 if !started {
231 match msg.as_ref() {
232 InboundMessage::User(u) if u.uuid.as_deref() == Some(uuid.as_str()) => {
233 started = true;
234 for m in held.drain(..) {
235 for ev in to_events(&m, partial) {
236 yield ev;
237 }
238 }
239 }
240 InboundMessage::Result(r) if r.answers(&uuid) => {
243 started = true;
244 for m in held.drain(..) {
245 for ev in to_events(&m, partial) {
246 yield ev;
247 }
248 }
249 }
250 InboundMessage::Result(_) => {
251 held.clear();
252 continue;
253 }
254 _ => {
255 held.push(msg);
256 continue;
257 }
258 }
259 if !matches!(msg.as_ref(), InboundMessage::Result(_)) {
260 continue;
261 }
262 }
263
264 if let InboundMessage::Result(r) = msg.as_ref() {
265 guard.disarm();
266 let t = TurnResult::from(r);
267 if let Some(v) = t.total_cost_usd { span.record("cost_usd", v); }
268 if let Some(v) = t.input_tokens { span.record("input_tokens", v); }
269 if let Some(v) = t.output_tokens { span.record("output_tokens", v); }
270 if let Some(v) = t.ttft_ms { span.record("ttft_ms", v); }
271 if !r.is_success() { span.record("error", r.subtype.as_str()); }
272 }
273 let done = matches!(msg.as_ref(), InboundMessage::Result(_));
274 for ev in to_events(&msg, partial) {
275 yield ev;
276 }
277 if done {
278 break;
279 }
280 }
281 };
282
283 Ok(Box::pin(stream))
284 }
285
286 pub fn watch(&self) -> AgentStream {
291 let mut rx = self.session.subscribe();
292 let partial = self.session.include_partial();
293 Box::pin(async_stream::stream! {
294 while let Some(msg) = rx.recv().await {
295 for ev in to_events(&msg, partial) {
296 yield ev;
297 }
298 }
299 })
300 }
301}
302
303struct CancelOnDrop {
305 session: Session,
306 uuid: String,
307 armed: bool,
308}
309
310impl CancelOnDrop {
311 fn disarm(&mut self) {
312 self.armed = false;
313 }
314}
315
316impl Drop for CancelOnDrop {
317 fn drop(&mut self) {
318 if !self.armed || !self.session.is_alive() {
319 return;
320 }
321 let Ok(rt) = tokio::runtime::Handle::try_current() else {
322 tracing::warn!("turn stream dropped outside a Tokio runtime; the turn keeps running");
323 return;
324 };
325 let session = self.session.clone();
326 let uuid = std::mem::take(&mut self.uuid);
327 rt.spawn(async move {
328 if let Err(e) = session.cancel_prompt(&uuid).await {
329 tracing::debug!(error = %e, "cancelling a dropped turn failed");
330 }
331 });
332 }
333}
334
335fn to_events(msg: &InboundMessage, partial: bool) -> Vec<AgentEvent> {
340 match msg {
341 InboundMessage::Assistant(a) => {
342 let sub = a.parent_tool_use_id.is_some();
343 let events = a.message.content.iter().filter_map(|block| match block {
344 AssistantBlock::Text { text } if sub || !partial => Some(AgentEvent::Text(text.clone())),
345 AssistantBlock::Thinking { thinking } if sub || !partial => {
346 Some(AgentEvent::Thinking(thinking.clone()))
347 }
348 AssistantBlock::RedactedThinking { data } => Some(AgentEvent::RedactedThinking(data.clone())),
349 AssistantBlock::ToolUse { id, name, input } => Some(AgentEvent::ToolUse {
350 id: id.clone(),
351 name: name.clone(),
352 input: input.clone(),
353 server: false,
354 }),
355 AssistantBlock::ServerToolUse { id, name, input } => Some(AgentEvent::ToolUse {
356 id: id.clone(),
357 name: name.clone(),
358 input: input.clone(),
359 server: true,
360 }),
361 AssistantBlock::WebSearchToolResult { tool_use_id, content } => Some(AgentEvent::ToolResult {
362 tool_use_id: tool_use_id.clone(),
363 content: content.clone(),
364 is_error: false,
365 structured: None,
366 }),
367 _ => None,
368 });
369 in_thread(a.parent_tool_use_id.as_deref(), events.collect())
370 }
371
372 InboundMessage::User(u) => in_thread(u.parent_tool_use_id.as_deref(), tool_results(u)),
373
374 InboundMessage::StreamEvent(se) if se.parent_tool_use_id.is_none() => {
375 let delta = se.event.get("delta");
376 let text = delta.and_then(|d| d.get("text")).and_then(|t| t.as_str());
377 let thinking = delta.and_then(|d| d.get("thinking")).and_then(|t| t.as_str());
378 text.map(|t| AgentEvent::Text(t.to_string()))
379 .into_iter()
380 .chain(thinking.map(|t| AgentEvent::Thinking(t.to_string())))
381 .collect()
382 }
383
384 InboundMessage::System(s) => match s.subtype.as_str() {
385 "background_tasks_changed" => {
386 let tasks = s.extra.get("tasks").cloned().unwrap_or_default();
387 match serde_json::from_value::<Vec<BackgroundTask>>(tasks) {
388 Ok(tasks) => vec![AgentEvent::BackgroundTasks(tasks)],
389 Err(e) => {
390 tracing::debug!(error = %e, "undecodable background_tasks_changed");
391 vec![]
392 }
393 }
394 }
395 "model_fallback" => {
396 let field = |k: &str| s.extra.get(k).and_then(|v| v.as_str()).unwrap_or("").to_string();
397 vec![AgentEvent::ModelFallback {
398 from: field("original_model"),
399 to: field("fallback_model"),
400 trigger: field("trigger"),
401 }]
402 }
403 "compact_boundary" => {
404 let meta = s.extra.get("compact_metadata");
405 let num = |k: &str| meta.and_then(|m| m.get(k)).and_then(|v| v.as_u64());
406 vec![AgentEvent::Compacted {
407 trigger: meta.and_then(|m| m.get("trigger")).and_then(|v| v.as_str()).unwrap_or("").to_string(),
408 pre_tokens: num("pre_tokens"),
409 post_tokens: num("post_tokens"),
410 }]
411 }
412 other => vec![AgentEvent::System {
413 subtype: other.to_string(),
414 data: serde_json::to_value(s).unwrap_or_default(),
415 }],
416 },
417
418 InboundMessage::Other(data) => vec![AgentEvent::Other {
419 kind: data.get("type").and_then(|t| t.as_str()).unwrap_or("").to_string(),
420 data: data.clone(),
421 }],
422
423 InboundMessage::Result(r) if r.is_success() => vec![AgentEvent::Done(TurnResult::from(r))],
424 InboundMessage::Result(r) => vec![AgentEvent::Error(TurnError::from(r))],
425
426 _ => vec![],
427 }
428}
429
430fn tool_results(u: &InboundUserMessage) -> Vec<AgentEvent> {
433 let results = u.tool_results();
434 let structured = if results.len() == 1 { u.tool_use_result.clone() } else { None };
435 results
436 .into_iter()
437 .map(|r| AgentEvent::ToolResult {
438 tool_use_id: r.tool_use_id,
439 content: r.content,
440 is_error: r.is_error,
441 structured: structured.clone(),
442 })
443 .collect()
444}
445
446fn is_cancelled(frame: &serde_json::Value, uuid: &str) -> bool {
448 let field = |k: &str| frame.get(k).and_then(|v| v.as_str());
449 field("type") == Some("command_lifecycle")
450 && field("state") == Some("cancelled")
451 && field("command_uuid").is_some_and(|u| u.eq_ignore_ascii_case(uuid))
452}
453
454fn in_thread(parent: Option<&str>, events: Vec<AgentEvent>) -> Vec<AgentEvent> {
456 match parent {
457 None => events,
458 Some(p) => events
459 .into_iter()
460 .map(|event| AgentEvent::Subagent { parent_tool_use_id: p.to_string(), event: Box::new(event) })
461 .collect(),
462 }
463}