initial commit scaffold

rust/crates/api/tests/client_integration.rs

@@ -0,0 +1,484 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::Duration;
+
+use api::{
+    ApiClient, ApiError, AuthSource, ContentBlockDelta, ContentBlockDeltaEvent,
+    ContentBlockStartEvent, InputContentBlock, InputMessage, MessageDeltaEvent, MessageRequest,
+    OutputContentBlock, ProviderClient, StreamEvent, ToolChoice, ToolDefinition,
+};
+use serde_json::json;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::TcpListener;
+use tokio::sync::Mutex;
+
+#[tokio::test]
+async fn send_message_posts_json_and_parses_response() {
+    let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
+    let body = concat!(
+        "{",
+        "\"id\":\"msg_test\",",
+        "\"type\":\"message\",",
+        "\"role\":\"assistant\",",
+        "\"content\":[{\"type\":\"text\",\"text\":\"Hello from Claw\"}],",
+        "\"model\":\"claude-sonnet-4-6\",",
+        "\"stop_reason\":\"end_turn\",",
+        "\"stop_sequence\":null,",
+        "\"usage\":{\"input_tokens\":12,\"output_tokens\":4},",
+        "\"request_id\":\"req_body_123\"",
+        "}"
+    );
+    let server = spawn_server(
+        state.clone(),
+        vec![http_response("200 OK", "application/json", body)],
+    )
+    .await;
+
+    let client = ApiClient::new("test-key")
+        .with_auth_token(Some("proxy-token".to_string()))
+        .with_base_url(server.base_url());
+    let response = client
+        .send_message(&sample_request(false))
+        .await
+        .expect("request should succeed");
+
+    assert_eq!(response.id, "msg_test");
+    assert_eq!(response.total_tokens(), 16);
+    assert_eq!(response.request_id.as_deref(), Some("req_body_123"));
+    assert_eq!(
+        response.content,
+        vec![OutputContentBlock::Text {
+            text: "Hello from Claw".to_string(),
+        }]
+    );
+
+    let captured = state.lock().await;
+    let request = captured.first().expect("server should capture request");
+    assert_eq!(request.method, "POST");
+    assert_eq!(request.path, "/v1/messages");
+    assert_eq!(
+        request.headers.get("x-api-key").map(String::as_str),
+        Some("test-key")
+    );
+    assert_eq!(
+        request.headers.get("authorization").map(String::as_str),
+        Some("Bearer proxy-token")
+    );
+    let body: serde_json::Value =
+        serde_json::from_str(&request.body).expect("request body should be json");
+    assert_eq!(
+        body.get("model").and_then(serde_json::Value::as_str),
+        Some("claude-sonnet-4-6")
+    );
+    assert!(body.get("stream").is_none());
+    assert_eq!(body["tools"][0]["name"], json!("get_weather"));
+    assert_eq!(body["tool_choice"]["type"], json!("auto"));
+}
+
+#[tokio::test]
+async fn stream_message_parses_sse_events_with_tool_use() {
+    let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
+    let sse = concat!(
+        "event: message_start\n",
+        "data: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_stream\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"model\":\"claude-sonnet-4-6\",\"stop_reason\":null,\"stop_sequence\":null,\"usage\":{\"input_tokens\":8,\"output_tokens\":0}}}\n\n",
+        "event: content_block_start\n",
+        "data: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"tool_use\",\"id\":\"toolu_123\",\"name\":\"get_weather\",\"input\":{}}}\n\n",
+        "event: content_block_delta\n",
+        "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"{\\\"city\\\":\\\"Paris\\\"}\"}}\n\n",
+        "event: content_block_stop\n",
+        "data: {\"type\":\"content_block_stop\",\"index\":0}\n\n",
+        "event: message_delta\n",
+        "data: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"tool_use\",\"stop_sequence\":null},\"usage\":{\"input_tokens\":8,\"output_tokens\":1}}\n\n",
+        "event: message_stop\n",
+        "data: {\"type\":\"message_stop\"}\n\n",
+        "data: [DONE]\n\n"
+    );
+    let server = spawn_server(
+        state.clone(),
+        vec![http_response_with_headers(
+            "200 OK",
+            "text/event-stream",
+            sse,
+            &[("request-id", "req_stream_456")],
+        )],
+    )
+    .await;
+
+    let client = ApiClient::new("test-key")
+        .with_auth_token(Some("proxy-token".to_string()))
+        .with_base_url(server.base_url());
+    let mut stream = client
+        .stream_message(&sample_request(false))
+        .await
+        .expect("stream should start");
+
+    assert_eq!(stream.request_id(), Some("req_stream_456"));
+
+    let mut events = Vec::new();
+    while let Some(event) = stream
+        .next_event()
+        .await
+        .expect("stream event should parse")
+    {
+        events.push(event);
+    }
+
+    assert_eq!(events.len(), 6);
+    assert!(matches!(events[0], StreamEvent::MessageStart(_)));
+    assert!(matches!(
+        events[1],
+        StreamEvent::ContentBlockStart(ContentBlockStartEvent {
+            content_block: OutputContentBlock::ToolUse { .. },
+            ..
+        })
+    ));
+    assert!(matches!(
+        events[2],
+        StreamEvent::ContentBlockDelta(ContentBlockDeltaEvent {
+            delta: ContentBlockDelta::InputJsonDelta { .. },
+            ..
+        })
+    ));
+    assert!(matches!(events[3], StreamEvent::ContentBlockStop(_)));
+    assert!(matches!(
+        events[4],
+        StreamEvent::MessageDelta(MessageDeltaEvent { .. })
+    ));
+    assert!(matches!(events[5], StreamEvent::MessageStop(_)));
+
+    match &events[1] {
+        StreamEvent::ContentBlockStart(ContentBlockStartEvent {
+            content_block: OutputContentBlock::ToolUse { name, input, .. },
+            ..
+        }) => {
+            assert_eq!(name, "get_weather");
+            assert_eq!(input, &json!({}));
+        }
+        other => panic!("expected tool_use block, got {other:?}"),
+    }
+
+    let captured = state.lock().await;
+    let request = captured.first().expect("server should capture request");
+    assert!(request.body.contains("\"stream\":true"));
+}
+
+#[tokio::test]
+async fn retries_retryable_failures_before_succeeding() {
+    let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
+    let server = spawn_server(
+        state.clone(),
+        vec![
+            http_response(
+                "429 Too Many Requests",
+                "application/json",
+                "{\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\",\"message\":\"slow down\"}}",
+            ),
+            http_response(
+                "200 OK",
+                "application/json",
+                "{\"id\":\"msg_retry\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"Recovered\"}],\"model\":\"claude-sonnet-4-6\",\"stop_reason\":\"end_turn\",\"stop_sequence\":null,\"usage\":{\"input_tokens\":3,\"output_tokens\":2}}",
+            ),
+        ],
+    )
+    .await;
+
+    let client = ApiClient::new("test-key")
+        .with_base_url(server.base_url())
+        .with_retry_policy(2, Duration::from_millis(1), Duration::from_millis(2));
+
+    let response = client
+        .send_message(&sample_request(false))
+        .await
+        .expect("retry should eventually succeed");
+
+    assert_eq!(response.total_tokens(), 5);
+    assert_eq!(state.lock().await.len(), 2);
+}
+
+#[tokio::test]
+async fn provider_client_dispatches_api_requests() {
+    let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
+    let server = spawn_server(
+        state.clone(),
+        vec![http_response(
+            "200 OK",
+            "application/json",
+            "{\"id\":\"msg_provider\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"Dispatched\"}],\"model\":\"claude-sonnet-4-6\",\"stop_reason\":\"end_turn\",\"stop_sequence\":null,\"usage\":{\"input_tokens\":3,\"output_tokens\":2}}",
+        )],
+    )
+    .await;
+
+    let client = ProviderClient::from_model_with_default_auth(
+        "claude-sonnet-4-6",
+        Some(AuthSource::ApiKey("test-key".to_string())),
+    )
+    .expect("api provider client should be constructed");
+    let client = match client {
+        ProviderClient::ClawApi(client) => {
+            ProviderClient::ClawApi(client.with_base_url(server.base_url()))
+        }
+        other => panic!("expected default provider, got {other:?}"),
+    };
+
+    let response = client
+        .send_message(&sample_request(false))
+        .await
+        .expect("provider-dispatched request should succeed");
+
+    assert_eq!(response.total_tokens(), 5);
+
+    let captured = state.lock().await;
+    let request = captured.first().expect("server should capture request");
+    assert_eq!(request.path, "/v1/messages");
+    assert_eq!(
+        request.headers.get("x-api-key").map(String::as_str),
+        Some("test-key")
+    );
+}
+
+#[tokio::test]
+async fn surfaces_retry_exhaustion_for_persistent_retryable_errors() {
+    let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
+    let server = spawn_server(
+        state.clone(),
+        vec![
+            http_response(
+                "503 Service Unavailable",
+                "application/json",
+                "{\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",\"message\":\"busy\"}}",
+            ),
+            http_response(
+                "503 Service Unavailable",
+                "application/json",
+                "{\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",\"message\":\"still busy\"}}",
+            ),
+        ],
+    )
+    .await;
+
+    let client = ApiClient::new("test-key")
+        .with_base_url(server.base_url())
+        .with_retry_policy(1, Duration::from_millis(1), Duration::from_millis(2));
+
+    let error = client
+        .send_message(&sample_request(false))
+        .await
+        .expect_err("persistent 503 should fail");
+
+    match error {
+        ApiError::RetriesExhausted {
+            attempts,
+            last_error,
+        } => {
+            assert_eq!(attempts, 2);
+            assert!(matches!(
+                *last_error,
+                ApiError::Api {
+                    status: reqwest::StatusCode::SERVICE_UNAVAILABLE,
+                    retryable: true,
+                    ..
+                }
+            ));
+        }
+        other => panic!("expected retries exhausted, got {other:?}"),
+    }
+}
+
+#[tokio::test]
+#[ignore = "requires ANTHROPIC_API_KEY and network access"]
+async fn live_stream_smoke_test() {
+    let client = ApiClient::from_env().expect("ANTHROPIC_API_KEY must be set");
+    let mut stream = client
+        .stream_message(&MessageRequest {
+            model: std::env::var("CLAW_MODEL")
+                .unwrap_or_else(|_| "claude-sonnet-4-6".to_string()),
+            max_tokens: 32,
+            messages: vec![InputMessage::user_text(
+                "Reply with exactly: hello from rust",
+            )],
+            system: None,
+            tools: None,
+            tool_choice: None,
+            stream: false,
+        })
+        .await
+        .expect("live stream should start");
+
+    while let Some(_event) = stream
+        .next_event()
+        .await
+        .expect("live stream should yield events")
+    {}
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct CapturedRequest {
+    method: String,
+    path: String,
+    headers: HashMap<String, String>,
+    body: String,
+}
+
+struct TestServer {
+    base_url: String,
+    join_handle: tokio::task::JoinHandle<()>,
+}
+
+impl TestServer {
+    fn base_url(&self) -> String {
+        self.base_url.clone()
+    }
+}
+
+impl Drop for TestServer {
+    fn drop(&mut self) {
+        self.join_handle.abort();
+    }
+}
+
+async fn spawn_server(
+    state: Arc<Mutex<Vec<CapturedRequest>>>,
+    responses: Vec<String>,
+) -> TestServer {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let address = listener
+        .local_addr()
+        .expect("listener should have local addr");
+    let join_handle = tokio::spawn(async move {
+        for response in responses {
+            let (mut socket, _) = listener.accept().await.expect("server should accept");
+            let mut buffer = Vec::new();
+            let mut header_end = None;
+
+            loop {
+                let mut chunk = [0_u8; 1024];
+                let read = socket
+                    .read(&mut chunk)
+                    .await
+                    .expect("request read should succeed");
+                if read == 0 {
+                    break;
+                }
+                buffer.extend_from_slice(&chunk[..read]);
+                if let Some(position) = find_header_end(&buffer) {
+                    header_end = Some(position);
+                    break;
+                }
+            }
+
+            let header_end = header_end.expect("request should include headers");
+            let (header_bytes, remaining) = buffer.split_at(header_end);
+            let header_text =
+                String::from_utf8(header_bytes.to_vec()).expect("headers should be utf8");
+            let mut lines = header_text.split("\r\n");
+            let request_line = lines.next().expect("request line should exist");
+            let mut parts = request_line.split_whitespace();
+            let method = parts.next().expect("method should exist").to_string();
+            let path = parts.next().expect("path should exist").to_string();
+            let mut headers = HashMap::new();
+            let mut content_length = 0_usize;
+            for line in lines {
+                if line.is_empty() {
+                    continue;
+                }
+                let (name, value) = line.split_once(':').expect("header should have colon");
+                let value = value.trim().to_string();
+                if name.eq_ignore_ascii_case("content-length") {
+                    content_length = value.parse().expect("content length should parse");
+                }
+                headers.insert(name.to_ascii_lowercase(), value);
+            }
+
+            let mut body = remaining[4..].to_vec();
+            while body.len() < content_length {
+                let mut chunk = vec![0_u8; content_length - body.len()];
+                let read = socket
+                    .read(&mut chunk)
+                    .await
+                    .expect("body read should succeed");
+                if read == 0 {
+                    break;
+                }
+                body.extend_from_slice(&chunk[..read]);
+            }
+
+            state.lock().await.push(CapturedRequest {
+                method,
+                path,
+                headers,
+                body: String::from_utf8(body).expect("body should be utf8"),
+            });
+
+            socket
+                .write_all(response.as_bytes())
+                .await
+                .expect("response write should succeed");
+        }
+    });
+
+    TestServer {
+        base_url: format!("http://{address}"),
+        join_handle,
+    }
+}
+
+fn find_header_end(bytes: &[u8]) -> Option<usize> {
+    bytes.windows(4).position(|window| window == b"\r\n\r\n")
+}
+
+fn http_response(status: &str, content_type: &str, body: &str) -> String {
+    http_response_with_headers(status, content_type, body, &[])
+}
+
+fn http_response_with_headers(
+    status: &str,
+    content_type: &str,
+    body: &str,
+    headers: &[(&str, &str)],
+) -> String {
+    let mut extra_headers = String::new();
+    for (name, value) in headers {
+        use std::fmt::Write as _;
+        write!(&mut extra_headers, "{name}: {value}\r\n").expect("header write should succeed");
+    }
+    format!(
+        "HTTP/1.1 {status}\r\ncontent-type: {content_type}\r\n{extra_headers}content-length: {}\r\nconnection: close\r\n\r\n{body}",
+        body.len()
+    )
+}
+
+fn sample_request(stream: bool) -> MessageRequest {
+    MessageRequest {
+        model: "claude-sonnet-4-6".to_string(),
+        max_tokens: 64,
+        messages: vec![InputMessage {
+            role: "user".to_string(),
+            content: vec![
+                InputContentBlock::Text {
+                    text: "Say hello".to_string(),
+                },
+                InputContentBlock::ToolResult {
+                    tool_use_id: "toolu_prev".to_string(),
+                    content: vec![api::ToolResultContentBlock::Json {
+                        value: json!({"forecast": "sunny"}),
+                    }],
+                    is_error: false,
+                },
+            ],
+        }],
+        system: Some("Use tools when needed".to_string()),
+        tools: Some(vec![ToolDefinition {
+            name: "get_weather".to_string(),
+            description: Some("Fetches the weather".to_string()),
+            input_schema: json!({
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"]
+            }),
+        }]),
+        tool_choice: Some(ToolChoice::Auto),
+        stream,
+    }
+}

rust/crates/api/tests/openai_compat_integration.rs

@@ -0,0 +1,415 @@
+use std::collections::HashMap;
+use std::ffi::OsString;
+use std::sync::Arc;
+use std::sync::{Mutex as StdMutex, OnceLock};
+
+use api::{
+    ContentBlockDelta, ContentBlockDeltaEvent, ContentBlockStartEvent, ContentBlockStopEvent,
+    InputContentBlock, InputMessage, MessageRequest, OpenAiCompatClient, OpenAiCompatConfig,
+    OutputContentBlock, ProviderClient, StreamEvent, ToolChoice, ToolDefinition,
+};
+use serde_json::json;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::TcpListener;
+use tokio::sync::Mutex;
+
+#[tokio::test]
+async fn send_message_uses_openai_compatible_endpoint_and_auth() {
+    let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
+    let body = concat!(
+        "{",
+        "\"id\":\"chatcmpl_test\",",
+        "\"model\":\"grok-3\",",
+        "\"choices\":[{",
+        "\"message\":{\"role\":\"assistant\",\"content\":\"Hello from Grok\",\"tool_calls\":[]},",
+        "\"finish_reason\":\"stop\"",
+        "}],",
+        "\"usage\":{\"prompt_tokens\":11,\"completion_tokens\":5}",
+        "}"
+    );
+    let server = spawn_server(
+        state.clone(),
+        vec![http_response("200 OK", "application/json", body)],
+    )
+    .await;
+
+    let client = OpenAiCompatClient::new("xai-test-key", OpenAiCompatConfig::xai())
+        .with_base_url(server.base_url());
+    let response = client
+        .send_message(&sample_request(false))
+        .await
+        .expect("request should succeed");
+
+    assert_eq!(response.model, "grok-3");
+    assert_eq!(response.total_tokens(), 16);
+    assert_eq!(
+        response.content,
+        vec![OutputContentBlock::Text {
+            text: "Hello from Grok".to_string(),
+        }]
+    );
+
+    let captured = state.lock().await;
+    let request = captured.first().expect("server should capture request");
+    assert_eq!(request.path, "/chat/completions");
+    assert_eq!(
+        request.headers.get("authorization").map(String::as_str),
+        Some("Bearer xai-test-key")
+    );
+    let body: serde_json::Value = serde_json::from_str(&request.body).expect("json body");
+    assert_eq!(body["model"], json!("grok-3"));
+    assert_eq!(body["messages"][0]["role"], json!("system"));
+    assert_eq!(body["tools"][0]["type"], json!("function"));
+}
+
+#[tokio::test]
+async fn send_message_accepts_full_chat_completions_endpoint_override() {
+    let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
+    let body = concat!(
+        "{",
+        "\"id\":\"chatcmpl_full_endpoint\",",
+        "\"model\":\"grok-3\",",
+        "\"choices\":[{",
+        "\"message\":{\"role\":\"assistant\",\"content\":\"Endpoint override works\",\"tool_calls\":[]},",
+        "\"finish_reason\":\"stop\"",
+        "}],",
+        "\"usage\":{\"prompt_tokens\":7,\"completion_tokens\":3}",
+        "}"
+    );
+    let server = spawn_server(
+        state.clone(),
+        vec![http_response("200 OK", "application/json", body)],
+    )
+    .await;
+
+    let endpoint_url = format!("{}/chat/completions", server.base_url());
+    let client = OpenAiCompatClient::new("xai-test-key", OpenAiCompatConfig::xai())
+        .with_base_url(endpoint_url);
+    let response = client
+        .send_message(&sample_request(false))
+        .await
+        .expect("request should succeed");
+
+    assert_eq!(response.total_tokens(), 10);
+
+    let captured = state.lock().await;
+    let request = captured.first().expect("server should capture request");
+    assert_eq!(request.path, "/chat/completions");
+}
+
+#[tokio::test]
+async fn stream_message_normalizes_text_and_multiple_tool_calls() {
+    let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
+    let sse = concat!(
+        "data: {\"id\":\"chatcmpl_stream\",\"model\":\"grok-3\",\"choices\":[{\"delta\":{\"content\":\"Hello\"}}]}\n\n",
+        "data: {\"id\":\"chatcmpl_stream\",\"choices\":[{\"delta\":{\"tool_calls\":[{\"index\":0,\"id\":\"call_1\",\"function\":{\"name\":\"weather\",\"arguments\":\"{\\\"city\\\":\\\"Paris\\\"}\"}},{\"index\":1,\"id\":\"call_2\",\"function\":{\"name\":\"clock\",\"arguments\":\"{\\\"zone\\\":\\\"UTC\\\"}\"}}]}}]}\n\n",
+        "data: {\"id\":\"chatcmpl_stream\",\"choices\":[{\"delta\":{},\"finish_reason\":\"tool_calls\"}]}\n\n",
+        "data: [DONE]\n\n"
+    );
+    let server = spawn_server(
+        state.clone(),
+        vec![http_response_with_headers(
+            "200 OK",
+            "text/event-stream",
+            sse,
+            &[("x-request-id", "req_grok_stream")],
+        )],
+    )
+    .await;
+
+    let client = OpenAiCompatClient::new("xai-test-key", OpenAiCompatConfig::xai())
+        .with_base_url(server.base_url());
+    let mut stream = client
+        .stream_message(&sample_request(false))
+        .await
+        .expect("stream should start");
+
+    assert_eq!(stream.request_id(), Some("req_grok_stream"));
+
+    let mut events = Vec::new();
+    while let Some(event) = stream.next_event().await.expect("event should parse") {
+        events.push(event);
+    }
+
+    assert!(matches!(events[0], StreamEvent::MessageStart(_)));
+    assert!(matches!(
+        events[1],
+        StreamEvent::ContentBlockStart(ContentBlockStartEvent {
+            content_block: OutputContentBlock::Text { .. },
+            ..
+        })
+    ));
+    assert!(matches!(
+        events[2],
+        StreamEvent::ContentBlockDelta(ContentBlockDeltaEvent {
+            delta: ContentBlockDelta::TextDelta { .. },
+            ..
+        })
+    ));
+    assert!(matches!(
+        events[3],
+        StreamEvent::ContentBlockStart(ContentBlockStartEvent {
+            index: 1,
+            content_block: OutputContentBlock::ToolUse { .. },
+        })
+    ));
+    assert!(matches!(
+        events[4],
+        StreamEvent::ContentBlockDelta(ContentBlockDeltaEvent {
+            index: 1,
+            delta: ContentBlockDelta::InputJsonDelta { .. },
+        })
+    ));
+    assert!(matches!(
+        events[5],
+        StreamEvent::ContentBlockStart(ContentBlockStartEvent {
+            index: 2,
+            content_block: OutputContentBlock::ToolUse { .. },
+        })
+    ));
+    assert!(matches!(
+        events[6],
+        StreamEvent::ContentBlockDelta(ContentBlockDeltaEvent {
+            index: 2,
+            delta: ContentBlockDelta::InputJsonDelta { .. },
+        })
+    ));
+    assert!(matches!(
+        events[7],
+        StreamEvent::ContentBlockStop(ContentBlockStopEvent { index: 1 })
+    ));
+    assert!(matches!(
+        events[8],
+        StreamEvent::ContentBlockStop(ContentBlockStopEvent { index: 2 })
+    ));
+    assert!(matches!(
+        events[9],
+        StreamEvent::ContentBlockStop(ContentBlockStopEvent { index: 0 })
+    ));
+    assert!(matches!(events[10], StreamEvent::MessageDelta(_)));
+    assert!(matches!(events[11], StreamEvent::MessageStop(_)));
+
+    let captured = state.lock().await;
+    let request = captured.first().expect("captured request");
+    assert_eq!(request.path, "/chat/completions");
+    assert!(request.body.contains("\"stream\":true"));
+}
+
+#[tokio::test]
+async fn provider_client_dispatches_xai_requests_from_env() {
+    let _lock = env_lock();
+    let _api_key = ScopedEnvVar::set("XAI_API_KEY", "xai-test-key");
+
+    let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
+    let server = spawn_server(
+        state.clone(),
+        vec![http_response(
+            "200 OK",
+            "application/json",
+            "{\"id\":\"chatcmpl_provider\",\"model\":\"grok-3\",\"choices\":[{\"message\":{\"role\":\"assistant\",\"content\":\"Through provider client\",\"tool_calls\":[]},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":9,\"completion_tokens\":4}}",
+        )],
+    )
+    .await;
+    let _base_url = ScopedEnvVar::set("XAI_BASE_URL", server.base_url());
+
+    let client =
+        ProviderClient::from_model("grok").expect("xAI provider client should be constructed");
+    assert!(matches!(client, ProviderClient::Xai(_)));
+
+    let response = client
+        .send_message(&sample_request(false))
+        .await
+        .expect("provider-dispatched request should succeed");
+
+    assert_eq!(response.total_tokens(), 13);
+
+    let captured = state.lock().await;
+    let request = captured.first().expect("captured request");
+    assert_eq!(request.path, "/chat/completions");
+    assert_eq!(
+        request.headers.get("authorization").map(String::as_str),
+        Some("Bearer xai-test-key")
+    );
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct CapturedRequest {
+    path: String,
+    headers: HashMap<String, String>,
+    body: String,
+}
+
+struct TestServer {
+    base_url: String,
+    join_handle: tokio::task::JoinHandle<()>,
+}
+
+impl TestServer {
+    fn base_url(&self) -> String {
+        self.base_url.clone()
+    }
+}
+
+impl Drop for TestServer {
+    fn drop(&mut self) {
+        self.join_handle.abort();
+    }
+}
+
+async fn spawn_server(
+    state: Arc<Mutex<Vec<CapturedRequest>>>,
+    responses: Vec<String>,
+) -> TestServer {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let address = listener.local_addr().expect("listener addr");
+    let join_handle = tokio::spawn(async move {
+        for response in responses {
+            let (mut socket, _) = listener.accept().await.expect("accept");
+            let mut buffer = Vec::new();
+            let mut header_end = None;
+            loop {
+                let mut chunk = [0_u8; 1024];
+                let read = socket.read(&mut chunk).await.expect("read request");
+                if read == 0 {
+                    break;
+                }
+                buffer.extend_from_slice(&chunk[..read]);
+                if let Some(position) = find_header_end(&buffer) {
+                    header_end = Some(position);
+                    break;
+                }
+            }
+
+            let header_end = header_end.expect("headers should exist");
+            let (header_bytes, remaining) = buffer.split_at(header_end);
+            let header_text = String::from_utf8(header_bytes.to_vec()).expect("utf8 headers");
+            let mut lines = header_text.split("\r\n");
+            let request_line = lines.next().expect("request line");
+            let path = request_line
+                .split_whitespace()
+                .nth(1)
+                .expect("path")
+                .to_string();
+            let mut headers = HashMap::new();
+            let mut content_length = 0_usize;
+            for line in lines {
+                if line.is_empty() {
+                    continue;
+                }
+                let (name, value) = line.split_once(':').expect("header");
+                let value = value.trim().to_string();
+                if name.eq_ignore_ascii_case("content-length") {
+                    content_length = value.parse().expect("content length");
+                }
+                headers.insert(name.to_ascii_lowercase(), value);
+            }
+
+            let mut body = remaining[4..].to_vec();
+            while body.len() < content_length {
+                let mut chunk = vec![0_u8; content_length - body.len()];
+                let read = socket.read(&mut chunk).await.expect("read body");
+                if read == 0 {
+                    break;
+                }
+                body.extend_from_slice(&chunk[..read]);
+            }
+
+            state.lock().await.push(CapturedRequest {
+                path,
+                headers,
+                body: String::from_utf8(body).expect("utf8 body"),
+            });
+
+            socket
+                .write_all(response.as_bytes())
+                .await
+                .expect("write response");
+        }
+    });
+
+    TestServer {
+        base_url: format!("http://{address}"),
+        join_handle,
+    }
+}
+
+fn find_header_end(bytes: &[u8]) -> Option<usize> {
+    bytes.windows(4).position(|window| window == b"\r\n\r\n")
+}
+
+fn http_response(status: &str, content_type: &str, body: &str) -> String {
+    http_response_with_headers(status, content_type, body, &[])
+}
+
+fn http_response_with_headers(
+    status: &str,
+    content_type: &str,
+    body: &str,
+    headers: &[(&str, &str)],
+) -> String {
+    let mut extra_headers = String::new();
+    for (name, value) in headers {
+        use std::fmt::Write as _;
+        write!(&mut extra_headers, "{name}: {value}\r\n").expect("header write");
+    }
+    format!(
+        "HTTP/1.1 {status}\r\ncontent-type: {content_type}\r\n{extra_headers}content-length: {}\r\nconnection: close\r\n\r\n{body}",
+        body.len()
+    )
+}
+
+fn sample_request(stream: bool) -> MessageRequest {
+    MessageRequest {
+        model: "grok-3".to_string(),
+        max_tokens: 64,
+        messages: vec![InputMessage {
+            role: "user".to_string(),
+            content: vec![InputContentBlock::Text {
+                text: "Say hello".to_string(),
+            }],
+        }],
+        system: Some("Use tools when needed".to_string()),
+        tools: Some(vec![ToolDefinition {
+            name: "weather".to_string(),
+            description: Some("Fetches weather".to_string()),
+            input_schema: json!({
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"]
+            }),
+        }]),
+        tool_choice: Some(ToolChoice::Auto),
+        stream,
+    }
+}
+
+fn env_lock() -> std::sync::MutexGuard<'static, ()> {
+    static LOCK: OnceLock<StdMutex<()>> = OnceLock::new();
+    LOCK.get_or_init(|| StdMutex::new(()))
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+struct ScopedEnvVar {
+    key: &'static str,
+    previous: Option<OsString>,
+}
+
+impl ScopedEnvVar {
+    fn set(key: &'static str, value: impl AsRef<std::ffi::OsStr>) -> Self {
+        let previous = std::env::var_os(key);
+        std::env::set_var(key, value);
+        Self { key, previous }
+    }
+}
+
+impl Drop for ScopedEnvVar {
+    fn drop(&mut self) {
+        match &self.previous {
+            Some(value) => std::env::set_var(self.key, value),
+            None => std::env::remove_var(self.key),
+        }
+    }
+}

rust/crates/api/tests/provider_client_integration.rs

@@ -0,0 +1,86 @@
+use std::ffi::OsString;
+use std::sync::{Mutex, OnceLock};
+
+use api::{read_xai_base_url, ApiError, AuthSource, ProviderClient, ProviderKind};
+
+#[test]
+fn provider_client_routes_grok_aliases_through_xai() {
+    let _lock = env_lock();
+    let _xai_api_key = EnvVarGuard::set("XAI_API_KEY", Some("xai-test-key"));
+
+    let client = ProviderClient::from_model("grok-mini").expect("grok alias should resolve");
+
+    assert_eq!(client.provider_kind(), ProviderKind::Xai);
+}
+
+#[test]
+fn provider_client_reports_missing_xai_credentials_for_grok_models() {
+    let _lock = env_lock();
+    let _xai_api_key = EnvVarGuard::set("XAI_API_KEY", None);
+
+    let error = ProviderClient::from_model("grok-3")
+        .expect_err("grok requests without XAI_API_KEY should fail fast");
+
+    match error {
+        ApiError::MissingCredentials { provider, env_vars } => {
+            assert_eq!(provider, "xAI");
+            assert_eq!(env_vars, &["XAI_API_KEY"]);
+        }
+        other => panic!("expected missing xAI credentials, got {other:?}"),
+    }
+}
+
+#[test]
+fn provider_client_uses_explicit_auth_without_env_lookup() {
+    let _lock = env_lock();
+    let _api_key = EnvVarGuard::set("ANTHROPIC_API_KEY", None);
+    let _auth_token = EnvVarGuard::set("ANTHROPIC_AUTH_TOKEN", None);
+
+    let client = ProviderClient::from_model_with_default_auth(
+        "claude-sonnet-4-6",
+        Some(AuthSource::ApiKey("claw-test-key".to_string())),
+    )
+    .expect("explicit auth should avoid env lookup");
+
+    assert_eq!(client.provider_kind(), ProviderKind::ClawApi);
+}
+
+#[test]
+fn read_xai_base_url_prefers_env_override() {
+    let _lock = env_lock();
+    let _xai_base_url = EnvVarGuard::set("XAI_BASE_URL", Some("https://example.xai.test/v1"));
+
+    assert_eq!(read_xai_base_url(), "https://example.xai.test/v1");
+}
+
+fn env_lock() -> std::sync::MutexGuard<'static, ()> {
+    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    LOCK.get_or_init(|| Mutex::new(()))
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+struct EnvVarGuard {
+    key: &'static str,
+    original: Option<OsString>,
+}
+
+impl EnvVarGuard {
+    fn set(key: &'static str, value: Option<&str>) -> Self {
+        let original = std::env::var_os(key);
+        match value {
+            Some(value) => std::env::set_var(key, value),
+            None => std::env::remove_var(key),
+        }
+        Self { key, original }
+    }
+}
+
+impl Drop for EnvVarGuard {
+    fn drop(&mut self) {
+        match &self.original {
+            Some(value) => std::env::set_var(self.key, value),
+            None => std::env::remove_var(self.key),
+        }
+    }
+}