clawdesk-agents

The agent pipeline processes incoming messages through a series of stages — context assembly, tool execution, provider interaction, and response delivery. This is the central orchestration crate for ClawDesk's AI capabilities.

Dependencies

Internal: clawdesk-types, clawdesk-domain, clawdesk-storage

External: tokio, async-trait, tracing, futures, uuid

Modules

Module	Description
context	Context assembly — gathers session history, system prompt, tools
pipeline	Pipeline — the main processing pipeline with configurable stages
runner	Runner — executes a single pipeline run with timeout/cancellation
tools	Tool definitions and execution for function calling
trace	Pipeline tracing and observability spans
workspace	Agent workspace for multi-step reasoning

Key Types

/// The main agent processing pipeline
pub struct Pipeline {
    context_builder: ContextBuilder,
    tool_registry: ToolRegistry,
    config: PipelineConfig,
}

impl Pipeline {
    /// Process a message through the full pipeline
    pub async fn process(
        &self,
        session: &Session,
        message: &Message,
        provider: &dyn Provider,
        store: &dyn ConversationStore,
    ) -> Result<Message, PipelineError> {
        // 1. Build context (system prompt + history + tools)
        // 2. Send to provider
        // 3. Handle tool calls if any
        // 4. Return final response
    }
}

/// Configuration for the agent pipeline
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PipelineConfig {
    pub max_tool_iterations: usize,
    pub timeout_secs: u64,
    pub enable_tracing: bool,
    pub compaction_threshold: usize,
}

/// A tool available to the agent
pub struct Tool {
    pub name: String,
    pub description: String,
    pub parameters: serde_json::Value,
    pub handler: Box<dyn ToolHandler>,
}

/// Executes a single pipeline run
pub struct Runner {
    pipeline: Arc<Pipeline>,
    cancel_token: CancellationToken,
}

Pipeline Stages

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Context  │───▶│ Provider │───▶│  Tool    │───▶│ Response │
│ Assembly │    │   Call   │    │  Loop    │    │ Delivery │
└──────────┘    └──────────┘    └──────────┘    └──────────┘

1. Context Assembly — Builds the full conversation context with token budget management
2. Provider Call — Sends context to the AI provider
3. Tool Loop — Iterates if the model requests tool calls (max iterations configurable)
4. Response Delivery — Formats and returns the final response

Example Usage

use clawdesk_agents::{Pipeline, PipelineConfig, Tool};

let config = PipelineConfig {
    max_tool_iterations: 5,
    timeout_secs: 60,
    enable_tracing: true,
    compaction_threshold: 100,
};

let pipeline = Pipeline::new(config);

// Register tools
pipeline.register_tool(Tool {
    name: "calculator".into(),
    description: "Perform arithmetic".into(),
    parameters: serde_json::json!({
        "type": "object",
        "properties": {
            "expression": { "type": "string" }
        }
    }),
    handler: Box::new(CalculatorHandler),
});

// Process a message
let response = pipeline
    .process(&session, &message, &provider, &store)
    .await?;

tip

The pipeline supports cancellation via CancellationToken. Long-running tool loops can be interrupted without leaving the session in an inconsistent state.