Skip to main content

claude_code_agent/
agent.rs

1//! Agent layer — sends a turn and returns a streaming event iterator.
2//!
3//! Control requests (hook callbacks, can_use_tool) are answered by the
4//! `Session` itself; this layer only turns frames into `AgentEvent`s.
5//! `prompt` yields the events of one turn; `watch` yields every turn's,
6//! including the turns the CLI starts on its own.
7use 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// ─── Event stream ─────────────────────────────────────────────────────────────
17
18#[derive(Debug, Clone)]
19pub enum AgentEvent {
20    /// A text delta (requires --include-partial-messages OR full assistant message).
21    Text(String),
22    /// A complete thinking block.
23    Thinking(String),
24    /// Encrypted thinking, opaque to the host.
25    RedactedThinking(String),
26    /// A tool call: one the CLI runs, or one the API runs itself
27    /// (`server: true`, e.g. web search).
28    ToolUse { id: String, name: String, input: serde_json::Value, server: bool },
29    /// The result of a tool call. `content` is a string or content blocks,
30    /// as sent to the model; `structured` is the tool's full output when
31    /// the CLI reports one (e.g. Bash `{stdout, stderr, interrupted, …}`).
32    ToolResult {
33        tool_use_id: String,
34        content: serde_json::Value,
35        is_error: bool,
36        structured: Option<serde_json::Value>,
37    },
38    /// An event of a subagent, started by the `Agent`/`Task` tool call
39    /// `parent_tool_use_id`.
40    Subagent { parent_tool_use_id: String, event: Box<AgentEvent> },
41    /// Background task tree updated (replace semantics).
42    BackgroundTasks(Vec<BackgroundTask>),
43    /// Model was switched during the turn.
44    ModelFallback { from: String, to: String, trigger: String },
45    /// Context was compacted (`trigger`: "manual" for /compact, "auto").
46    Compacted { trigger: String, pre_tokens: Option<u64>, post_tokens: Option<u64> },
47    /// Any other `system` frame (`init`, `api_retry`, `task_started`,
48    /// `hook_response`, `permission_denied`, `status`, …), verbatim.
49    System { subtype: String, data: serde_json::Value },
50    /// Any other frame (`rate_limit_event`, `tool_progress`,
51    /// `prompt_suggestion`, `command_lifecycle`, …), verbatim.
52    Other { kind: String, data: serde_json::Value },
53    /// Turn completed successfully.
54    Done(TurnResult),
55    /// Turn failed.
56    Error(TurnError),
57}
58
59#[derive(Debug, Clone)]
60pub struct TurnResult {
61    pub session_id: Option<String>,
62    /// Final text of the turn.
63    pub result: Option<String>,
64    /// Output matching `Initialize::json_schema`.
65    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    /// Agentic turns (model calls) the turn took.
71    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    /// Per-model token and cost breakdown.
77    pub model_usage: Option<serde_json::Value>,
78    pub stop_reason: Option<String>,
79    pub terminal_reason: Option<String>,
80    /// Tool calls the permission system denied.
81    pub permission_denials: Vec<serde_json::Value>,
82    /// Set when the CLI started the turn itself (e.g. after a background
83    /// task finished); `None` for prompted turns.
84    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/// Why a turn failed. `result` carries cost and usage up to the failure.
113#[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
149/// Events of one turn; ends after `Done` or `Error`. Dropping it before
150/// then cancels the turn (see `Agent::prompt_message`).
151pub type AgentStream = Pin<Box<dyn tokio_stream::Stream<Item = AgentEvent> + Send + 'static>>;
152
153// ─── Agent ────────────────────────────────────────────────────────────────────
154
155/// Runs turns on a Session.
156pub 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    /// Run a text prompt and return a streaming iterator of AgentEvents.
170    ///
171    /// The stream ends after a `Done` or `Error` event.
172    pub async fn prompt(&self, text: impl Into<String>) -> Result<AgentStream, AgentError> {
173        self.prompt_message(UserMessage::text(text.into())).await
174    }
175
176    /// Run a prompt built from content blocks (text, images, …).
177    ///
178    /// Dropping the stream before its `Done`/`Error` cancels the prompt:
179    /// still queued, it is withdrawn; running, its turn is interrupted.
180    /// Drain the stream to let the turn finish.
181    pub async fn prompt_message(&self, message: UserMessage) -> Result<AgentStream, AgentError> {
182        // Subscribe before sending so no frame of this turn is missed.
183        let mut rx = self.session.subscribe();
184        let uuid = message.uuid.clone();
185        self.session.send_prompt(&message).await?;
186        // With partial messages on, text already streamed as deltas; the
187        // complete assistant message would repeat it.
188        let partial = self.session.include_partial();
189        // Lives as long as the stream: its duration is the turn's duration.
190        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        // Created outside the generator: a stream dropped before its first
201        // poll still cancels. It also keeps the session alive until the turn
202        // ends, even when the Agent and every other handle are dropped first.
203        let mut guard = CancelOnDrop { session: self.session.clone(), uuid: uuid.clone(), armed: true };
204        let stream = async_stream::stream! {
205            // Turns run one after another and each ends with a `result`. Our
206            // prompt's echo falls inside our turn: first for a normal prompt,
207            // last for a slash command (after e.g. compact_boundary). So frames
208            // since the previous `result` are held until the echo shows whose
209            // turn they are. A `result` before our echo closes someone else's
210            // turn (a queued prompt, or one the CLI started itself) unless it
211            // names our prompt (a prompt refused up front is never echoed).
212            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                // Withdrawn before it ran (`cancel_prompt`, `interrupt_all`):
221                // no `result` will come.
222                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                        // Refused before it started: no echo, but the
241                        // result names our prompt. The held frames are ours.
242                        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    /// Every event of every turn from now on — prompted turns and the turns
287    /// the CLI starts itself (`TurnResult::origin` set), each ending with
288    /// `Done` or `Error`. Ends when the session closes. Dropping it cancels
289    /// nothing.
290    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
303/// Cancels the prompt `uuid` unless disarmed (its turn ended).
304struct 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
335/// The AgentEvents one frame produces. `partial`: text arrives as stream
336/// deltas, so complete main-thread text is skipped. Frames of subagents
337/// (`parent_tool_use_id` set) are wrapped in `AgentEvent::Subagent`; their
338/// text comes from complete messages only.
339fn 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
430/// The `ToolResult` events of a `user` frame. The frame's
431/// `tool_use_result` is the structured output of its (single) tool result.
432fn 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
446/// Whether `frame` is the CLI's `command_lifecycle` "cancelled" for prompt `uuid`.
447fn 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
454/// Wrap `events` as subagent events when `parent` is set.
455fn 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}