Backend Architecture

The Kuse Cowork backend is built with Rust and Tauri, providing high performance and native system integration.

Technology Stack

Project Structure

src-tauri/
├── Cargo.toml           # Dependencies
├── tauri.conf.json      # Tauri configuration
├── src/
│   ├── main.rs          # Entry point
│   ├── lib.rs           # Library root
│   ├── commands.rs      # Tauri commands (1800+ lines)
│   ├── database.rs      # Database operations
│   ├── llm_client.rs    # LLM providers (950+ lines)
│   ├── agent/
│   │   ├── mod.rs
│   │   ├── agent_loop.rs    # Agent execution (1000+ lines)
│   │   ├── message_builder.rs
│   │   ├── tool_executor.rs
│   │   └── types.rs
│   ├── tools/
│   │   ├── mod.rs
│   │   ├── bash.rs
│   │   ├── docker.rs
│   │   ├── file_read.rs
│   │   ├── file_write.rs
│   │   ├── file_edit.rs
│   │   ├── glob.rs
│   │   ├── grep.rs
│   │   └── list_dir.rs
│   ├── mcp/
│   │   ├── mod.rs
│   │   ├── client.rs
│   │   ├── http_client.rs
│   │   ├── config.rs
│   │   └── types.rs
│   └── skills/
│       └── mod.rs

Core Modules

Commands (commands.rs)

Tauri command handlers that bridge frontend and backend:

#[tauri::command]
pub async fn send_chat_message(
    state: tauri::State<'_, AppState>,
    window: tauri::Window,
    conversation_id: String,
    content: String,
) -> Result<String, CommandError> {
    // Get settings
    let settings = state.db.get_settings()?;

    // Create LLM client
    let client = LLMClient::new(
        settings.api_key,
        settings.base_url,
        settings.model,
    );

    // Stream response
    let response = client.send_message_stream(
        messages,
        |chunk| {
            window.emit("chat-stream", chunk)?;
            Ok(())
        }
    ).await?;

    // Save to database
    state.db.add_message(&response)?;

    Ok(response)
}

Database (database.rs)

SQLite operations for persistent storage:

pub struct Database {
    conn: Mutex<Connection>,
}

impl Database {
    pub fn new(data_dir: &Path) -> Result<Self, DatabaseError> {
        let db_path = data_dir.join("settings.db");
        let conn = Connection::open(&db_path)?;

        // Initialize schema
        conn.execute_batch(SCHEMA)?;

        Ok(Self {
            conn: Mutex::new(conn),
        })
    }

    pub fn get_settings(&self) -> Result<Settings, DatabaseError> {
        let conn = self.conn.lock().unwrap();
        // Query settings...
    }

    pub fn save_settings(&self, settings: &Settings) -> Result<(), DatabaseError> {
        let conn = self.conn.lock().unwrap();
        // Insert/update settings...
    }
}

LLM Client (llm_client.rs)

Multi-provider LLM integration:

pub struct LLMClient {
    client: Client,
    api_key: String,
    base_url: String,
    model: String,
    provider_config: ProviderConfig,
}

impl LLMClient {
    pub async fn send_message_stream(
        &self,
        messages: Vec<Message>,
        on_chunk: impl Fn(String) -> Result<(), LLMError>,
    ) -> Result<String, LLMError> {
        match self.provider_config.api_format {
            ApiFormat::Anthropic => self.send_anthropic_stream(messages, on_chunk).await,
            ApiFormat::OpenAI => self.send_openai_stream(messages, on_chunk).await,
            ApiFormat::Google => self.send_google_stream(messages, on_chunk).await,
            // ...
        }
    }
}

Agent System

Agent Loop (agent/agent_loop.rs)

Core autonomous agent execution:

pub struct AgentLoop {
    client: Client,
    api_key: String,
    base_url: String,
    config: AgentConfig,
    tool_executor: ToolExecutor,
    message_builder: MessageBuilder,
    provider_config: ProviderConfig,
}

impl AgentLoop {
    pub async fn run_with_history(
        &mut self,
        messages: Vec<AgentMessage>,
        event_tx: mpsc::Sender<AgentEvent>,
    ) -> Result<String, String> {
        let max_turns = self.config.max_turns;

        for turn in 1..=max_turns {
            // Build API request
            let request = self.message_builder.build_request(&messages).await;

            // Send to LLM
            let response = self.send_request(&request, &event_tx).await?;

            // Parse response
            let (text, tool_uses) = self.parse_response(&response)?;

            // Execute tools if needed
            if !tool_uses.is_empty() {
                for tool_use in &tool_uses {
                    let result = self.tool_executor.execute(tool_use).await;
                    // Add result to messages...
                }
            } else {
                // No more tools, we're done
                return Ok(text);
            }
        }

        Err("Max turns exceeded".to_string())
    }
}

Message Builder (agent/message_builder.rs)

Constructs API requests:

pub struct MessageBuilder {
    config: AgentConfig,
    model: String,
    max_tokens: u32,
    mcp_manager: Option<Arc<MCPManager>>,
}

impl MessageBuilder {
    pub async fn build_request(
        &self,
        messages: &[AgentMessage],
    ) -> ClaudeApiRequest {
        let mut tools = tools::get_tools(&self.config.allowed_tools);

        // Add MCP tools
        if let Some(mcp) = &self.mcp_manager {
            tools.extend(self.get_mcp_tools(mcp).await);
        }

        ClaudeApiRequest {
            model: self.model.clone(),
            max_tokens: self.max_tokens,
            system: self.config.system_prompt.clone(),
            messages: self.convert_messages(messages),
            tools,
            stream: true,
        }
    }
}

Tool Executor (agent/tool_executor.rs)

Executes agent tools:

pub struct ToolExecutor {
    project_path: Option<String>,
    mcp_manager: Option<Arc<MCPManager>>,
}

impl ToolExecutor {
    pub async fn execute(&self, tool_use: &ToolUse) -> ToolResult {
        // Check for MCP tools
        if tool_use.name.starts_with("mcp_") {
            return self.execute_mcp_tool(tool_use).await;
        }

        // Execute built-in tools
        match tool_use.name.as_str() {
            "read_file" => tools::read_file(tool_use),
            "write_file" => tools::write_file(tool_use),
            "edit_file" => tools::edit_file(tool_use),
            "bash" => tools::bash(tool_use, &self.project_path).await,
            "glob" => tools::glob(tool_use, &self.project_path),
            "grep" => tools::grep(tool_use, &self.project_path),
            "list_dir" => tools::list_dir(tool_use),
            "docker_run" => tools::docker_run(tool_use, &self.project_path),
            _ => ToolResult::error(tool_use.id.clone(), "Unknown tool"),
        }
    }
}

Tool Implementations

File Operations

// tools/file_read.rs
pub fn read_file(tool_use: &ToolUse) -> ToolResult {
    let path = tool_use.input.get("path")
        .and_then(|v| v.as_str())
        .ok_or("Missing path")?;

    // Expand ~ to home directory
    let expanded = expand_tilde(path);

    let content = std::fs::read_to_string(&expanded)?;

    ToolResult::success(tool_use.id.clone(), content)
}

Docker Integration

// tools/docker.rs
pub async fn docker_run(
    tool_use: &ToolUse,
    project_path: &Option<String>,
) -> ToolResult {
    let docker = Docker::connect_with_local_defaults()?;

    let image = tool_use.input.get("image")
        .and_then(|v| v.as_str())
        .unwrap_or("python:3.11-alpine");

    let command = tool_use.input.get("command")
        .and_then(|v| v.as_str())
        .ok_or("Missing command")?;

    // Create container config
    let config = Config {
        image: Some(image),
        cmd: Some(vec!["/bin/sh", "-c", command]),
        host_config: Some(HostConfig {
            binds: Some(vec![
                format!("{}:/workspace", project_path),
                format!("{}:/skills:ro", skills_path),
            ]),
            ..Default::default()
        }),
        ..Default::default()
    };

    // Create and run container
    let container = docker.create_container(None, config).await?;
    docker.start_container(&container.id, None).await?;

    // Wait and get output
    let output = docker.wait_container(&container.id).await?;
    let logs = docker.logs(&container.id, options).await?;

    // Cleanup
    docker.remove_container(&container.id, None).await?;

    ToolResult::success(tool_use.id.clone(), logs)
}

MCP Integration

MCP Manager (mcp/client.rs)

pub struct MCPManager {
    servers: RwLock<HashMap<String, MCPServer>>,
    http_client: Client,
}

impl MCPManager {
    pub async fn add_server(&self, config: MCPServerConfig) -> Result<(), MCPError> {
        let server = MCPServer::connect(config).await?;
        self.servers.write().await.insert(server.id.clone(), server);
        Ok(())
    }

    pub async fn get_all_tools(&self) -> Vec<MCPTool> {
        let servers = self.servers.read().await;
        let mut tools = Vec::new();

        for server in servers.values() {
            if server.is_connected() {
                tools.extend(server.tools.clone());
            }
        }

        tools
    }

    pub async fn execute_tool(&self, call: &MCPToolCall) -> Result<String, MCPError> {
        let servers = self.servers.read().await;
        let server = servers.get(&call.server_id)
            .ok_or(MCPError::ServerNotFound)?;

        server.call_tool(&call.tool_name, &call.parameters).await
    }
}

Error Handling

Error Types

#[derive(Error, Debug)]
pub enum LLMError {
    #[error("HTTP error: {0}")]
    Http(#[from] reqwest::Error),

    #[error("API error: {0}")]
    Api(String),

    #[error("Parse error: {0}")]
    Parse(String),

    #[error("Unsupported provider: {0}")]
    UnsupportedProvider(String),
}

#[derive(Debug, Serialize)]
pub struct CommandError {
    pub message: String,
}

impl From<LLMError> for CommandError {
    fn from(err: LLMError) -> Self {
        CommandError {
            message: err.to_string(),
        }
    }
}

Async Architecture

Tokio Runtime

// main.rs
#[tokio::main]
async fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_dialog::init())
        .plugin(tauri_plugin_shell::init())
        .plugin(tauri_plugin_fs::init())
        .invoke_handler(tauri::generate_handler![
            commands::get_settings,
            commands::save_settings,
            commands::send_chat_message,
            commands::run_task_agent,
            // ...
        ])
        .run(tauri::generate_context!())
        .expect("error running application");
}

Streaming with Channels

use tokio::sync::mpsc;

pub async fn run_agent_with_events(
    request: AgentRequest,
    window: Window,
) -> Result<String, CommandError> {
    let (tx, mut rx) = mpsc::channel(100);

    // Spawn event forwarder
    let event_window = window.clone();
    tokio::spawn(async move {
        while let Some(event) = rx.recv().await {
            let _ = event_window.emit("agent-event", event);
        }
    });

    // Run agent
    let result = agent_loop.run_with_history(messages, tx).await;

    Ok(result?)
}

Testing

Unit Tests

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_provider_detection() {
        assert_eq!(
            ProviderConfig::from_model("claude-3-sonnet").api_format,
            ApiFormat::Anthropic
        );
        assert_eq!(
            ProviderConfig::from_model("gpt-4o").api_format,
            ApiFormat::OpenAI
        );
    }

    #[tokio::test]
    async fn test_tool_execution() {
        let executor = ToolExecutor::new(None);
        let tool_use = ToolUse {
            id: "test".to_string(),
            name: "list_dir".to_string(),
            input: json!({"path": "."}),
        };

        let result = executor.execute(&tool_use).await;
        assert!(result.is_error.is_none());
    }
}

Integration Tests

#[cfg(test)]
mod integration_tests {
    #[tokio::test]
    async fn test_full_agent_flow() {
        // Create agent with mock LLM
        // Run a simple task
        // Verify tools are called
        // Check final output
    }
}

Performance Optimizations

Connection Pooling

let client = reqwest::Client::builder()
    .pool_max_idle_per_host(10)
    .timeout(Duration::from_secs(300))
    .build()?;

Parallel Tool Execution

// Future: Execute independent tools in parallel
let results = futures::future::join_all(
    tool_uses.iter().map(|tu| self.tool_executor.execute(tu))
).await;

Security Considerations

Input Validation

fn validate_path(path: &str) -> Result<PathBuf, ToolError> {
    let expanded = expand_tilde(path);
    let canonical = expanded.canonicalize()?;

    // Prevent path traversal
    if !canonical.starts_with(&project_root) {
        return Err(ToolError::AccessDenied);
    }

    Ok(canonical)
}

Command Sanitization

// Commands run in Docker are isolated
// But we still validate inputs
fn sanitize_command(cmd: &str) -> Result<String, ToolError> {
    if cmd.contains("rm -rf /") || cmd.contains(":(){ :|:& };:") {
        return Err(ToolError::DangerousCommand);
    }
    Ok(cmd.to_string())
}

Next Steps

• Architecture Overview
• Development Setup
• Contributing

‍