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)]
20#[non_exhaustive]
21pub enum AgentEvent {
22 Text(String),
24 Thinking(String),
26 RedactedThinking(String),
28 ToolUse {
31 id: String,
33 name: String,
35 input: serde_json::Value,
37 server: bool,
39 },
40 ToolResult {
44 tool_use_id: String,
46 content: serde_json::Value,
48 is_error: bool,
50 structured: Option<serde_json::Value>,
52 },
53 Subagent {
56 parent_tool_use_id: String,
58 event: Box<AgentEvent>,
60 },
61 BackgroundTasks(Vec<BackgroundTask>),
63 ModelFallback {
65 from: String,
67 to: String,
69 trigger: String,
71 },
72 Compacted {
74 trigger: String,
76 pre_tokens: Option<u64>,
78 post_tokens: Option<u64>,
80 },
81 System {
84 subtype: String,
86 data: serde_json::Value,
88 },
89 Other {
92 kind: String,
94 data: serde_json::Value,
96 },
97 Done(TurnResult),
99 Error(TurnError),
101}
102
103#[derive(Debug, Clone, PartialEq)]
105#[non_exhaustive]
106pub struct TurnResult {
107 pub session_id: Option<String>,
109 pub result: Option<String>,
111 pub structured_output: Option<serde_json::Value>,
113 pub total_cost_usd: Option<f64>,
115 pub ttft_ms: Option<u64>,
117 pub duration_ms: Option<u64>,
119 pub duration_api_ms: Option<u64>,
121 pub num_turns: Option<u64>,
123 pub input_tokens: Option<u64>,
125 pub output_tokens: Option<u64>,
127 pub cache_read_input_tokens: Option<u64>,
129 pub cache_creation_input_tokens: Option<u64>,
131 pub model_usage: Option<serde_json::Value>,
133 pub stop_reason: Option<String>,
135 pub terminal_reason: Option<String>,
137 pub permission_denials: Vec<serde_json::Value>,
139 pub origin: Option<serde_json::Value>,
142}
143
144impl From<&ResultMessage> for TurnResult {
145 fn from(r: &ResultMessage) -> Self {
146 let usage = r.usage.as_ref();
147 TurnResult {
148 session_id: r.session_id.clone(),
149 result: r.result.clone(),
150 structured_output: r.structured_output.clone(),
151 total_cost_usd: r.total_cost_usd,
152 ttft_ms: r.ttft_ms,
153 duration_ms: r.duration_ms,
154 duration_api_ms: r.duration_api_ms,
155 num_turns: r.num_turns,
156 input_tokens: usage.map(|u| u.input_tokens),
157 output_tokens: usage.map(|u| u.output_tokens),
158 cache_read_input_tokens: usage.and_then(|u| u.cache_read_input_tokens),
159 cache_creation_input_tokens: usage.and_then(|u| u.cache_creation_input_tokens),
160 model_usage: r.model_usage.clone(),
161 stop_reason: r.stop_reason.clone(),
162 terminal_reason: r.terminal_reason.clone(),
163 permission_denials: r.permission_denials.clone(),
164 origin: r.origin.clone(),
165 }
166 }
167}
168
169#[derive(Debug, Clone, PartialEq, thiserror::Error)]
171#[error("{message}")]
172#[non_exhaustive]
173pub struct TurnError {
174 pub kind: TurnErrorKind,
176 pub message: String,
178 pub result: Option<TurnResult>,
181}
182
183impl From<&ResultMessage> for TurnError {
184 fn from(r: &ResultMessage) -> Self {
185 TurnError { kind: r.error_kind(), message: r.error_message(), result: Some(TurnResult::from(r)) }
186 }
187}
188
189impl TurnError {
190 fn cancelled() -> Self {
191 TurnError { kind: TurnErrorKind::Cancelled, message: "prompt cancelled before it ran".into(), result: None }
192 }
193
194 fn session_closed() -> Self {
195 TurnError {
196 kind: TurnErrorKind::SessionClosed,
197 message: "session closed before the turn finished".into(),
198 result: None,
199 }
200 }
201}
202
203#[derive(Debug, thiserror::Error)]
205#[non_exhaustive]
206pub enum AgentError {
207 #[error("session error: {0}")]
209 Session(#[from] SessionError),
210 #[error("the CLI does not offer /{0}")]
213 CommandUnavailable(String),
214}
215
216pub type AgentStream = Pin<Box<dyn tokio_stream::Stream<Item = AgentEvent> + Send + 'static>>;
219
220pub struct Agent {
224 session: Session,
225}
226
227impl Agent {
228 #[must_use]
230 pub fn new(session: Session) -> Self {
231 Self { session }
232 }
233
234 #[must_use]
236 pub fn session(&self) -> &Session {
237 &self.session
238 }
239
240 pub async fn prompt(&self, text: impl Into<String>) -> Result<AgentStream, AgentError> {
244 self.prompt_message(UserMessage::text(text.into())).await
245 }
246
247 pub async fn prompt_message(&self, message: UserMessage) -> Result<AgentStream, AgentError> {
253 let mut rx = self.session.subscribe();
255 let uuid = message.uuid.clone();
256 self.session.send_prompt(&message).await?;
257 let partial = self.session.include_partial();
260 let span = tracing::info_span!(
262 "claude.turn",
263 session_id = self.session.session_id().unwrap_or_default(),
264 cost_usd = tracing::field::Empty,
265 input_tokens = tracing::field::Empty,
266 output_tokens = tracing::field::Empty,
267 ttft_ms = tracing::field::Empty,
268 error = tracing::field::Empty,
269 );
270
271 let mut guard = CancelOnDrop { session: self.session.clone(), uuid: uuid.clone(), armed: true };
275 let stream = async_stream::stream! {
276 let mut started = false;
284 let mut held: Vec<Arc<InboundMessage>> = vec![];
285 loop {
286 let Some(msg) = rx.recv().await else {
287 guard.disarm();
288 yield AgentEvent::Error(TurnError::session_closed());
289 break;
290 };
291 if let InboundMessage::Other(frame) = msg.as_ref()
294 && is_cancelled(frame, &uuid)
295 {
296 guard.disarm();
297 yield AgentEvent::Error(TurnError::cancelled());
298 break;
299 }
300
301 if !started {
302 match msg.as_ref() {
303 InboundMessage::User(u) if u.uuid.as_deref().is_some_and(|u| u.eq_ignore_ascii_case(&uuid)) => {
304 started = true;
305 for m in held.drain(..) {
306 for ev in to_events(&m, partial) {
307 yield ev;
308 }
309 }
310 }
311 InboundMessage::Result(r) if r.answers(&uuid) => {
314 started = true;
315 for m in held.drain(..) {
316 for ev in to_events(&m, partial) {
317 yield ev;
318 }
319 }
320 }
321 InboundMessage::Result(_) => {
322 held.clear();
323 continue;
324 }
325 _ => {
326 held.push(msg);
327 continue;
328 }
329 }
330 if !matches!(msg.as_ref(), InboundMessage::Result(_)) {
331 continue;
332 }
333 }
334
335 if let InboundMessage::Result(r) = msg.as_ref() {
336 guard.disarm();
337 let t = TurnResult::from(r);
338 if let Some(v) = t.total_cost_usd { span.record("cost_usd", v); }
339 if let Some(v) = t.input_tokens { span.record("input_tokens", v); }
340 if let Some(v) = t.output_tokens { span.record("output_tokens", v); }
341 if let Some(v) = t.ttft_ms { span.record("ttft_ms", v); }
342 if !r.is_success() { span.record("error", r.subtype.as_str()); }
343 }
344 let done = matches!(msg.as_ref(), InboundMessage::Result(_));
345 for ev in to_events(&msg, partial) {
346 yield ev;
347 }
348 if done {
349 break;
350 }
351 }
352 };
353
354 Ok(Box::pin(stream))
355 }
356
357 pub fn watch(&self) -> AgentStream {
363 let mut rx = self.session.subscribe();
364 let partial = self.session.include_partial();
365 Box::pin(async_stream::stream! {
366 while let Some(msg) = rx.recv().await {
367 for ev in to_events(&msg, partial) {
368 yield ev;
369 }
370 }
371 })
372 }
373}
374
375struct CancelOnDrop {
377 session: Session,
378 uuid: String,
379 armed: bool,
380}
381
382impl CancelOnDrop {
383 fn disarm(&mut self) {
384 self.armed = false;
385 }
386}
387
388impl Drop for CancelOnDrop {
389 fn drop(&mut self) {
390 if !self.armed || !self.session.is_alive() {
391 return;
392 }
393 let Ok(rt) = tokio::runtime::Handle::try_current() else {
394 tracing::warn!("turn stream dropped outside a Tokio runtime; the turn keeps running");
395 return;
396 };
397 let session = self.session.clone();
398 let uuid = std::mem::take(&mut self.uuid);
399 rt.spawn(async move {
400 if let Err(e) = session.cancel_prompt(&uuid).await {
401 tracing::debug!(error = %e, "cancelling a dropped turn failed");
402 }
403 });
404 }
405}
406
407fn to_events(msg: &InboundMessage, partial: bool) -> Vec<AgentEvent> {
412 match msg {
413 InboundMessage::Assistant(a) => {
414 let sub = a.parent_tool_use_id.is_some();
415 let events = a.message.content.iter().filter_map(|block| match block {
416 AssistantBlock::Text { text } if sub || !partial => Some(AgentEvent::Text(text.clone())),
417 AssistantBlock::Thinking { thinking } if sub || !partial => {
418 Some(AgentEvent::Thinking(thinking.clone()))
419 }
420 AssistantBlock::RedactedThinking { data } => Some(AgentEvent::RedactedThinking(data.clone())),
421 AssistantBlock::ToolUse { id, name, input } => Some(AgentEvent::ToolUse {
422 id: id.clone(),
423 name: name.clone(),
424 input: input.clone(),
425 server: false,
426 }),
427 AssistantBlock::ServerToolUse { id, name, input } => Some(AgentEvent::ToolUse {
428 id: id.clone(),
429 name: name.clone(),
430 input: input.clone(),
431 server: true,
432 }),
433 AssistantBlock::WebSearchToolResult { tool_use_id, content } => Some(AgentEvent::ToolResult {
434 tool_use_id: tool_use_id.clone(),
435 content: content.clone(),
436 is_error: false,
437 structured: None,
438 }),
439 _ => None,
440 });
441 in_thread(a.parent_tool_use_id.as_deref(), events.collect())
442 }
443
444 InboundMessage::User(u) => in_thread(u.parent_tool_use_id.as_deref(), tool_results(u)),
445
446 InboundMessage::StreamEvent(se) if se.parent_tool_use_id.is_none() => {
447 let delta = se.event.get("delta");
448 let text = delta.and_then(|d| d.get("text")).and_then(|t| t.as_str());
449 let thinking = delta.and_then(|d| d.get("thinking")).and_then(|t| t.as_str());
450 text.map(|t| AgentEvent::Text(t.to_string()))
451 .into_iter()
452 .chain(thinking.map(|t| AgentEvent::Thinking(t.to_string())))
453 .collect()
454 }
455
456 InboundMessage::System(s) => match s.subtype.as_str() {
457 "background_tasks_changed" => {
458 let tasks = s.extra.get("tasks").cloned().unwrap_or_default();
459 match serde_json::from_value::<Vec<BackgroundTask>>(tasks) {
460 Ok(tasks) => vec![AgentEvent::BackgroundTasks(tasks)],
461 Err(e) => {
462 tracing::debug!(error = %e, "undecodable background_tasks_changed");
463 vec![]
464 }
465 }
466 }
467 "model_fallback" => {
468 let field = |k: &str| s.extra.get(k).and_then(|v| v.as_str()).unwrap_or("").to_string();
469 vec![AgentEvent::ModelFallback {
470 from: field("original_model"),
471 to: field("fallback_model"),
472 trigger: field("trigger"),
473 }]
474 }
475 "compact_boundary" => {
476 let meta = s.extra.get("compact_metadata");
477 let num = |k: &str| meta.and_then(|m| m.get(k)).and_then(serde_json::Value::as_u64);
478 vec![AgentEvent::Compacted {
479 trigger: meta.and_then(|m| m.get("trigger")).and_then(|v| v.as_str()).unwrap_or("").to_string(),
480 pre_tokens: num("pre_tokens"),
481 post_tokens: num("post_tokens"),
482 }]
483 }
484 other => vec![AgentEvent::System {
485 subtype: other.to_string(),
486 data: serde_json::to_value(s).unwrap_or_else(|e| {
487 tracing::warn!(error = %e, "could not serialize a system frame");
488 serde_json::Value::Null
489 }),
490 }],
491 },
492
493 InboundMessage::Other(data) => vec![AgentEvent::Other {
494 kind: data.get("type").and_then(|t| t.as_str()).unwrap_or("").to_string(),
495 data: data.clone(),
496 }],
497
498 InboundMessage::Result(r) if r.is_success() => vec![AgentEvent::Done(TurnResult::from(r))],
499 InboundMessage::Result(r) => vec![AgentEvent::Error(TurnError::from(r))],
500
501 _ => vec![],
502 }
503}
504
505fn tool_results(u: &InboundUserMessage) -> Vec<AgentEvent> {
508 let results = u.tool_results();
509 let structured = if results.len() == 1 { u.tool_use_result.clone() } else { None };
510 results
511 .into_iter()
512 .map(|r| AgentEvent::ToolResult {
513 tool_use_id: r.tool_use_id,
514 content: r.content,
515 is_error: r.is_error,
516 structured: structured.clone(),
517 })
518 .collect()
519}
520
521fn is_cancelled(frame: &serde_json::Value, uuid: &str) -> bool {
523 crate::session::cancelled_prompt(frame).is_some_and(|u| u.eq_ignore_ascii_case(uuid))
524}
525
526fn in_thread(parent: Option<&str>, events: Vec<AgentEvent>) -> Vec<AgentEvent> {
528 match parent {
529 None => events,
530 Some(p) => events
531 .into_iter()
532 .map(|event| AgentEvent::Subagent { parent_tool_use_id: p.to_string(), event: Box::new(event) })
533 .collect(),
534 }
535}