Add OpenAI-compatible HTTP API (/v1/chat/completions, /v1/models) (#31)

* feat: add OpenAI-compatible HTTP API (/v1/chat/completions, /v1/models)

* - Reject model mismatches: validate req.model against the active model
    and return 404 model_not_found instead of silently ignoring it
  - Add x-ironclaw-streaming: simulated response header so clients know
    streaming is not true token-by-token delivery
  - Use SSE event type "error" for mid-stream LLM failures so clients can
    distinguish errors from content chunks
  - Mark docker-compose credentials as dev-only
  - Add integration tests for model mismatch, streaming header, and body
    size limit (axum's default 2MB)

* fix: address Copilot review feedback on OpenAI-compat API

- Wire chat_rate_limiter into /v1/chat/completions handler
- Execute LLM before starting SSE stream so failures return proper HTTP
  errors instead of SSE error events
- Validate tool-role messages require tool_call_id and name fields
- Surface list_models() errors in models_handler via map_llm_error
- Reject unknown roles with 400 instead of defaulting to User

Co-Authored-By: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: firat.sertgoz <[email protected]>
Co-authored-by: Claude Opus 4.6 <[email protected]>

FEATURE_PARITY.md

@@ -37,7 +37,7 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 | Session management/routing | ✅ | ✅ | SessionManager exists |
 | Configuration hot-reload | ✅ | ❌ | |
 | Network modes (loopback/LAN/remote) | ✅ | 🚧 | HTTP only |
-| OpenAI-compatible HTTP API | ✅ | ❌ | /v1/chat/completions |
+| OpenAI-compatible HTTP API | ✅ | ✅ | /v1/chat/completions |
 | Canvas hosting | ✅ | ❌ | Agent-driven UI |
 | Gateway lock (PID-based) | ✅ | ❌ | |
 | launchd/systemd integration | ✅ | ❌ | |

docker-compose.yml

@@ -0,0 +1,20 @@
+# Local development only — do NOT use these credentials in production.
+services:
+  postgres:
+    image: pgvector/pgvector:pg16
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_DB: ironclaw
+      POSTGRES_USER: ironclaw
+      POSTGRES_PASSWORD: ironclaw  # dev-only, change for any non-local deployment
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ironclaw"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  pgdata:

src/channels/web/mod.rs

@@ -16,6 +16,7 @@
 
 pub mod auth;
 pub mod log_layer;
+pub mod openai_compat;
 pub mod server;
 pub mod sse;
 pub mod types;
@@ -81,6 +82,7 @@ impl GatewayChannel {
             user_id: config.user_id.clone(),
             shutdown_tx: tokio::sync::RwLock::new(None),
             ws_tracker: Some(Arc::new(ws::WsConnectionTracker::new())),
+            llm_provider: None,
             chat_rate_limiter: server::RateLimiter::new(30, 60),
         });
 
@@ -107,6 +109,7 @@ impl GatewayChannel {
             user_id: self.state.user_id.clone(),
             shutdown_tx: tokio::sync::RwLock::new(None),
             ws_tracker: self.state.ws_tracker.clone(),
+            llm_provider: self.state.llm_provider.clone(),
             chat_rate_limiter: server::RateLimiter::new(30, 60),
         };
         mutate(&mut new_state);
@@ -171,6 +174,12 @@ impl GatewayChannel {
         self
     }
 
+    /// Inject the LLM provider for OpenAI-compatible API proxy.
+    pub fn with_llm_provider(mut self, llm: Arc<dyn crate::llm::LlmProvider>) -> Self {
+        self.rebuild_state(|s| s.llm_provider = Some(llm));
+        self
+    }
+
     /// Get the auth token (for printing to console on startup).
     pub fn auth_token(&self) -> &str {
         &self.auth_token

src/channels/web/server.rs

@@ -137,6 +137,8 @@ pub struct GatewayState {
     pub shutdown_tx: tokio::sync::RwLock<Option<oneshot::Sender<()>>>,
     /// WebSocket connection tracker.
     pub ws_tracker: Option<Arc<crate::channels::web::ws::WsConnectionTracker>>,
+    /// LLM provider for OpenAI-compatible API proxy.
+    pub llm_provider: Option<Arc<dyn crate::llm::LlmProvider>>,
     /// Rate limiter for chat endpoints (30 messages per 60 seconds).
     pub chat_rate_limiter: RateLimiter,
 }
@@ -235,6 +237,12 @@ pub async fn start_server(
         )
         // Gateway control plane
         .route("/api/gateway/status", get(gateway_status_handler))
+        // OpenAI-compatible API
+        .route(
+            "/v1/chat/completions",
+            post(super::openai_compat::chat_completions_handler),
+        )
+        .route("/v1/models", get(super::openai_compat::models_handler))
         .route_layer(middleware::from_fn_with_state(
             auth_state.clone(),
             auth_middleware,

src/channels/web/ws.rs

@@ -485,6 +485,7 @@ mod tests {
             user_id: "test".to_string(),
             shutdown_tx: tokio::sync::RwLock::new(None),
             ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
+            llm_provider: None,
             chat_rate_limiter: crate::channels::web::server::RateLimiter::new(30, 60),
         }
     }

src/main.rs

@@ -997,6 +997,7 @@ async fn main() -> anyhow::Result<()> {
         if let Some(ref jm) = container_job_manager {
             gw = gw.with_job_manager(Arc::clone(jm));
         }
+        gw = gw.with_llm_provider(Arc::clone(&llm));
         if config.sandbox.enabled {
             gw = gw.with_prompt_queue(Arc::clone(&prompt_queue));
 

tests/openai_compat_integration.rs

@@ -0,0 +1,478 @@
+//! Integration tests for the OpenAI-compatible API endpoints.
+//!
+//! Uses a mock LLM provider so no real API key is needed.
+
+use std::net::SocketAddr;
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use rust_decimal::Decimal;
+
+use ironclaw::channels::web::server::{GatewayState, start_server};
+use ironclaw::channels::web::sse::SseManager;
+use ironclaw::channels::web::ws::WsConnectionTracker;
+use ironclaw::error::LlmError;
+use ironclaw::llm::{
+    CompletionRequest, CompletionResponse, FinishReason, LlmProvider, ToolCompletionRequest,
+    ToolCompletionResponse,
+};
+
+const AUTH_TOKEN: &str = "test-openai-token";
+
+// ---------------------------------------------------------------------------
+// Mock LLM provider
+// ---------------------------------------------------------------------------
+
+struct MockLlmProvider;
+
+#[async_trait]
+impl LlmProvider for MockLlmProvider {
+    fn model_name(&self) -> &str {
+        "mock-model-v1"
+    }
+
+    fn cost_per_token(&self) -> (Decimal, Decimal) {
+        (Decimal::ZERO, Decimal::ZERO)
+    }
+
+    async fn complete(&self, req: CompletionRequest) -> Result<CompletionResponse, LlmError> {
+        // Echo the last user message back
+        let user_msg = req
+            .messages
+            .iter()
+            .rev()
+            .find(|m| m.role == ironclaw::llm::Role::User)
+            .map(|m| m.content.clone())
+            .unwrap_or_else(|| "no user message".to_string());
+
+        Ok(CompletionResponse {
+            content: format!("Mock response to: {}", user_msg),
+            input_tokens: 10,
+            output_tokens: 5,
+            finish_reason: FinishReason::Stop,
+            response_id: None,
+        })
+    }
+
+    async fn complete_with_tools(
+        &self,
+        req: ToolCompletionRequest,
+    ) -> Result<ToolCompletionResponse, LlmError> {
+        // If tools are provided, return a tool call
+        if let Some(tool) = req.tools.first() {
+            Ok(ToolCompletionResponse {
+                content: None,
+                tool_calls: vec![ironclaw::llm::ToolCall {
+                    id: "call_mock_001".to_string(),
+                    name: tool.name.clone(),
+                    arguments: serde_json::json!({"test": true}),
+                }],
+                input_tokens: 15,
+                output_tokens: 8,
+                finish_reason: FinishReason::ToolUse,
+                response_id: None,
+            })
+        } else {
+            Ok(ToolCompletionResponse {
+                content: Some("No tools available".to_string()),
+                tool_calls: vec![],
+                input_tokens: 10,
+                output_tokens: 4,
+                finish_reason: FinishReason::Stop,
+                response_id: None,
+            })
+        }
+    }
+
+    async fn list_models(&self) -> Result<Vec<String>, LlmError> {
+        Ok(vec![
+            "mock-model-v1".to_string(),
+            "mock-model-v2".to_string(),
+        ])
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+async fn start_test_server() -> (SocketAddr, Arc<GatewayState>) {
+    let state = Arc::new(GatewayState {
+        msg_tx: tokio::sync::RwLock::new(None),
+        sse: SseManager::new(),
+        workspace: None,
+        session_manager: None,
+        log_broadcaster: None,
+        extension_manager: None,
+        tool_registry: None,
+        store: None,
+        job_manager: None,
+        prompt_queue: None,
+        user_id: "test-user".to_string(),
+        shutdown_tx: tokio::sync::RwLock::new(None),
+        ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
+        llm_provider: Some(Arc::new(MockLlmProvider)),
+        chat_rate_limiter: ironclaw::channels::web::server::RateLimiter::new(30, 60),
+    });
+
+    let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
+    let bound_addr = start_server(addr, state.clone(), AUTH_TOKEN.to_string())
+        .await
+        .expect("Failed to start test server");
+
+    (bound_addr, state)
+}
+
+fn client() -> reqwest::Client {
+    reqwest::Client::builder()
+        .timeout(Duration::from_secs(10))
+        .build()
+        .unwrap()
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn test_chat_completions_basic() {
+    let (addr, _state) = start_test_server().await;
+    let url = format!("http://{}/v1/chat/completions", addr);
+
+    let resp = client()
+        .post(&url)
+        .bearer_auth(AUTH_TOKEN)
+        .json(&serde_json::json!({
+            "model": "mock-model-v1",
+            "messages": [
+                {"role": "user", "content": "Hello world"}
+            ]
+        }))
+        .send()
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), 200);
+
+    let body: serde_json::Value = resp.json().await.unwrap();
+    assert_eq!(body["object"], "chat.completion");
+    assert_eq!(body["model"], "mock-model-v1");
+    assert_eq!(body["choices"][0]["finish_reason"], "stop");
+
+    let content = body["choices"][0]["message"]["content"].as_str().unwrap();
+    assert!(
+        content.contains("Hello world"),
+        "Expected echo, got: {}",
+        content
+    );
+
+    // Check usage
+    assert_eq!(body["usage"]["prompt_tokens"], 10);
+    assert_eq!(body["usage"]["completion_tokens"], 5);
+    assert_eq!(body["usage"]["total_tokens"], 15);
+}
+
+#[tokio::test]
+async fn test_chat_completions_with_system_message() {
+    let (addr, _state) = start_test_server().await;
+    let url = format!("http://{}/v1/chat/completions", addr);
+
+    let resp = client()
+        .post(&url)
+        .bearer_auth(AUTH_TOKEN)
+        .json(&serde_json::json!({
+            "model": "mock-model-v1",
+            "messages": [
+                {"role": "system", "content": "You are helpful."},
+                {"role": "user", "content": "What is 2+2?"}
+            ],
+            "temperature": 0.5,
+            "max_tokens": 100
+        }))
+        .send()
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), 200);
+    let body: serde_json::Value = resp.json().await.unwrap();
+    let content = body["choices"][0]["message"]["content"].as_str().unwrap();
+    assert!(content.contains("2+2"));
+}
+
+#[tokio::test]
+async fn test_chat_completions_with_tools() {
+    let (addr, _state) = start_test_server().await;
+    let url = format!("http://{}/v1/chat/completions", addr);
+
+    let resp = client()
+        .post(&url)
+        .bearer_auth(AUTH_TOKEN)
+        .json(&serde_json::json!({
+            "model": "mock-model-v1",
+            "messages": [
+                {"role": "user", "content": "What's the weather?"}
+            ],
+            "tools": [{
+                "type": "function",
+                "function": {
+                    "name": "get_weather",
+                    "description": "Get the weather",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "location": {"type": "string"}
+                        }
+                    }
+                }
+            }]
+        }))
+        .send()
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), 200);
+    let body: serde_json::Value = resp.json().await.unwrap();
+
+    assert_eq!(body["choices"][0]["finish_reason"], "tool_calls");
+
+    let tool_calls = &body["choices"][0]["message"]["tool_calls"];
+    assert!(tool_calls.is_array());
+    assert_eq!(tool_calls[0]["id"], "call_mock_001");
+    assert_eq!(tool_calls[0]["type"], "function");
+    assert_eq!(tool_calls[0]["function"]["name"], "get_weather");
+}
+
+#[tokio::test]
+async fn test_chat_completions_streaming() {
+    let (addr, _state) = start_test_server().await;
+    let url = format!("http://{}/v1/chat/completions", addr);
+
+    let resp = client()
+        .post(&url)
+        .bearer_auth(AUTH_TOKEN)
+        .json(&serde_json::json!({
+            "model": "mock-model-v1",
+            "messages": [
+                {"role": "user", "content": "Stream test"}
+            ],
+            "stream": true
+        }))
+        .send()
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), 200);
+
+    // Check simulated streaming header
+    assert_eq!(
+        resp.headers()
+            .get("x-ironclaw-streaming")
+            .and_then(|v| v.to_str().ok()),
+        Some("simulated"),
+        "Expected x-ironclaw-streaming: simulated header"
+    );
+
+    let text = resp.text().await.unwrap();
+
+    // Should contain SSE data lines
+    assert!(
+        text.contains("data:"),
+        "Expected SSE data lines, got: {}",
+        text
+    );
+    // Should end with [DONE]
+    assert!(
+        text.contains("[DONE]"),
+        "Expected [DONE] sentinel, got: {}",
+        text
+    );
+    // Should contain the role chunk
+    assert!(
+        text.contains("\"role\":\"assistant\""),
+        "Expected role chunk, got: {}",
+        text
+    );
+
+    // Collect all content from the chunks
+    let mut full_content = String::new();
+    for line in text.lines() {
+        if let Some(data) = line.strip_prefix("data:") {
+            let data = data.trim();
+            if data == "[DONE]" {
+                continue;
+            }
+            if let Ok(chunk) = serde_json::from_str::<serde_json::Value>(data) {
+                if let Some(content) = chunk["choices"][0]["delta"]["content"].as_str() {
+                    full_content.push_str(content);
+                }
+            }
+        }
+    }
+    assert!(
+        full_content.contains("Stream test"),
+        "Expected reassembled content to contain 'Stream test', got: '{}'",
+        full_content
+    );
+}
+
+#[tokio::test]
+async fn test_chat_completions_empty_messages() {
+    let (addr, _state) = start_test_server().await;
+    let url = format!("http://{}/v1/chat/completions", addr);
+
+    let resp = client()
+        .post(&url)
+        .bearer_auth(AUTH_TOKEN)
+        .json(&serde_json::json!({
+            "model": "mock-model-v1",
+            "messages": []
+        }))
+        .send()
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), 400);
+    let body: serde_json::Value = resp.json().await.unwrap();
+    assert!(body["error"]["message"].as_str().unwrap().contains("empty"));
+}
+
+#[tokio::test]
+async fn test_chat_completions_model_mismatch() {
+    let (addr, _state) = start_test_server().await;
+    let url = format!("http://{}/v1/chat/completions", addr);
+
+    let resp = client()
+        .post(&url)
+        .bearer_auth(AUTH_TOKEN)
+        .json(&serde_json::json!({
+            "model": "gpt-4",
+            "messages": [{"role": "user", "content": "Hi"}]
+        }))
+        .send()
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), 404);
+    let body: serde_json::Value = resp.json().await.unwrap();
+    assert_eq!(body["error"]["code"], "model_not_found");
+    assert!(
+        body["error"]["message"]
+            .as_str()
+            .unwrap()
+            .contains("mock-model-v1")
+    );
+}
+
+#[tokio::test]
+async fn test_chat_completions_no_auth() {
+    let (addr, _state) = start_test_server().await;
+    let url = format!("http://{}/v1/chat/completions", addr);
+
+    let resp = client()
+        .post(&url)
+        // No auth header
+        .json(&serde_json::json!({
+            "model": "mock-model-v1",
+            "messages": [{"role": "user", "content": "Hi"}]
+        }))
+        .send()
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), 401);
+}
+
+#[tokio::test]
+async fn test_models_endpoint() {
+    let (addr, _state) = start_test_server().await;
+    let url = format!("http://{}/v1/models", addr);
+
+    let resp = client()
+        .get(&url)
+        .bearer_auth(AUTH_TOKEN)
+        .send()
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), 200);
+    let body: serde_json::Value = resp.json().await.unwrap();
+
+    assert_eq!(body["object"], "list");
+    let data = body["data"].as_array().unwrap();
+    assert_eq!(data.len(), 2);
+    assert_eq!(data[0]["id"], "mock-model-v1");
+    assert_eq!(data[1]["id"], "mock-model-v2");
+    assert_eq!(data[0]["object"], "model");
+}
+
+#[tokio::test]
+async fn test_models_no_auth() {
+    let (addr, _state) = start_test_server().await;
+    let url = format!("http://{}/v1/models", addr);
+
+    let resp = client().get(&url).send().await.unwrap();
+    assert_eq!(resp.status(), 401);
+}
+
+#[tokio::test]
+async fn test_no_llm_provider_returns_503() {
+    // Create state WITHOUT llm_provider
+    let state = Arc::new(GatewayState {
+        msg_tx: tokio::sync::RwLock::new(None),
+        sse: SseManager::new(),
+        workspace: None,
+        session_manager: None,
+        log_broadcaster: None,
+        extension_manager: None,
+        tool_registry: None,
+        store: None,
+        job_manager: None,
+        prompt_queue: None,
+        user_id: "test-user".to_string(),
+        shutdown_tx: tokio::sync::RwLock::new(None),
+        ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
+        llm_provider: None, // No LLM!
+        chat_rate_limiter: ironclaw::channels::web::server::RateLimiter::new(30, 60),
+    });
+
+    let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
+    let bound_addr = start_server(addr, state, AUTH_TOKEN.to_string())
+        .await
+        .unwrap();
+
+    let url = format!("http://{}/v1/chat/completions", bound_addr);
+    let resp = client()
+        .post(&url)
+        .bearer_auth(AUTH_TOKEN)
+        .json(&serde_json::json!({
+            "model": "mock-model-v1",
+            "messages": [{"role": "user", "content": "Hi"}]
+        }))
+        .send()
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), 503);
+}
+
+#[tokio::test]
+async fn test_chat_completions_body_too_large() {
+    let (addr, _state) = start_test_server().await;
+    let url = format!("http://{}/v1/chat/completions", addr);
+
+    // Build a payload over 1 MB (the gateway's DefaultBodyLimit)
+    let big_content = "x".repeat(2 * 1024 * 1024);
+    let resp = client()
+        .post(&url)
+        .bearer_auth(AUTH_TOKEN)
+        .json(&serde_json::json!({
+            "model": "mock-model-v1",
+            "messages": [{"role": "user", "content": big_content}]
+        }))
+        .send()
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), 413);
+}

tests/ws_gateway_integration.rs

@@ -51,6 +51,7 @@ async fn start_test_server() -> (
         user_id: "test-user".to_string(),
         shutdown_tx: tokio::sync::RwLock::new(None),
         ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
+        llm_provider: None,
         chat_rate_limiter: ironclaw::channels::web::server::RateLimiter::new(30, 60),
     });