Skip to main content

claude_code_sdk_rust/
query.rs

1use crate::error::{ClaudeSDKError, Result};
2use crate::internal::control::{
3    initialize_request, initialize_timeout_duration, respond_to_control_request,
4    send_control_request_with_callbacks_and_timeout, ControlCallbacks,
5};
6use crate::internal::parser::parse_message_line;
7use crate::internal::session_resume::{apply_materialized_options, materialize_resume_session};
8use crate::internal::session_store_validation::validate_session_store_options;
9use crate::internal::transcript_mirror::TranscriptMirrorBatcher;
10use crate::internal::transport::{SubprocessCLITransport, Transport, TransportOptions};
11use crate::types::{ClaudeAgentOptions, Message};
12use futures::{Stream, StreamExt};
13use serde::{Deserialize, Serialize};
14
15/// Token usage information from a query response.
16#[derive(Debug, Clone, Serialize, Deserialize)]
17pub struct TokenUsage {
18    pub input_tokens: i32,
19    pub output_tokens: i32,
20    pub total_tokens: i32,
21}
22
23/// Result from a one-shot query to Claude.
24#[derive(Debug, Clone)]
25pub struct QueryResult {
26    /// The text content of the response.
27    pub content: String,
28    /// Token usage statistics, if available.
29    pub usage: Option<TokenUsage>,
30    /// The reason the response finished (e.g., "end_turn", "max_tokens").
31    pub finish_reason: String,
32}
33
34/// Perform a one-shot query to Claude Code.
35///
36/// This is a convenience function for simple, stateless interactions where you do not
37/// need bidirectional communication or conversation management. It creates a temporary
38/// client, sends a single prompt, and returns the complete response.
39///
40/// # Arguments
41///
42/// * `prompt` - The prompt to send to Claude.
43/// * `options` - Optional configuration options. If None, default options are used.
44///
45/// # Returns
46///
47/// A `QueryResult` containing the response content, usage statistics, and finish reason.
48///
49/// # Example
50///
51/// ```rust
52/// use claude_code_sdk_rust::query;
53///
54/// async fn example() -> Result<(), Box<dyn std::error::Error>> {
55///     let result = query("What is Rust?", None).await?;
56///     println!("{}", result.content);
57///     Ok(())
58/// }
59/// ```
60pub async fn query(
61    prompt: impl Into<String>,
62    options: Option<ClaudeAgentOptions>,
63) -> Result<QueryResult> {
64    let messages = query_messages(prompt, options).await?;
65    Ok(summarize_messages(messages))
66}
67
68/// Perform a one-shot query and return the full message sequence.
69///
70/// This is the Rust equivalent of the Python SDK's `query()` async iterator,
71/// adapted to return the collected messages as a `Vec<Message>`.
72pub async fn query_messages(
73    prompt: impl Into<String>,
74    options: Option<ClaudeAgentOptions>,
75) -> Result<Vec<Message>> {
76    let prompt = prompt.into();
77    let mut options = options.unwrap_or_default();
78    if options.can_use_tool.is_some() {
79        return Err(ClaudeSDKError::Other(
80            "can_use_tool callback requires streaming mode. \
81             Please use ClaudeAgentClient instead of query_messages with a string prompt."
82                .to_string(),
83        ));
84    }
85    validate_session_store_options(&options)?;
86    let materialized = materialize_resume_session(&options).await?;
87    if let Some(materialized) = &materialized {
88        options = apply_materialized_options(&options, materialized);
89    }
90    let result = run_query_messages(prompt, options).await;
91    if let Some(materialized) = &materialized {
92        materialized.cleanup().await;
93    }
94    result
95}
96
97pub async fn query_messages_with_transport(
98    prompt: impl Into<String>,
99    options: Option<ClaudeAgentOptions>,
100    transport: Box<dyn Transport>,
101) -> Result<Vec<Message>> {
102    let prompt = prompt.into();
103    let options = options.unwrap_or_default();
104    if options.can_use_tool.is_some() {
105        return Err(ClaudeSDKError::Other(
106            "can_use_tool callback requires streaming mode. \
107             Please use ClaudeAgentClient instead of query_messages with a string prompt."
108                .to_string(),
109        ));
110    }
111    validate_session_store_options(&options)?;
112    run_query_messages_with_transport(prompt, options, transport).await
113}
114
115/// Perform a one-shot query from a stream of raw prompt messages.
116///
117/// Each streamed value is written to the Claude Code transport as one JSON line.
118/// If a message is an object and does not include `session_id`, `"default"` is
119/// inserted to match the interactive client's streaming prompt behavior.
120pub async fn query_stream_messages<S>(
121    stream: S,
122    options: Option<ClaudeAgentOptions>,
123) -> Result<Vec<Message>>
124where
125    S: Stream<Item = serde_json::Value> + Unpin,
126{
127    let mut options = options.unwrap_or_default();
128    validate_session_store_options(&options)?;
129    let materialized = materialize_resume_session(&options).await?;
130    if let Some(materialized) = &materialized {
131        options = apply_materialized_options(&options, materialized);
132    }
133    let result = run_query_stream_messages(stream, options).await;
134    if let Some(materialized) = &materialized {
135        materialized.cleanup().await;
136    }
137    result
138}
139
140pub async fn query_stream_messages_with_transport<S>(
141    stream: S,
142    options: Option<ClaudeAgentOptions>,
143    transport: Box<dyn Transport>,
144) -> Result<Vec<Message>>
145where
146    S: Stream<Item = serde_json::Value> + Unpin,
147{
148    let options = options.unwrap_or_default();
149    validate_session_store_options(&options)?;
150    run_query_stream_messages_with_transport(stream, options, transport).await
151}
152
153async fn run_query_messages(prompt: String, options: ClaudeAgentOptions) -> Result<Vec<Message>> {
154    // Create transport with options
155    let transport_options = TransportOptions::from(&options);
156    let transport = SubprocessCLITransport::new(transport_options);
157    run_query_messages_with_transport(prompt, options, Box::new(transport)).await
158}
159
160async fn run_query_stream_messages<S>(
161    stream: S,
162    options: ClaudeAgentOptions,
163) -> Result<Vec<Message>>
164where
165    S: Stream<Item = serde_json::Value> + Unpin,
166{
167    let transport_options = TransportOptions::from(&options);
168    let transport = SubprocessCLITransport::new(transport_options);
169    run_query_stream_messages_with_transport(stream, options, Box::new(transport)).await
170}
171
172async fn run_query_messages_with_transport(
173    prompt: String,
174    options: ClaudeAgentOptions,
175    mut transport: Box<dyn Transport>,
176) -> Result<Vec<Message>> {
177    let control_callbacks = ControlCallbacks::from_options(&options);
178    let mut transcript_mirror = TranscriptMirrorBatcher::from_options(&options);
179
180    // Connect to the CLI
181    transport.connect().await?;
182    send_control_request_with_callbacks_and_timeout(
183        transport.as_mut(),
184        initialize_request(&control_callbacks),
185        &control_callbacks,
186        initialize_timeout_duration(),
187    )
188    .await?;
189
190    // Build and send the user message
191    let user_message = serde_json::json!({
192        "type": "user",
193        "session_id": "",
194        "message": {
195            "role": "user",
196            "content": prompt
197        },
198        "parent_tool_use_id": null
199    });
200
201    transport
202        .write(format!("{}\n", user_message).as_bytes())
203        .await?;
204
205    let messages =
206        collect_until_result(transport.as_mut(), &control_callbacks, &mut transcript_mirror)
207            .await?;
208
209    // Close the transport
210    flush_transcript_mirror(&mut transcript_mirror).await?;
211    transport.close().await?;
212
213    Ok(messages)
214}
215
216async fn run_query_stream_messages_with_transport<S>(
217    mut stream: S,
218    options: ClaudeAgentOptions,
219    mut transport: Box<dyn Transport>,
220) -> Result<Vec<Message>>
221where
222    S: Stream<Item = serde_json::Value> + Unpin,
223{
224    let control_callbacks = ControlCallbacks::from_options(&options);
225    let mut transcript_mirror = TranscriptMirrorBatcher::from_options(&options);
226
227    transport.connect().await?;
228    send_control_request_with_callbacks_and_timeout(
229        transport.as_mut(),
230        initialize_request(&control_callbacks),
231        &control_callbacks,
232        initialize_timeout_duration(),
233    )
234    .await?;
235
236    while let Some(mut message) = stream.next().await {
237        if let Some(object) = message.as_object_mut() {
238            object
239                .entry("session_id")
240                .or_insert_with(|| serde_json::Value::String("default".to_string()));
241        }
242        let mut json_payload = serde_json::to_vec(&message)?;
243        json_payload.push(b'\n');
244        transport.write(&json_payload).await?;
245    }
246    transport.close_input().await?;
247
248    let messages =
249        collect_until_result(transport.as_mut(), &control_callbacks, &mut transcript_mirror)
250            .await?;
251
252    flush_transcript_mirror(&mut transcript_mirror).await?;
253    transport.close().await?;
254
255    Ok(messages)
256}
257
258/// Read CLI stdout lines until the terminal `result` message, dispatching
259/// control requests and transcript-mirror frames along the way.
260///
261/// A single unparseable line is logged and skipped rather than aborting the
262/// whole turn: one unrecognized message shape must never discard an entire
263/// response. Shared by both the string-prompt and streamed-prompt query paths.
264async fn collect_until_result(
265    transport: &mut dyn Transport,
266    control_callbacks: &ControlCallbacks,
267    transcript_mirror: &mut Option<TranscriptMirrorBatcher>,
268) -> Result<Vec<Message>> {
269    let mut messages = Vec::new();
270    while let Some(data) = transport.read().await? {
271        let line = String::from_utf8_lossy(&data);
272        let value = serde_json::from_slice::<serde_json::Value>(&data)?;
273        if value.get("type").and_then(|v| v.as_str()) == Some("control_request") {
274            respond_to_control_request(transport, &value, control_callbacks).await?;
275            continue;
276        }
277        if value.get("type").and_then(|v| v.as_str()) == Some("transcript_mirror") {
278            if let Some(batcher) = transcript_mirror {
279                messages.extend(batcher.enqueue_value(&value).await?);
280            }
281            continue;
282        }
283        let parsed = match parse_message_line(&line) {
284            Ok(parsed) => parsed,
285            Err(err) => {
286                // Non-fatal: mirror the interactive client's resilience so a
287                // single bad line can't sink the whole query.
288                tracing::warn!("skipping unparseable CLI message: {err}");
289                continue;
290            }
291        };
292        match parsed {
293            Some(message @ Message::ResultMsg { .. }) => {
294                flush_transcript_mirror(transcript_mirror).await?;
295                messages.push(message);
296                break;
297            }
298            Some(message) => messages.push(message),
299            None => {}
300        }
301    }
302    Ok(messages)
303}
304
305fn summarize_messages(messages: Vec<Message>) -> QueryResult {
306    let mut content_parts: Vec<String> = Vec::new();
307    let mut usage: Option<TokenUsage> = None;
308    let mut finish_reason = String::from("unknown");
309
310    for message in messages {
311        match message {
312            Message::AssistantMsg { content, .. } => {
313                for block in &content.content {
314                    if let crate::types::ContentBlock::Text { text } = block {
315                        content_parts.push(text.clone());
316                    }
317                }
318            }
319            Message::ResultMsg {
320                usage: msg_usage,
321                stop_reason,
322                result,
323                ..
324            } => {
325                if let Some(result_text) = result {
326                    if content_parts.is_empty() {
327                        content_parts.push(result_text);
328                    }
329                }
330                if let Some(u) = msg_usage {
331                    usage = extract_token_usage(&u);
332                }
333                if let Some(reason) = stop_reason {
334                    finish_reason = reason;
335                }
336            }
337            _ => {}
338        }
339    }
340
341    QueryResult {
342        content: content_parts.join(""),
343        usage,
344        finish_reason,
345    }
346}
347
348async fn flush_transcript_mirror(
349    transcript_mirror: &mut Option<TranscriptMirrorBatcher>,
350) -> Result<()> {
351    if let Some(batcher) = transcript_mirror {
352        let _ = batcher.flush().await?;
353    }
354    Ok(())
355}
356
357/// Extract TokenUsage from a JSON map.
358fn extract_token_usage(
359    usage_map: &serde_json::Map<String, serde_json::Value>,
360) -> Option<TokenUsage> {
361    let input_tokens = usage_map
362        .get("input_tokens")
363        .and_then(|v| v.as_i64())
364        .map(|v| v as i32)?;
365    let output_tokens = usage_map
366        .get("output_tokens")
367        .and_then(|v| v.as_i64())
368        .map(|v| v as i32)?;
369    let total_tokens = usage_map
370        .get("total_tokens")
371        .and_then(|v| v.as_i64())
372        .map(|v| v as i32)?;
373
374    Some(TokenUsage {
375        input_tokens,
376        output_tokens,
377        total_tokens,
378    })
379}