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#[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#[derive(Debug, Clone)]
25pub struct QueryResult {
26 pub content: String,
28 pub usage: Option<TokenUsage>,
30 pub finish_reason: String,
32}
33
34pub 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
68pub 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
115pub 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 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 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 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 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
258async 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 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
357fn 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}