Synwire

Synwire is an async-first Rust framework for building LLM-powered applications, designed around trait-based composition and zero unsafe code.

Key features

• Trait-based architecture -- swap providers, vector stores, and tools via trait objects
• Async-first -- all I/O uses async/await with Tokio
• Graph orchestration -- build stateful agent workflows with StateGraph
• Type-safe macros -- #[tool] and #[derive(State)] for ergonomic definitions
• Comprehensive testing -- FakeChatModel and FakeEmbeddings for offline testing
• Zero unsafe code -- #![forbid(unsafe_code)] in core crates

Quick example

use synwire_core::language_models::{FakeChatModel, BaseChatModel};
use synwire_core::messages::Message;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let model = FakeChatModel::new(vec!["Hello from Synwire!".into()]);
    let messages = vec![Message::human("Hi")];
    let result = model.invoke(&messages, None).await?;
    println!("{}", result.message.content().as_text());
    Ok(())
}

Crate overview

Navigation

• Getting Started -- step-by-step tutorials from first chat to graph agents
• How-To Guides -- task-focused recipes for common operations
• Explanation -- design rationale and architecture decisions
• Reference -- glossary, error guide, feature flags
• Contributing -- setup, style guide

First Chat

This tutorial walks through installing Synwire and making your first chat model invocation.

Add dependencies

Add the following to your Cargo.toml:

[dependencies]
synwire-core = "0.1"
tokio = { version = "1", features = ["full"] }

For testing without API keys, synwire-core includes FakeChatModel. To use a real provider, add synwire-llm-openai or synwire-llm-ollama.

Using FakeChatModel (no API key)

use synwire_core::language_models::{FakeChatModel, BaseChatModel};
use synwire_core::messages::Message;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // FakeChatModel returns pre-configured responses in order
    let model = FakeChatModel::new(vec![
        "I'm doing well, thanks for asking!".into(),
    ]);

    let messages = vec![Message::human("How are you?")];
    let result = model.invoke(&messages, None).await?;

    println!("{}", result.message.content().as_text());
    // Output: I'm doing well, thanks for asking!

    Ok(())
}

Using ChatOpenAI

Add synwire-llm-openai to your dependencies:

[dependencies]
synwire-llm-openai = "0.1"

use synwire_core::language_models::BaseChatModel;
use synwire_core::messages::Message;
use synwire_llm_openai::ChatOpenAI;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let model = ChatOpenAI::builder()
        .model("gpt-4o-mini")
        .api_key_env("OPENAI_API_KEY")
        .build()?;

    let messages = vec![Message::human("What is Rust?")];
    let result = model.invoke(&messages, None).await?;

    println!("{}", result.message.content().as_text());

    Ok(())
}

Multi-turn conversations

All chat models accept a slice of Message values. Build a conversation by including system, human, and AI messages:

use synwire_core::language_models::{FakeChatModel, BaseChatModel};
use synwire_core::messages::Message;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let model = FakeChatModel::new(vec![
        "Paris is the capital of France.".into(),
    ]);

    let messages = vec![
        Message::system("You are a helpful geography assistant."),
        Message::human("What is the capital of France?"),
    ];

    let result = model.invoke(&messages, None).await?;
    println!("{}", result.message.content().as_text());

    Ok(())
}

Batch invocation

Call batch to invoke on multiple inputs:

let inputs = vec![
    vec![Message::human("Question 1")],
    vec![Message::human("Question 2")],
];
let results = model.batch(&inputs, None).await?;
for r in &results {
    println!("{}", r.message.content().as_text());
}

Key types

Next steps

• Prompt Chains -- compose templates with models
• Streaming -- stream responses token by token

See also

• Local Inference with Ollama — run the same example with a local model, no API key required
• LLM Providers Explanation — choosing and swapping providers

Background: Zero-shot Prompting — how LLMs respond to instructions without examples.

Local Inference with Ollama

Ollama lets you run large language models on your own machine — no API key, no data leaving the network boundary. synwire-llm-ollama implements the same BaseChatModel and Embeddings traits as the OpenAI provider, so switching is a one-line change.

When to use Ollama:

• Privacy-sensitive workloads (data must not leave the machine)
• Air-gapped environments
• Development and testing without API costs
• Experimenting with open-weight models (Llama 3, Mistral, Gemma, Phi)

📖 Rust note: A trait is Rust's equivalent of an interface. BaseChatModel is a trait — because both ChatOllama and ChatOpenAI implement it, you can store either behind a Box<dyn BaseChatModel> and swap them without changing any other code.

Prerequisites

1. Install Ollama from https://ollama.com
2. Pull a model:

ollama pull llama3.2

3. Confirm it is running:

ollama run llama3.2 "hello"

Ollama listens on http://localhost:11434 by default.

Add the dependency

[dependencies]
synwire-llm-ollama = "0.1"
tokio = { version = "1", features = ["full"] }

Basic invoke

use synwire_llm_ollama::ChatOllama;
use synwire_core::language_models::chat::BaseChatModel;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let model = ChatOllama::builder()
        .model("llama3.2")
        .build()?;

    let result = model.invoke("What is the Rust borrow checker?").await?;
    println!("{}", result.content);
    Ok(())
}

Streaming

📖 Rust note: async fn and .await let this code run concurrently without blocking a thread. StreamExt::next().await yields each chunk as the model generates it — you see output appear progressively rather than waiting for the full response.

use synwire_llm_ollama::ChatOllama;
use synwire_core::language_models::chat::BaseChatModel;
use futures_util::StreamExt;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let model = ChatOllama::builder()
        .model("llama3.2")
        .build()?;

    let mut stream = model.stream("Explain ownership in Rust step by step.").await?;
    while let Some(chunk) = stream.next().await {
        print!("{}", chunk?.content);
    }
    println!();
    Ok(())
}

Local RAG with OllamaEmbeddings

Use a local embedding model so that retrieval-augmented generation never sends data to an external API:

ollama pull nomic-embed-text

use synwire_llm_ollama::{ChatOllama, OllamaEmbeddings};
use synwire_core::embeddings::Embeddings;
use synwire_core::language_models::chat::BaseChatModel;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let embeddings = OllamaEmbeddings::builder()
        .model("nomic-embed-text")
        .build()?;

    // Embed your documents
    let docs = vec![
        "Rust ownership means each value has exactly one owner.".to_string(),
        "The borrow checker enforces ownership rules at compile time.".to_string(),
    ];
    let vectors = embeddings.embed_documents(docs).await?;
    println!("Embedded {} documents, dimension {}", vectors.len(), vectors[0].len());

    // Embed a query
    let query_vec = embeddings.embed_query("what is ownership?").await?;
    println!("Query vector dimension: {}", query_vec.len());

    // Use vectors with your vector store, then answer with the chat model:
    let model = ChatOllama::builder().model("llama3.2").build()?;
    let answer = model.invoke("Given context about Rust ownership, explain it simply.").await?;
    println!("{}", answer.content);

    Ok(())
}

See Getting Started: RAG for a complete retrieval-augmented generation example.

Swapping from OpenAI to Ollama

Store the model as Box<dyn BaseChatModel> — swap by changing the constructor:

#![allow(unused)]
fn main() {
use synwire_core::language_models::chat::BaseChatModel;

fn build_model() -> anyhow::Result<Box<dyn BaseChatModel>> {
    if std::env::var("USE_LOCAL").is_ok() {
        // Local: no API key required
        Ok(Box::new(
            synwire_llm_ollama::ChatOllama::builder().model("llama3.2").build()?
        ))
    } else {
        // Cloud: reads OPENAI_API_KEY from environment
        Ok(Box::new(
            synwire_llm_openai::ChatOpenAI::builder()
                .model("gpt-4o")
                .api_key_env("OPENAI_API_KEY")
                .build()?
        ))
    }
}
}

All downstream code that calls model.invoke(...) or model.stream(...) is unchanged.

Builder options

See also

• Getting Started: First Chat — the same example using OpenAI
• Getting Started: RAG — full retrieval pipeline (add OllamaEmbeddings for local RAG)
• LLM Providers Explanation — choosing and swapping providers
• How-To: Switch Provider

Prompt Chains

This tutorial shows how to use PromptTemplate and compose chains of runnables.

Prompt templates

PromptTemplate formats strings with named variables:

use std::collections::HashMap;
use synwire_core::prompts::PromptTemplate;

let template = PromptTemplate::new(
    "Tell me a joke about {topic}",
    vec!["topic".into()],
);

let mut vars = HashMap::new();
vars.insert("topic".into(), "Rust programming".into());
let prompt = template.format(&vars)?;
// "Tell me a joke about Rust programming"

Template + Model + Parser

Compose a prompt template with a model and output parser:

use std::collections::HashMap;
use synwire_core::language_models::{FakeChatModel, BaseChatModel};
use synwire_core::messages::Message;
use synwire_core::output_parsers::{OutputParser, StrOutputParser};
use synwire_core::prompts::PromptTemplate;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Create a template
    let template = PromptTemplate::new(
        "Explain {concept} in one sentence.",
        vec!["concept".into()],
    );

    // 2. Format the prompt
    let mut vars = HashMap::new();
    vars.insert("concept".into(), "ownership in Rust".into());
    let prompt = template.format(&vars)?;

    // 3. Invoke the model
    let model = FakeChatModel::new(vec![
        "Ownership is Rust's system for managing memory without a garbage collector.".into(),
    ]);
    let result = model.invoke(&[Message::human(&prompt)], None).await?;

    // 4. Parse the output
    let parser = StrOutputParser;
    let output = parser.parse(&result.message.content().as_text())?;
    println!("{output}");

    Ok(())
}

Chat prompt templates

For multi-message prompts, use ChatPromptTemplate:

use synwire_core::prompts::{ChatPromptTemplate, MessageTemplate};

let chat_template = ChatPromptTemplate::new(vec![
    MessageTemplate::system("You are a {role}."),
    MessageTemplate::human("{question}"),
]);

RunnableCore composition

All components implement RunnableCore with serde_json::Value as the universal I/O type. This enables heterogeneous chaining:

use synwire_core::runnables::{RunnableCore, RunnableLambda, pipe};

// Create a lambda runnable
let add_prefix = RunnableLambda::new(|input: serde_json::Value| {
    let text = input.as_str().unwrap_or_default();
    Ok(serde_json::json!(format!("Processed: {text}")))
});

Output parsers

Next steps

• Streaming -- stream responses incrementally
• RAG -- add retrieval-augmented generation

Background: Prompt Chaining — the technique of decomposing a task into sequential LLM calls, each building on the previous output.

Streaming

This tutorial shows how to stream responses from chat models token by token.

Basic streaming

Every BaseChatModel provides a stream method that returns a BoxStream of ChatChunk values:

use futures_util::StreamExt;
use synwire_core::language_models::{FakeChatModel, BaseChatModel};
use synwire_core::messages::Message;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let model = FakeChatModel::new(vec!["Hello, world!".into()])
        .with_chunk_size(3); // Split into 3-character chunks

    let messages = vec![Message::human("Greet me")];
    let mut stream = model.stream(&messages, None).await?;

    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        if let Some(content) = &chunk.delta_content {
            print!("{content}");
        }
    }
    println!();
    // Output: Hel lo, wo rld !

    Ok(())
}

Streaming with OpenAI

use futures_util::StreamExt;
use synwire_core::language_models::BaseChatModel;
use synwire_core::messages::Message;
use synwire_llm_openai::ChatOpenAI;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let model = ChatOpenAI::builder()
        .model("gpt-4o-mini")
        .api_key_env("OPENAI_API_KEY")
        .build()?;

    let messages = vec![Message::human("Write a haiku about Rust")];
    let mut stream = model.stream(&messages, None).await?;

    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        if let Some(content) = &chunk.delta_content {
            print!("{content}");
        }
    }
    println!();

    Ok(())
}

ChatChunk fields

Collecting streamed output

To accumulate the full response:

let mut full_text = String::new();
while let Some(chunk) = stream.next().await {
    let chunk = chunk?;
    if let Some(content) = &chunk.delta_content {
        full_text.push_str(content);
    }
}

Error handling during streaming

Errors can occur mid-stream. Handle them per-chunk:

while let Some(result) = stream.next().await {
    match result {
        Ok(chunk) => { /* process chunk */ }
        Err(e) => {
            eprintln!("Stream error: {e}");
            break;
        }
    }
}

Testing streams

FakeChatModel supports configurable chunking and error injection for stream testing:

// Split into 5-char chunks, inject error after 2 chunks
let model = FakeChatModel::new(vec!["abcdefghij".into()])
    .with_chunk_size(5)
    .with_stream_error_after(2);

Next steps

• RAG -- retrieval-augmented generation
• Tools and Agents -- tool-using agents

RAG (Retrieval-Augmented Generation)

This tutorial builds a RAG pipeline using vector stores, embeddings, and a retriever.

Overview

A RAG pipeline:

1. Splits documents into chunks
2. Embeds chunks into a vector store
3. Retrieves relevant chunks for a query
4. Passes retrieved context to the model

Dependencies

[dependencies]
synwire-core = "0.1"
synwire = "0.1"
tokio = { version = "1", features = ["full"] }

Full example with fake models

use synwire::text_splitters::RecursiveCharacterTextSplitter;
use synwire_core::documents::Document;
use synwire_core::embeddings::FakeEmbeddings;
use synwire_core::language_models::{FakeChatModel, BaseChatModel};
use synwire_core::messages::Message;
use synwire_core::vectorstores::{InMemoryVectorStore, VectorStore};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Split documents
    let splitter = RecursiveCharacterTextSplitter::new(100, 20);
    let text = "Rust is a systems programming language. \
                It emphasises safety and performance. \
                The ownership system prevents data races.";
    let chunks = splitter.split_text(text);

    // 2. Create documents from chunks
    let docs: Vec<Document> = chunks
        .into_iter()
        .map(|chunk| Document::new(chunk))
        .collect();

    // 3. Add to vector store
    let embeddings = FakeEmbeddings::new(32);
    let store = InMemoryVectorStore::new();
    let _ids = store.add_documents(&docs, &embeddings).await?;

    // 4. Retrieve relevant documents
    let results = store
        .similarity_search("What is Rust?", 2, &embeddings)
        .await?;

    // 5. Build context and query the model
    let context: String = results
        .iter()
        .map(|doc| doc.page_content.as_str())
        .collect::<Vec<_>>()
        .join("\n");

    let model = FakeChatModel::new(vec![
        "Rust is a systems programming language focused on safety.".into(),
    ]);

    let prompt = format!(
        "Answer based on this context:\n{context}\n\nQuestion: What is Rust?"
    );
    let result = model.invoke(&[Message::human(&prompt)], None).await?;
    println!("{}", result.message.content().as_text());

    Ok(())
}

Cached embeddings

Use CacheBackedEmbeddings to avoid recomputing embeddings:

use std::sync::Arc;
use synwire::cache::CacheBackedEmbeddings;
use synwire_core::embeddings::FakeEmbeddings;

let embeddings = Arc::new(FakeEmbeddings::new(32));
let cached = CacheBackedEmbeddings::new(embeddings, 1000); // cache up to 1000 entries

Similarity search with scores

let scored_results = store
    .similarity_search_with_score("query", 5, &embeddings)
    .await?;

for (doc, score) in &scored_results {
    println!("Score: {score:.4} -- {}", doc.page_content);
}

VectorStoreRetriever

For integration with the Retriever trait:

use synwire_core::retrievers::{VectorStoreRetriever, SearchType};

let retriever = VectorStoreRetriever::new(store, embeddings, SearchType::Similarity, 4);

Next steps

• Tools and Agents -- add tool-using agents
• Graph Agents -- build stateful agent graphs

See also

• Local Inference with Ollama — use OllamaEmbeddings for local, private RAG with no API costs
• LLM Providers Explanation — swapping embedding providers

Background: Retrieval Augmented Generation — the pattern behind grounding LLM responses in external knowledge.

Tools and Agents

This tutorial shows how to define tools and create a ReAct agent that uses them.

Defining a tool

Implement the Tool trait:

use synwire_core::tools::{Tool, ToolOutput, ToolSchema};
use synwire_core::error::SynwireError;
use synwire_core::BoxFuture;

struct Calculator;

impl Tool for Calculator {
    fn name(&self) -> &str { "calculator" }
    fn description(&self) -> &str { "Evaluates simple maths expressions" }
    fn schema(&self) -> &ToolSchema {
        // In practice, store this in a field
        Box::leak(Box::new(ToolSchema {
            name: "calculator".into(),
            description: "Evaluates simple maths expressions".into(),
            parameters: serde_json::json!({
                "type": "object",
                "properties": {
                    "expression": {"type": "string"}
                },
                "required": ["expression"]
            }),
        }))
    }
    fn invoke(
        &self,
        input: serde_json::Value,
    ) -> BoxFuture<'_, Result<ToolOutput, SynwireError>> {
        Box::pin(async move {
            let expr = input["expression"].as_str().unwrap_or("0");
            Ok(ToolOutput {
                content: format!("Result: {expr}"),
                artifact: None,
            })
        })
    }
}

Using StructuredTool

For simpler tool definitions without implementing the trait manually:

use synwire_core::tools::StructuredTool;

let tool = StructuredTool::builder()
    .name("search")
    .description("Searches the web")
    .parameters(serde_json::json!({
        "type": "object",
        "properties": {
            "query": {"type": "string"}
        },
        "required": ["query"]
    }))
    .func(|input| Box::pin(async move {
        let query = input["query"].as_str().unwrap_or("");
        Ok(synwire_core::tools::ToolOutput {
            content: format!("Results for: {query}"),
            artifact: None,
        })
    }))
    .build()?;

Creating a ReAct agent

The create_react_agent function builds a graph that loops between the model and tools:

use synwire_core::language_models::{FakeChatModel, BaseChatModel};
use synwire_core::tools::Tool;
use synwire_orchestrator::prebuilt::create_react_agent;

let model: Box<dyn BaseChatModel> = Box::new(
    FakeChatModel::new(vec!["The answer is 42.".into()])
);
let tools: Vec<Box<dyn Tool>> = vec![/* your tools here */];

let graph = create_react_agent(model, tools)?;

let state = serde_json::json!({
    "messages": [
        {"type": "human", "content": "What is 6 * 7?"}
    ]
});

let result = graph.invoke(state).await?;

How ReAct works

The agent graph follows this pattern:

graph TD
    __start__([__start__]) --> agent
    agent -->|tool_calls present| tools
    agent -->|no tool_calls| __end__([__end__])
    tools --> agent

1. agent node: invokes the model with current messages
2. tools_condition: checks if the AI response contains tool calls
3. tools node: executes tool calls and appends results
4. Loop continues until the model responds without tool calls

Tool name validation

Tool names must match [a-zA-Z0-9_-]{1,64}:

use synwire_core::tools::validate_tool_name;

assert!(validate_tool_name("my-tool").is_ok());
assert!(validate_tool_name("my tool").is_err()); // spaces not allowed

Next steps

• Graph Agents -- build custom graph-based agents
• Derive Macros -- use #[tool] for ergonomic tool definitions

Background: Function Calling — how LLMs invoke structured tools. Background: ReAct — the Reason + Act pattern that most tool-using agents follow.

Graph Agents

This tutorial builds a custom graph-based agent using StateGraph from synwire-orchestrator.

Overview

A StateGraph is a directed graph where:

• Nodes are async functions that transform state
• Edges are transitions between nodes (static or conditional)
• State is a serde_json::Value passed through the graph

Basic graph

use synwire_orchestrator::graph::StateGraph;
use synwire_orchestrator::constants::END;
use synwire_orchestrator::error::GraphError;

#[tokio::main]
async fn main() -> Result<(), GraphError> {
    let mut graph = StateGraph::new();

    // Add a node that appends a greeting
    graph.add_node("greet", Box::new(|mut state| {
        Box::pin(async move {
            state["greeting"] = serde_json::json!("Hello!");
            Ok(state)
        })
    }))?;

    // Add a node that appends a farewell
    graph.add_node("farewell", Box::new(|mut state| {
        Box::pin(async move {
            state["farewell"] = serde_json::json!("Goodbye!");
            Ok(state)
        })
    }))?;

    // Wire the graph: start -> greet -> farewell -> end
    graph.set_entry_point("greet");
    graph.add_edge("greet", "farewell");
    graph.set_finish_point("farewell");

    // Compile and run
    let compiled = graph.compile()?;
    let result = compiled.invoke(serde_json::json!({})).await?;

    assert_eq!(result["greeting"], "Hello!");
    assert_eq!(result["farewell"], "Goodbye!");

    Ok(())
}

Conditional edges

Route execution based on state:

use std::collections::HashMap;
use synwire_orchestrator::constants::END;

// Condition function inspects state and returns a branch key
fn route(state: &serde_json::Value) -> String {
    if state["score"].as_i64().unwrap_or(0) > 80 {
        "pass".into()
    } else {
        "retry".into()
    }
}

let mut mapping = HashMap::new();
mapping.insert("pass".into(), END.into());
mapping.insert("retry".into(), "evaluate".into());

graph.add_conditional_edges("evaluate", Box::new(route), mapping);

Recursion limit

Guard against infinite loops:

let compiled = graph.compile()?
    .with_recursion_limit(10);

If execution exceeds the limit, GraphError::RecursionLimit is returned.

Visualisation

Generate a Mermaid diagram of your graph:

let mermaid = compiled.to_mermaid();
println!("{mermaid}");

Output:

graph TD
    __start__([__start__]) --> greet
    greet --> farewell
    farewell --> __end__([__end__])

Using with a chat model

Combine graph orchestration with model invocations:

use std::sync::Arc;
use synwire_core::language_models::{FakeChatModel, BaseChatModel};
use synwire_core::messages::Message;

let model = Arc::new(FakeChatModel::new(vec!["Processed.".into()]));

let model_ref = Arc::clone(&model);
graph.add_node("llm_node", Box::new(move |state| {
    let model = Arc::clone(&model_ref);
    Box::pin(async move {
        let query = state["query"].as_str().unwrap_or("");
        let result = model
            .invoke(&[Message::human(query)], None)
            .await
            .map_err(|e| GraphError::Core(e))?;
        let mut new_state = state;
        new_state["response"] = serde_json::json!(
            result.message.content().as_text()
        );
        Ok(new_state)
    })
}))?;

Next steps

• Derive Macros -- #[derive(State)] for typed graph state
• Add Checkpointing -- persist graph state
• Graph Interrupts -- pause and resume graphs

See also

• StateGraph vs FsmStrategy — when to use a graph pipeline vs a single-agent FSM
• Pregel Execution Model — how supersteps work under the hood
• synwire-orchestrator Explanation — channels and conditional routing

Background: AI Workflows vs AI Agents — the spectrum from deterministic pipelines to autonomous agents. Background: Introduction to Agents — agent architecture fundamentals.

Derive Macros

Synwire provides two procedural macros for ergonomic definitions: #[tool] and #[derive(State)].

#[tool] attribute macro

Transforms an annotated async function into a StructuredTool factory. The original function is preserved, and a companion {name}_tool() function is generated.

Usage

use synwire_derive::tool;
use synwire_core::error::SynwireError;

/// Searches the web for information.
#[tool]
async fn search(query: String) -> Result<String, SynwireError> {
    Ok(format!("Results for: {query}"))
}

// Generated: search_tool() -> Result<StructuredTool, SynwireError>

Parameter type mapping

Function parameters are automatically mapped to JSON Schema types:

Documentation

Doc comments on the function become the tool's description:

/// Calculates the sum of two numbers.
#[tool]
async fn add(a: i64, b: i64) -> Result<String, SynwireError> {
    Ok(format!("{}", a + b))
}
// Tool description: "Calculates the sum of two numbers."

#[derive(State)] derive macro

Generates channel configuration from struct field annotations for use with StateGraph.

Usage

use synwire_derive::State;

#[derive(State)]
struct AgentState {
    /// Messages accumulate via a Topic channel
    #[reducer(topic)]
    messages: Vec<String>,

    /// Current step uses LastValue (default)
    current_step: String,
}

// Generated: AgentState::channels() -> Vec<(String, Box<dyn BaseChannel>)>

Channel types

Using with StateGraph

use synwire_orchestrator::graph::StateGraph;

let channels = AgentState::channels();
// Use channels when configuring the graph

Combining both macros

A typical agent combines #[tool] for tool definitions and #[derive(State)] for graph state:

use synwire_derive::{tool, State};
use synwire_core::error::SynwireError;

#[derive(State)]
struct MyAgentState {
    #[reducer(topic)]
    messages: Vec<String>,
    result: String,
}

/// Looks up information in a database.
#[tool]
async fn lookup(key: String) -> Result<String, SynwireError> {
    Ok(format!("Value for {key}"))
}

Next steps

• Custom Tool -- more tool patterns
• Graph Agents -- use State with graphs

Your First Agent

Time: ~20 minutes Prerequisites: Rust 1.85+, Cargo, a working internet connection for crate downloads

By the end of this tutorial you will have a Rust program that constructs a Synwire agent, drives it with the Runner, and collects streaming events from the response. You will understand what each component does and how errors surface.

What you are building

A minimal binary that:

1. Constructs an Agent using the builder API.
2. Wraps it in a Runner.
3. Sends a single input message and reads the event stream to completion.
4. Prints any text delta and the termination reason.

Step 1: Create a new Cargo project

cargo new synwire-hello
cd synwire-hello

Step 2: Add Synwire to Cargo.toml

Open Cargo.toml and add the dependencies. If you are working inside the Synwire workspace, use the workspace path. For a standalone project, add version numbers from crates.io once the crate is published.

[dependencies]
# Core agent types (Agent builder, Runner, AgentError, AgentEvent)
synwire-core = { path = "../../crates/synwire-core" }

# Tokio async runtime
tokio = { version = "1", features = ["full"] }

# JSON value construction
serde_json = "1"

If you are working inside the Synwire repository workspace, use synwire-core = { workspace = true } and tokio = { workspace = true }.

Step 3: Write the agent

Replace the contents of src/main.rs:

use synwire_core::agents::agent_node::Agent;
use synwire_core::agents::runner::{Runner, RunnerConfig};
use synwire_core::agents::streaming::AgentEvent;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build the agent.
    //
    // Agent::new(name, model) creates the builder directly.
    // Every method on Agent consumes and returns `self`, so they chain.
    let agent: Agent = Agent::new("my-agent", "stub-model")
        .description("A simple demonstration agent")
        .max_turns(10);

    // The Runner drives the agent turn loop. It holds the agent behind an Arc
    // so it can be shared and stopped from another task if needed.
    let runner = Runner::new(agent);

    // runner.run() returns a channel receiver. The runner spawns a background
    // task that sends events; we read them in this loop.
    let config = RunnerConfig::default();
    let mut rx = runner
        .run(serde_json::json!("What is 2+2?"), config)
        .await?;

    // Drain the event stream until the channel closes.
    while let Some(event) = rx.recv().await {
        match event {
            AgentEvent::TextDelta { content } => {
                print!("{content}");
            }
            AgentEvent::TurnComplete { reason } => {
                println!("\n[done: {reason:?}]");
            }
            AgentEvent::Error { message } => {
                eprintln!("Agent error: {message}");
            }
            _ => {
                // Other events (UsageUpdate, ToolCallStart, etc.) are ignored here.
            }
        }
    }

    Ok(())
}

Run it:

cargo run

You will see [done: Complete] printed — the stub model finishes immediately. In a production setup you would provide a real LLM backend crate (such as synwire-llm-openai) that replaces the stub model invocation.

Step 4: Understand the Agent builder

Agent<O> is a plain builder struct. The type parameter O is the optional structured output type. Omitting it (or writing Agent without a type argument) defaults O to (), which means the agent returns unstructured text.

The builder fields you will use most often:

The builder is consumed by Runner::new(agent). After that point, configuration is fixed.

Step 5: Understand the Runner

Runner<O> drives the agent execution loop in a background Tokio task. It is intentionally stateless between calls to run().

#![allow(unused)]
fn main() {
// Create a runner from the agent.
let runner = Runner::new(agent);

// Override the model for one run without rebuilding the agent.
runner.set_model("gpt-4o").await;

// Start a run and receive the event channel.
let mut rx = runner.run(input, RunnerConfig::default()).await?;
}

RunnerConfig lets you pass per-run options:

#![allow(unused)]
fn main() {
use synwire_core::agents::runner::RunnerConfig;

let config = RunnerConfig {
    // Resume an existing conversation by session ID.
    session_id: Some("session-abc".to_string()),
    // Override the model for this single run.
    model_override: Some("claude-3-5-sonnet".to_string()),
    // Retry transient model errors up to this many times.
    max_retries: 3,
};
}

Step 6: Understand AgentError

Runner::run returns Result<mpsc::Receiver<AgentEvent>, AgentError>. The error fires only if setup fails before the event stream starts (for example, an invalid configuration).

AgentError is #[non_exhaustive], meaning new variants may be added in future releases. Always include a catch-all arm:

#![allow(unused)]
fn main() {
use synwire_core::agents::error::AgentError;

async fn run_agent(runner: &Runner) -> Result<(), AgentError> {
    let config = RunnerConfig::default();
    let mut rx = runner
        .run(serde_json::json!("Hello"), config)
        .await?;   // <-- AgentError propagated here with `?`

    while let Some(event) = rx.recv().await {
        if let AgentEvent::Error { message } = event {
            // Errors during the run arrive as events, not as Err(AgentError).
            eprintln!("runtime error: {message}");
        }
    }
    Ok(())
}
}

The key AgentError variants you are likely to encounter:

Because AgentError is #[non_exhaustive], write:

#![allow(unused)]
fn main() {
match err {
    AgentError::Model(model_err) => { /* ... */ }
    AgentError::BudgetExceeded(cost) => { /* ... */ }
    _ => eprintln!("unexpected agent error: {err}"),
}
}

Step 7: Read the full event stream

AgentEvent carries all observable agent behaviour. The events you should always handle:

The channel closes after the TurnComplete (or Error) event, so rx.recv().await returning None is the correct loop termination signal.

Stopping an agent from outside

You can stop a running agent by holding an Arc<Runner> and calling stop_graceful or stop_force from another task:

#![allow(unused)]
fn main() {
use std::sync::Arc;

let runner = Arc::new(Runner::new(agent));
let runner_handle = Arc::clone(&runner);

// Spawn the run.
let mut rx = runner.run(serde_json::json!("Long task"), RunnerConfig::default()).await?;

// In another task, stop after 5 seconds.
tokio::spawn(async move {
    tokio::time::sleep(std::time::Duration::from_secs(5)).await;
    runner_handle.stop_graceful().await;
});

// Drain events normally; you will receive TurnComplete { reason: Stopped }.
while let Some(event) = rx.recv().await {
    // ...
}
}

Next steps

• Add tools: See ../how-to/tools.md for registering typed tool handlers.
• Structured output: See ../how-to/structured_output.md for binding Agent<MyType>.
• Understanding the event model: See ../explanation/event_model.md for a deep dive into how events, turns, and retries interact.
• Next tutorial: Continue with 02-pure-directive-testing.md to learn how to test agent logic without executing any side effects.

Background: Agent Components — the memory, tools, and planning components of an agent; all three appear in this tutorial.

Testing Agent Logic Without Side Effects

Time: ~25 minutes Prerequisites: Completed 01-first-agent.md, familiarity with Rust #[test]

Agent nodes often want to spawn child agents, emit events, or stop themselves. These are side effects that are expensive or inconvenient to trigger in unit tests. Synwire separates the description of effects from their execution through the directive/effect pattern. This tutorial teaches you to write pure node functions, assert on the directives they return, and verify nothing actually executed.

What you are building

A counter agent node that:

1. Increments a counter in state.
2. Emits a SpawnAgent directive when the counter reaches a threshold.
3. Emits a Stop directive when it reaches a hard limit.

You will test all three behaviours without running any LLM or spawning any real child agent.

Step 1: Understand DirectiveResult

DirectiveResult<S> is the return type of a pure agent node function:

#![allow(unused)]
fn main() {
pub struct DirectiveResult<S: State> {
    pub state: S,
    pub directives: Vec<Directive>,
}
}

• state is the new state value after the node ran. It is applied immediately.
• directives is a list of effects to be executed by the runtime later.

The split matters: your node function can be a plain synchronous fn returning a DirectiveResult. It does not need to be async, does not take a runtime reference, and cannot accidentally trigger real side effects.

Step 2: Define a State type

Add this to src/lib.rs (or a test module):

#![allow(unused)]
fn main() {
use serde::{Deserialize, Serialize};
use serde_json::Value;
use synwire_core::State;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CounterState {
    pub count: u32,
}

impl State for CounterState {
    fn to_value(&self) -> Result<Value, Box<dyn std::error::Error + Send + Sync>> {
        Ok(serde_json::to_value(self)?)
    }

    fn from_value(value: Value) -> Result<Self, Box<dyn std::error::Error + Send + Sync>> {
        Ok(serde_json::from_value(value)?)
    }
}
}

State requires Send + Sync + Clone + Serialize + DeserializeOwned. The body of both methods is identical for almost every concrete state type — delegate to serde_json.

Step 3: Write the pure node function

#![allow(unused)]
fn main() {
use synwire_core::agents::directive::{Directive, DirectiveResult};
use serde_json::json;

const SPAWN_THRESHOLD: u32 = 3;
const STOP_LIMIT: u32 = 5;

pub fn counter_node(state: CounterState) -> DirectiveResult<CounterState> {
    let new_count = state.count + 1;
    let new_state = CounterState { count: new_count };

    if new_count >= STOP_LIMIT {
        // Request agent stop. The runtime will act on this; the node does not.
        return DirectiveResult::with_directive(
            new_state,
            Directive::Stop {
                reason: Some(format!("limit {STOP_LIMIT} reached")),
            },
        );
    }

    if new_count == SPAWN_THRESHOLD {
        // Request spawning a helper agent. Config is arbitrary JSON.
        return DirectiveResult::with_directive(
            new_state,
            Directive::SpawnAgent {
                name: "helper-agent".to_string(),
                config: json!({ "model": "gpt-4o-mini", "task": "summarise" }),
            },
        );
    }

    // No side effects — state only.
    DirectiveResult::state_only(new_state)
}
}

Key constructors on DirectiveResult:

Step 4: The Directive enum

Directive is #[non_exhaustive]. The variants you will use most often:

Step 5: Write unit tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    use synwire_core::agents::directive::Directive;

    #[test]
    fn increments_count() {
        let state = CounterState { count: 0 };
        let result = counter_node(state);

        assert_eq!(result.state.count, 1);
        assert!(result.directives.is_empty(), "no side effects below threshold");
    }

    #[test]
    fn spawns_agent_at_threshold() {
        let state = CounterState { count: SPAWN_THRESHOLD - 1 };
        let result = counter_node(state);

        assert_eq!(result.state.count, SPAWN_THRESHOLD);
        assert_eq!(result.directives.len(), 1);
        assert!(
            matches!(
                &result.directives[0],
                Directive::SpawnAgent { name, .. } if name == "helper-agent"
            ),
            "expected SpawnAgent directive"
        );
    }

    #[test]
    fn stops_at_limit() {
        let state = CounterState { count: STOP_LIMIT - 1 };
        let result = counter_node(state);

        assert_eq!(result.state.count, STOP_LIMIT);
        assert_eq!(result.directives.len(), 1);
        assert!(
            matches!(&result.directives[0], Directive::Stop { .. }),
            "expected Stop directive"
        );
    }

    #[test]
    fn stop_reason_is_set() {
        let state = CounterState { count: STOP_LIMIT - 1 };
        let result = counter_node(state);

        if let Directive::Stop { reason } = &result.directives[0] {
            assert!(reason.is_some(), "reason should be set");
            assert!(reason.as_ref().unwrap().contains("limit"));
        } else {
            panic!("expected Stop directive");
        }
    }
}
}

Run:

cargo test

All four tests pass with zero network calls, zero spawned processes, and zero LLM tokens.

Step 6: Use NoOpExecutor to confirm no execution

In integration tests you may wire your node function into a broader harness that passes directives to an executor. NoOpExecutor records nothing and executes nothing — it always returns Ok(None):

#![allow(unused)]
fn main() {
#[cfg(test)]
mod executor_tests {
    use synwire_core::agents::directive::{Directive, DirectiveResult};
    use synwire_core::agents::directive_executor::{DirectiveExecutor, NoOpExecutor};

    #[tokio::test]
    async fn noop_executor_does_not_execute() {
        let executor = NoOpExecutor;
        let directive = Directive::SpawnAgent {
            name: "child".to_string(),
            config: serde_json::json!({}),
        };

        // execute_directive returns Ok(None) — no child was spawned.
        let result = executor
            .execute_directive(&directive)
            .await
            .expect("executor should not error");

        assert!(result.is_none(), "NoOpExecutor never returns a value");
    }
}
}

When you later integrate a real executor (for example one that makes HTTP calls to spawn agents), you can substitute NoOpExecutor in tests while keeping the same node functions.

Step 7: Serde round-trip

Directive derives Serialize and Deserialize, with #[serde(tag = "type")]. This lets you persist directives to a queue, send them over the wire, or log them for auditing.

#![allow(unused)]
fn main() {
#[cfg(test)]
mod serde_tests {
    use synwire_core::agents::directive::Directive;

    #[test]
    fn stop_directive_round_trips() {
        let original = Directive::Stop {
            reason: Some("task complete".to_string()),
        };

        let json = serde_json::to_string(&original).expect("serialize");

        // The discriminant is the "type" field.
        assert!(json.contains(r#""type":"stop""#));

        let deserialized: Directive = serde_json::from_str(&json).expect("deserialize");
        assert!(matches!(deserialized, Directive::Stop { .. }));
    }

    #[test]
    fn spawn_agent_directive_round_trips() {
        let original = Directive::SpawnAgent {
            name: "worker".to_string(),
            config: serde_json::json!({ "model": "gpt-4o" }),
        };

        let json = serde_json::to_string(&original).expect("serialize");
        assert!(json.contains(r#""type":"spawn_agent""#));

        let back: Directive = serde_json::from_str(&json).expect("deserialize");
        assert!(matches!(back, Directive::SpawnAgent { name, .. } if name == "worker"));
    }

    #[test]
    fn run_instruction_directive_round_trips() {
        let original = Directive::RunInstruction {
            instruction: "summarise this text".to_string(),
            input: serde_json::json!({ "text": "hello world" }),
        };

        let json = serde_json::to_string(&original).expect("serialize");
        let back: Directive = serde_json::from_str(&json).expect("deserialize");
        assert!(matches!(back, Directive::RunInstruction { .. }));
    }
}
}

The serialised form uses "type" as the tag field. For example, Directive::Stop becomes:

{"type":"stop","reason":"task complete"}

What you have learned

• DirectiveResult<S> separates state mutation from side-effect description.
• Pure node functions are plain synchronous fns — no async, no runtime references.
• The Directive enum describes every possible side effect.
• NoOpExecutor lets you wire the executor interface into tests without executing anything.
• Directive is fully serialisable for logging, queueing, or persistence.

Next steps

• Execution strategies: Continue with 03-execution-strategies.md to learn how to constrain which actions an agent can take based on FSM state.
• Custom directives: See ../explanation/directive_system.md for implementing a custom DirectivePayload via typetag.
• How-to guide: See ../how-to/testing.md for composing test fixtures with synwire-test-utils proptest strategies.

Controlling Agent Behaviour with Execution Strategies

Time: ~30 minutes Prerequisites: Completed 02-pure-directive-testing.md, basic understanding of finite-state machines

An execution strategy constrains how an agent orchestrates actions. By default agents use DirectStrategy, which accepts any action immediately. When you need to enforce an ordered workflow — for example, an agent that must authenticate before it can process data — you use FsmStrategy to model the allowed transitions as a state machine.

This tutorial covers both strategies and shows how to add guard conditions that inspect input before allowing a transition.

What you are building

1. A DirectStrategy agent that accepts any action.
2. An FsmStrategy for a simple three-state workflow: idle → running → done.
3. A guard that rejects a transition based on input content.
4. Snapshot serialisation to inspect FSM state.

Step 1: Add dependencies

[dependencies]
synwire-core = { path = "../../crates/synwire-core" }
synwire-agent = { path = "../../crates/synwire-agent" }
tokio = { version = "1", features = ["full"] }
serde_json = "1"

Step 2: DirectStrategy — immediate execution

DirectStrategy is the simplest implementation of ExecutionStrategy. It accepts any action and passes the input through unchanged as its output. There is no state to set up and no builder step — just construct and call:

use synwire_agent::strategies::DirectStrategy;
use synwire_core::agents::execution_strategy::ExecutionStrategy;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let strategy = DirectStrategy::new();

    // Execute any action — DirectStrategy never rejects.
    let output = strategy
        .execute("generate_text", json!({ "prompt": "hello" }))
        .await?;

    println!("output: {output}");

    // Snapshot tells you the strategy type.
    let snap = strategy.snapshot()?;
    let snap_value = snap.to_value()?;
    println!("snapshot: {snap_value}");  // {"type":"direct"}

    Ok(())
}

DirectStrategy is appropriate when:

• The agent orchestrates LLM calls without a defined state machine.
• You want no constraints on action ordering.
• You are prototyping and will add an FSM later.

Step 3: FsmStrategy — state-constrained execution

FsmStrategy models the allowed actions as a directed graph. Each node is a state and each edge is an (action, target-state) pair. The FSM rejects any action not defined for the current state.

Build the FSM with FsmStrategy::builder():

use synwire_agent::strategies::{FsmStrategy, FsmStrategyWithRoutes};
use synwire_core::agents::execution_strategy::{ExecutionStrategy, StrategyError};
use serde_json::json;

fn build_workflow_fsm() -> Result<FsmStrategyWithRoutes, StrategyError> {
    FsmStrategy::builder()
        // Declare states for readability (optional — states are inferred from transitions).
        .state("idle")
        .state("running")
        .state("done")
        // Set the state the FSM starts in.
        .initial("idle")
        // Define allowed transitions: (from, action, to).
        .transition("idle", "start", "running")
        .transition("running", "finish", "done")
        .build()
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let fsm = build_workflow_fsm()?;

    // Valid transition: idle --start--> running.
    fsm.execute("start", json!({})).await?;
    println!("state: {:?}", fsm.strategy.current_state()?);  // running

    // Valid transition: running --finish--> done.
    fsm.execute("finish", json!({})).await?;
    println!("state: {:?}", fsm.strategy.current_state()?);  // done

    Ok(())
}

FsmStrategy::builder().build() returns FsmStrategyWithRoutes (not FsmStrategy directly). FsmStrategyWithRoutes implements ExecutionStrategy and bundles any signal routes defined on the builder. The inner FsmStrategy is available as the public .strategy field when you need to call current_state().

Step 4: Handle invalid transitions

When you call execute with an action that has no transition from the current state, you receive StrategyError::InvalidTransition:

#![allow(unused)]
fn main() {
#[tokio::test]
async fn test_invalid_transition() {
    let fsm = FsmStrategy::builder()
        .initial("idle")
        .state("idle")
        .state("running")
        .transition("idle", "start", "running")
        .build()
        .expect("valid FSM");

    // "finish" is not a valid action from "idle".
    let err = fsm
        .execute("finish", serde_json::json!({}))
        .await
        .expect_err("should reject unknown action");

    match err {
        StrategyError::InvalidTransition {
            current_state,
            attempted_action,
            valid_actions,
        } => {
            assert_eq!(current_state, "idle");
            assert_eq!(attempted_action, "finish");
            // valid_actions lists what IS allowed from the current state.
            assert!(valid_actions.contains(&"start".to_string()));
        }
        other => panic!("unexpected error: {other}"),
    }
}
}

The error message from Display is also human-readable:

Invalid transition from idle via finish. Valid actions: ["start"]

Note that StrategyError is #[non_exhaustive]; always include a catch-all arm in match blocks.

Step 5: Add a ClosureGuard

Guards let you inspect the action input before committing to a transition. Use transition_with_guard and provide a ClosureGuard:

#![allow(unused)]
fn main() {
use synwire_agent::strategies::FsmStrategy;
use synwire_core::agents::execution_strategy::{ClosureGuard, ExecutionStrategy, StrategyError};
use serde_json::json;

#[tokio::test]
async fn test_guard_on_transition() {
    // Guard: only allow "start" when the input contains a non-empty "task" field.
    let has_task = ClosureGuard::new("requires-task", |input| {
        input
            .get("task")
            .and_then(|v| v.as_str())
            .is_some_and(|s| !s.is_empty())
    });

    let fsm = FsmStrategy::builder()
        .initial("idle")
        .transition_with_guard("idle", "start", "running", has_task, 0)
        .build()
        .expect("valid FSM");

    // Input without "task" — guard rejects.
    let err = fsm
        .execute("start", json!({}))
        .await
        .expect_err("guard should reject");
    assert!(matches!(err, StrategyError::GuardRejected(_)));

    // Input with "task" — guard passes, transition succeeds.
    fsm.execute("start", json!({ "task": "summarise" }))
        .await
        .expect("guard should pass");
    assert_eq!(
        fsm.strategy.current_state().expect("state").0,
        "running"
    );
}
}

ClosureGuard::new(name, f) wraps any Fn(&Value) -> bool closure. The name string appears in StrategyError::GuardRejected messages to help diagnose failures.

Step 6: Priority ordering with multiple guards

When multiple transitions share the same (from, action) key, the FSM evaluates them in descending priority order and accepts the first one whose guard passes:

#![allow(unused)]
fn main() {
use synwire_agent::strategies::FsmStrategy;
use synwire_core::agents::execution_strategy::{ClosureGuard, ExecutionStrategy};
use serde_json::json;

#[tokio::test]
async fn test_priority_ordering() {
    // Priority 10: premium path — only when input has "premium": true.
    let premium_guard = ClosureGuard::new("premium", |v| {
        v.get("premium").and_then(|p| p.as_bool()).unwrap_or(false)
    });

    // Priority 5: standard path — always passes.
    let standard_guard = ClosureGuard::new("always", |_| true);

    let fsm = FsmStrategy::builder()
        .initial("idle")
        .transition_with_guard("idle", "start", "premium-queue", premium_guard, 10)
        .transition_with_guard("idle", "start", "standard-queue", standard_guard, 5)
        .build()
        .expect("valid FSM");

    // Non-premium input: premium guard (priority 10) fails, standard guard (priority 5) passes.
    fsm.execute("start", json!({ "premium": false }))
        .await
        .expect("standard path");
    assert_eq!(
        fsm.strategy.current_state().expect("state").0,
        "standard-queue"
    );
}
}

The priority parameter is an i32. Higher values are evaluated first.

Step 7: Snapshot the FSM state

ExecutionStrategy::snapshot() captures the current state of the strategy as a Box<dyn StrategySnapshot>. Call to_value() to serialise it:

#![allow(unused)]
fn main() {
use synwire_agent::strategies::FsmStrategy;
use synwire_core::agents::execution_strategy::ExecutionStrategy;
use serde_json::json;

#[tokio::test]
async fn test_fsm_snapshot() {
    let fsm = FsmStrategy::builder()
        .initial("idle")
        .transition("idle", "start", "running")
        .build()
        .expect("valid FSM");

    // Snapshot before transition.
    let before = fsm.snapshot().expect("snapshot").to_value().expect("to_value");
    assert_eq!(before["type"], "fsm");
    assert_eq!(before["current_state"], "idle");

    fsm.execute("start", json!({})).await.expect("transition");

    // Snapshot after transition.
    let after = fsm.snapshot().expect("snapshot").to_value().expect("to_value");
    assert_eq!(after["current_state"], "running");
}
}

The snapshot for DirectStrategy is simpler:

#![allow(unused)]
fn main() {
use synwire_agent::strategies::DirectStrategy;
use synwire_core::agents::execution_strategy::ExecutionStrategy;

let snap = DirectStrategy::new()
    .snapshot()
    .expect("snapshot")
    .to_value()
    .expect("to_value");
assert_eq!(snap, serde_json::json!({"type": "direct"}));
}

Snapshots are useful for persisting workflow state to a checkpoint store so a long-running agent can resume after a restart.

Step 8: Signal routes

FsmStrategyBuilder::route attaches SignalRoute values to the built strategy. Signal routes tell the agent runtime how to map incoming external signals to FSM actions. They are declared at build time and queried via ExecutionStrategy::signal_routes():

#![allow(unused)]
fn main() {
use synwire_agent::strategies::FsmStrategy;
use synwire_core::agents::signal::SignalRoute;
use synwire_core::agents::execution_strategy::ExecutionStrategy;

let fsm = FsmStrategy::builder()
    .initial("idle")
    .transition("idle", "start", "running")
    .route(SignalRoute {
        signal: "user.message".to_string(),
        action: "start".to_string(),
    })
    .build()
    .expect("valid FSM");

let routes = fsm.signal_routes();
assert_eq!(routes.len(), 1);
assert_eq!(routes[0].signal, "user.message");
assert_eq!(routes[0].action, "start");
}

See ../explanation/signal_routing.md for how the runtime dispatches signals.

Summary

Next steps

• Plugin state: Continue with 04-plugin-state-isolation.md to learn how plugins attach isolated state slices to an agent.
• Persisting snapshots: See ../how-to/checkpointing.md for storing FSM snapshots in the SQLite checkpoint backend.
• Deep dive: See ../explanation/execution_strategies.md for the full lifecycle of a strategy within the runner loop.

See also

• StateGraph vs FsmStrategy — when to use the state machine vs a graph pipeline
• FSM Strategy Design — guard semantics and transition priority

Background: AI Workflows vs AI Agents — when structured workflows outperform unconstrained agents.

Composing Plugins with Type-Safe State

Time: ~30 minutes Prerequisites: Completed 01-first-agent.md, familiarity with Rust generics

Synwire agents support a plugin system that lets independent modules each hold their own private state alongside the agent, without being able to interfere with one another. The isolation is enforced at compile time through Rust's type system, not at runtime through naming conventions.

This tutorial shows you how to define plugin state keys, store state in a PluginStateMap, access it through typed handles, implement the Plugin lifecycle trait, and verify that two plugins cannot read each other's data.

What you are building

Two plugins:

• CachePlugin — holds a simple in-memory cache with a hit counter.
• MetricsPlugin — holds a message count.

You will verify that mutating CachePlugin state does not affect MetricsPlugin state, and that PluginStateMap enforces this isolation.

Step 1: Add dependencies

[dependencies]
synwire-core = { path = "../../crates/synwire-core" }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

Step 2: Understand PluginStateKey

PluginStateKey is a marker trait that pairs a zero-sized key type with its associated state type and a unique string identifier:

#![allow(unused)]
fn main() {
pub trait PluginStateKey: Send + Sync + 'static {
    type State: Send + Sync + 'static;
    const KEY: &'static str;
}
}

• type State is the concrete data type stored for this plugin.
• KEY is a stable string used in serialised output (e.g. debug dumps or checkpoints). It must be unique across all plugins in an agent. Duplicate registrations are detected at runtime and return an error.

The key type itself is never instantiated — it is purely a compile-time token.

Step 3: Define the CachePlugin key and state

#![allow(unused)]
fn main() {
use std::collections::HashMap;
use serde::{Deserialize, Serialize};
use synwire_core::agents::plugin::PluginStateKey;

/// State stored by CachePlugin.
#[derive(Debug, Default, Serialize, Deserialize)]
pub struct CacheState {
    pub hits: u32,
    pub entries: HashMap<String, String>,
}

/// Zero-sized key type. Never instantiated.
pub struct CachePlugin;

impl PluginStateKey for CachePlugin {
    type State = CacheState;
    const KEY: &'static str = "cache";
}
}

Step 4: Define the MetricsPlugin key and state

#![allow(unused)]
fn main() {
/// State stored by MetricsPlugin.
#[derive(Debug, Default, Serialize, Deserialize)]
pub struct MetricsState {
    pub messages_processed: u64,
}

/// Zero-sized key type.
pub struct MetricsPlugin;

impl PluginStateKey for MetricsPlugin {
    type State = MetricsState;
    const KEY: &'static str = "metrics";
}
}

Step 5: Register state in PluginStateMap

PluginStateMap is the container that holds all plugin state slices for one agent instance. Register each plugin's initial state with register:

#![allow(unused)]
fn main() {
use synwire_core::agents::plugin::{PluginHandle, PluginStateMap};

fn create_plugin_map() -> (PluginStateMap, PluginHandle<CachePlugin>, PluginHandle<MetricsPlugin>) {
    let mut map = PluginStateMap::new();

    // register() returns a PluginHandle — a zero-sized proof token.
    // If you try to register the same type twice, register() returns Err(KEY).
    let cache_handle = map
        .register::<CachePlugin>(CacheState::default())
        .expect("cache not yet registered");

    let metrics_handle = map
        .register::<MetricsPlugin>(MetricsState::default())
        .expect("metrics not yet registered");

    (map, cache_handle, metrics_handle)
}
}

PluginHandle<P> is a Copy + Clone zero-sized struct. Holding one proves that the plugin is registered in the associated map. It has no runtime data — it is a compile-time witness only.

Step 6: Read and write through typed access

PluginStateMap::get::<P>() and get_mut::<P>() are generic over the key type. They return Option<&P::State> and Option<&mut P::State> respectively. The type checker prevents you from using the wrong key:

#![allow(unused)]
fn main() {
#[test]
fn read_and_write_cache_state() {
    let (mut map, _cache, _metrics) = create_plugin_map();

    // Read initial state.
    let state = map.get::<CachePlugin>().expect("cache registered");
    assert_eq!(state.hits, 0);
    assert!(state.entries.is_empty());

    // Mutate via get_mut.
    {
        let state = map.get_mut::<CachePlugin>().expect("cache registered");
        state.hits += 1;
        state.entries.insert("greeting".to_string(), "hello".to_string());
    }

    // Verify mutation.
    let state = map.get::<CachePlugin>().expect("cache registered");
    assert_eq!(state.hits, 1);
    assert_eq!(state.entries.get("greeting").map(String::as_str), Some("hello"));
}
}

You cannot pass MetricsPlugin to get::<CachePlugin>() — the types do not match and the code will not compile.

Step 7: Verify cross-plugin isolation

The following test confirms that mutating one plugin's state does not affect another:

#![allow(unused)]
fn main() {
#[test]
fn plugin_isolation_is_enforced() {
    let (mut map, _cache, _metrics) = create_plugin_map();

    // Mutate cache state aggressively.
    {
        let cache = map.get_mut::<CachePlugin>().expect("registered");
        cache.hits = 9999;
        cache.entries.insert("key".to_string(), "value".to_string());
    }

    // MetricsPlugin state is untouched.
    let metrics = map.get::<MetricsPlugin>().expect("registered");
    assert_eq!(metrics.messages_processed, 0);

    // Mutate metrics state.
    map.get_mut::<MetricsPlugin>().expect("registered").messages_processed = 42;

    // Cache state is untouched.
    let cache = map.get::<CachePlugin>().expect("registered");
    assert_eq!(cache.hits, 9999);
}
}

The isolation holds because the map is keyed by TypeId::of::<P>() — the Rust type identity, not a string. Even if two plugins happened to share the same KEY string, the TypeId lookup would still route correctly. (Duplicate TypeId registrations are caught and return Err.)

Step 8: Implement the Plugin lifecycle trait

To hook into agent events, implement Plugin on a concrete struct:

#![allow(unused)]
fn main() {
use synwire_core::agents::directive::Directive;
use synwire_core::agents::plugin::{Plugin, PluginInput, PluginStateMap};
use synwire_core::BoxFuture;

pub struct CachePluginImpl;

impl Plugin for CachePluginImpl {
    fn name(&self) -> &str {
        "cache"
    }

    /// Called when the agent receives a user message.
    /// We count cache accesses and emit no directives.
    fn on_user_message<'a>(
        &'a self,
        input: &'a PluginInput,
        state: &'a PluginStateMap,
    ) -> BoxFuture<'a, Vec<Directive>> {
        Box::pin(async move {
            // Read-only access is fine — PluginStateMap is shared here.
            if let Some(cache) = state.get::<CachePlugin>() {
                tracing::debug!(
                    turn = input.turn,
                    hits = cache.hits,
                    "CachePlugin: on_user_message"
                );
            }
            Vec::new()  // return empty slice — no directives
        })
    }
}
}

All Plugin methods have default no-op implementations. Override only the lifecycle hooks you care about:

Step 9: Register the plugin with an Agent

Attach the plugin implementation to the Agent builder with .plugin():

#![allow(unused)]
fn main() {
use synwire_core::agents::agent_node::Agent;

let agent: Agent = Agent::new("my-agent", "stub-model")
    .plugin(CachePluginImpl)
    .plugin(MetricsPluginImpl);
}

Multiple .plugin() calls are chained. Each plugin is stored as Box<dyn Plugin> and called in registration order during lifecycle events.

Step 10: Serialise all plugin state

PluginStateMap::serialize_all() produces a JSON object keyed by each plugin's KEY string. This is useful for logging, debugging, or persisting agent state:

#![allow(unused)]
fn main() {
#[test]
fn serialize_all_plugin_state() {
    let (mut map, _, _) = create_plugin_map();

    map.get_mut::<CachePlugin>().expect("registered").hits = 7;
    map.get_mut::<MetricsPlugin>().expect("registered").messages_processed = 3;

    let snapshot = map.serialize_all();
    assert_eq!(snapshot["cache"]["hits"], 7);
    assert_eq!(snapshot["metrics"]["messages_processed"], 3);
}
}

The keys in the output object are the KEY constants you defined — "cache" and "metrics" in this example.

Step 11: Detect duplicate registration

Attempting to register the same plugin key type twice returns an error:

#![allow(unused)]
fn main() {
#[test]
fn duplicate_registration_is_rejected() {
    let mut map = PluginStateMap::new();
    let _ = map
        .register::<CachePlugin>(CacheState::default())
        .expect("first registration succeeds");

    // Second registration of the same type returns the KEY string as the error.
    let err = map
        .register::<CachePlugin>(CacheState::default())
        .expect_err("duplicate registration should fail");

    assert_eq!(err, CachePlugin::KEY);  // "cache"
}
}

Why this design matters

Most plugin systems use HashMap<String, Box<dyn Any>> with string keys. This approach trades compile-time safety for flexibility: if you mistype a key string you get a silent None at runtime, not a compiler error.

PluginStateMap uses TypeId as the map key. TypeId is derived from the Rust type system, so:

• Accessing the wrong plugin state is a compile error, not a runtime panic.
• There is no string lookup — TypeId lookups are O(1) hash operations.
• The KEY string constant exists only for serialisation; it plays no role in access control.

Next steps

• Backend operations: Continue with 05-backend-operations.md to learn how to read and write files through the backend protocol.
• Plugin how-to: See ../how-to/plugins.md for a complete guide to plugin registration, ordering, and dependency injection.
• Architecture: See ../explanation/plugin_system.md for a deeper explanation of how TypeId-keyed maps enforce isolation.

Working with Files and Shell

Time: ~35 minutes Prerequisites: Completed 01-first-agent.md, basic familiarity with async Rust

Agents often need to read configuration files, write output artefacts, search source code, or navigate a directory hierarchy. Synwire provides a uniform interface for all of these through the Vfs trait. Two concrete implementations are built in:

• MemoryProvider — ephemeral, in-memory storage. No files on disk. Ideal for tests and agent scratchpads.
• LocalProvider — real OS filesystem, scoped to a root directory. Suitable for agents that must persist output between runs.

Both backends enforce safety boundaries that prevent an agent from escaping its allowed working directory. This tutorial teaches you to use both, understand the error model, and search file content with ripgrep-style options.

What you are building

1. Writing, reading, and navigating with MemoryProvider.
2. Attempting a path traversal and observing the rejection.
3. Using LocalProvider scoped to a temporary directory.
4. Searching file content with grep and GrepOptions.
5. Reading GrepMatch fields.

Step 1: Add dependencies

[dependencies]
synwire-core  = { path = "../../crates/synwire-core" }
synwire-agent = { path = "../../crates/synwire-agent" }
tokio = { version = "1", features = ["full"] }

Step 2: Understand Vfs

Vfs is the trait all backends implement. Every method returns a BoxFuture<'_, Result<T, VfsError>>, so operations are always async:

#![allow(unused)]
fn main() {
pub trait Vfs: Send + Sync {
    fn read(&self, path: &str)    -> BoxFuture<'_, Result<FileContent, VfsError>>;
    fn write(&self, path: &str, content: &[u8])
                                  -> BoxFuture<'_, Result<WriteResult, VfsError>>;
    fn ls(&self, path: &str)      -> BoxFuture<'_, Result<Vec<DirEntry>, VfsError>>;
    fn grep(&self, pattern: &str, opts: GrepOptions)
                                  -> BoxFuture<'_, Result<Vec<GrepMatch>, VfsError>>;
    fn pwd(&self)                 -> BoxFuture<'_, Result<String, VfsError>>;
    fn cd(&self, path: &str)      -> BoxFuture<'_, Result<(), VfsError>>;
    // ... and rm, cp, mv_file, edit, glob, upload, download, capabilities
}
}

You call backend.read("file.txt").await? exactly the same way for both MemoryProvider and LocalProvider.

Step 3: MemoryProvider — write and read

use synwire_core::vfs::state_backend::MemoryProvider;
use synwire_core::vfs::protocol::Vfs;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let backend = MemoryProvider::new();

    // Write a file. Content is raw bytes; use b"..." for UTF-8 string literals.
    backend.write("notes.txt", b"hello from synwire").await?;

    // Read it back. FileContent.content is Vec<u8>.
    let file = backend.read("notes.txt").await?;
    let text = String::from_utf8(file.content)?;
    assert_eq!(text, "hello from synwire");

    println!("read back: {text}");
    Ok(())
}

MemoryProvider::new() creates an empty backend with / as the working directory. There is no persistence — when the MemoryProvider is dropped, all data is lost.

Step 4: Navigate the working directory

Paths in MemoryProvider are resolved relative to the current working directory, exactly like a real shell. Absolute paths (starting with /) are always resolved from root:

#[tokio::test]
async fn navigate_directories() {
    let backend = MemoryProvider::new();

    // Write a file at an absolute path.
    backend.write("/project/src/main.rs", b"fn main() {}").await.expect("write");

    // Check the initial working directory.
    let cwd = backend.pwd().await.expect("pwd");
    assert_eq!(cwd, "/");

    // Change into the project directory.
    backend.cd("/project").await.expect("cd");
    assert_eq!(backend.pwd().await.expect("pwd"), "/project");

    // Relative read now works from /project.
    let file = backend.read("src/main.rs").await.expect("read relative");
    assert_eq!(file.content, b"fn main() {}");

    // cd with a relative path.
    backend.cd("src").await.expect("cd src");
    assert_eq!(backend.pwd().await.expect("pwd"), "/project/src");
}

cd to a path that does not exist returns VfsError::NotFound. The working directory is not changed on error.

Step 5: Path traversal protection

Both backends block traversal attempts that would escape the root. In MemoryProvider the root is always /; in LocalProvider it is the directory you passed to new:

#![allow(unused)]
fn main() {
#[tokio::test]
async fn path_traversal_is_rejected() {
    use synwire_core::vfs::error::VfsError;

    let backend = MemoryProvider::new();

    // Attempt to cd above root using "..".
    let err = backend.cd("/../etc").await.expect_err("should be blocked");

    // The error is PathTraversal, not NotFound.
    assert!(
        matches!(err, VfsError::PathTraversal { .. }),
        "expected PathTraversal, got: {err}"
    );

    // The working directory is unchanged.
    assert_eq!(backend.pwd().await.expect("pwd"), "/");
}
}

VfsError::PathTraversal carries two fields:

#![allow(unused)]
fn main() {
VfsError::PathTraversal {
    attempted: String,  // The normalised path that was attempted
    root: String,       // The root boundary that was violated
}
}

Step 6: VfsError — the full error model

VfsError is #[non_exhaustive]. The variants you will encounter most often:

Always handle VfsError with a match and a catch-all arm:

#![allow(unused)]
fn main() {
use synwire_core::vfs::error::VfsError;

match err {
    VfsError::NotFound(p) => eprintln!("missing: {p}"),
    VfsError::PathTraversal { attempted, root } => {
        eprintln!("traversal blocked: {attempted} outside {root}")
    }
    VfsError::PermissionDenied(p) => eprintln!("permission denied: {p}"),
    other => eprintln!("backend error: {other}"),
}
}

Step 7: LocalProvider — real files on disk

LocalProvider operates on the real filesystem but confines all operations to the root directory you pass to new. Attempting to access anything outside that root is treated as a PathTraversal error.

#![allow(unused)]
fn main() {
use synwire_agent::vfs::filesystem::LocalProvider;
use synwire_core::vfs::protocol::Vfs;

#[tokio::test]
async fn filesystem_backend_write_and_read() {
    // Use a temporary directory so the test cleans up after itself.
    let dir = tempfile::tempdir().expect("tmpdir");
    let root = dir.path();

    // new() canonicalises root and verifies it exists.
    let backend = LocalProvider::new(root).expect("create backend");

    // Write a file. Parent directories are created automatically.
    backend
        .write("output/result.txt", b"42")
        .await
        .expect("write");

    // Read it back.
    let content = backend.read("output/result.txt").await.expect("read");
    assert_eq!(content.content, b"42");
}
}

To use tempfile in tests, add it to your [dev-dependencies]:

[dev-dependencies]
tempfile = "3"

Step 8: Path traversal with LocalProvider

LocalProvider normalises paths without requiring them to exist (it avoids calling canonicalize on non-existent paths). The boundary check happens after normalisation:

#![allow(unused)]
fn main() {
#[tokio::test]
async fn filesystem_backend_blocks_traversal() {
    use synwire_core::vfs::error::VfsError;

    let dir = tempfile::tempdir().expect("tmpdir");
    let backend = LocalProvider::new(dir.path()).expect("create");

    // Attempt to read a file above the workspace root.
    let err = backend
        .read("../../etc/passwd")
        .await
        .expect_err("traversal must be blocked");

    assert!(
        matches!(err, VfsError::PathTraversal { .. }),
        "expected PathTraversal, got: {err}"
    );
}
}

Step 9: Grep — searching file content

Vfs::grep accepts a regex pattern and a GrepOptions struct. The options mirror ripgrep's command-line flags:

use synwire_core::vfs::state_backend::MemoryProvider;
use synwire_core::vfs::protocol::Vfs;
use synwire_core::vfs::grep_options::{GrepOptions, GrepOutputMode};

#[tokio::test]
async fn grep_with_context() {
    let backend = MemoryProvider::new();

    // Seed the backend with some files.
    backend
        .write("/src/lib.rs", b"// lib\npub fn add(a: u32, b: u32) -> u32 {\n    a + b\n}\n")
        .await
        .expect("write");
    backend
        .write("/src/main.rs", b"// main\nfn main() {\n    println!(\"hello\");\n}\n")
        .await
        .expect("write");

    let opts = GrepOptions {
        case_insensitive: false,
        line_numbers: true,
        // Show one line of context before and after each match.
        after_context: 1,
        before_context: 1,
        // Restrict to .rs files.
        glob: Some("*.rs".to_string()),
        ..GrepOptions::default()
    };

    let matches = backend.grep("pub fn", opts).await.expect("grep");

    // "pub fn" appears only in lib.rs.
    assert_eq!(matches.len(), 1);

    let m = &matches[0];
    assert!(m.file.ends_with("lib.rs"));
    assert_eq!(m.line_number, 2);          // 1-indexed
    assert!(m.line_content.contains("pub fn add"));
    assert!(!m.before.is_empty());         // "// lib" is the before context
    assert!(!m.after.is_empty());          // "    a + b" is the after context
}

Step 10: GrepOptions reference

Step 11: GrepOutputMode variants

GrepOutputMode controls the shape of the GrepMatch values returned:

#![allow(unused)]
fn main() {
use synwire_core::vfs::grep_options::{GrepOptions, GrepOutputMode};

// Content mode (default): full line content with context.
let content_opts = GrepOptions {
    output_mode: GrepOutputMode::Content,
    line_numbers: true,
    ..GrepOptions::default()
};

// FilesWithMatches: one entry per file that has at least one match.
// GrepMatch.line_content and context fields are empty.
let files_opts = GrepOptions {
    output_mode: GrepOutputMode::FilesWithMatches,
    ..GrepOptions::default()
};

// Count: one entry per file; GrepMatch.line_number holds the match count.
let count_opts = GrepOptions {
    output_mode: GrepOutputMode::Count,
    ..GrepOptions::default()
};
}

Count mode example:

#![allow(unused)]
fn main() {
#[tokio::test]
async fn grep_count_mode() {
    let backend = MemoryProvider::new();
    backend.write("/f.txt", b"foo\nfoo\nbar\nfoo").await.expect("write");

    let matches = backend
        .grep(
            "foo",
            GrepOptions {
                output_mode: GrepOutputMode::Count,
                ..GrepOptions::default()
            },
        )
        .await
        .expect("grep");

    // One GrepMatch per file; line_number holds the count.
    assert_eq!(matches.len(), 1);
    assert_eq!(matches[0].line_number, 3);
}
}

Step 12: GrepMatch fields

GrepMatch carries all information about a single match:

#![allow(unused)]
fn main() {
pub struct GrepMatch {
    /// File path where the match was found.
    pub file: String,
    /// Line number (1-indexed). 0 when line_numbers: false or in FilesWithMatches mode.
    pub line_number: usize,
    /// Column of the match start (0-indexed). 0 in invert or FilesWithMatches mode.
    pub column: usize,
    /// Full content of the matched line.
    pub line_content: String,
    /// Lines before the match (up to before_context).
    pub before: Vec<String>,
    /// Lines after the match (up to after_context).
    pub after: Vec<String>,
}
}

In Count mode, line_number is repurposed to hold the match count and line_content holds the count as a string. All other fields are empty.

Step 13: Case-insensitive and invert search

#![allow(unused)]
fn main() {
#[tokio::test]
async fn case_insensitive_and_invert() {
    let backend = MemoryProvider::new();
    backend
        .write("/log.txt", b"INFO: start\nERROR: fail\nINFO: end")
        .await
        .expect("write");

    // Case-insensitive: "error" matches "ERROR".
    let errors = backend
        .grep(
            "error",
            GrepOptions {
                case_insensitive: true,
                line_numbers: true,
                ..GrepOptions::default()
            },
        )
        .await
        .expect("grep");
    assert_eq!(errors.len(), 1);
    assert!(errors[0].line_content.contains("ERROR"));

    // Invert: show lines that do NOT match "ERROR".
    let non_errors = backend
        .grep(
            "ERROR",
            GrepOptions {
                invert: true,
                ..GrepOptions::default()
            },
        )
        .await
        .expect("grep");
    assert_eq!(non_errors.len(), 2);
    assert!(non_errors.iter().all(|m| !m.line_content.contains("ERROR")));
}
}

What you have learned

• Vfs is the uniform interface for file operations across backends.
• MemoryProvider is fully in-memory — perfect for tests and agent scratchpads.
• LocalProvider is scoped to a root directory and enforces path traversal protection using normalised path comparison.
• Both backends reject ../../etc/passwd-style traversal attempts with VfsError::PathTraversal.
• grep supports case insensitivity, context lines, file type/glob filters, output modes, invert matching, and match limits through GrepOptions.
• GrepMatch carries the file path, line number, column, matched content, and context lines.

Next steps

• Composite backends: See ../how-to/vfs.md for composing MemoryProvider, LocalProvider, and custom backends through the CompositeProvider pipeline.
• Shell execution: See ../how-to/shell.md for running commands with Shell and reading ExecuteResponse.
• Architecture: See ../explanation/backend_protocol.md for a deeper explanation of how backends integrate with the agent runner, middleware, and approval gates.
• Previous tutorial: 04-plugin-state-isolation.md — composing plugins with type-safe state.

Tutorial 6: Checkpointing — Resumable Workflows

Prerequisites: Rust 1.85+, completion of Tutorial 5, familiarity with StateGraph from Getting Started: Graph Agents.

In this tutorial you will:

1. Understand what checkpointing does and when you need it
2. Wire InMemoryCheckpointSaver into a StateGraph
3. Resume a run from a checkpoint using thread_id
4. Switch to SqliteSaver for persistence across process restarts
5. Fork a run from a past checkpoint

1. Why checkpoint?

Without checkpointing, every graph.invoke(...) starts from scratch. Checkpointing enables:

• Resume — a long-running workflow interrupted mid-way (network error, process restart) picks up from the last completed superstep
• Fork — run alternative continuations from the same past state without re-executing earlier steps
• Replay / debug — rewind to an intermediate state and inspect what changed
• Human-in-the-loop — pause execution at a decision point, wait for human input, then resume

📖 Rust note: Arc<T> (Atomically Reference Counted) enables shared ownership of a value across threads. We use Arc<dyn BaseCheckpointSaver> because the compiled graph and the caller both need access to the saver.

2. In-memory checkpointing

Add dependencies:

[dependencies]
synwire-orchestrator = "0.1"
synwire-checkpoint = "0.1"
synwire-derive = "0.1"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }

Define state and a simple two-step graph:

use synwire_derive::State;
use synwire_orchestrator::graph::StateGraph;
use synwire_orchestrator::constants::END;
use synwire_orchestrator::func::sync_node;
use synwire_checkpoint::{InMemoryCheckpointSaver, CheckpointConfig};
use std::sync::Arc;
use serde::{Serialize, Deserialize};

#[derive(State, Clone, Debug, Default, Serialize, Deserialize)]
struct WorkflowState {
    #[reducer(topic)]
    steps_completed: Vec<String>,
    #[reducer(last_value)]
    result: String,
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut graph = StateGraph::<WorkflowState>::new();

    graph.add_node("step_one", sync_node(|mut s: WorkflowState| {
        s.steps_completed.push("step_one".to_string());
        Ok(s)
    }))?;

    graph.add_node("step_two", sync_node(|mut s: WorkflowState| {
        s.steps_completed.push("step_two".to_string());
        s.result = format!("Completed: {:?}", s.steps_completed);
        Ok(s)
    }))?;

    graph.set_entry_point("step_one")
        .add_edge("step_one", "step_two")
        .add_edge("step_two", END);

    let compiled = graph.compile()?;

    // Attach the saver
    let saver = Arc::new(InMemoryCheckpointSaver::new());
    let checkpointed = compiled.with_checkpoint_saver(saver.clone());

    // Run with thread_id "session-1"
    let config = CheckpointConfig::new("session-1");
    let state = checkpointed.invoke(WorkflowState::default(), Some(config)).await?;
    println!("Result: {}", state.result);

    Ok(())
}

After invoke completes, saver holds a checkpoint for "session-1". The checkpoint contains the full state after each superstep.

3. Resuming from a checkpoint

Pass the same thread_id on a subsequent call. The graph loads the latest checkpoint and continues from there:

#![allow(unused)]
fn main() {
// ... (same graph and saver from above)

// First run
let config = CheckpointConfig::new("my-thread");
checkpointed.invoke(WorkflowState::default(), Some(config.clone())).await?;

// Simulate an interruption here. On resume:
let resumed = checkpointed.invoke(WorkflowState::default(), Some(config)).await?;
println!("Resumed result: {}", resumed.result);
// The graph finds the existing checkpoint and skips already-completed supersteps.
}

Note: InMemoryCheckpointSaver loses all state when the process exits. For true resumability across restarts, use SqliteSaver (next section).

4. SQLite checkpointing for durable persistence

Add synwire-checkpoint-sqlite:

[dependencies]
synwire-checkpoint-sqlite = "0.1"
# ... rest unchanged

Replace InMemoryCheckpointSaver with SqliteSaver:

#![allow(unused)]
fn main() {
use synwire_checkpoint_sqlite::SqliteSaver;
use std::path::Path;
use std::sync::Arc;

// Opens or creates "checkpoints.db" in the current directory.
// File permissions are set to 0600 automatically.
let saver = Arc::new(SqliteSaver::new(Path::new("checkpoints.db"))?);

let checkpointed = compiled.with_checkpoint_saver(saver);
let config = CheckpointConfig::new("persistent-session");
checkpointed.invoke(WorkflowState::default(), Some(config.clone())).await?;

// Kill the process here. On restart:
// The same code opens "checkpoints.db" and resumes from the last superstep.
let resumed = checkpointed.invoke(WorkflowState::default(), Some(config)).await?;
}

No system SQLite library is required — synwire-checkpoint-sqlite bundles SQLite via the rusqlite bundled feature.

5. Forking from a past checkpoint

To fork at a specific checkpoint, provide its checkpoint_id:

#![allow(unused)]
fn main() {
use synwire_checkpoint::{CheckpointConfig, BaseCheckpointSaver};

// List all checkpoints for a thread
let checkpoints = saver.list(&CheckpointConfig::new("my-thread"), None).await?;

// Fork from the first checkpoint (earliest in the run)
if let Some(first) = checkpoints.first() {
    let fork_config = CheckpointConfig::new("my-thread")
        .with_checkpoint_id(first.checkpoint.id.clone());

    let forked = checkpointed.invoke(WorkflowState::default(), Some(fork_config)).await?;
    println!("Fork result: {}", forked.result);
}
}

The forked run creates a new branch in the checkpoint tree, identified by a new checkpoint_id. The original thread remains unchanged.

Next steps

• How-To: Add Checkpointing — configuration options and advanced patterns
• Checkpointing Explanation — BaseStore and the serde protocol
• Pregel Execution Model — how supersteps relate to checkpoints

Tutorial 7: Building a Coding Agent

Time: ~90 minutes Prerequisites: Rust 1.85+, completion of Tutorial 5: File and Shell Operations, basic familiarity with async Rust

Background: Function Calling — how LLMs invoke tools; ReAct — the reason-then-act loop that coding agents use.

In this tutorial you will build a terminal-based coding assistant — similar in spirit to tools like OpenCode or Aider — using the Synwire agent runtime. By the end you will have a working binary that:

• Reads and writes files inside a project directory
• Searches source code for patterns
• Runs shell commands (cargo build, cargo test, linters)
• Streams output to the terminal as the model generates it
• Resumes conversations across sessions
• Asks for approval before running shell commands

📖 Rust note: A trait is Rust's equivalent of an interface. Synwire's Vfs and Tool are traits — they define a contract that multiple implementations satisfy, letting you swap backends without changing the agent.

What makes a coding agent different

A plain chatbot responds with text. A coding agent calls tools on every turn:

1. Model receives the user's request plus the conversation history.
2. Model emits a tool call (e.g., read_file("src/main.rs")).
3. Runtime executes the tool and appends the result to the conversation.
4. Model receives the tool result and decides whether to call another tool or respond.
5. Repeat until the model emits a text response with no tool calls.

This loop — called ReAct (Reason + Act) — continues until the model decides the task is done. Synwire's Runner drives this loop automatically. Your job is to define the tools and the system prompt.

sequenceDiagram
    participant User
    participant Runner
    participant Model
    participant Tools

    User->>Runner: "Fix the failing test in lib.rs"
    loop ReAct
        Runner->>Model: conversation + tool schemas
        Model->>Runner: ToolCall(read_file, "src/lib.rs")
        Runner->>Tools: read_file("src/lib.rs")
        Tools->>Runner: file content
        Runner->>Model: conversation + tool result
        Model->>Runner: ToolCall(write_file, "src/lib.rs", fixed_content)
        Runner->>Tools: write_file(...)
        Tools->>Runner: OK
        Runner->>Model: conversation + tool result
        Model->>Runner: ToolCall(run_command, "cargo test")
        Runner->>Tools: cargo test
        Tools->>Runner: "test result: ok. 3 passed"
        Runner->>Model: conversation + tool result
        Model->>Runner: TextDelta("All tests are passing now.")
    end
    Runner->>User: stream events

Step 1: Project setup

Create a new binary crate:

cargo new synwire-coder
cd synwire-coder

Add dependencies to Cargo.toml:

[package]
name = "synwire-coder"
version = "0.1.0"
edition = "2024"

[dependencies]
# Agent builder and Runner
synwire-core  = "0.1"
synwire-agent = "0.1"

# OpenAI provider (swap for synwire-llm-ollama for local inference)
synwire-llm-openai = "0.1"

# Async runtime
tokio = { version = "1", features = ["full"] }

# JSON tool schemas and input parsing
serde        = { version = "1", features = ["derive"] }
serde_json   = "1"
schemars     = { version = "0.8", features = ["derive"] }

# Error handling
anyhow = "1"

# Command-line argument parsing
clap = { version = "4", features = ["derive"] }

[dev-dependencies]
synwire-test-utils = "0.1"

📖 Rust note: schemars derives JSON Schema from your Rust types. The #[tool] attribute macro in synwire-derive calls it automatically to generate the schema that the model uses to format tool call arguments.

Step 2: The five core tools

A coding agent needs exactly five tools to handle most tasks. Create src/tools.rs:

📖 Rust note: serde::Deserialize and schemars::JsonSchema on the same struct serve different purposes: Deserialize parses JSON arguments at runtime; JsonSchema generates the schema at startup that tells the model what arguments to supply.

#![allow(unused)]
fn main() {
// src/tools.rs
use std::sync::Arc;

use anyhow::Context;
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::Value;
use synwire_core::error::SynwireError;
use synwire_core::tools::{StructuredTool, ToolOutput, ToolSchema};

use crate::backend::ProjectBackend;

// ─────────────────────────────────────────────────────────────────────────────
// 1. read_file
// ─────────────────────────────────────────────────────────────────────────────

#[derive(Debug, Deserialize, JsonSchema)]
pub struct ReadFileInput {
    /// Path to the file, relative to the project root.
    pub path: String,
    /// Optional: only return lines `start_line` through `end_line` (1-indexed).
    pub start_line: Option<usize>,
    pub end_line: Option<usize>,
}

pub fn read_file_tool(backend: Arc<ProjectBackend>) -> Result<StructuredTool, SynwireError> {
    StructuredTool::builder()
        .name("read_file")
        .description(
            "Read the contents of a file in the project. \
             Use start_line and end_line to retrieve a window when the file is large.",
        )
        .schema(ToolSchema {
            name: "read_file".into(),
            description: "Read a project file".into(),
            parameters: schemars::schema_for!(ReadFileInput)
                .schema
                .into_object()
                .into(),
        })
        .func(move |args: Value| {
            let backend = Arc::clone(&backend);
            Box::pin(async move {
                let input: ReadFileInput = serde_json::from_value(args)
                    .context("invalid read_file arguments")
                    .map_err(|e| SynwireError::Tool(e.to_string()))?;

                let content = backend
                    .read(&input.path)
                    .await
                    .map_err(|e| SynwireError::Tool(e.to_string()))?;

                let text = String::from_utf8_lossy(&content.content).into_owned();

                // Apply optional line window.
                let output = match (input.start_line, input.end_line) {
                    (Some(start), Some(end)) => text
                        .lines()
                        .enumerate()
                        .filter(|(i, _)| *i + 1 >= start && *i + 1 <= end)
                        .map(|(_, line)| line)
                        .collect::<Vec<_>>()
                        .join("\n"),
                    _ => text,
                };

                Ok(ToolOutput {
                    content: output,
                    ..Default::default()
                })
            })
        })
        .build()
}

// ─────────────────────────────────────────────────────────────────────────────
// 2. write_file
// ─────────────────────────────────────────────────────────────────────────────

#[derive(Debug, Deserialize, JsonSchema)]
pub struct WriteFileInput {
    /// Path to create or overwrite, relative to the project root.
    pub path: String,
    /// Complete new content for the file.
    pub content: String,
}

pub fn write_file_tool(backend: Arc<ProjectBackend>) -> Result<StructuredTool, SynwireError> {
    StructuredTool::builder()
        .name("write_file")
        .description(
            "Write content to a file, creating it if it does not exist. \
             Overwrites the entire file. Always write the complete file content — \
             do not write partial content.",
        )
        .schema(ToolSchema {
            name: "write_file".into(),
            description: "Write a project file".into(),
            parameters: schemars::schema_for!(WriteFileInput)
                .schema
                .into_object()
                .into(),
        })
        .func(move |args: Value| {
            let backend = Arc::clone(&backend);
            Box::pin(async move {
                let input: WriteFileInput = serde_json::from_value(args)
                    .context("invalid write_file arguments")
                    .map_err(|e| SynwireError::Tool(e.to_string()))?;

                backend
                    .write(&input.path, input.content.as_bytes())
                    .await
                    .map_err(|e| SynwireError::Tool(e.to_string()))?;

                Ok(ToolOutput {
                    content: format!("Wrote {} bytes to {}", input.content.len(), input.path),
                    ..Default::default()
                })
            })
        })
        .build()
}

// ─────────────────────────────────────────────────────────────────────────────
// 3. list_dir
// ─────────────────────────────────────────────────────────────────────────────

#[derive(Debug, Deserialize, JsonSchema)]
pub struct ListDirInput {
    /// Directory to list, relative to the project root. Defaults to "." (root).
    pub path: Option<String>,
}

pub fn list_dir_tool(backend: Arc<ProjectBackend>) -> Result<StructuredTool, SynwireError> {
    StructuredTool::builder()
        .name("list_dir")
        .description(
            "List the contents of a directory. \
             Returns file names and whether each entry is a file or directory.",
        )
        .schema(ToolSchema {
            name: "list_dir".into(),
            description: "List a directory".into(),
            parameters: schemars::schema_for!(ListDirInput)
                .schema
                .into_object()
                .into(),
        })
        .func(move |args: Value| {
            let backend = Arc::clone(&backend);
            Box::pin(async move {
                let input: ListDirInput = serde_json::from_value(args)
                    .context("invalid list_dir arguments")
                    .map_err(|e| SynwireError::Tool(e.to_string()))?;

                let path = input.path.as_deref().unwrap_or(".");
                let entries = backend
                    .ls(path)
                    .await
                    .map_err(|e| SynwireError::Tool(e.to_string()))?;

                let lines: Vec<String> = entries
                    .iter()
                    .map(|e| {
                        if e.is_dir {
                            format!("{}/", e.name)
                        } else {
                            e.name.clone()
                        }
                    })
                    .collect();

                Ok(ToolOutput {
                    content: lines.join("\n"),
                    ..Default::default()
                })
            })
        })
        .build()
}

// ─────────────────────────────────────────────────────────────────────────────
// 4. search_code
// ─────────────────────────────────────────────────────────────────────────────

#[derive(Debug, Deserialize, JsonSchema)]
pub struct SearchCodeInput {
    /// Regular expression pattern to search for.
    pub pattern: String,
    /// Restrict search to this subdirectory (optional).
    pub path: Option<String>,
    /// File glob filter, e.g. "*.rs" (optional).
    pub glob: Option<String>,
    /// Number of context lines before and after each match.
    pub context_lines: Option<u32>,
    /// Case-insensitive search.
    pub case_insensitive: Option<bool>,
}

pub fn search_code_tool(backend: Arc<ProjectBackend>) -> Result<StructuredTool, SynwireError> {
    StructuredTool::builder()
        .name("search_code")
        .description(
            "Search for a regex pattern across the project files. \
             Returns matching lines with optional context. \
             Use glob to restrict to a file type (e.g. '*.rs', '*.toml').",
        )
        .schema(ToolSchema {
            name: "search_code".into(),
            description: "Grep the project files".into(),
            parameters: schemars::schema_for!(SearchCodeInput)
                .schema
                .into_object()
                .into(),
        })
        .func(move |args: Value| {
            use synwire_core::vfs::grep_options::GrepOptions;

            let backend = Arc::clone(&backend);
            Box::pin(async move {
                let input: SearchCodeInput = serde_json::from_value(args)
                    .context("invalid search_code arguments")
                    .map_err(|e| SynwireError::Tool(e.to_string()))?;

                let ctx = input.context_lines.unwrap_or(2);
                let opts = GrepOptions {
                    path: input.path,
                    glob: input.glob,
                    before_context: ctx,
                    after_context: ctx,
                    case_insensitive: input.case_insensitive.unwrap_or(false),
                    line_numbers: true,
                    ..GrepOptions::default()
                };

                let matches = backend
                    .grep(&input.pattern, opts)
                    .await
                    .map_err(|e| SynwireError::Tool(e.to_string()))?;

                if matches.is_empty() {
                    return Ok(ToolOutput {
                        content: "No matches found.".into(),
                        ..Default::default()
                    });
                }

                // Format like ripgrep terminal output.
                let mut out = String::new();
                let mut last_file = String::new();
                for m in &matches {
                    if m.file != last_file {
                        if !last_file.is_empty() {
                            out.push('\n');
                        }
                        out.push_str(&format!("{}:\n", m.file));
                        last_file = m.file.clone();
                    }
                    for line in &m.before {
                        out.push_str(&format!("  {}\n", line));
                    }
                    out.push_str(&format!(
                        "  {:>4}: {}\n",
                        m.line_number, m.line_content
                    ));
                    for line in &m.after {
                        out.push_str(&format!("  {}\n", line));
                    }
                }

                Ok(ToolOutput {
                    content: out,
                    ..Default::default()
                })
            })
        })
        .build()
}

// ─────────────────────────────────────────────────────────────────────────────
// 5. run_command
// ─────────────────────────────────────────────────────────────────────────────

#[derive(Debug, Deserialize, JsonSchema)]
pub struct RunCommandInput {
    /// Command to run, e.g. "cargo".
    pub command: String,
    /// Arguments, e.g. ["test", "--", "--nocapture"].
    pub args: Vec<String>,
    /// Optional timeout in seconds. Defaults to 120.
    pub timeout_secs: Option<u64>,
}

pub fn run_command_tool(backend: Arc<ProjectBackend>) -> Result<StructuredTool, SynwireError> {
    StructuredTool::builder()
        .name("run_command")
        .description(
            "Run a shell command in the project root directory. \
             Use for 'cargo build', 'cargo test', 'cargo clippy', 'cargo fmt', \
             and similar development commands. \
             Returns stdout, stderr, and the exit code.",
        )
        .schema(ToolSchema {
            name: "run_command".into(),
            description: "Execute a shell command".into(),
            parameters: schemars::schema_for!(RunCommandInput)
                .schema
                .into_object()
                .into(),
        })
        .func(move |args: Value| {
            use std::time::Duration;
            let backend = Arc::clone(&backend);
            Box::pin(async move {
                let input: RunCommandInput = serde_json::from_value(args)
                    .context("invalid run_command arguments")
                    .map_err(|e| SynwireError::Tool(e.to_string()))?;

                let timeout = input.timeout_secs.map(Duration::from_secs);

                let resp = backend
                    .execute_cmd(&input.command, &input.args, timeout)
                    .await
                    .map_err(|e| SynwireError::Tool(e.to_string()))?;

                // Format output for model consumption.
                let mut out = String::new();
                if !resp.stdout.is_empty() {
                    out.push_str("stdout:\n");
                    out.push_str(&resp.stdout);
                }
                if !resp.stderr.is_empty() {
                    if !out.is_empty() {
                        out.push('\n');
                    }
                    out.push_str("stderr:\n");
                    out.push_str(&resp.stderr);
                }
                out.push_str(&format!("\nexit code: {}", resp.exit_code));

                Ok(ToolOutput {
                    content: out,
                    ..Default::default()
                })
            })
        })
        .build()
}
}

📖 Rust note: Box::pin(async move { ... }) is required because async closures can't be used directly in trait objects. The move keyword transfers ownership of captured variables (backend, input) into the async block. See the Rust async book for a full explanation.

Step 3: The backend

The agent needs access to the project's filesystem and the ability to run commands. Shell wraps LocalProvider and adds command execution. Create src/backend.rs:

📖 Rust note: Arc<T> (Atomically Reference Counted) lets multiple tools share ownership of the same backend without copying it. Calling .clone() on an Arc creates another pointer to the same data — no allocation.

#![allow(unused)]
fn main() {
// src/backend.rs
use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::Arc;

use synwire_agent::vfs::local_shell::Shell;
use synwire_core::vfs::error::VfsError;
use synwire_core::vfs::protocol::Vfs;

/// Wraps Shell as a shared, Arc-compatible project backend.
///
/// The Arc lets multiple tools borrow the same backend concurrently
/// without copying it.
pub type ProjectBackend = dyn Vfs;

/// Create the shared backend for a project directory.
pub fn create_backend(
    project_root: PathBuf,
) -> Result<Arc<Shell>, VfsError> {
    // Inherit PATH and common Rust toolchain variables from the environment.
    let env: HashMap<String, String> = std::env::vars()
        .filter(|(k, _)| {
            matches!(
                k.as_str(),
                "PATH" | "HOME" | "CARGO_HOME" | "RUSTUP_HOME" | "RUST_LOG"
            )
        })
        .collect();

    let backend = Shell::new(
        project_root,
        env,
        120, // default command timeout: 2 minutes
    )?;

    Ok(Arc::new(backend))
}
}

Step 4: The system prompt

The system prompt is the most important part of any coding agent. It defines the agent's constraints, tells it which tools to reach for first, and prevents common failure modes. Create src/prompt.rs:

#![allow(unused)]
fn main() {
// src/prompt.rs

/// System prompt for the coding agent.
///
/// Design principles:
/// - Tell the model to read before writing (prevents hallucinated edits).
/// - Tell the model to run tests after editing (validates the change).
/// - Constrain the working directory explicitly.
/// - Describe each tool's purpose so the model reaches for the right one.
pub fn system_prompt(project_root: &str) -> String {
    format!(
        r#"You are a coding assistant with direct access to the files and shell in a \
Rust project located at `{project_root}`.

# Core workflow

When asked to make a change:
1. Use `list_dir` to orient yourself if you haven't seen the project yet.
2. Use `read_file` to read the relevant files before editing them.
3. Use `search_code` to find definitions, usages, or error messages when you \
   don't know where something is.
4. Use `write_file` to make the edit. Always write the complete file — never \
   write partial content.
5. After editing, run `cargo check` with `run_command` to verify the code \
   compiles.
6. Run `cargo test` to check for regressions.
7. If tests fail, read the error output carefully, fix the code, and re-test.

# Tool guidance

- **read_file**: Use `start_line`/`end_line` to read large files in sections. \
  Check `list_dir` first if you're not sure the file exists.
- **write_file**: Always write the complete file content. The tool overwrites \
  the entire file.
- **search_code**: Use for finding function definitions, error messages, or \
  usages of a type. Prefer `*.rs` glob for Rust files.
- **run_command**: Prefer `cargo check` over `cargo build` for speed. Run \
  `cargo clippy` when asked to improve code quality. Run `cargo fmt` when \
  asked to format.
- **list_dir**: Start here when exploring an unfamiliar project.

# Constraints

- Only modify files inside the project root.
- Do not install system packages or modify global configuration.
- If a change is destructive or irreversible, explain what you are about to \
  do before calling write_file or run_command.

When the task is complete, summarise what you changed and why.
"#
    )
}
}

Step 5: Building the agent

Now assemble the tools and agent. Create src/agent.rs:

📖 Rust note: Result<T, E> is Rust's error type. The ? operator unwraps Ok(value) or immediately returns the Err to the caller — it replaces the boilerplate match result { Ok(v) => v, Err(e) => return Err(e.into()) }.

#![allow(unused)]
fn main() {
// src/agent.rs
use std::sync::Arc;

use synwire_core::agents::agent_node::Agent;
use synwire_core::agents::permission::{PermissionBehavior, PermissionMode, PermissionRule};
use synwire_core::error::SynwireError;

use crate::backend::ProjectBackend;
use crate::prompt::system_prompt;
use crate::tools::{
    list_dir_tool, read_file_tool, run_command_tool, search_code_tool, write_file_tool,
};

/// Configuration for the coding agent.
pub struct CoderAgentConfig {
    /// LLM model to use (e.g. "claude-opus-4-6").
    pub model: String,
    /// Absolute path to the project root shown in the system prompt.
    pub project_root: String,
    /// Whether to require approval before running shell commands.
    pub require_command_approval: bool,
}

/// Build the coding agent with all five tools registered.
pub fn build_coding_agent(
    backend: Arc<dyn ProjectBackend>,
    config: CoderAgentConfig,
) -> Result<Agent, SynwireError> {
    let system = system_prompt(&config.project_root);

    // Register tools — each tool captures an Arc<backend> clone.
    let read   = read_file_tool(Arc::clone(&backend))?;
    let write  = write_file_tool(Arc::clone(&backend))?;
    let ls     = list_dir_tool(Arc::clone(&backend))?;
    let search = search_code_tool(Arc::clone(&backend))?;
    let run    = run_command_tool(Arc::clone(&backend))?;

    // Permission rules: file tools auto-approve; shell commands require
    // confirmation unless require_command_approval is false.
    let permission_rules = if config.require_command_approval {
        vec![
            PermissionRule {
                tool_pattern: "read_file".into(),
                behavior: PermissionBehavior::Allow,
            },
            PermissionRule {
                tool_pattern: "list_dir".into(),
                behavior: PermissionBehavior::Allow,
            },
            PermissionRule {
                tool_pattern: "search_code".into(),
                behavior: PermissionBehavior::Allow,
            },
            PermissionRule {
                tool_pattern: "write_file".into(),
                behavior: PermissionBehavior::Ask,
            },
            PermissionRule {
                tool_pattern: "run_command".into(),
                behavior: PermissionBehavior::Ask,
            },
        ]
    } else {
        vec![PermissionRule {
            tool_pattern: "*".into(),
            behavior: PermissionBehavior::Allow,
        }]
    };

    let agent = Agent::new("coder", &config.model)
        .description("A coding assistant with filesystem and shell access")
        .system_prompt(system)
        .tool(read)
        .tool(write)
        .tool(ls)
        .tool(search)
        .tool(run)
        .permission_mode(PermissionMode::DenyUnauthorized)
        .permission_rules(permission_rules)
        .max_turns(50);

    Ok(agent)
}
}

Step 6: The terminal REPL

The REPL reads user input, runs the agent, and streams events to the terminal. Create src/repl.rs:

📖 Rust note: Rust's match is exhaustive — the compiler forces you to handle every variant. #[non_exhaustive] on AgentEvent means new variants may appear in future releases, which is why the _ catch-all arm is required.

#![allow(unused)]
fn main() {
// src/repl.rs
use std::io::{self, BufRead, Write};

use synwire_core::agents::runner::{Runner, RunnerConfig};
use synwire_core::agents::streaming::AgentEvent;

use crate::approval::handle_approval;

/// Run the interactive REPL until the user types "exit" or EOF.
///
/// `session_id` is used to resume conversations across process restarts.
pub async fn run_repl(
    runner: &Runner,
    session_id: &str,
) -> anyhow::Result<()> {
    let stdin = io::stdin();
    let mut stdout = io::stdout();

    println!("Coding agent ready. Type your request, or 'exit' to quit.");
    println!("Session: {session_id}");
    println!();

    loop {
        // Print the prompt and flush so it appears before blocking.
        print!("you> ");
        stdout.flush()?;

        // Read one line of input.
        let mut line = String::new();
        let n = stdin.lock().read_line(&mut line)?;
        if n == 0 || line.trim() == "exit" {
            println!("Goodbye.");
            break;
        }
        let input = line.trim().to_string();
        if input.is_empty() {
            continue;
        }

        // Run the agent with the current session_id so conversation
        // history is preserved across turns.
        let config = RunnerConfig {
            session_id: Some(session_id.to_string()),
            ..RunnerConfig::default()
        };

        let mut stream = runner.run(serde_json::json!(input), config).await?;

        println!();
        print!("agent> ");
        stdout.flush()?;

        // Drain the event stream.
        while let Some(event) = stream.recv().await {
            match event {
                AgentEvent::TextDelta { content } => {
                    print!("{content}");
                    stdout.flush()?;
                }

                AgentEvent::ToolCallStart { name, .. } => {
                    println!();
                    println!("\x1b[2m[calling {name}]\x1b[0m");
                }

                AgentEvent::ToolResult { output, .. } => {
                    // Show a preview of tool results so the user can
                    // see what the agent is reading.
                    let preview: String = output.content.chars().take(120).collect();
                    let ellipsis = if output.content.len() > 120 { "…" } else { "" };
                    println!("\x1b[2m  → {preview}{ellipsis}\x1b[0m");
                }

                AgentEvent::StatusUpdate { status, .. } => {
                    println!("\x1b[2m[{status}]\x1b[0m");
                }

                AgentEvent::UsageUpdate { usage } => {
                    // Print token usage at end of turn.
                    println!(
                        "\n\x1b[2m[tokens: {}↑ {}↓]\x1b[0m",
                        usage.input_tokens, usage.output_tokens
                    );
                }

                AgentEvent::TurnComplete { reason } => {
                    println!("\n\x1b[2m[done: {reason:?}]\x1b[0m");
                }

                AgentEvent::Error { message } => {
                    eprintln!("\n\x1b[31merror: {message}\x1b[0m");
                }

                _ => {
                    // Ignore other events (ToolCallDelta, DirectiveEmitted, etc.)
                }
            }
        }

        println!();
    }

    Ok(())
}
}

Step 7: Approval gates

When PermissionBehavior::Ask is set for a tool, Synwire calls an approval callback before executing that tool call. The callback receives the proposed Directive and must return ApprovalDecision. Create src/approval.rs:

#![allow(unused)]
fn main() {
// src/approval.rs
use std::io::{self, Write};

use synwire_core::agents::directive::Directive;
use synwire_agent::vfs::threshold_gate::{ApprovalDecision, ApprovalRequest};

/// Interactive approval callback for write_file and run_command.
///
/// Returns Allow, AllowAlways (never ask again), or Deny.
pub async fn handle_approval(request: &ApprovalRequest) -> ApprovalDecision {
    let tool_name = match &request.directive {
        Directive::Emit { event } => {
            // Extract tool name from ToolCall events if present.
            format!("{event:?}")
        }
        _ => format!("{:?}", request.directive),
    };

    // In practice, the approval request arrives with the tool name and
    // arguments already formatted. Display them to the user.
    eprintln!();
    eprintln!("\x1b[33m⚠ Approval required\x1b[0m");
    eprintln!("  Tool: {}", request.tool_name.as_deref().unwrap_or("unknown"));
    eprintln!("  Risk: {:?}", request.risk_level);
    if let Some(args) = &request.tool_args {
        eprintln!("  Args: {}", serde_json::to_string_pretty(args).unwrap_or_default());
    }
    eprint!("  Allow? [y]es / [a]lways / [n]o: ");
    io::stderr().flush().ok();

    let mut line = String::new();
    io::stdin().read_line(&mut line).ok();
    match line.trim() {
        "y" | "yes" => ApprovalDecision::Allow,
        "a" | "always" => ApprovalDecision::AllowAlways,
        _ => ApprovalDecision::Deny,
    }
}
}

Step 8: The main binary

Wire everything together in src/main.rs:

📖 Rust note: #[tokio::main] transforms async fn main into a standard synchronous entry point by starting the Tokio runtime. Without it, you cannot .await at the top level.

// src/main.rs
mod agent;
mod approval;
mod backend;
mod prompt;
mod repl;
mod tools;

use std::path::PathBuf;

use clap::Parser;
use synwire_agent::runner::Runner;

use crate::agent::{CoderAgentConfig, build_coding_agent};
use crate::backend::create_backend;
use crate::repl::run_repl;

/// A Synwire-powered coding assistant.
#[derive(Parser)]
#[command(version, about)]
struct Cli {
    /// Project root directory to operate on.
    #[arg(short, long, default_value = ".")]
    project: PathBuf,

    /// LLM model identifier.
    #[arg(short, long, default_value = "claude-opus-4-6")]
    model: String,

    /// Session ID for conversation continuity (auto-generated if omitted).
    #[arg(short, long)]
    session: Option<String>,

    /// Automatically approve write and shell operations without prompting.
    #[arg(long)]
    auto_approve: bool,
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let cli = Cli::parse();

    // Resolve the project root to an absolute path.
    let project_root = cli.project.canonicalize()
        .unwrap_or_else(|_| cli.project.clone());
    let project_root_str = project_root.to_string_lossy().into_owned();

    // Create the shared backend scoped to the project root.
    let backend = create_backend(project_root)?;

    // Build the agent with the five tools.
    let agent_config = CoderAgentConfig {
        model: cli.model,
        project_root: project_root_str,
        require_command_approval: !cli.auto_approve,
    };
    let agent = build_coding_agent(backend, agent_config)?;

    // Wrap in a Runner.
    let runner = Runner::new(agent);

    // Use the provided session ID or generate a new one.
    let session_id = cli.session.unwrap_or_else(|| {
        uuid::Uuid::new_v4().to_string()
    });

    // Run the interactive REPL.
    run_repl(&runner, &session_id).await?;

    Ok(())
}

Add uuid to your dependencies for session ID generation:

uuid = { version = "1", features = ["v4"] }

Step 9: Testing without side effects

Use FakeChatModel to test agent behaviour without an API key or real files. Create tests/agent_tools.rs:

📖 Rust note: #[tokio::test] is the async equivalent of #[test]. It starts the Tokio runtime for the duration of the test function, which is required because all Synwire operations are async.

// tests/agent_tools.rs
use std::sync::Arc;

use synwire_core::vfs::state_backend::MemoryProvider;
use synwire_test_utils::fake_chat_model::FakeChatModel;
use synwire_test_utils::recording_executor::RecordingExecutor;

use synwire_coder::agent::{CoderAgentConfig, build_coding_agent};
use synwire_coder::tools::read_file_tool;

#[tokio::test]
async fn read_file_tool_returns_content() {
    // Use MemoryProvider — ephemeral, no real filesystem.
    let backend = Arc::new(MemoryProvider::new());
    backend
        .write("/src/main.rs", b"fn main() { println!(\"hello\"); }")
        .await
        .unwrap();

    let tool = read_file_tool(Arc::clone(&backend) as Arc<_>).unwrap();

    let output = tool
        .invoke(serde_json::json!({ "path": "/src/main.rs" }))
        .await
        .unwrap();

    assert!(output.content.contains("println!"));
}

#[tokio::test]
async fn read_file_with_line_window() {
    let backend = Arc::new(MemoryProvider::new());
    let content = "line1\nline2\nline3\nline4\nline5";
    backend.write("/file.txt", content.as_bytes()).await.unwrap();

    let tool = read_file_tool(Arc::clone(&backend) as Arc<_>).unwrap();

    let output = tool
        .invoke(serde_json::json!({
            "path": "/file.txt",
            "start_line": 2,
            "end_line": 3
        }))
        .await
        .unwrap();

    assert_eq!(output.content.trim(), "line2\nline3");
    assert!(!output.content.contains("line1"), "line1 should be excluded");
    assert!(!output.content.contains("line5"), "line5 should be excluded");
}

/// Test the full agent turn loop with a fake model.
/// The fake model emits a tool call then a text response.
#[tokio::test]
async fn agent_calls_read_file_then_responds() {
    use synwire_core::agents::runner::{Runner, RunnerConfig};
    use synwire_core::agents::streaming::AgentEvent;

    let backend = Arc::new(MemoryProvider::new());
    backend
        .write("/lib.rs", b"pub fn add(a: i32, b: i32) -> i32 { a + b }")
        .await
        .unwrap();

    // FakeChatModel returns pre-programmed responses in order.
    // Response 1: a tool call to read_file.
    // Response 2: text after seeing the file content.
    let model = FakeChatModel::new(vec![
        // The model calls read_file on the first turn.
        r#"{"tool_calls": [{"id": "tc1", "name": "read_file", "arguments": {"path": "/lib.rs"}}]}"#.into(),
        // After seeing the file, it responds with text.
        "The `add` function takes two i32 arguments and returns their sum.".into(),
    ]);

    let agent_config = CoderAgentConfig {
        model: model.model_name().to_string(),
        project_root: "/".to_string(),
        require_command_approval: false,
    };
    let agent = build_coding_agent(
        Arc::clone(&backend) as Arc<_>,
        agent_config,
    )
    .unwrap();

    let runner = Runner::new(agent).with_model(model);
    let config = RunnerConfig::default();
    let mut stream = runner
        .run(serde_json::json!("Explain the add function."), config)
        .await
        .unwrap();

    let mut text = String::new();
    let mut tool_called = false;

    while let Some(event) = stream.recv().await {
        match event {
            AgentEvent::ToolCallStart { name, .. } if name == "read_file" => {
                tool_called = true;
            }
            AgentEvent::TextDelta { content } => {
                text.push_str(&content);
            }
            _ => {}
        }
    }

    assert!(tool_called, "agent should have called read_file");
    assert!(
        text.contains("add"),
        "agent should mention the function"
    );
}

Run the tests:

cargo test

Step 10: Running the agent

Build and run against your current Rust project:

# Set your API key (if using OpenAI/Anthropic)
export ANTHROPIC_API_KEY="..."

# Run against the current directory
cargo run -- --project . --model claude-opus-4-6

# Run with a fixed session to resume later
cargo run -- --project . --session my-session-001

# Disable approval prompts (auto-approve all tool calls)
cargo run -- --project . --auto-approve

Example session:

Coding agent ready. Type your request, or 'exit' to quit.
Session: my-session-001

you> Why is cargo test failing?

agent>
[calling list_dir]
  → src/ Cargo.toml Cargo.lock README.md tests/…
[calling run_command]
  → stdout:
    running 3 tests
    test tests::it_works ... FAILED

    failures:
      tests::it_works
    …
[calling read_file]
  → use crate::processor::process;

  #[test]
  fn it_works() {
      assert_eq!(process("hello"), "HELLO");
  }…
[calling search_code]
  → src/processor.rs:
    3:  pub fn process(input: &str) -> String {
    4:      input.to_lowercase()  ← match here
[calling write_file]

⚠ Approval required
  Tool: write_file
  Risk: Medium
  Args: { "path": "src/processor.rs", "content": "pub fn process ..." }
  Allow? [y]es / [a]lways / [n]o: y

[calling run_command]
  → stdout: test result: ok. 3 passed

[tokens: 2847↑ 412↓]
[done: Complete]

I found the issue: `process()` returns lowercase but the test expects uppercase.
I changed `to_lowercase()` to `to_uppercase()` in `src/processor.rs`.
All 3 tests now pass.

Step 11: Session continuity

The session_id in RunnerConfig tells the runner to load and save conversation history via InMemorySessionManager. To persist sessions across process restarts, swap the session manager:

#![allow(unused)]
fn main() {
// In agent.rs, when building the Runner:
use synwire_agent::session::InMemorySessionManager;
use std::sync::Arc;

// In-memory session (lost on exit — good for development):
let session_manager = Arc::new(InMemorySessionManager::new());

// For production, implement SessionManager backed by a database.
// The runner accepts any Arc<dyn SessionManager>:
let runner = Runner::new(agent)
    .with_session_manager(session_manager);
}

With a fixed --session argument, the agent picks up the conversation exactly where it left off, including the full tool call history. This is how multi-session coding workflows — "continue the refactor you started yesterday" — become possible.

Step 12: Extension ideas

Now that you have the foundation, here are natural next steps:

Git-aware operations

Replace LocalProvider with GitBackend to give the agent version control awareness. The agent can then check git diff, create commits, and revert changes:

#![allow(unused)]
fn main() {
use synwire_agent::vfs::git::GitBackend;

let backend = Arc::new(GitBackend::new(&project_root)?);
// The agent can now call run_command("git", ["diff", "--stat"])
// and GitBackend enforces the repository boundary.
}

Multi-file context via search first

Constrain the agent to always search before reading. Add this to the system prompt:

Before reading any file, always call search_code with the symbol name to find where it is defined. Only then call read_file on the relevant file.

Streaming diffs in the terminal

Intercept write_file tool calls in the approval gate to show a diff before applying:

#![allow(unused)]
fn main() {
// In approval.rs, compute and show a diff before accepting.
use similar::{ChangeTag, TextDiff};

let diff = TextDiff::from_lines(&old_content, &new_content);
for change in diff.iter_all_changes() {
    match change.tag() {
        ChangeTag::Delete => eprint!("\x1b[31m- {change}\x1b[0m"),
        ChangeTag::Insert => eprint!("\x1b[32m+ {change}\x1b[0m"),
        ChangeTag::Equal  => eprint!("  {change}"),
    }
}
}

Parallel sub-agents

For large refactors, spawn a sub-agent per file using Directive::SpawnAgent. The orchestrator collects results via the directive system without blocking the main conversation.

Local inference with Ollama

Swap the provider without changing any other code:

[dependencies]
synwire-llm-ollama = "0.1"

#![allow(unused)]
fn main() {
// src/main.rs
use synwire_llm_ollama::ChatOllama;

// Replace ChatOpenAI with ChatOllama — same BaseChatModel trait.
let runner = Runner::new(agent)
    .with_model(ChatOllama::builder().model("codestral").build()?);
}

See Local Inference with Ollama for setup instructions.

Language server intelligence (LSP)

Add the synwire-lsp crate to give the agent semantic code understanding — hover documentation, go-to-definition, find-references, and real-time diagnostics — without reading every file:

[dependencies]
synwire-lsp = "0.1"

use synwire_lsp::plugin::LspPlugin;
use synwire_lsp::registry::LanguageServerRegistry;
use synwire_lsp::config::LspPluginConfig;

let registry = LanguageServerRegistry::default_registry();
let lsp = LspPlugin::new(registry, LspPluginConfig::default());

let agent = Agent::new("coder", "coding assistant")
    .plugin(Box::new(lsp))
    // ... other configuration
    .build()?;

The plugin auto-detects language servers on PATH based on file extension. For a Rust project, if rust-analyzer is installed, tools like lsp_goto_definition, lsp_hover, and lsp_diagnostics become available immediately. Add a line to the system prompt to take advantage:

Before reading an entire file, use lsp_hover or lsp_goto_definition to navigate directly to the relevant symbol. Use lsp_diagnostics after edits to check for errors without running a full build.

See How-To: LSP Integration for full details.

Interactive debugging (DAP)

Add the synwire-dap crate so the agent can debug failing tests by setting breakpoints and inspecting runtime values:

[dependencies]
synwire-dap = "0.1"

use synwire_dap::plugin::DapPlugin;
use synwire_dap::registry::DebugAdapterRegistry;
use synwire_dap::config::DapPluginConfig;

let registry = DebugAdapterRegistry::default_registry();
let dap = DapPlugin::new(registry, DapPluginConfig::default());

let agent = Agent::new("coder", "coding assistant")
    .plugin(Box::new(dap))
    // ... other configuration
    .build()?;

The agent gains tools like debug.launch, debug.set_breakpoints, debug.continue, debug.variables, and debug.evaluate. Add a system prompt hint:

When a test fails and the cause is not obvious from the source code, use debug.launch to run it under the debugger. Set a breakpoint at the failing assertion, then use debug.variables to inspect local state.

Note that debug.evaluate is marked as destructive since it can execute arbitrary code in the debuggee — the approval gate will prompt the user before execution.

See How-To: DAP Integration for full details.

What you have built

You now have a working coding agent with:

See also

• Tutorial 5: File and Shell Operations — deep dive into Vfs, path traversal protection, and GrepOptions
• Tutorial 2: Testing Without Side Effects — RecordingExecutor for testing directives without executing them
• How-To: Approval Gates — ThresholdGate and RiskLevel-based approval
• How-To: MCP Integration — give the agent access to external tools via the Model Context Protocol
• How-To: Backend Implementations — CompositeProvider, GitBackend, and custom backends
• Explanation: synwire-agent — full reference for the Runner, middleware, and all backends
• Local Inference with Ollama — run the agent locally without an API key
• Explanation: StateGraph vs FsmStrategy — when to use an agent runtime vs. a graph workflow
• How-To: LSP Integration — add code intelligence tools (hover, goto-definition, diagnostics) to your agent
• How-To: DAP Integration — add interactive debugging (breakpoints, stepping, variable inspection)
• Explanation: synwire-lsp — architecture and design of the LSP integration
• Explanation: synwire-dap — architecture and design of the DAP integration

Background: AI Workflows vs AI Agents — the distinction between an orchestrated pipeline and a ReAct agent loop; this tutorial builds the latter. Context Engineering for AI Agents — how the system prompt and tool descriptions shape agent behaviour.

Tutorial 8: Deep Research + Coding Agent

Time: ~2 hours Prerequisites: Rust 1.85+, completion of Tutorial 7: Building a Coding Agent, completion of Tutorial 3: Execution Strategies

Background: AI Workflows vs AI Agents — the distinction between a static multi-step workflow and an open-ended agent loop. This tutorial uses both: the coding agent is an open-ended agent that decides what to do; the deep research tool it can call is a fixed workflow.

This tutorial builds a coding agent that can invoke deep research as a tool. Two Synwire primitives compose to make this work:

The key idea: the StateGraph pipeline is not the top-level entrypoint — it is wrapped as a StructuredTool and handed to an FSM-governed coding agent. The agent decides when to call deep_research, and the FSM ensures it does so before writing any code.

graph TD
    subgraph "Coding Agent (FsmStrategy)"
        A[Idle] -->|start| B[Researching]
        B -->|"deep_research ✓"| C[Implementing]
        C -->|"files written"| D[Testing]
        D -->|pass| E[Done]
        D -->|"fail (retries < 3)"| C
    end

    subgraph "deep_research tool (StateGraph)"
        R1[explore_codebase] --> R2[synthesise_report]
        R2 --> R3[END]
    end

    B -.->|"agent calls deep_research"| R1
    R3 -.->|"returns report"| C

• The outer agent uses FsmStrategy to enforce: research first, then implement, then test.
• The inner tool uses StateGraph to chain two nodes: codebase exploration → report synthesis.
• The agent sees deep_research as just another tool — it doesn't know there's a graph inside.

📖 Rust note: A StructuredTool wraps a closure Fn(Value) -> BoxFuture<Result<ToolOutput, SynwireError>>. Because StateGraph::invoke is an async function that returns Result<S, GraphError>, wrapping a graph as a tool is a one-liner: call invoke inside the closure, serialise the result.

Architecture: why the agent holds the graph, not the other way round

In Tutorial 7 the coding agent was a standalone tool-calling loop. In this tutorial, the agent gains a research capability — but the research itself is a multi-step pipeline that's too complex for a single tool call.

You could build this two ways:

The agent-first approach is more powerful: the agent can skip research for trivial tasks, call it multiple times for complex ones, or interleave research with implementation. The FSM still prevents it from writing code without researching first — you get autonomy within structural bounds.

Background: Agent Components — the deep research tool is the agent's memory retrieval component. The FSM is its planning component. Tools are its action component.

Step 1: Project setup

[package]
name = "synwire-research-coder"
version = "0.1.0"
edition = "2024"

[dependencies]
# Agent runtime + FSM strategy
synwire-core  = "0.1"
synwire-agent = "0.1"

# Graph orchestration (for the research tool's internal pipeline)
synwire-orchestrator = "0.1"
synwire-derive       = "0.1"

# LLM provider
synwire-llm-openai = "0.1"

# Async + serde
tokio        = { version = "1", features = ["full"] }
serde        = { version = "1", features = ["derive"] }
serde_json   = "1"
schemars     = { version = "0.8", features = ["derive"] }

# Error handling + CLI
anyhow = "1"
clap   = { version = "4", features = ["derive"] }

[dev-dependencies]
synwire-test-utils = "0.1"
tempfile           = "3"

Step 2: The research pipeline state

The research graph has its own typed state, separate from the outer agent's working memory. This state flows through the two graph nodes and is discarded after the tool call completes — only the final report string is returned to the agent.

📖 Rust note: #[derive(State)] generates the State trait implementation. #[reducer(last_value)] overwrites on each superstep; #[reducer(topic)] appends. See synwire-derive.

#![allow(unused)]
fn main() {
// src/research/state.rs
use serde::{Deserialize, Serialize};
use synwire_derive::State;

/// Internal state for the deep research pipeline.
///
/// This state is NOT exposed to the outer coding agent.
/// Only `report` is extracted and returned as the tool result.
#[derive(State, Debug, Clone, Default, Serialize, Deserialize)]
pub struct ResearchState {
    /// The question or task to research.
    #[reducer(last_value)]
    pub query: String,

    /// Absolute path to the project root.
    #[reducer(last_value)]
    pub project_root: String,

    /// Files discovered and read during exploration.
    #[reducer(topic)]
    pub files_explored: Vec<String>,

    /// Raw findings from the exploration node (file contents, search hits).
    #[reducer(topic)]
    pub raw_findings: Vec<String>,

    /// Final synthesised report returned to the caller.
    #[reducer(last_value)]
    pub report: String,
}
}

Step 3: The exploration node

The first graph node uses a DirectStrategy agent to explore the codebase. It reads files, searches for patterns, and records raw findings.

#![allow(unused)]
fn main() {
// src/research/explore.rs
use std::sync::Arc;

use synwire_core::agents::agent_node::Agent;
use synwire_core::agents::runner::{Runner, RunnerConfig};
use synwire_core::agents::streaming::AgentEvent;
use synwire_orchestrator::error::GraphError;

use crate::backend::create_backend;
use crate::research::state::ResearchState;
use crate::tools::{list_dir_tool, read_file_tool, search_code_tool};

/// Exploration node: agent reads the codebase and populates `raw_findings`.
pub async fn explore_node(mut state: ResearchState) -> Result<ResearchState, GraphError> {
    let backend = create_backend(state.project_root.clone().into())
        .map_err(|e| GraphError::NodeError { message: e.to_string() })?;
    let backend = Arc::new(backend);

    let system = format!(
        r#"You are a code researcher exploring a Rust codebase.

Your goal: gather all information relevant to this question:
  {query}

Use list_dir to understand project structure, search_code to find relevant
symbols and patterns, and read_file to read the actual source.

Focus on:
- Relevant types, traits, and functions
- Test patterns and conventions
- Module boundaries and public APIs
- Any existing code that relates to the question

Output your findings as structured notes — one paragraph per file or concept.
Be thorough but focused: only include information that helps answer the question."#,
        query = state.query,
    );

    let read   = read_file_tool(Arc::clone(&backend) as Arc<_>)
        .map_err(|e| GraphError::NodeError { message: e.to_string() })?;
    let ls     = list_dir_tool(Arc::clone(&backend) as Arc<_>)
        .map_err(|e| GraphError::NodeError { message: e.to_string() })?;
    let search = search_code_tool(Arc::clone(&backend) as Arc<_>)
        .map_err(|e| GraphError::NodeError { message: e.to_string() })?;

    let agent = Agent::new("explorer", "claude-opus-4-6")
        .system_prompt(system)
        .tool(read)
        .tool(ls)
        .tool(search)
        .max_turns(20);

    let runner = Runner::new(agent);
    let mut stream = runner
        .run(serde_json::json!(state.query.clone()), RunnerConfig::default())
        .await
        .map_err(|e| GraphError::NodeError { message: e.to_string() })?;

    let mut findings = String::new();
    while let Some(event) = stream.recv().await {
        match event {
            AgentEvent::TextDelta { content } => findings.push_str(&content),
            AgentEvent::Error { message } => {
                return Err(GraphError::NodeError { message });
            }
            _ => {}
        }
    }

    state.raw_findings.push(findings);
    Ok(state)
}
}

Step 4: The synthesis node

The second graph node is a one-shot agent that reads the raw findings and produces a structured report. No tools needed — just reasoning.

#![allow(unused)]
fn main() {
// src/research/synthesise.rs
use synwire_core::agents::agent_node::Agent;
use synwire_core::agents::runner::{Runner, RunnerConfig};
use synwire_core::agents::streaming::AgentEvent;
use synwire_orchestrator::error::GraphError;

use crate::research::state::ResearchState;

/// Synthesis node: distils raw findings into a structured report.
pub async fn synthesise_node(mut state: ResearchState) -> Result<ResearchState, GraphError> {
    let system = r#"You receive raw findings from a codebase exploration and produce
a structured research report. Format the report as markdown with these sections:

1. **Relevant Code** — files, types, and functions that relate to the task
2. **Data Types** — key structs, enums, and traits the implementation must use
3. **Test Patterns** — how existing tests are structured in this project
4. **Integration Points** — where new code should fit in
5. **Constraints** — things the implementation must not break

Be concise. The implementation agent will use this report to guide its work."#;

    let prompt = format!(
        "Question: {}\n\nRaw findings:\n{}",
        state.query,
        state.raw_findings.join("\n\n---\n\n"),
    );

    let agent = Agent::new("synthesiser", "claude-opus-4-6")
        .system_prompt(system)
        .max_turns(1);

    let runner = Runner::new(agent);
    let mut stream = runner
        .run(serde_json::json!(prompt), RunnerConfig::default())
        .await
        .map_err(|e| GraphError::NodeError { message: e.to_string() })?;

    let mut report = String::new();
    while let Some(event) = stream.recv().await {
        match event {
            AgentEvent::TextDelta { content } => report.push_str(&content),
            AgentEvent::Error { message } => {
                return Err(GraphError::NodeError { message });
            }
            _ => {}
        }
    }

    state.report = report;
    Ok(state)
}
}

Step 5: Assembling the research graph

Two nodes, one edge, no conditionals:

#![allow(unused)]
fn main() {
// src/research/graph.rs
use synwire_orchestrator::constants::END;
use synwire_orchestrator::error::GraphError;
use synwire_orchestrator::graph::{CompiledGraph, StateGraph};

use crate::research::explore::explore_node;
use crate::research::state::ResearchState;
use crate::research::synthesise::synthesise_node;

/// Build and compile the two-stage research pipeline.
///
/// ```text
/// START → explore → synthesise → END
/// ```
pub fn build_research_graph() -> Result<CompiledGraph<ResearchState>, GraphError> {
    let mut graph = StateGraph::<ResearchState>::new();

    graph.add_node("explore",    Box::new(|s| Box::pin(explore_node(s))))?;
    graph.add_node("synthesise", Box::new(|s| Box::pin(synthesise_node(s))))?;

    graph
        .set_entry_point("explore")
        .add_edge("explore", "synthesise")
        .add_edge("synthesise", END);

    graph.compile()
}
}

Step 6: Wrapping the graph as a tool

This is the composition point. The StateGraph pipeline becomes a StructuredTool — the agent sees it as a single function call that takes a query and returns a research report.

📖 Rust note: Arc (Atomic Reference Count) allows multiple owners of a value across threads. The compiled graph is Send + Sync, so wrapping it in Arc lets the tool closure capture it safely. The closure itself must be Fn (not FnOnce) because it may be called multiple times.

#![allow(unused)]
fn main() {
// src/research/tool.rs
use std::sync::Arc;

use synwire_core::BoxFuture;
use synwire_core::error::SynwireError;
use synwire_core::tools::{StructuredTool, ToolOutput, ToolSchema};

use crate::research::graph::build_research_graph;
use crate::research::state::ResearchState;

/// Creates the `deep_research` tool.
///
/// When invoked, this tool:
/// 1. Builds a `ResearchState` from the JSON input
/// 2. Runs the two-stage `StateGraph` (explore → synthesise)
/// 3. Returns the synthesised report as the tool output
///
/// The calling agent never sees the internal graph topology —
/// it receives a plain-text research report.
pub fn deep_research_tool(
    project_root: String,
) -> Result<StructuredTool, SynwireError> {
    // Compile the graph once; share it across invocations via Arc.
    let graph = Arc::new(
        build_research_graph()
            .map_err(|e| SynwireError::Tool(
                synwire_core::error::ToolError::InvocationFailed {
                    message: format!("failed to compile research graph: {e}"),
                },
            ))?,
    );

    let root = project_root.clone();

    StructuredTool::builder()
        .name("deep_research")
        .description(
            "Performs deep codebase research. Takes a question about the codebase \
             and returns a structured report covering relevant code, data types, \
             test patterns, integration points, and constraints. Use this BEFORE \
             writing any code to understand the existing codebase."
        )
        .schema(ToolSchema {
            name: "deep_research".into(),
            description: "Deep codebase research tool".into(),
            parameters: serde_json::json!({
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The research question about the codebase"
                    }
                },
                "required": ["query"]
            }),
        })
        .func(move |input: serde_json::Value| -> BoxFuture<'static, Result<ToolOutput, SynwireError>> {
            let graph = Arc::clone(&graph);
            let project_root = root.clone();

            Box::pin(async move {
                let query = input["query"]
                    .as_str()
                    .unwrap_or("general codebase overview")
                    .to_owned();

                let initial = ResearchState {
                    query,
                    project_root,
                    ..ResearchState::default()
                };

                // Run the two-stage pipeline to completion.
                let result = graph.invoke(initial).await.map_err(|e| {
                    SynwireError::Tool(synwire_core::error::ToolError::InvocationFailed {
                        message: format!("research pipeline failed: {e}"),
                    })
                })?;

                Ok(ToolOutput {
                    content: result.report,
                    ..Default::default()
                })
            })
        })
        .build()
}
}

What just happened

The entire StateGraph — two agents, file I/O tools, a synthesis step — is now hidden behind a single deep_research(query: String) -> String interface. From the outer coding agent's perspective, it's no different from read_file or search_code. But internally, it spawns two sub-agents, explores the codebase, and synthesises findings.

This is the composability the crate architecture enables: synwire-orchestrator and synwire-agent are independent crates that compose through synwire-core's Tool trait.

Step 7: The coding agent's FSM

The FSM constrains the coding agent's turn loop. The critical constraint: the agent must call deep_research before it can write any files.

#![allow(unused)]
fn main() {
// src/fsm.rs
use serde_json::Value;
use synwire_agent::strategies::fsm::{FsmStrategy, FsmStrategyWithRoutes};
use synwire_core::agents::execution_strategy::{ClosureGuard, StrategyError};

/// FSM states for the coding agent.
pub mod states {
    pub const IDLE:          &str = "idle";
    pub const RESEARCHING:   &str = "researching";
    pub const IMPLEMENTING:  &str = "implementing";
    pub const TESTING:       &str = "testing";
    pub const DONE:          &str = "done";
}

/// Actions that drive FSM transitions.
pub mod actions {
    /// Idle → Researching: agent starts working.
    pub const START:              &str = "start";
    /// Researching → Implementing: deep_research has been called.
    pub const RESEARCH_COMPLETE:  &str = "research_complete";
    /// Implementing → Testing: at least one file written.
    pub const RUN_TESTS:          &str = "run_tests";
    /// Testing → Done: tests passed.
    pub const TESTS_PASS:         &str = "tests_pass";
    /// Testing → Implementing: tests failed, retry.
    pub const TESTS_FAIL:         &str = "tests_fail";
}

/// Payload keys inspected by guards.
pub mod payload {
    pub const RESEARCH_CALLS:  &str = "research_calls";
    pub const FILES_WRITTEN:   &str = "files_written";
    pub const RETRIES:         &str = "retries";
}

/// Build the FSM for the coding agent.
///
/// ```text
/// idle → [start] → researching
/// researching → [research_complete | research_calls > 0] → implementing
/// implementing → [run_tests | files_written > 0] → testing
/// testing → [tests_pass] → done
/// testing → [tests_fail | retries < 3] → implementing
/// ```
///
/// Guards enforce three invariants:
/// 1. Agent must call `deep_research` at least once before implementing.
/// 2. Agent must write at least one file before running tests.
/// 3. Test retries are capped at 3.
pub fn build_coder_fsm() -> Result<FsmStrategyWithRoutes, StrategyError> {
    let guard_has_researched = ClosureGuard::new(
        "has_researched",
        |p: &Value| p[payload::RESEARCH_CALLS].as_u64().unwrap_or(0) > 0,
    );

    let guard_has_written = ClosureGuard::new(
        "has_written",
        |p: &Value| p[payload::FILES_WRITTEN].as_u64().unwrap_or(0) > 0,
    );

    let guard_retry_allowed = ClosureGuard::new(
        "retry_allowed",
        |p: &Value| p[payload::RETRIES].as_u64().unwrap_or(0) < 3,
    );

    FsmStrategy::builder()
        .state(states::IDLE)
        .state(states::RESEARCHING)
        .state(states::IMPLEMENTING)
        .state(states::TESTING)
        .state(states::DONE)
        // idle → researching (unconditional)
        .transition(states::IDLE, actions::START, states::RESEARCHING)
        // researching → implementing (must have called deep_research)
        .transition_with_guard(
            states::RESEARCHING,
            actions::RESEARCH_COMPLETE,
            states::IMPLEMENTING,
            guard_has_researched,
            10,
        )
        // implementing → testing (must have written at least one file)
        .transition_with_guard(
            states::IMPLEMENTING,
            actions::RUN_TESTS,
            states::TESTING,
            guard_has_written,
            10,
        )
        // testing → done
        .transition(states::TESTING, actions::TESTS_PASS, states::DONE)
        // testing → implementing (retry if allowed)
        .transition_with_guard(
            states::TESTING,
            actions::TESTS_FAIL,
            states::IMPLEMENTING,
            guard_retry_allowed,
            10,
        )
        .initial(states::IDLE)
        .build()
}
}

Testing the FSM in isolation

The FSM is pure Rust — no model, no I/O:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    use synwire_core::agents::execution_strategy::{ExecutionStrategy, StrategyError};

    #[tokio::test]
    async fn cannot_implement_without_research() {
        let fsm = build_coder_fsm().unwrap();

        // Start working.
        fsm.execute(actions::START, serde_json::json!({})).await.unwrap();

        // Try to skip research.
        let err = fsm
            .execute(
                actions::RESEARCH_COMPLETE,
                serde_json::json!({ payload::RESEARCH_CALLS: 0 }),
            )
            .await
            .expect_err("guard should reject");

        assert!(matches!(err, StrategyError::GuardRejected(_)));
    }

    #[tokio::test]
    async fn research_then_implement_succeeds() {
        let fsm = build_coder_fsm().unwrap();

        fsm.execute(actions::START, serde_json::json!({})).await.unwrap();
        fsm.execute(
            actions::RESEARCH_COMPLETE,
            serde_json::json!({ payload::RESEARCH_CALLS: 1 }),
        )
        .await
        .unwrap();

        // Now in implementing state — can write files.
        assert_eq!(
            fsm.strategy.current_state().unwrap().0,
            states::IMPLEMENTING,
        );
    }

    #[tokio::test]
    async fn cannot_test_without_writing() {
        let fsm = build_coder_fsm().unwrap();
        fsm.execute(actions::START, serde_json::json!({})).await.unwrap();
        fsm.execute(
            actions::RESEARCH_COMPLETE,
            serde_json::json!({ payload::RESEARCH_CALLS: 1 }),
        )
        .await
        .unwrap();

        let err = fsm
            .execute(
                actions::RUN_TESTS,
                serde_json::json!({ payload::FILES_WRITTEN: 0 }),
            )
            .await
            .expect_err("guard should reject");
        assert!(matches!(err, StrategyError::GuardRejected(_)));
    }

    #[tokio::test]
    async fn retry_capped_at_three() {
        let fsm = build_coder_fsm().unwrap();

        // Advance to testing.
        fsm.execute(actions::START, serde_json::json!({})).await.unwrap();
        fsm.execute(
            actions::RESEARCH_COMPLETE,
            serde_json::json!({ payload::RESEARCH_CALLS: 1 }),
        )
        .await
        .unwrap();
        fsm.execute(
            actions::RUN_TESTS,
            serde_json::json!({ payload::FILES_WRITTEN: 1 }),
        )
        .await
        .unwrap();

        // Three retries succeed.
        for i in 0..3 {
            fsm.execute(
                actions::TESTS_FAIL,
                serde_json::json!({ payload::RETRIES: i }),
            )
            .await
            .unwrap();
            fsm.execute(
                actions::RUN_TESTS,
                serde_json::json!({ payload::FILES_WRITTEN: 1 }),
            )
            .await
            .unwrap();
        }

        // Fourth retry rejected.
        let err = fsm
            .execute(
                actions::TESTS_FAIL,
                serde_json::json!({ payload::RETRIES: 3 }),
            )
            .await
            .expect_err("retry limit");
        assert!(matches!(err, StrategyError::GuardRejected(_)));
    }

    #[tokio::test]
    async fn happy_path_reaches_done() {
        let fsm = build_coder_fsm().unwrap();

        fsm.execute(actions::START, serde_json::json!({})).await.unwrap();
        fsm.execute(
            actions::RESEARCH_COMPLETE,
            serde_json::json!({ payload::RESEARCH_CALLS: 1 }),
        )
        .await
        .unwrap();
        fsm.execute(
            actions::RUN_TESTS,
            serde_json::json!({ payload::FILES_WRITTEN: 2 }),
        )
        .await
        .unwrap();
        fsm.execute(actions::TESTS_PASS, serde_json::json!({}))
            .await
            .unwrap();

        assert_eq!(fsm.strategy.current_state().unwrap().0, states::DONE);
    }
}
}

Step 8: The coding agent

Now assemble the agent with all its tools, including deep_research:

📖 Rust note: move closures take ownership of captured variables. The event-loop closure captures Arc clones of the counters and FSM, so each closure call can mutate the shared counters through Mutex::lock().

#![allow(unused)]
fn main() {
// src/agent.rs
use std::sync::{Arc, Mutex};

use synwire_core::agents::agent_node::Agent;
use synwire_core::agents::permission::{PermissionBehavior, PermissionMode, PermissionRule};
use synwire_core::agents::runner::{Runner, RunnerConfig};
use synwire_core::agents::streaming::AgentEvent;

use crate::backend::create_backend;
use crate::fsm::{actions, build_coder_fsm, payload, states};
use crate::research::tool::deep_research_tool;
use crate::tools::{
    list_dir_tool, read_file_tool, run_command_tool, search_code_tool, write_file_tool,
};

/// Result of running the coding agent.
pub struct CodingResult {
    pub files_written: Vec<String>,
    pub test_output: String,
    pub test_passed: bool,
    pub research_report: String,
}

/// Build and run the FSM-governed coding agent.
///
/// The agent has six tools:
///
/// | Tool | Purpose | FSM constraint |
/// |---|---|---|
/// | `deep_research` | Runs the StateGraph research pipeline | Must call before implementing |
/// | `read_file` | Read source files | Allowed in all states |
/// | `list_dir` | List directories | Allowed in all states |
/// | `search_code` | Search for patterns | Allowed in all states |
/// | `write_file` | Write source files | Only after research |
/// | `run_command` | Run cargo test | Only after writing files |
pub async fn run_coding_agent(
    task: &str,
    project_root: &str,
) -> anyhow::Result<CodingResult> {
    let backend = Arc::new(create_backend(project_root.into())?);

    // ── Tools ─────────────────────────────────────────────────────────────

    let deep_research = deep_research_tool(project_root.to_owned())?;
    let read   = read_file_tool(Arc::clone(&backend) as Arc<_>)?;
    let write  = write_file_tool(Arc::clone(&backend) as Arc<_>)?;
    let ls     = list_dir_tool(Arc::clone(&backend) as Arc<_>)?;
    let search = search_code_tool(Arc::clone(&backend) as Arc<_>)?;
    let run    = run_command_tool(Arc::clone(&backend) as Arc<_>)?;

    // ── FSM ───────────────────────────────────────────────────────────────

    let fsm = Arc::new(build_coder_fsm()?);

    // Counters for FSM guard payloads.
    let research_calls:  Arc<Mutex<u32>> = Arc::new(Mutex::new(0));
    let files_written:   Arc<Mutex<u32>> = Arc::new(Mutex::new(0));
    let retries:         Arc<Mutex<u32>> = Arc::new(Mutex::new(0));

    // ── Agent ─────────────────────────────────────────────────────────────

    let system = format!(
        r#"You are a coding agent that implements changes to a Rust project.

# Your task
{task}

# Workflow
1. FIRST, call deep_research to understand the existing codebase.
   Pass a focused question about what you need to understand.
2. Read the research report carefully before writing any code.
3. Implement the changes by writing files.
4. Run `cargo test` to verify your changes.
5. If tests fail, read the error output and fix the code.

# Rules
- You MUST call deep_research before writing any files.
- You MUST write files before running tests.
- You may call deep_research multiple times with different questions.
- Read files directly with read_file for quick lookups; use deep_research
  for broader understanding.

When all tests pass, state that you are done."#,
    );

    let agent = Agent::new("coder", "claude-opus-4-6")
        .system_prompt(system)
        .tool(deep_research)
        .tool(read)
        .tool(write)
        .tool(ls)
        .tool(search)
        .tool(run)
        .permission_rules(vec![
            PermissionRule {
                tool_pattern: "*".into(),
                behavior: PermissionBehavior::Allow,
            },
        ])
        .permission_mode(PermissionMode::DenyUnauthorized)
        .max_turns(50);

    // ── Kick off ──────────────────────────────────────────────────────────

    // Transition to Researching immediately.
    fsm.execute(actions::START, serde_json::json!({})).await?;

    let runner = Runner::new(agent);
    let mut stream = runner
        .run(serde_json::json!(task), RunnerConfig::default())
        .await?;

    // ── Event loop ────────────────────────────────────────────────────────

    let mut result = CodingResult {
        files_written: Vec::new(),
        test_output: String::new(),
        test_passed: false,
        research_report: String::new(),
    };

    let fsm_ref           = Arc::clone(&fsm);
    let research_ctr      = Arc::clone(&research_calls);
    let files_written_ctr = Arc::clone(&files_written);
    let retries_ctr       = Arc::clone(&retries);

    while let Some(event) = stream.recv().await {
        match &event {
            AgentEvent::ToolResult { name, output, .. } => {
                let current = fsm_ref.strategy.current_state()?;

                match name.as_str() {
                    "deep_research" => {
                        // Record the research report.
                        result.research_report.push_str(&output.content);
                        result.research_report.push_str("\n\n---\n\n");

                        // Increment research call counter.
                        *research_ctr.lock().unwrap() += 1;
                        let rc = *research_ctr.lock().unwrap();

                        // Advance FSM: researching → implementing.
                        if current.0 == states::RESEARCHING {
                            let _ = fsm_ref.execute(
                                actions::RESEARCH_COMPLETE,
                                serde_json::json!({ payload::RESEARCH_CALLS: rc }),
                            ).await;
                        }
                    }

                    "write_file" => {
                        *files_written_ctr.lock().unwrap() += 1;
                        // Extract the file path from the tool call input if available.
                        result.files_written.push(
                            output.content.lines().next().unwrap_or("unknown").to_owned()
                        );
                    }

                    "run_command" => {
                        // Check test results.
                        if current.0 == states::IMPLEMENTING {
                            // First, try to advance to Testing.
                            let fw = *files_written_ctr.lock().unwrap();
                            let _ = fsm_ref.execute(
                                actions::RUN_TESTS,
                                serde_json::json!({ payload::FILES_WRITTEN: fw }),
                            ).await;
                        }

                        let current = fsm_ref.strategy.current_state()?;
                        if current.0 == states::TESTING {
                            let passed = output.content.contains("test result: ok");
                            result.test_output = output.content.clone();

                            if passed {
                                result.test_passed = true;
                                let _ = fsm_ref.execute(
                                    actions::TESTS_PASS,
                                    serde_json::json!({}),
                                ).await;
                            } else {
                                let r = *retries_ctr.lock().unwrap();
                                let _ = fsm_ref.execute(
                                    actions::TESTS_FAIL,
                                    serde_json::json!({ payload::RETRIES: r }),
                                ).await;
                                *retries_ctr.lock().unwrap() += 1;
                            }
                        }
                    }

                    _ => {}
                }
            }

            AgentEvent::Error { message } => {
                anyhow::bail!("Agent error: {message}");
            }

            _ => {}
        }
    }

    Ok(result)
}
}

Step 9: The main binary

// src/main.rs
mod agent;
mod backend;
mod fsm;
mod research;
mod tools;

use clap::Parser;

#[derive(Parser)]
#[command(version, about = "Coding agent with deep research capability")]
struct Cli {
    /// The coding task to complete.
    task: String,

    /// Project root directory.
    #[arg(short, long, default_value = ".")]
    project: String,
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let cli = Cli::parse();

    let project_root = std::path::Path::new(&cli.project)
        .canonicalize()?
        .to_string_lossy()
        .into_owned();

    println!("Task: {}", cli.task);
    println!("Project root: {project_root}");
    println!();

    let result = agent::run_coding_agent(&cli.task, &project_root).await?;

    println!("\n── Research report ──────────────────────────────────────\n");
    println!("{}", result.research_report);

    println!("\n── Test output ──────────────────────────────────────────\n");
    println!("{}", result.test_output);

    if result.test_passed {
        println!("\nPipeline completed successfully.");
        println!("Files modified: {:?}", result.files_written);
    } else {
        eprintln!("\nTests did not pass after all retries.");
        std::process::exit(1);
    }

    Ok(())
}

Run it:

export ANTHROPIC_API_KEY="..."

cargo run -- \
  --project /path/to/my-crate \
  "Add a words_longer_than function to src/text.rs that takes a &str \
   and a usize threshold and returns Vec<&str> of words longer than \
   the threshold. Add tests."

What happens:

1. The agent starts in Idle, transitions to Researching.
2. The agent calls deep_research("How is src/text.rs structured? What existing functions and tests exist?").
3. Inside deep_research, the StateGraph runs: explore_node reads the codebase with sub-agents → synthesise_node produces a report → the report string is returned.
4. The FSM transitions to Implementing. The agent can now call write_file.
5. The agent writes src/text.rs, calls cargo test.
6. The FSM transitions to Testing. On pass → Done. On fail → back to Implementing (up to 3 retries).

Step 10: Testing the composition

Unit test: the research tool returns a report

#![allow(unused)]
fn main() {
// tests/research_tool.rs
use synwire_test_utils::fake_chat_model::FakeChatModel;

/// Verify the deep_research tool compiles its graph and accepts input.
#[tokio::test]
async fn deep_research_tool_accepts_query() {
    // In a real test, you'd inject a FakeChatModel into the graph nodes.
    // Here we just verify the tool builds without error.
    let tool = synwire_research_coder::research::tool::deep_research_tool(
        "/tmp/test-project".to_owned(),
    );
    assert!(tool.is_ok());

    let tool = tool.unwrap();
    assert_eq!(synwire_core::tools::Tool::name(&tool), "deep_research");
}
}

Integration test: FSM blocks premature writes

#![allow(unused)]
fn main() {
// tests/fsm_integration.rs
use synwire_core::agents::execution_strategy::{ExecutionStrategy, StrategyError};
use synwire_research_coder::fsm::*;

/// The FSM must reject write_file before deep_research has been called.
#[tokio::test]
async fn fsm_blocks_implement_before_research() {
    let fsm = build_coder_fsm().unwrap();

    // Start → Researching.
    fsm.execute(actions::START, serde_json::json!({})).await.unwrap();

    // Try to skip straight to implementing.
    let err = fsm
        .execute(
            actions::RESEARCH_COMPLETE,
            serde_json::json!({ payload::RESEARCH_CALLS: 0 }),
        )
        .await
        .expect_err("should be blocked by guard");

    assert!(matches!(err, StrategyError::GuardRejected(_)));
}
}

Verify graph topology

#![allow(unused)]
fn main() {
// tests/research_graph.rs
use synwire_research_coder::research::graph::build_research_graph;

#[test]
fn research_graph_has_two_nodes() {
    let graph = build_research_graph().unwrap();
    let mut names = graph.node_names();
    names.sort_unstable();
    assert_eq!(names, ["explore", "synthesise"]);
}

#[test]
fn research_graph_entry_is_explore() {
    let graph = build_research_graph().unwrap();
    assert_eq!(graph.entry_point(), "explore");
}
}

How the primitives compose

Coding Agent (FsmStrategy: Idle → Researching → Implementing → Testing → Done)
│
├── Tools available:
│   ├── deep_research ← wraps a StateGraph
│   │   └── explore_node (DirectStrategy agent)
│   │       └── read_file, list_dir, search_code
│   │   └── synthesise_node (one-shot agent)
│   │       └── (no tools — reasoning only)
│   ├── read_file
│   ├── write_file
│   ├── list_dir
│   ├── search_code
│   └── run_command
│
└── FSM enforces:
    1. deep_research called ≥1 time before write_file
    2. write_file called ≥1 time before run_command (test)
    3. test retry ≤ 3 times

The StateGraph is encapsulated inside the tool's closure. The FsmStrategy governs the outer agent. Neither knows the other exists. The only connection is the tool interface: deep_research(query) → report.

Extending the design

Multiple research tools with different graphs

Build separate tools for different research concerns:

#![allow(unused)]
fn main() {
// Code review tool: three nodes — read diff, check style, report issues.
let code_review = code_review_tool(project_root.clone())?;

// Dependency audit: two nodes — parse Cargo.toml, check advisories.
let dep_audit = dependency_audit_tool(project_root.clone())?;

let agent = Agent::new("coder", "claude-opus-4-6")
    .tool(deep_research)
    .tool(code_review)    // another graph-as-tool
    .tool(dep_audit)      // yet another graph-as-tool
    .tool(read)
    .tool(write)
    .tool(run);
}

Each tool encapsulates its own StateGraph — the agent treats them all identically.

Recursive agents: a research tool that calls research tools

Since deep_research is just a tool, a sub-agent inside the research graph could itself have tools that wrap other graphs. This is structurally legal but should be used with care — recursion depth is bounded only by the max_turns limit on each agent.

Ollama for local inference

Replace "claude-opus-4-6" with any Ollama model:

#![allow(unused)]
fn main() {
use synwire_llm_ollama::ChatOllama;

let model = ChatOllama::builder().model("codestral").build()?;
let runner = Runner::new(agent).with_model(model);
}

Both ChatOpenAI and ChatOllama implement BaseChatModel — no other changes needed. See Local Inference with Ollama.

Checkpointing

Add checkpointing to the research graph for long-running explorations:

#![allow(unused)]
fn main() {
use synwire_checkpoint::InMemoryCheckpointSaver;
use std::sync::Arc;

let saver = Arc::new(InMemoryCheckpointSaver::new());
let graph = build_research_graph()?.with_checkpoint_saver(saver);
}

If the exploration agent crashes mid-run, restarting with the same thread_id resumes from the last completed node. See Tutorial 6: Checkpointing.

What you have built

See also

• Explanation: StateGraph vs FsmStrategy — when to use each primitive and how they compose
• Tutorial 7: Building a Coding Agent — the five-tool coding agent this tutorial extends
• Tutorial 6: Checkpointing — SqliteSaver for durable graph state
• Tutorial 3: Execution Strategies — FsmStrategy and DirectStrategy from first principles
• Explanation: synwire-orchestrator — StateGraph, channels, and conditional edges
• Explanation: synwire-agent — Runner, middleware, and backend reference
• Explanation: synwire-core — Tool trait, StructuredTool, and ToolSchema
• How-To: VFS Backends — CompositeProvider, HttpBackend
• Local Inference with Ollama — run the pipeline locally

Background: AI Workflows vs AI Agents — the research pipeline is a workflow (fixed stages); the coding agent is an agent (open-ended). This tutorial shows how workflows can live inside agents as tools. Context Engineering — the research report is context the agent engineers for itself by choosing when and what to research.

Tutorial 9: Semantic Search

Time: ~1 hour Prerequisites: Rust 1.85+, completion of Your First Agent

Background: Retrieval-Augmented Generation — semantic search is the retrieval component of RAG. Instead of matching exact text, it finds code by meaning.

This tutorial covers three ways to use Synwire's semantic search:

1. Direct API — call LocalProvider methods from your own code
2. As a built-in agent tool — the agent calls semantic_search alongside file and shell tools
3. As a StateGraph node — semantic search as a stage in a multi-step pipeline

All three approaches use the same underlying pipeline: walk → chunk → embed → store → search. The difference is who controls when and how it runs.

📖 Rust note: Arc<dyn Vfs> is a thread-safe reference-counted pointer to a trait object. Arc lets multiple tools share one VFS provider without copying it. dyn Vfs means "any type implementing the Vfs trait" — the concrete type (LocalProvider) is erased at runtime.

Step 1: Enable the feature flag

Add the semantic-search feature to your synwire-agent dependency:

[dependencies]
synwire-agent = { version = "0.1", features = ["semantic-search"] }

This pulls in synwire-index, synwire-chunker, synwire-embeddings-local, and synwire-vectorstore-lancedb — everything needed for local semantic search.

Note: The first time the embedding models are used, fastembed downloads ~30 MB from Hugging Face Hub and caches them locally. Subsequent runs load from cache with no network access.

Step 2: Create a LocalProvider with semantic search

LocalProvider is the VFS implementation for local filesystem access. When the semantic-search feature is enabled, it gains index, index_status, and semantic_search capabilities.

use synwire_agent::vfs::local::LocalProvider;
use synwire_core::vfs::protocol::Vfs;
use synwire_core::vfs::types::{IndexOptions, SemanticSearchOptions};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let project_root = PathBuf::from("/path/to/your/project");
    let vfs = LocalProvider::new(project_root)?;

    // The VFS reports its capabilities — INDEX and SEMANTIC_SEARCH are included:
    let caps = vfs.capabilities();
    println!("Capabilities: {:?}", caps);

    Ok(())
}

Step 3: Index a directory

Call index() to start building the semantic index. This returns immediately with an IndexHandle — the actual work runs in a background task.

let handle = vfs.index("src", IndexOptions {
    force: false,           // reuse cache if available
    include: vec![],        // no include filter (index everything)
    exclude: vec![
        "target/**".into(), // skip build artifacts
        "*.lock".into(),    // skip lock files
    ],
    max_file_size: Some(1_048_576), // skip files over 1 MiB
}).await?;

println!("Indexing started: id={}", handle.index_id);

What happens in the background

1. Walk: synwire-index recursively traverses the directory, applying your include/exclude filters and file size limit.
2. Chunk: Each file is split into semantic units. Code files are parsed with tree-sitter to extract functions, structs, classes, and other definitions. Non-code files use a recursive character splitter.
3. Embed: Each chunk is converted into a 384-dimension vector using BAAI/bge-small-en-v1.5 (local ONNX inference).
4. Store: Vectors are written to a LanceDB table cached on disk.
5. Watch: A file watcher starts monitoring for changes to keep the index up to date.

Step 4: Wait for indexing to complete

Poll index_status() to check progress:

use synwire_core::vfs::types::IndexStatus;

loop {
    let status = vfs.index_status(&handle.index_id).await?;
    match status {
        IndexStatus::Pending => println!("Waiting to start..."),
        IndexStatus::Indexing { progress } => {
            println!("Indexing: {:.0}%", progress * 100.0);
        }
        IndexStatus::Ready(result) => {
            println!(
                "Done! {} files indexed, {} chunks produced (cached: {})",
                result.files_indexed,
                result.chunks_produced,
                result.was_cached,
            );
            break;
        }
        IndexStatus::Failed(err) => {
            eprintln!("Indexing failed: {err}");
            return Err(err.into());
        }
    }
    tokio::time::sleep(std::time::Duration::from_millis(500)).await;
}

📖 Rust note: The loop { ... break } pattern runs until break is reached. The match arms handle each variant of the [IndexStatus] enum. Rust's exhaustive matching ensures you handle every possible state — if a new variant is added, the compiler tells you.

For a medium-sized Rust project (~500 files), indexing typically takes 5–30 seconds depending on CPU speed and whether models need downloading.

Step 5: Search by meaning

Now search for code by what it does, not what it is called:

let results = vfs.semantic_search("error handling and recovery logic", SemanticSearchOptions {
    top_k: Some(5),
    min_score: None,          // no minimum score threshold
    file_filter: vec![],      // search all indexed files
    rerank: Some(true),       // enable cross-encoder reranking (default)
}).await?;

for result in &results {
    println!("--- {} (lines {}-{}, score: {:.3}) ---",
        result.file,
        result.line_start,
        result.line_end,
        result.score,
    );
    if let Some(ref sym) = result.symbol {
        println!("Symbol: {sym}");
    }
    if let Some(ref lang) = result.language {
        println!("Language: {lang}");
    }
    // Print the first 200 characters of content
    let preview: String = result.content.chars().take(200).collect();
    println!("{preview}");
    println!();
}

Understanding results

Each SemanticSearchResult contains:

Step 6: Filter results

Use file_filter globs to restrict search to specific paths:

// Only search Rust files in the auth module:
let auth_results = vfs.semantic_search("credential validation", SemanticSearchOptions {
    top_k: Some(3),
    min_score: Some(0.5),
    file_filter: vec!["src/auth/**/*.rs".into()],
    rerank: Some(true),
}).await?;

Use min_score to exclude low-confidence results. The appropriate threshold depends on your use case — start with None and observe the score distribution, then set a threshold that filters noise.

Step 7: Incremental updates

After the initial index, the file watcher keeps it up to date automatically. When you save a file, the watcher detects the change, re-chunks the file, re-embeds it, and updates the vector store. No manual re-indexing needed.

To force a full re-index (e.g. after a large merge):

let handle = vfs.index("src", IndexOptions {
    force: true,  // ignore cache, re-index everything
    ..Default::default()
}).await?;

Direct API: complete example

use synwire_agent::vfs::local::LocalProvider;
use synwire_core::vfs::protocol::Vfs;
use synwire_core::vfs::types::{IndexOptions, IndexStatus, SemanticSearchOptions};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Create VFS with local filesystem access
    let vfs = LocalProvider::new(PathBuf::from("."))?;

    // 2. Start indexing
    let handle = vfs.index("src", IndexOptions::default()).await?;

    // 3. Wait for completion
    loop {
        match vfs.index_status(&handle.index_id).await? {
            IndexStatus::Ready(_) => break,
            IndexStatus::Failed(e) => return Err(e.into()),
            _ => tokio::time::sleep(std::time::Duration::from_millis(500)).await,
        }
    }

    // 4. Search by meaning
    let results = vfs.semantic_search(
        "database connection pooling",
        SemanticSearchOptions::default(),
    ).await?;

    for r in &results {
        println!("{} (lines {}-{}): {:.3}", r.file, r.line_start, r.line_end, r.score);
    }

    Ok(())
}

Built-in agent tools: semantic search as a tool call

The VFS tools module automatically generates index, index_status, and semantic_search tools when the provider has the INDEX and SEMANTIC_SEARCH capabilities. You don't write tool wrappers — they're built in.

How it works

vfs_tools() inspects the provider's capabilities and emits only the tools the provider supports:

use std::sync::Arc;
use synwire_agent::vfs::local::LocalProvider;
use synwire_core::vfs::{vfs_tools, OutputFormat};
use std::path::PathBuf;

let vfs = Arc::new(LocalProvider::new(PathBuf::from("."))?);

// This returns tools for ls, read, write, grep, glob, find,
// AND index, index_status, semantic_search (because LocalProvider
// with semantic-search feature has those capabilities).
let tools = vfs_tools(Arc::clone(&vfs) as Arc<_>, OutputFormat::Plain);

for tool in &tools {
    println!("  {}: {}", tool.name(), tool.description());
}

Giving the agent semantic search

Pass the VFS tools to an agent — the LLM sees semantic_search as a callable tool alongside read_file, grep, etc.:

use std::sync::Arc;
use synwire_agent::vfs::local::LocalProvider;
use synwire_core::agents::agent_node::Agent;
use synwire_core::agents::runner::{Runner, RunnerConfig};
use synwire_core::agents::streaming::AgentEvent;
use synwire_core::vfs::{vfs_tools, OutputFormat};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let vfs = Arc::new(
        LocalProvider::new(PathBuf::from("."))?
    );

    // Built-in tools include semantic_search, index, index_status,
    // plus all file operations (read, write, ls, grep, glob, etc.)
    let tools = vfs_tools(Arc::clone(&vfs) as Arc<_>, OutputFormat::Plain);

    let agent = Agent::new("code-assistant", "claude-opus-4-6")
        .system_prompt(
            "You are a code assistant with access to the local filesystem.\n\
             You have both grep (exact text search) and semantic_search \
             (meaning-based search).\n\n\
             IMPORTANT: Before using semantic_search, you must call the \
             `index` tool to build the index, then poll `index_status` \
             until it reports Ready.\n\n\
             Use grep for known patterns (function names, error strings).\n\
             Use semantic_search for conceptual queries ('how are errors \
             handled?', 'authentication flow')."
        )
        .tools(tools)  // all VFS tools including semantic_search
        .max_turns(30);

    let runner = Runner::new(agent);
    let mut stream = runner
        .run(
            serde_json::json!("Find all the error handling patterns in this project"),
            RunnerConfig::default(),
        )
        .await?;

    while let Some(event) = stream.recv().await {
        match event {
            AgentEvent::TextDelta { content } => print!("{content}"),
            AgentEvent::ToolCallStart { name, .. } => {
                eprintln!("\n[calling {name}]");
            }
            _ => {}
        }
    }

    Ok(())
}

The agent autonomously decides the workflow:

1. Calls index("src", {}) to start indexing
2. Polls index_status until Ready
3. Calls semantic_search("error handling patterns", { top_k: 10 })
4. Reads the results, possibly calls read_file on interesting hits for full context
5. Synthesises an answer

You write zero tool wrappers — vfs_tools handles everything.

Combining grep and semantic search

The built-in tools let the agent choose the right search for each sub-query:

let agent = Agent::new("researcher", "claude-opus-4-6")
    .system_prompt(
        "You have two search tools:\n\
         - `grep`: fast exact text/regex search — use for known identifiers\n\
         - `semantic_search`: meaning-based search — use for conceptual queries\n\n\
         Strategy: start with semantic_search for broad understanding, then \
         use grep to find exact call sites of specific symbols you discover."
    )
    .tools(vfs_tools(vfs, OutputFormat::Plain))
    .max_turns(30);

The agent might:

1. semantic_search("authentication and authorization") → finds fn verify_token in auth.rs
2. grep("verify_token") → finds all 14 call sites across the codebase
3. read_file("src/middleware/auth_middleware.rs") → reads the main consumer

This grep-then-semantic or semantic-then-grep pattern is natural for LLMs and requires no special orchestration.

StateGraph node: semantic search in a pipeline

For structured multi-step workflows, embed semantic search as a node in a StateGraph. This is useful when search results feed into a downstream processing step — summarisation, code generation, or report writing.

Example: Research pipeline with semantic search

This graph indexes the codebase, searches for relevant code, and produces a summary:

use std::sync::Arc;
use serde::{Deserialize, Serialize};
use synwire_derive::State;
use synwire_orchestrator::constants::END;
use synwire_orchestrator::error::GraphError;
use synwire_orchestrator::graph::StateGraph;

use synwire_agent::vfs::local::LocalProvider;
use synwire_core::vfs::protocol::Vfs;
use synwire_core::vfs::types::{IndexOptions, IndexStatus, SemanticSearchOptions};

/// Pipeline state flowing through three nodes.
#[derive(State, Debug, Clone, Default, Serialize, Deserialize)]
struct ResearchState {
    /// The conceptual query to research.
    #[reducer(last_value)]
    query: String,

    /// Project root path.
    #[reducer(last_value)]
    project_root: String,

    /// Raw search results (file:lines → content).
    #[reducer(topic)]
    search_hits: Vec<String>,

    /// Final summary produced by the summarise node.
    #[reducer(last_value)]
    summary: String,
}

Node 1: Index and search

This node handles both indexing and searching — it's a pure Rust function, no agent needed:

/// Index the codebase and run a semantic search.
async fn search_node(mut state: ResearchState) -> Result<ResearchState, GraphError> {
    let vfs = LocalProvider::new(state.project_root.clone().into())
        .map_err(|e| GraphError::NodeError { message: e.to_string() })?;

    // Start indexing.
    let handle = vfs.index("src", IndexOptions::default()).await
        .map_err(|e| GraphError::NodeError { message: e.to_string() })?;

    // Wait for completion.
    loop {
        match vfs.index_status(&handle.index_id).await
            .map_err(|e| GraphError::NodeError { message: e.to_string() })?
        {
            IndexStatus::Ready(_) => break,
            IndexStatus::Failed(e) => {
                return Err(GraphError::NodeError { message: e.to_string() });
            }
            _ => tokio::time::sleep(std::time::Duration::from_millis(500)).await,
        }
    }

    // Search by meaning.
    let results = vfs.semantic_search(&state.query, SemanticSearchOptions {
        top_k: Some(10),
        rerank: Some(true),
        ..Default::default()
    }).await
        .map_err(|e| GraphError::NodeError { message: e.to_string() })?;

    // Record hits as "file:start-end → content" strings.
    for r in &results {
        let hit = format!(
            "{}:{}-{} [score={:.3}{}]\n{}",
            r.file,
            r.line_start,
            r.line_end,
            r.score,
            r.symbol.as_deref().map_or(String::new(), |s| format!(", symbol={s}")),
            r.content,
        );
        state.search_hits.push(hit);
    }

    Ok(state)
}

Node 2: Summarise

An LLM agent reads the search hits and produces a structured summary:

use synwire_core::agents::agent_node::Agent;
use synwire_core::agents::runner::{Runner, RunnerConfig};
use synwire_core::agents::streaming::AgentEvent;

/// Summarise the search results into a concise report.
async fn summarise_node(mut state: ResearchState) -> Result<ResearchState, GraphError> {
    let system = "You receive semantic search results from a codebase and produce \
                  a concise technical summary. Group findings by theme. Include \
                  file paths and line numbers for every claim.";

    let prompt = format!(
        "Query: {}\n\nSearch results ({} hits):\n\n{}",
        state.query,
        state.search_hits.len(),
        state.search_hits.join("\n---\n"),
    );

    let agent = Agent::new("summariser", "claude-opus-4-6")
        .system_prompt(system)
        .max_turns(1);

    let runner = Runner::new(agent);
    let mut stream = runner
        .run(serde_json::json!(prompt), RunnerConfig::default())
        .await
        .map_err(|e| GraphError::NodeError { message: e.to_string() })?;

    let mut summary = String::new();
    while let Some(event) = stream.recv().await {
        match event {
            AgentEvent::TextDelta { content } => summary.push_str(&content),
            AgentEvent::Error { message } => {
                return Err(GraphError::NodeError { message });
            }
            _ => {}
        }
    }

    state.summary = summary;
    Ok(state)
}

Assembling the graph

let mut graph = StateGraph::<ResearchState>::new();

graph.add_node("search",    Box::new(|s| Box::pin(search_node(s))))?;
graph.add_node("summarise", Box::new(|s| Box::pin(summarise_node(s))))?;

graph
    .set_entry_point("search")
    .add_edge("search", "summarise")
    .add_edge("summarise", END);

let pipeline = graph.compile()?;

// Run the pipeline.
let result = pipeline.invoke(ResearchState {
    query: "How does error propagation work across module boundaries?".into(),
    project_root: "/path/to/project".into(),
    ..Default::default()
}).await?;

println!("{}", result.summary);

When to use each approach

The built-in tool approach is the most common — it gives the agent maximum autonomy while requiring zero wrapper code. The graph approach is best when search must happen at a specific point in a deterministic workflow.

Wrapping the pipeline as an agent tool

Following the pattern from Tutorial 8, you can wrap the entire search → summarise graph as a StructuredTool and give it to an agent:

use std::sync::Arc;
use synwire_core::tools::{StructuredTool, ToolOutput, ToolSchema};

fn semantic_research_tool(project_root: String) -> Result<StructuredTool, synwire_core::error::SynwireError> {
    let graph = Arc::new(build_research_graph()?);
    let root = project_root.clone();

    StructuredTool::builder()
        .name("semantic_research")
        .description(
            "Searches the codebase by meaning and returns a summarised report. \
             Use for broad conceptual queries about how the codebase works."
        )
        .schema(ToolSchema {
            name: "semantic_research".into(),
            description: "Semantic codebase research".into(),
            parameters: serde_json::json!({
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Conceptual query about the codebase"
                    }
                },
                "required": ["query"]
            }),
        })
        .func(move |input| {
            let graph = Arc::clone(&graph);
            let project_root = root.clone();
            Box::pin(async move {
                let query = input["query"].as_str().unwrap_or("overview").to_owned();
                let result = graph.invoke(ResearchState {
                    query,
                    project_root,
                    ..Default::default()
                }).await.map_err(|e| synwire_core::error::SynwireError::Tool(
                    synwire_core::error::ToolError::InvocationFailed {
                        message: format!("research pipeline failed: {e}"),
                    },
                ))?;
                Ok(ToolOutput {
                    content: result.summary,
                    ..Default::default()
                })
            })
        })
        .build()
}

Now the agent has three levels of search capability:

The agent picks the right tool for the job — grep for precision, semantic_search for discovery, semantic_research for understanding.

What you learned

• The semantic-search feature flag enables local semantic search on LocalProvider
• index() starts background indexing and returns an IndexHandle immediately
• index_status() polls progress until the index is ready
• semantic_search() finds code by meaning, with optional filtering and reranking
• vfs_tools() automatically generates agent tools for all VFS capabilities — including index, index_status, and semantic_search
• StateGraph nodes can run the index/search pipeline as a deterministic stage
• The graph can be wrapped as a StructuredTool for agent-driven research

See also

• Semantic Search Architecture — the four-stage pipeline in depth
• Semantic Search How-To — task-focused recipes
• synwire-chunker — AST-aware code chunking
• synwire-embeddings-local — local ONNX embedding models
• synwire-vectorstore-lancedb — LanceDB vector storage
• synwire-index — indexing pipeline lifecycle
• Tutorial 8: Deep Research + Coding Agent — graph-as-tool composition pattern
• Tutorial 7: Building a Coding Agent — combine semantic search with tool use

Background: RAG techniques — semantic search is the retrieval step. The summarise node or the agent's reasoning is the generation step. The two-stage retrieve-then-rerank pipeline improves relevance without sacrificing speed.

Sandboxed Command Execution

Time: ~30 minutes Prerequisites: Rust 1.85+, Cargo, runc on $PATH

This tutorial builds an agent whose LLM can run shell commands inside an isolated sandbox through tool calls. Three scenarios show progressively complex interactions:

1. Oneshot command — LLM runs a compiler, gets exit code + diagnostics
2. Long-lived command with polling — LLM starts a test suite in background, polls for completion, reads partial output
3. CLI that prompts for confirmation (HITL) — LLM runs a tool that asks for human input, recognises the prompt, and hands the terminal to the user

Note: File listing, reading, and writing are handled by VFS tools (vfs_list, vfs_read, vfs_write). Use run_command for things VFS can't do: compiling, running tests, invoking CLI tools, package management.

What you are building

An agent with thirteen sandbox tools (backed by expectrl for cross-platform PTY support), automatically wired via .with_sandbox(config):

Setup

cargo new synwire-sandbox-demo
cd synwire-sandbox-demo

[dependencies]
synwire = { path = "../../crates/synwire", features = ["sandbox"] }
synwire-core = { path = "../../crates/synwire-core" }
tokio = { version = "1", features = ["full"] }

Build the agent

use synwire::agent::prelude::*;
use synwire::sandbox::SandboxedAgent;
use synwire_core::agents::sandbox::{
    FilesystemConfig, IsolationLevel, NetworkConfig, ProcessTracking,
    ResourceLimits, SandboxConfig, SecurityPreset, SecurityProfile,
};

let config = SandboxConfig {
    enabled: true,
    isolation: IsolationLevel::Namespace,
    filesystem: Some(FilesystemConfig {
        allow_write: vec![".".into()],
        deny_write: vec![],
        deny_read: vec![],
        inherit_readable: true,
    }),
    network: Some(NetworkConfig {
        enabled: false,
        ..Default::default()
    }),
    security: SecurityProfile {
        standard: SecurityPreset::Baseline,
        ..Default::default()
    },
    resources: Some(ResourceLimits {
        memory_bytes: Some(512 * 1024 * 1024),
        cpu_quota: Some(1.0),
        max_pids: Some(64),
        exec_timeout_secs: Some(30),
    }),
    process_tracking: ProcessTracking {
        enabled: true,
        max_tracked: Some(64),
    },
    ..Default::default()
};

// with_sandbox() does all the wiring:
// - Finds runc on $PATH
// - Creates ProcessRegistry + ProcessVisibilityScope
// - Registers ProcessPlugin with all 9 tools
// - Sets the sandbox config on the agent
let (agent, handle) = Agent::<()>::new("sandbox-agent", "gpt-4")
    .description("Agent with sandboxed command execution")
    .max_turns(20)
    .with_sandbox(config);

// handle.registry and handle.scope are available for sub-agent wiring

That's it for setup. The LLM now has all nine tools available. The rest of this tutorial shows what the LLM's tool calls look like in each scenario.

Scenario 1: Oneshot command — compile and check

The LLM has edited a Rust file via VFS tools and wants to check if it compiles. It runs cargo check as a oneshot command:

{
  "tool": "run_command",
  "input": {
    "command": "cargo",
    "args": ["check", "--message-format=json"],
    "wait": true,
    "timeout_secs": 60
  }
}

The tool spawns the command inside a namespace container, waits for it to exit, and returns:

{
  "pid": 42,
  "exit_code": 1,
  "timed_out": false,
  "stdout": "{\"reason\":\"compiler-message\",\"message\":{\"rendered\":\"error[E0308]: mismatched types\\n  --> src/main.rs:14:5\\n   |\\n14 |     42u32\\n   |     ^^^^^ expected `String`, found `u32`\\n\"}}",
  "stderr": "error: could not compile `myproject` (bin \"myproject\") due to 1 previous error"
}

The LLM parses the compiler JSON, identifies the type mismatch at src/main.rs:14, uses VFS tools to fix the code, then runs cargo check again. One tool call per compilation attempt — the simplest path.

How it works internally

1. run_command translates SandboxConfig to an OCI runtime spec
2. Calls runc run --bundle <tmpdir> <id> with stdout/stderr redirected to files (so output survives even if the process is killed)
3. Waits up to timeout_secs for the process to exit
4. Reads the captured output files
5. Returns everything in one JSON response

If timeout_secs is exceeded, the process is killed and timed_out: true is returned.

Scenario 2: Long-lived command with polling — test suite

The LLM starts the full test suite which takes a while. It uses wait: false to get a PID back immediately and monitors progress:

Turn 1 — start the tests:

{
  "tool": "run_command",
  "input": {
    "command": "cargo",
    "args": ["nextest", "run", "--no-fail-fast"],
    "wait": false
  }
}

Response:

{
  "pid": 87,
  "status": "running",
  "hint": "Use wait_for_process to block until exit, or read_process_output to read partial output."
}

Turn 2 — check if it's done yet:

{
  "tool": "wait_for_process",
  "input": {
    "pid": 87,
    "timeout_ms": 10000
  }
}

Response (still running after 10s):

{
  "pid": 87,
  "status": "timeout",
  "message": "process still running after 10000ms"
}

Turn 3 — read partial output to see progress:

{
  "tool": "read_process_output",
  "input": {
    "pid": 87,
    "stream": "stderr"
  }
}

Response:

    Starting 47 tests across 8 binaries
        PASS [   0.234s] synwire-core::tools::test_tool_schema_validation
        PASS [   0.567s] synwire-core::tools::test_structured_tool_invoke
        PASS [   1.123s] synwire-orchestrator::test_graph_compilation
     RUNNING synwire-sandbox::test_namespace_spawn_echo

The LLM sees tests are progressing and decides to wait longer.

Turn 4 — wait for completion:

{
  "tool": "wait_for_process",
  "input": {
    "pid": 87,
    "timeout_ms": 120000
  }
}

Response:

{
  "pid": 87,
  "status": "exited",
  "exit_code": 0
}

Turn 5 — read final output:

{
  "tool": "read_process_output",
  "input": {
    "pid": 87,
    "stream": "stderr"
  }
}

    Starting 47 tests across 8 binaries
        ...
     Summary [  12.456s] 47 tests run: 47 passed, 0 failed, 0 skipped

Key points

• wait: false returns immediately — the process runs in background
• monitor_child updates the registry when the process exits
• read_process_output reads from files on disk, so output is available even while the process is still running (buffered by the OS)
• The LLM controls the polling loop through its FSM turns — it can do other work between polls
• Output files are in a TempDir — automatically cleaned up when the last Arc<CapturedOutput> is dropped (Go defer semantics)

Scenario 3: CLI prompts for confirmation (HITL)

The LLM needs to run terraform apply which prompts the user to type yes before making changes. The LLM can't (and shouldn't) type the confirmation itself — it uses shell_expect to detect the prompt, then hands off to the user.

Turn 1 — open a shell and run terraform:

{
  "tool": "open_shell",
  "input": {
    "shell": "/bin/sh"
  }
}

Response:

{
  "session_id": "a1b2c3d4-...",
  "shell": "/bin/sh",
  "hint": "Use shell_write to send commands and shell_read to see output."
}

Turn 2 — start the terraform apply:

{
  "tool": "shell_write",
  "input": {
    "session_id": "a1b2c3d4-...",
    "input": "terraform apply -no-color\n"
  }
}

Turn 3 — wait for the confirmation prompt using shell_expect:

{
  "tool": "shell_expect",
  "input": {
    "session_id": "a1b2c3d4-...",
    "pattern": "Enter a value:",
    "timeout_secs": 120
  }
}

shell_expect reads from the PTY in a loop until "Enter a value:" appears in the accumulated output, then returns everything captured up to the match:

{
  "matched": true,
  "pattern": "Enter a value:",
  "output": "$ terraform apply -no-color\n\nTerraform will perform the following actions:\n\n  # aws_instance.web will be created\n  + resource \"aws_instance\" \"web\" {\n      + ami           = \"ami-0c55b159cbfafe1f0\"\n      + instance_type = \"t2.micro\"\n      + tags          = {\n          + \"Name\" = \"production-web\"\n        }\n    }\n\nPlan: 1 to add, 0 to change, 0 to destroy.\n\nDo you want to perform these actions?\n  Terraform will perform the actions described above.\n  Only 'yes' will be accepted to approve.\n\n  Enter a value: "
}

The LLM gets matched: true and the full plan output in a single tool call — no polling loop needed.

Turn 4 — the LLM recognises this is a confirmation prompt and hands off to the user:

The LLM responds to the user (not a tool call):

Terraform wants to create an aws_instance.web (t2.micro in production). The plan is:

• +1 resource: aws_instance.web
• No changes or deletions

The terminal is waiting for you to type yes to approve or anything else to cancel. Please type your response in the shell session.

The user types yes directly in the PTY (the controller fd is connected to their terminal via the SandboxHandle).

Turn 5 — wait for terraform to finish applying:

{
  "tool": "shell_expect",
  "input": {
    "session_id": "a1b2c3d4-...",
    "pattern": "Apply complete!",
    "timeout_secs": 300
  }
}

Response:

{
  "matched": true,
  "pattern": "Apply complete!",
  "output": "  Enter a value: yes\n\naws_instance.web: Creating...\naws_instance.web: Still creating... [10s elapsed]\naws_instance.web: Creation complete after 23s [id=i-0a1b2c3d4e5f67890]\n\nApply complete! Resources: 1 added, 0 changed, 0 destroyed.\n"
}

The LLM confirms the apply succeeded. Two shell_expect calls replaced what would have been a manual polling loop of shell_read calls.

Why this matters

The LLM never types yes itself — it reads the prompt, explains it to the user, and waits for the user to confirm. This pattern applies to any CLI that requires human confirmation:

• terraform apply / terraform destroy
• kubectl delete with --confirm
• apt upgrade / dnf update
• SSH host key verification
• GPG key trust decisions
• Database migration tools (diesel migration run --confirm)
• Any interactive installer

How PTY handoff works

LLM agent                     synwire                     runc
    │                            │                           │
    │── open_shell() ──────────▶│                           │
    │                            │── bind(console.sock) ───▶│
    │                            │── spawn("runc run        │
    │                            │    --console-socket ...")─▶│
    │                            │                           │── create PTY
    │                            │                           │── setsid + TIOCSCTTY
    │                            │◀── SCM_RIGHTS(pty_fd) ───│
    │◀── {session_id} ──────────│                           │
    │                            │                           │
    │── shell_write(cmd) ──────▶│── write(pty_fd) ────────▶│── container stdin
    │── shell_expect(           │                           │
    │     "Enter a value:")────▶│── read loop ◀────────────│── container stdout
    │                            │   (polls every 100ms)    │
    │◀── {matched: true,        │                           │
    │     output: "Plan: 1...   │                           │
    │     Enter a value:"}──────│                           │
    │                            │                           │
    │ "Please type yes to       │                           │
    │  confirm in the terminal" │                           │
    │                            │                           │
    │                       USER │── write(pty_fd) ────────▶│── "yes\n"
    │                            │                           │── applies changes
    │── shell_expect(           │                           │
    │     "Apply complete!") ──▶│── read loop ◀────────────│── "Apply complete!"
    │◀── {matched: true} ──────│                           │

When to use each mode

Scenario 4: Switch/case with shell_expect_cases

The LLM runs ssh user@host and doesn't know whether it will get a password prompt, a host key verification prompt, or a shell prompt (already authenticated). shell_expect_cases handles all three:

{
  "tool": "shell_expect_cases",
  "input": {
    "session_id": "a1b2c3d4-...",
    "cases": [
      {
        "pattern": "password:",
        "tag": "needs_user",
        "label": "Password prompt — hand off to user"
      },
      {
        "pattern": "Are you sure you want to continue connecting",
        "tag": "needs_user",
        "label": "Host key verification — hand off to user"
      },
      {
        "pattern": "\\$\\s*$",
        "tag": "ok",
        "label": "Shell prompt — already authenticated"
      }
    ],
    "timeout_secs": 30
  }
}

Response (password prompt was first):

{
  "matched": true,
  "matched_case": 0,
  "tag": "needs_user",
  "label": "Password prompt — hand off to user",
  "output": "user@host's password: ",
  "captures": ["password:"]
}

The LLM sees tag: "needs_user" and tells the user to type their password. If the tag had been "ok", the LLM would continue autonomously.

Auto-response with capture groups

Cases can include a respond field for auto-responses. Use $1, $2 to substitute captured regex groups:

{
  "cases": [
    {
      "pattern": "version (\\d+\\.\\d+)",
      "tag": "ok",
      "respond": "Detected version $1\n",
      "label": "Version detected"
    }
  ]
}

Scenario 5: Scripted interaction with shell_batch

The LLM needs to run a multi-step CLI interaction in one tool call — no round-trips. shell_batch runs send/expect steps sequentially:

{
  "tool": "shell_batch",
  "input": {
    "session_id": "a1b2c3d4-...",
    "steps": [
      { "type": "send", "input": "git status --porcelain\n" },
      { "type": "expect", "pattern": "\\$\\s*$", "timeout_secs": 5 },
      { "type": "send", "input": "cargo test --no-fail-fast 2>&1 | tail -5\n" },
      { "type": "expect", "pattern": "test result:", "timeout_secs": 120 }
    ],
    "timeout_secs": 30
  }
}

Response:

{
  "steps": [
    { "index": 0, "step_type": "send", "success": true },
    {
      "index": 1, "step_type": "expect", "success": true,
      "output": "$ git status --porcelain\n M src/lib.rs\n?? src/new_file.rs\n$ ",
      "captures": ["$ "]
    },
    { "index": 2, "step_type": "send", "success": true },
    {
      "index": 3, "step_type": "expect", "success": true,
      "output": "$ cargo test ...\ntest result: ok. 47 passed; 0 failed; 0 ignored",
      "captures": ["test result:"]
    }
  ],
  "completed": 4,
  "total": 4
}

The LLM gets both the working tree status and test results in a single tool call. If any step fails (timeout or expect error), execution stops and the partial results are returned.

Batch with switch/case

Batches support expect_cases steps for branching:

{
  "steps": [
    { "type": "send", "input": "npm publish\n" },
    {
      "type": "expect_cases",
      "cases": [
        { "pattern": "Enter OTP:", "tag": "needs_user", "label": "2FA required" },
        { "pattern": "npm ERR!", "tag": "fail", "label": "Publish failed" },
        { "pattern": "\\+ my-package@", "tag": "ok", "label": "Published successfully" }
      ],
      "timeout_secs": 60
    }
  ]
}

Parent-child visibility

When a parent agent spawns sub-agents, each gets its own ProcessRegistry. The parent can see all sub-agent processes; sub-agents can only see their own:

let (parent_agent, parent_handle) = Agent::<()>::new("parent", "gpt-4")
    .with_sandbox(config.clone());

let child_registry = Arc::new(RwLock::new(ProcessRegistry::new(Some(16))));
parent_handle.scope
    .add_child_registry("research-agent", Arc::clone(&child_registry))
    .await;

Next steps

• Sandbox setup: Process Sandboxing — cgroup delegation, gVisor, WSL2, macOS Seatbelt
• Approval gates: Approval Gates — require human approval before executing commands
• Permission modes: Permission Modes — control which tools need approval
• VFS operations: File and Shell Operations — the virtual filesystem layer above the sandbox

Getting Started with the MCP Server

This tutorial is a placeholder. Content will be added when synwire-mcp-server reaches its first stable release.

What you will build: A working synwire-mcp-server configuration for Claude Code that indexes a Rust project and enables semantic search, code graph queries, and LSP integration.

Prerequisites:

• Rust toolchain (stable)
• Claude Code installed
• A Rust project to index

See the synwire-mcp-server explanation for current installation and configuration instructions.

Authoring Your First Agent Skill

This tutorial is a placeholder. Content will be added in a future release.

What you will build: A complete agent skill following the agentskills.io specification that the MCP server discovers and makes available as a tool.

Prerequisites:

• synwire-mcp-server installed and running
• Basic understanding of YAML

See the synwire-agent-skills explanation for the SKILL.md format, available runtimes, and discovery paths.

Setting Up Semantic Search

This tutorial is a placeholder. Content will be added in a future release.

What you will build: A fully indexed project with semantic search, hybrid BM25+vector search, and code graph queries working end-to-end.

Prerequisites:

• synwire-mcp-server installed
• A project of at least 1 000 lines of code to make search interesting

See these existing resources:

• How-To: Semantic Search — task-focused recipes
• Semantic Search Architecture — design rationale
• Tutorial 09: Semantic Search — existing walkthrough using the Rust API directly

Fault Localization with SBFL

Time: ~45 minutes Prerequisites: Rust 1.85+, completion of Your First Agent, familiarity with test coverage concepts

Background: Spectrum-Based Fault Localization -- a family of techniques that rank code locations by how strongly they correlate with test failures.

This tutorial shows how to use Synwire's SbflRanker to identify suspicious files from test coverage data, then fuse those rankings with semantic search results to produce a combined fault-likelihood score.

What SBFL does

When a test suite has failures, some source lines are covered by failing tests but not by passing tests. SBFL assigns a suspiciousness score to each line using a statistical formula. Synwire uses the Ochiai coefficient:

score = ef / sqrt((ef + nf) * (ef + ep))

Where:

• ef = number of failing tests that cover this line
• nf = number of passing tests that cover this line
• ep = number of passing tests that do not cover this line

A score of 1.0 means the line is covered exclusively by failing tests. A score of 0.0 means no failing test touches it.

Step 1: Add dependencies

[dependencies]
synwire-agent = { version = "0.1" }
tokio = { version = "1", features = ["full"] }
serde_json = "1"

Step 2: Build coverage records

CoverageRecord holds per-line coverage data. In practice you would parse output from cargo-llvm-cov, gcov, or a DAP coverage session. Here we construct records directly:

use synwire_agent::sbfl::{CoverageRecord, SbflRanker};

fn example_coverage() -> Vec<CoverageRecord> {
    vec![
        // Line 42 of buggy.rs: hit by 8 failing tests, 2 passing, 0 passing miss it
        CoverageRecord { file: "src/buggy.rs".into(), line: 42, ef: 8, nf: 2, np: 0 },
        CoverageRecord { file: "src/buggy.rs".into(), line: 43, ef: 6, nf: 4, np: 0 },
        // clean.rs: never hit by failing tests
        CoverageRecord { file: "src/clean.rs".into(), line: 10, ef: 0, nf: 5, np: 5 },
        CoverageRecord { file: "src/clean.rs".into(), line: 11, ef: 0, nf: 3, np: 7 },
        // utils.rs: sometimes hit by failing tests but also by many passing tests
        CoverageRecord { file: "src/utils.rs".into(), line: 20, ef: 3, nf: 7, np: 0 },
    ]
}

Step 3: Rank files by suspiciousness

SbflRanker computes the Ochiai score for every line, then ranks files by their maximum score:

fn main() {
    let records = example_coverage();
    let ranker = SbflRanker::new(records);
    let ranked = ranker.rank_files();

    println!("Files ranked by fault likelihood:");
    for (file, score) in &ranked {
        println!("  {file}: {score:.3}");
    }
    // Output:
    //   src/buggy.rs: 0.894
    //   src/utils.rs: 0.548
    //   src/clean.rs: 0.000
}

src/buggy.rs scores highest because line 42 is covered almost exclusively by failing tests.

Step 4: Fuse with semantic search

SBFL tells you where failures concentrate. Semantic search tells you what code is relevant to a bug description. Fusing both signals produces better results than either alone.

use synwire_agent::sbfl::fuse_sbfl_semantic;

let sbfl_scores = ranker.rank_files();

// Semantic search results (from Tutorial 09) -- score = relevance to bug description
let semantic_scores = vec![
    ("src/utils.rs".into(), 0.85_f32),
    ("src/buggy.rs".into(), 0.60),
    ("src/handler.rs".into(), 0.45),
];

// Fuse with 70% weight on SBFL, 30% on semantic similarity
let fused = fuse_sbfl_semantic(&sbfl_scores, &semantic_scores, 0.7);

println!("\nFused ranking (SBFL 70% + semantic 30%):");
for (file, score) in &fused {
    println!("  {file}: {score:.3}");
}

Adjusting sbfl_weight lets you shift emphasis. Use higher SBFL weight (0.7--0.8) when coverage data is reliable. Use lower weight (0.3--0.5) when coverage is sparse but the bug description is precise.

Step 5: Use as an MCP tool

The code.fault_localize MCP tool wraps this pipeline. When running synwire-mcp-server, an agent can call it directly:

{
  "tool": "code.fault_localize",
  "arguments": {
    "coverage": [
      {"file": "src/buggy.rs", "line": 42, "ef": 8, "nf": 2, "np": 0},
      {"file": "src/clean.rs", "line": 10, "ef": 0, "nf": 5, "np": 5}
    ],
    "semantic_results": [
      {"file": "src/buggy.rs", "score": 0.6},
      {"file": "src/utils.rs", "score": 0.85}
    ],
    "sbfl_weight": 0.7
  }
}

The tool returns files ranked by combined score. The agent can then read the top-ranked files and investigate further.

Step 6: Wire it into an agent

Give the agent both code.fault_localize and VFS tools so it can autonomously collect coverage, rank files, and read the suspicious code:

use synwire_core::agents::agent_node::Agent;
use synwire_core::agents::runner::{Runner, RunnerConfig};

let agent = Agent::new("debugger", "claude-opus-4-6")
    .system_prompt(
        "You are a debugging assistant. When given a failing test:\n\
         1. Run the test suite to collect coverage data\n\
         2. Call code.fault_localize with the coverage records\n\
         3. Read the top-ranked files\n\
         4. Identify the root cause and suggest a fix"
    )
    .tools(tools)  // VFS tools + code.fault_localize
    .max_turns(20);

let runner = Runner::new(agent);
let mut rx = runner
    .run(serde_json::json!("test_auth_token is failing -- find the bug"), RunnerConfig::default())
    .await?;

What you learned

• The Ochiai coefficient ranks code lines by how strongly they correlate with test failures
• SbflRanker aggregates line-level scores to file-level rankings
• fuse_sbfl_semantic combines SBFL with semantic search for better fault localization
• The code.fault_localize MCP tool exposes this pipeline to agents

See also

• Tutorial 9: Semantic Search -- generating the semantic scores to fuse with SBFL
• Tutorial 15: Dataflow Analysis -- tracing how a variable reaches the faulty line
• Tutorial 18: Building a Debugging Agent -- end-to-end debugging workflow
• How-To: DAP Integration -- collecting coverage via the debug adapter

Dataflow Analysis

Time: ~30 minutes Prerequisites: Rust 1.85+, completion of Your First Agent

Background: Dataflow analysis traces how values propagate through code -- where a variable is defined, where it is reassigned, and which expressions contribute to its current value. This is essential for understanding why a variable holds an unexpected value.

This tutorial shows how to use the DataflowTracer to trace variable origins in source code, and how to integrate it into an agent workflow for automated debugging.

What the tracer does

DataflowTracer performs heuristic backward slicing: given a variable name and source text, it finds assignment sites (x = ...) and definition sites (let x = ...) by pattern matching. Each result is a DataflowHop containing the file, line, code snippet, and origin kind.

This is a lightweight analysis -- it does not require compilation or a running language server. For precise type-aware tracing, combine it with LSP tools (see How-To: LSP Integration).

Step 1: Add dependencies

[dependencies]
synwire-agent = { version = "0.1" }

Step 2: Trace a variable in Rust source

use synwire_agent::dataflow::DataflowTracer;

fn main() {
    let source = r#"
fn process_request(input: &str) -> Result<Response, Error> {
    let config = load_config()?;
    let timeout = config.timeout_ms;
    let client = HttpClient::new(timeout);
    let response = client.get(input)?;
    let status = response.status();
    status = override_status(status);
    Ok(Response::new(status))
}
"#;

    let tracer = DataflowTracer::new(10);
    let hops = tracer.trace(source, "status", "src/handler.rs");

    for hop in &hops {
        println!(
            "[{}] {}:{} -- {}",
            hop.origin.kind,
            hop.origin.file,
            hop.origin.line,
            hop.origin.snippet,
        );
    }
}

Output:

[definition] src/handler.rs:6 -- let status = response.status();
[assignment] src/handler.rs:7 -- status = override_status(status);

The tracer found two sites: the initial let binding and a subsequent reassignment. An agent investigating an unexpected status value now knows to look at both response.status() and override_status.

Step 3: Control trace depth

The max_hops parameter limits how many origin sites are returned. Use a small value (2--3) for focused traces, or a larger value (10+) for thorough analysis of heavily-reassigned variables:

// Only find the first 2 assignment sites
let tracer = DataflowTracer::new(2);
let hops = tracer.trace(source, "x", "lib.rs");
assert!(hops.len() <= 2);

Step 4: Trace variables in other languages

The tracer works on any language that uses = for assignment and let for bindings. For languages like Python or JavaScript, the assignment patterns still match:

let python_source = r#"
def calculate_total(items):
    total = 0
    for item in items:
        price = item.get_price()
        total = total + price
    total = apply_discount(total)
    return total
"#;

let tracer = DataflowTracer::new(10);
let hops = tracer.trace(python_source, "total", "cart.py");

for hop in &hops {
    println!("{}: line {} -- {}", hop.origin.kind, hop.origin.line, hop.origin.snippet);
}
// definition: line 2 -- total = 0
// assignment: line 5 -- total = total + price
// assignment: line 6 -- total = apply_discount(total)

Step 5: Use as an MCP tool

The code.trace_dataflow MCP tool wraps DataflowTracer. An agent calls it with a file path and variable name:

{
  "tool": "code.trace_dataflow",
  "arguments": {
    "file": "src/handler.rs",
    "variable": "status",
    "max_hops": 10
  }
}

The server reads the file, runs the tracer, and returns the hops as structured text.

Step 6: Integrate into an agent workflow

Combine dataflow tracing with file reading and semantic search to build an automated variable investigator:

use std::sync::Arc;
use synwire_core::agents::agent_node::Agent;
use synwire_core::agents::runner::{Runner, RunnerConfig};
use synwire_core::agents::streaming::AgentEvent;

let agent = Agent::new("tracer", "claude-opus-4-6")
    .system_prompt(
        "You investigate unexpected variable values. Your workflow:\n\
         1. Read the file containing the variable\n\
         2. Call code.trace_dataflow to find all assignment sites\n\
         3. For each assignment, use semantic_search or grep to find the \
            called functions\n\
         4. Explain the full data flow from origin to the point of failure"
    )
    .tools(tools)  // VFS tools + code.trace_dataflow
    .max_turns(15);

let runner = Runner::new(agent);
let mut rx = runner
    .run(
        serde_json::json!("The variable `timeout` in src/client.rs has value 0 -- trace where it comes from"),
        RunnerConfig::default(),
    )
    .await?;

while let Some(event) = rx.recv().await {
    match event {
        AgentEvent::TextDelta { content } => print!("{content}"),
        AgentEvent::ToolCallStart { name, .. } => eprintln!("\n[calling {name}]"),
        _ => {}
    }
}

The agent reads the file, calls code.trace_dataflow to find assignment sites for timeout, then reads each called function to explain the full data flow.

Limitations

• The tracer uses text pattern matching, not a full AST. It may produce false positives for variables whose names appear in comments or strings.
• It does not trace across function boundaries. Use LSP goto_definition to follow values through call chains.
• For languages without let or = assignment syntax, results may be incomplete.

What you learned

• DataflowTracer finds where a variable is defined and modified using heuristic pattern matching
• max_hops controls how many origin sites are returned
• The tracer works across languages that use standard assignment syntax
• The code.trace_dataflow MCP tool makes this available to agents
• Combine with LSP tools for cross-function tracing

See also

• Tutorial 14: Fault Localization -- ranking files by suspiciousness
• Tutorial 16: Code Analysis Tools -- combining dataflow with call graphs
• How-To: LSP Integration -- precise type-aware goto-definition
• Tutorial 18: Building a Debugging Agent -- full debugging workflow

Code Analysis Tools

Time: ~1 hour Prerequisites: Rust 1.85+, completion of Tutorial 9: Semantic Search

Background: Code Intelligence -- understanding code structure through call graphs, data flow, and semantic search enables agents to reason about codebases the way developers do.

This tutorial shows how to combine Synwire's analysis tools -- call graphs, semantic search, and dataflow tracing -- to build an agent that investigates bug reports by understanding code structure.

The DynamicCallGraph API

DynamicCallGraph is an incrementally-built directed graph. Each edge represents a caller-to-callee relationship discovered via LSP goto-definition or static analysis. The graph supports three key queries:

use synwire_agent::call_graph::DynamicCallGraph;

let mut graph = DynamicCallGraph::new();

// Build the graph edge by edge (typically populated by LSP results)
graph.add_edge("main", "parse_config");
graph.add_edge("main", "run_server");
graph.add_edge("run_server", "handle_request");
graph.add_edge("handle_request", "validate_auth");
graph.add_edge("handle_request", "execute_query");
graph.add_edge("execute_query", "db_connect");

// Query 1: What does handle_request call?
let callees = graph.callees("handle_request");
println!("handle_request calls: {:?}", callees);
// ["validate_auth", "execute_query"]

// Query 2: Who calls execute_query?
let callers = graph.callers("execute_query");
println!("execute_query called by: {:?}", callers);
// ["handle_request"]

// Query 3: Are there cycles?
println!("Has cycles: {}", graph.has_cycle());
// false

Step 1: Build a call graph from LSP

In practice, the call graph is populated by following LSP goto-definition results. The MCP server's code.trace_callers tool does this automatically, but you can also build it programmatically:

use synwire_agent::call_graph::{CallNode, DynamicCallGraph};

/// Build a call graph by following goto-definition for each function call.
async fn build_call_graph(
    lsp: &synwire_lsp::client::LspClient,
    entry_file: &str,
) -> DynamicCallGraph {
    let mut graph = DynamicCallGraph::new();

    // Get all symbols in the entry file
    let symbols = lsp.document_symbols(entry_file).await.unwrap_or_default();

    for symbol in &symbols {
        // For each function, find what it calls via references
        let refs = lsp.references(entry_file, symbol.line, symbol.column).await;
        if let Ok(locations) = refs {
            for loc in &locations {
                graph.add_edge(&symbol.name, &loc.symbol_name);
            }
        }
    }

    graph
}

Step 2: Detect dependency cycles

Circular dependencies often indicate architectural problems. The has_cycle method uses depth-first search to detect them:

let mut graph = DynamicCallGraph::new();
graph.add_edge("module_a::init", "module_b::setup");
graph.add_edge("module_b::setup", "module_c::configure");
graph.add_edge("module_c::configure", "module_a::init"); // cycle!

if graph.has_cycle() {
    println!("Circular dependency detected!");
    // An agent could report the cycle and suggest refactoring
}

Step 3: Combine call graph with semantic search

Use semantic search to find relevant code, then expand understanding with the call graph:

use synwire_core::vfs::types::SemanticSearchOptions;

// Step 1: Semantic search finds entry points
let results = vfs.semantic_search(
    "authentication token validation",
    SemanticSearchOptions { top_k: Some(5), ..Default::default() },
).await?;

// Step 2: For each result, query the call graph to find callers and callees
let mut graph = DynamicCallGraph::new();
for result in &results {
    if let Some(ref symbol) = result.symbol {
        // Use LSP or MCP code.trace_callers to populate edges
        let callees = get_callees_from_lsp(symbol).await;
        for callee in &callees {
            graph.add_edge(symbol, callee);
        }
    }
}

// Step 3: Find all callers of the token validator
let callers = graph.callers("validate_token");
println!("validate_token is called by: {:?}", callers);

This pattern -- semantic search for discovery, call graph for structure -- is how agents build a mental model of unfamiliar code.

Step 4: Use analysis tools via MCP

The MCP server exposes three analysis tools that agents can call:

An agent investigating a bug typically uses them in sequence:

// 1. Find relevant code
{"tool": "index.search", "arguments": {"query": "payment processing error"}}

// 2. Understand the call chain
{"tool": "code.trace_callers", "arguments": {"symbol": "process_payment", "direction": "both"}}

// 3. Trace the problematic variable
{"tool": "code.trace_dataflow", "arguments": {"file": "src/payment.rs", "variable": "amount"}}

// 4. Rank files by fault likelihood (if tests are failing)
{"tool": "code.fault_localize", "arguments": {"coverage": [...]}}

Step 5: Build a bug investigation agent

Combine all analysis tools into a single agent that can investigate a bug report end-to-end:

use std::sync::Arc;
use synwire_core::agents::agent_node::Agent;
use synwire_core::agents::runner::{Runner, RunnerConfig};
use synwire_core::agents::streaming::AgentEvent;

let agent = Agent::new("investigator", "claude-opus-4-6")
    .system_prompt(
        "You are a code investigation agent. Given a bug report, follow this process:\n\n\
         1. Use index.search to find code related to the bug description\n\
         2. Use code.trace_callers to understand what calls what\n\
         3. Use code.trace_dataflow on suspicious variables\n\
         4. Use read to examine specific functions in detail\n\
         5. Synthesize your findings into a root cause analysis\n\n\
         Always explain your reasoning at each step."
    )
    .tools(tools)  // VFS + index.search + code.trace_callers + code.trace_dataflow
    .max_turns(30);

let runner = Runner::new(agent);
let mut rx = runner
    .run(
        serde_json::json!(
            "Bug #1234: Users report that discount codes are applied twice \
             when checking out with multiple items. The total shown is lower \
             than expected."
        ),
        RunnerConfig::default(),
    )
    .await?;

while let Some(event) = rx.recv().await {
    match event {
        AgentEvent::TextDelta { content } => print!("{content}"),
        AgentEvent::ToolCallStart { name, .. } => {
            eprintln!("\n[{name}]");
        }
        _ => {}
    }
}

The agent might:

1. Search for "discount code application" via index.search
2. Find apply_discount in src/checkout.rs
3. Query code.trace_callers for callers of apply_discount -- discovers it is called from both process_item and finalize_cart
4. Trace discount_amount via code.trace_dataflow -- finds it is accumulated without resetting
5. Report that the discount is applied per-item and per-cart, causing double application

What you learned

• DynamicCallGraph stores caller/callee relationships and detects cycles
• Call graph queries reveal code structure that text search cannot
• Combining semantic search (find relevant code) with call graphs (understand structure) and dataflow (trace values) gives agents comprehensive code understanding
• The MCP tools code.trace_callers, code.trace_dataflow, and code.fault_localize are available via synwire-mcp-server

See also

• Tutorial 14: Fault Localization -- SBFL ranking
• Tutorial 15: Dataflow Analysis -- tracing variable origins
• Tutorial 9: Semantic Search -- meaning-based code search
• Tutorial 18: Building a Debugging Agent -- full end-to-end debugging agent
• How-To: LSP Integration -- using LSP for precise goto-definition

Advanced MCP Server Setup

Time: ~1 hour Prerequisites: Rust 1.85+, synwire-mcp-server installed, completion of Tutorial 11: Getting Started with the MCP Server

This tutorial covers advanced synwire-mcp-server configuration: enabling LSP and DAP tools, setting up the daemon for multi-project indexing, and using namespace-based tool discovery to reduce token usage.

MCP server architecture

The synwire-mcp-server binary runs as a stdio-based MCP server. It communicates with the host (Claude Code, an IDE, or your own agent) over stdin/stdout using the MCP protocol.

Internally it connects to the synwire-daemon, a singleton background process that owns the embedding model, file watchers, indexing pipelines, and all persistent state. Multiple MCP server instances share a single daemon.

Host (Claude Code)
  |  stdio
  v
synwire-mcp-server  (thin proxy)
  |  Unix domain socket
  v
synwire-daemon  (singleton, owns indices + LSP + DAP)

Step 1: Basic configuration

The minimal configuration indexes a single project:

{
  "mcpServers": {
    "synwire": {
      "command": "synwire-mcp-server",
      "args": ["--project", "."]
    }
  }
}

This registers all VFS tools (fs.read, fs.write, fs.edit, fs.grep, fs.glob, fs.tree, code.skeleton), indexing tools (index.run, index.status, index.search), and meta tools (meta.tool_search, meta.tool_list).

Step 2: LSP tools (auto-detected by default)

When --project is set, the MCP server automatically detects which language servers to use. It scans the project directory for file extensions, matches them against the built-in LanguageServerRegistry (22+ servers), and checks if the binary is on your PATH.

With the basic config from Step 1 and rust-analyzer installed, a Rust project gets LSP tools with zero extra flags:

{
  "mcpServers": {
    "synwire": {
      "command": "synwire-mcp-server",
      "args": ["--project", "."]
    }
  }
}

Auto-detection enables four additional tools:

The MCP server launches the language server as a child process, manages document synchronisation, and translates MCP tool calls into LSP requests.

Overriding auto-detection

Use --lsp to force a specific server (e.g., when multiple servers handle the same language):

# Force pyright instead of auto-detected pylsp
synwire-mcp-server --project . --lsp pyright

Disabling LSP entirely

Use --no-lsp to disable auto-detection and all LSP tools:

synwire-mcp-server --project . --no-lsp

Polyglot repos

Auto-detection supports polyglot repositories. If your project contains both .rs and .ts files and both rust-analyzer and typescript-language-server are installed, both are detected. The server logs which servers were found:

INFO Auto-detected language servers servers=["rust-analyzer", "typescript-language-server"]

Currently the primary server (most common extension) is used for tool dispatch. Future versions will support concurrent multi-server dispatch.

Supported language servers

The built-in LanguageServerRegistry includes definitions for 22+ language servers. Common examples:

# Rust project (auto-detected, or explicit)
synwire-mcp-server --project . --lsp rust-analyzer

# Python project
synwire-mcp-server --project . --lsp pyright

# Go project
synwire-mcp-server --project . --lsp gopls

Step 3: DAP tools (auto-detected by default)

Like LSP, debug adapters are auto-detected when --project is set. The server maps detected file extensions to language identifiers and checks if a matching adapter binary is on PATH.

For a Rust project with codelldb installed, debugging tools appear automatically:

{
  "mcpServers": {
    "synwire": {
      "command": "synwire-mcp-server",
      "args": ["--project", "."]
    }
  }
}

Use --dap to override, or --no-dap to disable:

# Override: force a specific adapter
synwire-mcp-server --project . --dap codelldb

# Disable all DAP tools
synwire-mcp-server --project . --no-dap

This enables debugging tools:

The DAP plugin also exposes session management tools (debug.launch, debug.attach, debug.continue, debug.step_over, debug.variables, etc.) through the agent plugin system.

Step 4: Tool discovery with tool_search

With LSP, DAP, VFS, indexing, and analysis tools all registered, the full tool set exceeds 25 tools. Listing all of them in every prompt wastes tokens. The tool_search and tool_list meta-tools solve this.

How it works

At startup, the server registers all tools with a ToolSearchIndex. Tools are grouped into namespaces:

Browse a namespace

{"tool": "meta.tool_search", "arguments": {"namespace": "lsp"}}

Returns all LSP tools with name and description.

Search by intent

{"tool": "meta.tool_search", "arguments": {"query": "find where a function is defined"}}

Returns the most relevant tools ranked by keyword + semantic similarity.

Progressive discovery

The index applies adaptive scoring: tools already returned in previous searches get a 0.8x penalty, surfacing unseen tools in subsequent queries. This naturally guides the agent toward tools it has not yet tried.

Step 5: Agent skills integration

Agent skills are reusable tool bundles following the agentskills.io specification. They live in two locations:

• Global: $XDG_DATA_HOME/synwire/skills/ (shared across projects)
• Project-local: .synwire/skills/ (project-specific)

Each skill is a directory containing:

my-skill/
  SKILL.md         # Name, description, parameters, runtime
  scripts/         # Lua, Rhai, or WASM implementation
  references/      # Documentation the skill can read
  assets/          # Static files

The MCP server discovers skills at startup and registers them with tool_search. The agent sees only name and description until it activates a skill, at which point the full body is loaded.

Creating a project-local skill

mkdir -p .synwire/skills/lint-fix

Create .synwire/skills/lint-fix/SKILL.md:

---
name: lint-fix
description: Run the project linter and auto-fix warnings
runtime: tool-sequence
parameters:
  - name: path
    type: string
    description: File or directory to lint
---

1. Run `cargo clippy --fix --allow-dirty` on the target path
2. Read the output and report any remaining warnings

The tool-sequence runtime means the skill is a sequence of existing tool calls -- no scripting needed. The MCP server expands the steps into tool calls at invocation time.

Step 6: Daemon configuration

The daemon starts automatically when the first MCP server connects and stops 5 minutes after the last client disconnects. You can configure it via environment variables or a config file:

# Environment variables
export SYNWIRE_PRODUCT=myapp          # Isolates storage from other instances
export SYNWIRE_EMBEDDING_MODEL=bge-small-en-v1.5
export RUST_LOG=synwire=debug

# Config file (~/.config/synwire/config.toml)
[daemon]
embedding_model = "bge-small-en-v1.5"
log_level = "info"
grace_period_secs = 300

Multi-project indexing

The daemon identifies projects by RepoId (git first-commit hash) and WorktreeId (repo + worktree path). Multiple MCP servers pointing at different worktrees of the same repo share a single RepoId but maintain separate indices.

# Terminal 1: main branch
cd ~/projects/myapp
synwire-mcp-server --project .

# Terminal 2: feature branch (different worktree, same repo)
cd ~/projects/myapp-feature
synwire-mcp-server --project .

Both connect to the same daemon. Indices are stored separately under $XDG_CACHE_HOME/synwire/<repo_id>/<worktree_id>/.

Full configuration example

With auto-detection, a minimal config is usually sufficient:

{
  "mcpServers": {
    "synwire": {
      "command": "synwire-mcp-server",
      "args": ["--project", "."]
    }
  }
}

For full control, all options can be specified explicitly:

{
  "mcpServers": {
    "synwire": {
      "command": "synwire-mcp-server",
      "args": [
        "--project", ".",
        "--lsp", "rust-analyzer",
        "--dap", "codelldb",
        "--product-name", "myapp",
        "--embedding-model", "bge-small-en-v1.5",
        "--log-level", "info"
      ]
    }
  }
}

To disable auto-detection for one or both integrations:

{
  "mcpServers": {
    "synwire": {
      "command": "synwire-mcp-server",
      "args": [
        "--project", ".",
        "--no-lsp",
        "--no-dap"
      ]
    }
  }
}

What you learned

• LSP and DAP tools are auto-detected when --project is set
• --lsp and --dap override auto-detection with a specific server/adapter
• --no-lsp and --no-dap disable auto-detection and all related tools
• Polyglot repos detect multiple servers; the primary language is used for dispatch
• meta.tool_search and meta.tool_list provide namespace-based progressive tool discovery
• Agent skills are discovered from global and project-local directories
• The daemon manages shared state across multiple MCP server instances
• Multi-worktree projects share a RepoId but maintain separate indices

See also

• Tutorial 11: Getting Started with the MCP Server -- basic setup
• Tutorial 12: Authoring Your First Agent Skill -- skill authoring
• How-To: LSP Integration -- LSP tool details
• How-To: DAP Integration -- DAP tool details
• How-To: MCP Integration -- MCP transport options
• synwire-daemon -- daemon architecture

Building a Debugging Agent

Time: ~90 minutes Prerequisites: Rust 1.85+, completion of tutorials 14, 15, and 16

Background: ReAct Agents -- the reason-then-act loop that debugging agents use. Each observation (search result, coverage data, variable trace) feeds back into the next reasoning step.

This tutorial builds an end-to-end debugging agent that accepts a bug report and produces a root cause analysis with a proposed fix. It combines semantic search, SBFL fault localization, dataflow analysis, LSP tools, and file operations into a single agent.

What you are building

A binary that:

1. Accepts a bug report as input
2. Uses semantic search to find relevant code
3. Uses SBFL to identify suspicious files from test coverage
4. Uses dataflow analysis to trace variable origins
5. Uses LSP tools for precise type information
6. Produces a root cause analysis and suggests a fix

Step 1: Dependencies

[dependencies]
synwire-agent = { version = "0.1", features = ["semantic-search"] }
synwire-core = { version = "0.1" }
synwire-lsp = { version = "0.1" }
tokio = { version = "1", features = ["full"] }
serde_json = "1"

Step 2: Set up the VFS and tools

The agent needs access to file operations, semantic search, and analysis tools. Start by creating the VFS and collecting all tools:

use std::sync::Arc;
use synwire_agent::vfs::local::LocalProvider;
use synwire_core::vfs::{vfs_tools, OutputFormat};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let project_root = PathBuf::from(".");
    let vfs = Arc::new(LocalProvider::new(project_root)?);

    // VFS tools: fs.read, fs.write, fs.edit, fs.grep, fs.glob, fs.tree,
    // code.skeleton, index.run, index.status, index.search
    let tools = vfs_tools(Arc::clone(&vfs) as Arc<_>, OutputFormat::Plain);

    // The MCP server adds code.fault_localize, code.trace_dataflow, and
    // code.trace_callers on top of VFS tools. When using the Rust API
    // directly, we construct them as StructuredTool instances.

    Ok(())
}

Step 3: Create analysis tools

Wrap the SBFL, dataflow, and call graph modules as agent tools:

use synwire_core::tools::{StructuredTool, ToolOutput, ToolSchema};
use synwire_agent::sbfl::{CoverageRecord, SbflRanker, fuse_sbfl_semantic};
use synwire_agent::dataflow::DataflowTracer;
use synwire_agent::call_graph::DynamicCallGraph;

fn fault_localize_tool() -> StructuredTool {
    StructuredTool::builder()
        .name("code.fault_localize")
        .description(
            "Rank source files by fault likelihood using SBFL/Ochiai. \
             Provide coverage data as an array of {file, line, ef, nf, np} objects."
        )
        .schema(ToolSchema {
            name: "code.fault_localize".into(),
            description: "SBFL fault localization".into(),
            parameters: serde_json::json!({
                "type": "object",
                "properties": {
                    "coverage": {
                        "type": "array",
                        "items": { "type": "object" }
                    }
                },
                "required": ["coverage"]
            }),
        })
        .func(|input| Box::pin(async move {
            let coverage: Vec<CoverageRecord> = input["coverage"]
                .as_array()
                .unwrap_or(&vec![])
                .iter()
                .filter_map(|v| Some(CoverageRecord {
                    file: v["file"].as_str()?.to_owned(),
                    line: v["line"].as_u64()? as u32,
                    ef: v["ef"].as_u64()? as u32,
                    nf: v["nf"].as_u64()? as u32,
                    np: v["np"].as_u64()? as u32,
                }))
                .collect();

            let ranker = SbflRanker::new(coverage);
            let ranked = ranker.rank_files();

            let output = ranked
                .iter()
                .map(|(f, s)| format!("{f}: {s:.3}"))
                .collect::<Vec<_>>()
                .join("\n");

            Ok(ToolOutput { content: output, ..Default::default() })
        }))
        .build()
        .expect("valid tool")
}

fn dataflow_trace_tool(vfs: Arc<dyn synwire_core::vfs::protocol::Vfs>) -> StructuredTool {
    StructuredTool::builder()
        .name("code.trace_dataflow")
        .description(
            "Trace a variable's assignments backward through a source file. \
             Returns definition and assignment sites."
        )
        .schema(ToolSchema {
            name: "code.trace_dataflow".into(),
            description: "Variable dataflow tracing".into(),
            parameters: serde_json::json!({
                "type": "object",
                "properties": {
                    "file": { "type": "string" },
                    "variable": { "type": "string" },
                    "max_hops": { "type": "integer" }
                },
                "required": ["file", "variable"]
            }),
        })
        .func(move |input| {
            let vfs = Arc::clone(&vfs);
            Box::pin(async move {
                let file = input["file"].as_str().unwrap_or("");
                let variable = input["variable"].as_str().unwrap_or("");
                let max_hops = input["max_hops"].as_u64().unwrap_or(10) as u32;

                let content = vfs.read(file).await.map_err(|e|
                    synwire_core::error::SynwireError::Tool(
                        synwire_core::error::ToolError::InvocationFailed {
                            message: e.to_string(),
                        },
                    )
                )?;

                let tracer = DataflowTracer::new(max_hops);
                let hops = tracer.trace(&content, variable, file);

                let output = hops
                    .iter()
                    .map(|h| format!(
                        "[{}] {}:{} -- {}",
                        h.origin.kind, h.origin.file, h.origin.line, h.origin.snippet,
                    ))
                    .collect::<Vec<_>>()
                    .join("\n");

                Ok(ToolOutput { content: output, ..Default::default() })
            })
        })
        .build()
        .expect("valid tool")
}

Step 4: Configure the agent

The system prompt guides the agent through a structured debugging workflow:

use synwire_core::agents::agent_node::Agent;
use synwire_core::agents::runner::{Runner, RunnerConfig};
use synwire_core::agents::streaming::AgentEvent;

let mut all_tools = tools; // VFS tools from Step 2
all_tools.push(Box::new(fault_localize_tool()));
all_tools.push(Box::new(dataflow_trace_tool(Arc::clone(&vfs) as Arc<_>)));

let agent = Agent::new("debugger", "claude-opus-4-6")
    .system_prompt(
        "You are an expert debugging agent. Follow this structured process:\n\n\
         # Phase 1: Understand the bug\n\
         - Parse the bug report for symptoms, expected vs actual behaviour\n\
         - Identify key terms, error messages, and affected features\n\n\
         # Phase 2: Locate relevant code\n\
         - Call `index.run` then `index.search` with the bug description\n\
         - Use `fs.grep` for specific error messages or identifiers\n\
         - Use `fs.tree` to understand project structure if needed\n\n\
         # Phase 3: Analyse fault likelihood\n\
         - If test coverage data is available, call `code.fault_localize`\n\
         - Read the top-ranked files\n\n\
         # Phase 4: Trace data flow\n\
         - For suspicious variables, call `code.trace_dataflow`\n\
         - Follow the chain of assignments to find the origin\n\n\
         # Phase 5: Report\n\
         - State the root cause with file paths and line numbers\n\
         - Explain the causal chain from origin to symptom\n\
         - Suggest a specific fix with code changes\n\n\
         Be methodical. Show your reasoning at each phase."
    )
    .tools(all_tools)
    .max_turns(40);

Step 5: Run the agent

let runner = Runner::new(agent);
let config = RunnerConfig::default();

let bug_report = serde_json::json!(
    "Bug #4521: When a user submits a form with special characters in the \
     'name' field (e.g. O'Brien), the server returns a 500 error. \
     The error log shows: 'SqliteError: unrecognized token near O'. \
     This started after the recent refactor of the user service."
);

let mut rx = runner.run(bug_report, config).await?;

while let Some(event) = rx.recv().await {
    match event {
        AgentEvent::TextDelta { content } => print!("{content}"),
        AgentEvent::ToolCallStart { name, .. } => {
            eprintln!("\n--- [{name}] ---");
        }
        AgentEvent::ToolCallEnd { name, .. } => {
            eprintln!("--- [/{name}] ---\n");
        }
        AgentEvent::TurnComplete { reason } => {
            println!("\n\n[Agent finished: {reason:?}]");
        }
        AgentEvent::Error { message } => {
            eprintln!("Error: {message}");
        }
        _ => {}
    }
}

Expected agent behaviour

For the SQL injection bug above, the agent would typically:

1. Semantic search for "SQL query construction" and "user input sanitisation"
2. fs.grep for the error string unrecognized token
3. Read the user service files found by search
4. Dataflow trace the name variable to find where it enters the SQL query
5. Report that user input is interpolated directly into a SQL string without escaping, and suggest using parameterised queries

Step 6: Add LSP for precision

When synwire-lsp is available, add LSP tools for type-aware investigation:

use synwire_lsp::{client::LspClient, config::LspServerConfig, tools::lsp_tools};

let lsp_config = LspServerConfig::new("rust-analyzer");
let lsp_client = LspClient::start(&lsp_config).await?;
lsp_client.initialize().await?;

let lsp_tool_set = lsp_tools(Arc::new(lsp_client));

// Add LSP tools to the agent's tool set
all_tools.extend(lsp_tool_set);

With LSP tools, the agent can:

• lsp.hover to check the type of a variable (is name a &str or a sanitised SafeString?)
• lsp.goto_definition to find the exact function that builds the SQL query
• lsp.references to find all call sites that pass unsanitised input

Putting it all together

The complete main.rs:

use std::sync::Arc;
use synwire_agent::vfs::local::LocalProvider;
use synwire_core::agents::agent_node::Agent;
use synwire_core::agents::runner::{Runner, RunnerConfig};
use synwire_core::agents::streaming::AgentEvent;
use synwire_core::vfs::{vfs_tools, OutputFormat};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let vfs = Arc::new(LocalProvider::new(PathBuf::from("."))?);

    let mut tools = vfs_tools(Arc::clone(&vfs) as Arc<_>, OutputFormat::Plain);
    tools.push(Box::new(fault_localize_tool()));
    tools.push(Box::new(dataflow_trace_tool(Arc::clone(&vfs) as Arc<_>)));

    let agent = Agent::new("debugger", "claude-opus-4-6")
        .system_prompt("...")  // system prompt from Step 4
        .tools(tools)
        .max_turns(40);

    let runner = Runner::new(agent);
    let bug = std::env::args().nth(1).unwrap_or_else(|| {
        "Describe the bug here".to_string()
    });

    let mut rx = runner
        .run(serde_json::json!(bug), RunnerConfig::default())
        .await?;

    while let Some(event) = rx.recv().await {
        match event {
            AgentEvent::TextDelta { content } => print!("{content}"),
            AgentEvent::ToolCallStart { name, .. } => {
                eprintln!("\n--- [{name}] ---");
            }
            AgentEvent::TurnComplete { reason } => {
                println!("\n[{reason:?}]");
            }
            _ => {}
        }
    }

    Ok(())
}

Run it:

cargo run -- "Bug #4521: form submission with special characters causes 500 error"

What you learned

• A debugging agent combines semantic search, SBFL, dataflow tracing, and file operations
• The system prompt structures the agent's investigation into phases
• Analysis modules from synwire-agent can be wrapped as StructuredTool instances
• LSP tools add type-aware precision to the investigation
• The agent autonomously decides which tools to call and in what order

See also

• Tutorial 7: Building a Coding Agent -- general coding agent pattern
• Tutorial 14: Fault Localization -- SBFL in depth
• Tutorial 15: Dataflow Analysis -- variable tracing
• Tutorial 16: Code Analysis Tools -- call graphs and combined analysis
• Tutorial 17: Advanced MCP Setup -- all these tools via MCP
• How-To: Approval Gates -- requiring human approval before the agent applies fixes

Building a Custom MCP Server

Time: ~60 minutes Prerequisites: Rust 1.85+, familiarity with Tutorial 11 and Tutorial 17

This tutorial builds a custom MCP server binary from scratch using Synwire's tool composition primitives. By the end you will have a working stdio JSON-RPC server that exposes file operations, code analysis tools, a custom tool, and a multi-step investigation workflow -- all wired through a single CompositeToolProvider.

Architecture

graph LR
    subgraph "MCP Host"
        Host[Claude Code / Cursor / IDE]
    end

    subgraph "Your MCP Server (stdio)"
        Router[CompositeToolProvider]
        MW[LoggingInterceptor]
    end

    subgraph "Backends"
        VFS[LocalProvider<br/>fs.* tools]
        Code[code_tool_provider<br/>code.* tools]
        Idx[index_tool_provider<br/>index.* tools]
        LSP[lsp_tool_provider<br/>lsp.* tools]
        DAP[debug_tool_provider<br/>debug.* tools]
        Custom[custom.greet]
    end

    Host -- JSON-RPC stdin --> MW
    MW --> Router
    Router --> VFS
    Router --> Code
    Router --> Idx
    Router --> LSP
    Router --> DAP
    Router --> Custom

The host sends MCP requests over stdin. The server dispatches each tool call through middleware, resolves the target tool from the CompositeToolProvider, invokes it, and writes the result to stdout.

Step 1: Create the project

cargo new my-mcp-server
cd my-mcp-server

Add dependencies to Cargo.toml:

[dependencies]
synwire = { version = "0.1" }
synwire-core = { version = "0.1" }
synwire-agent = { version = "0.1", features = ["semantic-search"] }
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

Step 2: Assemble tools with CompositeToolProvider

Synwire ships pre-built tool providers grouped by namespace. Combine them into a single provider:

use std::path::PathBuf;
use std::sync::Arc;
use synwire_agent::vfs::local::LocalProvider;
use synwire_core::tools::{CompositeToolProvider, ToolProvider};
use synwire_core::vfs::vfs_tools;
use synwire_agent::tools::{code_tool_provider, index_tool_provider};

fn build_provider(project: PathBuf) -> Arc<CompositeToolProvider> {
    let vfs = Arc::new(LocalProvider::new(project).expect("valid project path"));

    let mut composite = CompositeToolProvider::new();

    // fs.read, fs.write, fs.edit, fs.grep, fs.glob, fs.tree
    composite.add_provider(vfs_tools(Arc::clone(&vfs) as Arc<_>));

    // code.search, code.definition, code.references, code.trace_callers,
    // code.trace_dataflow, code.fault_localize, and more
    composite.add_provider(code_tool_provider(Arc::clone(&vfs) as Arc<_>));

    // index.run, index.status, index.search, index.hybrid_search
    composite.add_provider(index_tool_provider(Arc::clone(&vfs) as Arc<_>));

    Arc::new(composite)
}

Each provider registers its tools under a namespace prefix. When the host calls fs.read, the CompositeToolProvider routes it to the VFS provider.

Step 3: Define a custom tool

Use the #[tool] derive macro to create a tool in your own namespace:

use synwire_derive::tool;
use synwire_core::tools::{ToolOutput, ToolError};

/// Greet a user by name.
///
/// Returns a friendly greeting. Use this tool when the user asks
/// for a personalised welcome message.
#[tool(name = "custom.greet")]
async fn greet(
    /// The name of the person to greet.
    name: String,
    /// Optional language code (default: "en").
    lang: Option<String>,
) -> Result<ToolOutput, ToolError> {
    let greeting = match lang.as_deref().unwrap_or("en") {
        "es" => format!("Hola, {name}!"),
        "fr" => format!("Bonjour, {name}!"),
        "de" => format!("Hallo, {name}!"),
        _ => format!("Hello, {name}!"),
    };
    Ok(ToolOutput::text(greeting))
}

Register it alongside the built-in providers:

composite.add_tool(greet_tool());

Step 4: Wire middleware for logging

Wrap every tool call in a LoggingInterceptor so you can observe traffic on stderr:

use synwire_core::tools::middleware::{
    ToolCallInterceptor, LoggingInterceptor, InterceptorStack,
};

fn build_interceptor_stack() -> InterceptorStack {
    let mut stack = InterceptorStack::new();
    stack.push(LoggingInterceptor::new(tracing::Level::DEBUG));
    stack
}

The LoggingInterceptor emits a tracing span for each tool call containing the tool name, a truncated argument summary, and the wall-clock duration. All output goes to stderr -- stdout is reserved for the MCP protocol.

Step 5: Add a composed multi-step workflow

Turn a StateGraph into a single tool. This example creates code.investigate -- a tool that chains semantic search, file read, and LLM analysis into one call:

use synwire_orchestrator::{StateGraph, CompiledGraph};
use synwire_core::tools::ToolOutput;

fn investigate_tool(
    provider: Arc<CompositeToolProvider>,
) -> impl synwire_core::tools::Tool {
    let mut graph = StateGraph::new("investigate");

    // Node 1: semantic search for the query
    graph.add_node("search", {
        let p = Arc::clone(&provider);
        move |state: &mut InvestigateState| {
            let p = Arc::clone(&p);
            Box::pin(async move {
                let tool = p.get_tool("index.search").expect("index.search registered");
                let result = tool.invoke(serde_json::json!({
                    "query": state.query,
                    "top_k": 3,
                })).await?;
                state.search_results = result.content;
                Ok(())
            })
        }
    });

    // Node 2: read the top-ranked file
    graph.add_node("read", {
        let p = Arc::clone(&provider);
        move |state: &mut InvestigateState| {
            let p = Arc::clone(&p);
            Box::pin(async move {
                let first_file = state.search_results
                    .lines()
                    .next()
                    .unwrap_or("")
                    .to_string();
                let tool = p.get_tool("fs.read").expect("fs.read registered");
                let result = tool.invoke(serde_json::json!({
                    "path": first_file,
                })).await?;
                state.file_content = result.content;
                Ok(())
            })
        }
    });

    // Node 3: produce a summary
    graph.add_node("summarise", |state: &mut InvestigateState| {
        Box::pin(async move {
            state.summary = format!(
                "## Search results\n{}\n\n## Top file content\n{}",
                state.search_results, state.file_content,
            );
            Ok(())
        })
    });

    graph.add_edge("search", "read");
    graph.add_edge("read", "summarise");
    graph.set_entry("search");

    // Convert the graph into a callable tool
    graph.as_tool(
        "code.investigate",
        "Search for code matching a query, read the top result, \
         and return a combined summary. Use when you need to understand \
         how a feature is implemented.",
    )
}

Register it:

composite.add_tool(investigate_tool(Arc::clone(&provider)));

Step 6: Serve via stdio JSON-RPC

The server reads newline-delimited JSON-RPC requests from stdin, dispatches each tool call through the interceptor stack and provider, and writes responses to stdout:

use tokio::io::{self, AsyncBufReadExt, AsyncWriteExt, BufReader};

async fn serve(
    provider: Arc<CompositeToolProvider>,
    interceptors: InterceptorStack,
) -> Result<(), Box<dyn std::error::Error>> {
    let stdin = BufReader::new(io::stdin());
    let mut stdout = io::stdout();
    let mut lines = stdin.lines();

    while let Some(line) = lines.next_line().await? {
        let request: serde_json::Value = serde_json::from_str(&line)?;

        let method = request["method"].as_str().unwrap_or("");
        match method {
            "tools/list" => {
                let tools = provider.list_tools();
                let response = serde_json::json!({
                    "jsonrpc": "2.0",
                    "id": request["id"],
                    "result": { "tools": tools },
                });
                let mut out = serde_json::to_string(&response)?;
                out.push('\n');
                stdout.write_all(out.as_bytes()).await?;
                stdout.flush().await?;
            }
            "tools/call" => {
                let name = request["params"]["name"].as_str().unwrap_or("");
                let args = request["params"]["arguments"].clone();

                let result = interceptors
                    .wrap(name, &args, || async {
                        let tool = provider
                            .get_tool(name)
                            .ok_or_else(|| format!("unknown tool: {name}"))?;
                        tool.invoke(args.clone()).await
                    })
                    .await;

                let response = match result {
                    Ok(output) => serde_json::json!({
                        "jsonrpc": "2.0",
                        "id": request["id"],
                        "result": {
                            "content": [{ "type": "text", "text": output.content }],
                        },
                    }),
                    Err(e) => serde_json::json!({
                        "jsonrpc": "2.0",
                        "id": request["id"],
                        "result": {
                            "content": [{ "type": "text", "text": e.to_string() }],
                            "isError": true,
                        },
                    }),
                };
                let mut out = serde_json::to_string(&response)?;
                out.push('\n');
                stdout.write_all(out.as_bytes()).await?;
                stdout.flush().await?;
            }
            _ => {
                // Ignore unknown methods (initialize, notifications, etc.)
            }
        }
    }

    Ok(())
}

Step 7: Full working main.rs

use std::path::PathBuf;
use std::sync::Arc;

mod tools; // greet_tool(), investigate_tool()

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Send logs to stderr only -- stdout is the MCP transport.
    tracing_subscriber::fmt()
        .with_writer(std::io::stderr)
        .with_env_filter("my_mcp_server=debug,synwire=info")
        .init();

    let project = std::env::args()
        .nth(1)
        .map(PathBuf::from)
        .unwrap_or_else(|| PathBuf::from("."));

    // Assemble all tool providers.
    let provider = build_provider(project);

    // Add custom tools.
    let provider = {
        let mut p = (*provider).clone();
        p.add_tool(greet_tool());
        p.add_tool(investigate_tool(Arc::new(p.clone())));
        Arc::new(p)
    };

    // Build the interceptor stack.
    let interceptors = build_interceptor_stack();

    tracing::info!("MCP server ready, listening on stdin");
    serve(provider, interceptors).await
}

Configure it in .claude/mcp.json:

{
  "my-tools": {
    "command": "./target/release/my-mcp-server",
    "args": ["/path/to/project"]
  }
}

What you learned

• CompositeToolProvider merges multiple namespace-grouped providers into one dispatch table
• vfs_tools(), code_tool_provider(), and index_tool_provider() supply pre-built tools under fs.*, code.*, and index.* namespaces
• The #[tool] macro creates tools with automatic JSON Schema generation
• LoggingInterceptor traces every tool call without touching tool implementations
• StateGraph::as_tool() turns a multi-step graph into a single callable tool
• A stdio MCP server is a thin JSON-RPC loop: read stdin, dispatch to CompositeToolProvider, write stdout

See also

• Tutorial 11: Getting Started with the MCP Server -- using the built-in server
• Tutorial 17: Advanced MCP Server Setup -- LSP, DAP, and daemon configuration
• How-To: MCP Integration -- MCP transport options
• How-To: Middleware Stack -- custom interceptors
• How-To: Tool Output Formats -- TOON, JSON, Markdown output

Custom Tool

Using the #[tool] macro

The simplest way to create a tool:

use synwire_derive::tool;
use synwire_core::error::SynwireError;

/// Reverses the input string.
#[tool]
async fn reverse(text: String) -> Result<String, SynwireError> {
    Ok(text.chars().rev().collect())
}

// Use: let tool = reverse_tool()?;

Using StructuredToolBuilder

For dynamic tool creation:

use synwire_core::tools::{StructuredTool, ToolOutput};

let tool = StructuredTool::builder()
    .name("word_count")
    .description("Counts words in text")
    .parameters(serde_json::json!({
        "type": "object",
        "properties": {
            "text": {"type": "string", "description": "Text to count"}
        },
        "required": ["text"]
    }))
    .func(|input| Box::pin(async move {
        let text = input["text"].as_str().unwrap_or("");
        let count = text.split_whitespace().count();
        Ok(ToolOutput {
            content: format!("{count} words"),
            artifact: None,
        })
    }))
    .build()?;

Implementing the Tool trait

For full control:

use synwire_core::tools::{Tool, ToolOutput, ToolSchema};
use synwire_core::error::SynwireError;
use synwire_core::BoxFuture;

struct HttpFetcher {
    schema: ToolSchema,
}

impl HttpFetcher {
    fn new() -> Self {
        Self {
            schema: ToolSchema {
                name: "http_fetch".into(),
                description: "Fetches a URL".into(),
                parameters: serde_json::json!({
                    "type": "object",
                    "properties": {
                        "url": {"type": "string"}
                    },
                    "required": ["url"]
                }),
            },
        }
    }
}

impl Tool for HttpFetcher {
    fn name(&self) -> &str { &self.schema.name }
    fn description(&self) -> &str { &self.schema.description }
    fn schema(&self) -> &ToolSchema { &self.schema }

    fn invoke(
        &self,
        input: serde_json::Value,
    ) -> BoxFuture<'_, Result<ToolOutput, SynwireError>> {
        Box::pin(async move {
            let url = input["url"].as_str().unwrap_or("");
            // Fetch URL...
            Ok(ToolOutput {
                content: format!("Fetched: {url}"),
                artifact: None,
            })
        })
    }
}

Returning artifacts

Tools can return both text content and structured artifacts:

Ok(ToolOutput {
    content: "Found 3 results".into(),
    artifact: Some(serde_json::json!([
        {"title": "Result 1", "url": "https://example.com/1"},
        {"title": "Result 2", "url": "https://example.com/2"},
        {"title": "Result 3", "url": "https://example.com/3"},
    ])),
})

Switch Provider

All chat models implement the BaseChatModel trait, so switching providers requires only changing the constructor.

Using trait objects

use synwire_core::language_models::BaseChatModel;
use synwire_core::messages::Message;

async fn ask(
    model: &dyn BaseChatModel,
    question: &str,
) -> Result<String, synwire_core::error::SynwireError> {
    let messages = vec![Message::human(question)];
    let result = model.invoke(&messages, None).await?;
    Ok(result.message.content().as_text())
}

Selecting at runtime

use synwire_core::language_models::{FakeChatModel, BaseChatModel};
use synwire_llm_openai::ChatOpenAI;
use synwire_llm_ollama::ChatOllama;

fn create_model(provider: &str) -> Result<Box<dyn BaseChatModel>, Box<dyn std::error::Error>> {
    match provider {
        "openai" => Ok(Box::new(
            ChatOpenAI::builder()
                .model("gpt-4o-mini")
                .api_key_env("OPENAI_API_KEY")
                .build()?
        )),
        "ollama" => Ok(Box::new(
            ChatOllama::builder()
                .model("llama3.2")
                .build()?
        )),
        "fake" => Ok(Box::new(
            FakeChatModel::new(vec!["Fake response".into()])
        )),
        _ => Err("Unknown provider".into()),
    }
}

Feature flags for optional providers

Use Cargo feature flags to conditionally compile providers:

[dependencies]
synwire = "0.1"

[features]
default = []
openai = ["synwire/openai"]
ollama = ["synwire/ollama"]

Testing with FakeChatModel

Replace any real provider with FakeChatModel in tests:

#[cfg(test)]
mod tests {
    use synwire_core::language_models::{FakeChatModel, BaseChatModel};

    #[tokio::test]
    async fn test_my_agent() {
        let model: Box<dyn BaseChatModel> = Box::new(
            FakeChatModel::new(vec!["Test response".into()])
        );
        // Use model in your agent...
    }
}

Add Checkpointing

Checkpointing persists graph state between supersteps, enabling pause/resume and state inspection.

In-memory checkpointing

For development and testing:

use synwire_checkpoint::memory::InMemoryCheckpointSaver;

let saver = InMemoryCheckpointSaver::new();

SQLite checkpointing

For persistent storage:

use synwire_checkpoint_sqlite::saver::SqliteSaver;

let saver = SqliteSaver::new("checkpoints.db")?;

BaseCheckpointSaver trait

All checkpoint implementations satisfy BaseCheckpointSaver:

use synwire_checkpoint::base::BaseCheckpointSaver;

async fn save_state(
    saver: &dyn BaseCheckpointSaver,
    thread_id: &str,
    state: serde_json::Value,
) -> Result<(), Box<dyn std::error::Error>> {
    // Save checkpoint...
    Ok(())
}

Key-value store

For arbitrary key-value storage alongside checkpoints, use BaseStore:

use synwire_checkpoint::store::base::BaseStore;

Custom checkpoint backend

Implement BaseCheckpointSaver for your own storage backend. Use the conformance test suite to validate:

use synwire_checkpoint_conformance::run_conformance_tests;

// In a test:
run_conformance_tests(|| your_saver_factory()).await;

See also

• Checkpointing Tutorial — hands-on: in-memory → SQLite → fork
• Checkpointing Explanation — BaseStore, serde protocol, and trade-offs
• Pregel Execution Model — how checkpoints relate to supersteps

Custom Channel

Channels control how state is accumulated in graph execution. Synwire provides built-in channels, but you can implement your own.

Built-in channels

Implementing BaseChannel

use synwire_orchestrator::channels::traits::BaseChannel;
use synwire_orchestrator::error::GraphError;

struct MaxChannel {
    key: String,
    value: Option<serde_json::Value>,
}

impl MaxChannel {
    fn new(key: impl Into<String>) -> Self {
        Self { key: key.into(), value: None }
    }
}

impl BaseChannel for MaxChannel {
    fn key(&self) -> &str { &self.key }

    fn update(&mut self, values: Vec<serde_json::Value>) -> Result<(), GraphError> {
        for v in values {
            match (&self.value, &v) {
                (Some(current), _) if v.as_f64() > current.as_f64() => {
                    self.value = Some(v);
                }
                (None, _) => {
                    self.value = Some(v);
                }
                _ => {}
            }
        }
        Ok(())
    }

    fn get(&self) -> Option<&serde_json::Value> { self.value.as_ref() }

    fn checkpoint(&self) -> serde_json::Value {
        self.value.clone().unwrap_or(serde_json::Value::Null)
    }

    fn restore_checkpoint(&mut self, value: serde_json::Value) {
        self.value = Some(value);
    }

    fn consume(&mut self) -> Option<serde_json::Value> { self.value.take() }

    fn is_available(&self) -> bool { self.value.is_some() }
}

Channel requirements

When implementing BaseChannel:

• update receives a batch of values from a single superstep
• get must return the current accumulated value
• checkpoint/restore_checkpoint enable state persistence
• consume takes the value and resets the channel
• Implement Send + Sync (required by the trait bound)

Graph Interrupts

Graph interrupts allow you to pause execution at a specific node and resume later, useful for human-in-the-loop workflows.

How interrupts work

When a node returns GraphError::Interrupt, execution pauses. The graph state at that point can be checkpointed and later resumed by re-invoking with the saved state.

Implementing an interrupt

use synwire_orchestrator::error::GraphError;

graph.add_node("review", Box::new(|state| {
    Box::pin(async move {
        let needs_review = state["needs_review"]
            .as_bool()
            .unwrap_or(false);

        if needs_review {
            return Err(GraphError::Interrupt {
                message: "Human review required".into(),
            });
        }

        Ok(state)
    })
}))?;

Handling interrupts

match compiled.invoke(state).await {
    Ok(result) => {
        // Normal completion
    }
    Err(GraphError::Interrupt { message }) => {
        // Save state for later resumption
        println!("Paused: {message}");
    }
    Err(e) => {
        // Other error
    }
}

Resume pattern

After human review modifies the state:

// Modify state based on human input
state["needs_review"] = serde_json::json!(false);
state["human_feedback"] = serde_json::json!("Approved");

// Re-invoke from the interrupted node
let result = compiled.invoke(state).await?;

Combining with checkpointing

For durable interrupts, checkpoint the state before pausing:

use synwire_checkpoint::memory::InMemoryCheckpointSaver;

let saver = InMemoryCheckpointSaver::new();
// Save state on interrupt, restore on resume

Custom Provider

Implement BaseChatModel to add support for a new LLM provider.

Implement the trait

use synwire_core::error::SynwireError;
use synwire_core::language_models::{BaseChatModel, ChatResult, ChatChunk};
use synwire_core::messages::Message;
use synwire_core::runnables::RunnableConfig;
use synwire_core::tools::ToolSchema;
use synwire_core::{BoxFuture, BoxStream};

pub struct MyProvider {
    model_name: String,
    api_key: String,
}

impl BaseChatModel for MyProvider {
    fn invoke<'a>(
        &'a self,
        messages: &'a [Message],
        config: Option<&'a RunnableConfig>,
    ) -> BoxFuture<'a, Result<ChatResult, SynwireError>> {
        Box::pin(async move {
            // Make API call to your provider...
            let response_text = "Response from my provider";
            Ok(ChatResult {
                message: Message::ai(response_text),
                generation_info: None,
                cost: None,
            })
        })
    }

    fn stream<'a>(
        &'a self,
        messages: &'a [Message],
        config: Option<&'a RunnableConfig>,
    ) -> BoxFuture<'a, Result<BoxStream<'a, Result<ChatChunk, SynwireError>>, SynwireError>> {
        Box::pin(async move {
            // Return a stream of ChatChunk values...
            let chunks = vec![Ok(ChatChunk {
                delta_content: Some("Response".into()),
                delta_tool_calls: Vec::new(),
                finish_reason: Some("stop".into()),
                usage: None,
            })];
            Ok(Box::pin(futures_util::stream::iter(chunks))
                as BoxStream<'_, Result<ChatChunk, SynwireError>>)
        })
    }

    fn model_type(&self) -> &str {
        "my-provider"
    }
}

Builder pattern

Use the builder pattern for ergonomic construction:

pub struct MyProviderBuilder {
    model: Option<String>,
    api_key: Option<String>,
}

impl MyProviderBuilder {
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = Some(model.into());
        self
    }

    pub fn api_key_env(mut self, env_var: &str) -> Self {
        self.api_key = std::env::var(env_var).ok();
        self
    }

    pub fn build(self) -> Result<MyProvider, SynwireError> {
        Ok(MyProvider {
            model_name: self.model.unwrap_or_else(|| "default".into()),
            api_key: self.api_key.ok_or(SynwireError::Credential {
                message: "API key required".into(),
            })?,
        })
    }
}

Embeddings provider

Implement Embeddings for embedding support:

use synwire_core::embeddings::Embeddings;
use synwire_core::error::SynwireError;
use synwire_core::BoxFuture;

impl Embeddings for MyProvider {
    fn embed_documents<'a>(
        &'a self,
        texts: &'a [String],
    ) -> BoxFuture<'a, Result<Vec<Vec<f32>>, SynwireError>> {
        Box::pin(async move {
            // Call embedding API...
            Ok(vec![vec![0.0; 768]; texts.len()])
        })
    }

    fn embed_query<'a>(
        &'a self,
        text: &'a str,
    ) -> BoxFuture<'a, Result<Vec<f32>, SynwireError>> {
        Box::pin(async move {
            Ok(vec![0.0; 768])
        })
    }
}

Testing your provider

Use FakeChatModel as a reference for expected behaviour, and write tests against the BaseChatModel trait:

#[tokio::test]
async fn test_invoke_returns_ai_message() {
    let model = MyProvider::builder()
        .model("test")
        .build()
        .unwrap();
    let result = model.invoke(&[Message::human("Hi")], None).await.unwrap();
    assert_eq!(result.message.message_type(), "ai");
}

Enable Tracing

Synwire supports OpenTelemetry-based tracing via the tracing feature flag on synwire-core.

Enable the feature

[dependencies]
synwire-core = { version = "0.1", features = ["tracing"] }

Setup tracing subscriber

use tracing_subscriber::prelude::*;

fn init_tracing() {
    tracing_subscriber::registry()
        .with(tracing_subscriber::fmt::layer())
        .init();
}

Callbacks for custom observability

Implement CallbackHandler to receive events during execution:

use synwire_core::callbacks::CallbackHandler;
use synwire_core::BoxFuture;

struct MetricsCallback;

impl CallbackHandler for MetricsCallback {
    fn on_llm_start<'a>(
        &'a self,
        model_type: &'a str,
        messages: &'a [synwire_core::messages::Message],
    ) -> BoxFuture<'a, ()> {
        Box::pin(async move {
            // Record metrics, emit spans, etc.
        })
    }

    fn on_llm_end<'a>(
        &'a self,
        response: &'a serde_json::Value,
    ) -> BoxFuture<'a, ()> {
        Box::pin(async move {
            // Record latency, token usage, etc.
        })
    }
}

Attaching callbacks to invocations

Pass callbacks via RunnableConfig:

use synwire_core::runnables::RunnableConfig;

let config = RunnableConfig {
    callbacks: vec![Box::new(MetricsCallback)],
    ..Default::default()
};

let result = model.invoke(&messages, Some(&config)).await?;

Filtering callback events

Override the ignore_* methods to skip categories:

impl CallbackHandler for MetricsCallback {
    fn ignore_tool(&self) -> bool { true }  // Skip tool events
    fn ignore_llm(&self) -> bool { false }  // Keep LLM events
}

Credentials

Synwire provides a credential management system with secret redaction and multiple provider strategies.

Credential providers

Using environment variables

use synwire_core::credentials::EnvCredentialProvider;
use synwire_core::credentials::CredentialProvider;

let provider = EnvCredentialProvider::new("OPENAI_API_KEY");
let secret = provider.get_credential()?;
// secret is a SecretValue that redacts on Display/Debug

SecretValue

API keys are wrapped in SecretValue (from the secrecy crate) to prevent accidental logging:

use synwire_core::credentials::SecretValue;

let secret = SecretValue::new("sk-abc123".into());
// println!("{secret}") prints "[REDACTED]"

Static credentials for testing

use synwire_core::credentials::StaticCredentialProvider;
use synwire_core::credentials::CredentialProvider;

let provider = StaticCredentialProvider::new("test-key");
let secret = provider.get_credential()?;

Provider integration

Providers like ChatOpenAI accept credentials via their builders:

use synwire_llm_openai::ChatOpenAI;

// From environment variable
let model = ChatOpenAI::builder()
    .model("gpt-4o-mini")
    .api_key_env("OPENAI_API_KEY")
    .build()?;

Custom credential provider

Implement CredentialProvider for custom sources (vaults, config files, etc.):

use synwire_core::credentials::CredentialProvider;
use synwire_core::credentials::SecretValue;
use synwire_core::error::SynwireError;

struct VaultCredentialProvider {
    key_name: String,
}

impl CredentialProvider for VaultCredentialProvider {
    fn get_credential(&self) -> Result<SecretValue, SynwireError> {
        // Fetch from vault...
        Ok(SecretValue::new("fetched-key".into()))
    }
}

Retry and Fallback

Synwire provides built-in retry and fallback mechanisms for handling transient errors.

Retry configuration

Wrap any RunnableCore with retry logic:

use synwire_core::runnables::{RunnableRetry, RetryConfig};
use synwire_core::error::SynwireErrorKind;

let config = RetryConfig::new()
    .max_retries(3)
    .retry_on(vec![SynwireErrorKind::Model]);  // Only retry model errors

let retryable = RunnableRetry::new(my_runnable, config);

Fallbacks

Chain multiple runnables as fallbacks. If the primary fails, the next is tried:

use synwire_core::runnables::with_fallbacks;
use synwire_core::language_models::{FakeChatModel, BaseChatModel};

let primary = FakeChatModel::new(vec!["Primary response".into()]);
let fallback = FakeChatModel::new(vec!["Fallback response".into()]);

// with_fallbacks tries each in order
let resilient = with_fallbacks(vec![
    Box::new(primary),
    Box::new(fallback),
]);

Error kinds for matching

SynwireErrorKind categorises errors for retry/fallback decisions:

Combining retry and fallback

use synwire_core::runnables::{RunnableRetry, RetryConfig, with_fallbacks};
use synwire_core::error::SynwireErrorKind;

// Primary with retry
let primary_with_retry = RunnableRetry::new(
    primary_model,
    RetryConfig::new()
        .max_retries(2)
        .retry_on(vec![SynwireErrorKind::Model]),
);

// Fallback without retry
let resilient = with_fallbacks(vec![
    Box::new(primary_with_retry),
    Box::new(fallback_model),
]);

Callback on retry

Monitor retries via the CallbackHandler:

impl CallbackHandler for MyCallback {
    fn on_retry<'a>(
        &'a self,
        attempt: u32,
        error: &'a str,
    ) -> BoxFuture<'a, ()> {
        Box::pin(async move {
            eprintln!("Retry attempt {attempt}: {error}");
        })
    }
}

How to: Use the Virtual Filesystem (VFS)

Goal: Give an LLM agent filesystem-like access to heterogeneous data sources through a single interface that mirrors coreutils.

Quick start

Instantiate a VFS provider, call vfs_tools to get pre-built tools, and pass them to create_react_agent. The LLM can then ls, read, grep, tree, find, write, edit, etc.

#![allow(unused)]
fn main() {
use std::sync::Arc;
use synwire_agent::vfs::local::LocalProvider;
use synwire_core::vfs::{Vfs, OutputFormat, vfs_tools};
use synwire_orchestrator::prebuilt::create_react_agent;

// 1. Create a VFS scoped to the project directory.
let vfs: Arc<dyn Vfs> = Arc::new(
    LocalProvider::new("/home/user/project")?
);

// 2. Get all tools the provider supports — automatically.
let tools = vfs_tools(Arc::clone(&vfs), OutputFormat::Toon);

// 3. Hand them to the react agent.
let graph = create_react_agent(model, tools)?;
let result = graph.invoke(initial_state).await?;
}

That's it. vfs_tools inspects capabilities() and only includes tools the provider actually supports. The OutputFormat controls how structured results (directory listings, grep matches, etc.) are serialized before the LLM sees them.

The LLM sees these as callable tools:

Agent: "Let me explore the project."
  → ls { path: ".", recursive: false }
  → tree { path: "src", max_depth: 2 }
  → head { path: "src/main.rs", lines: 20 }
  → grep { pattern: "TODO", path: "src", file_type: "rust" }
  → edit { path: "src/main.rs", old: "// TODO", new: "// DONE" }

VFS providers

Choose the provider based on what data the LLM should access.

LocalProvider — real filesystem with path-traversal protection

All operations are scoped to root. Any path escaping root is rejected with VfsError::PathTraversal.

#![allow(unused)]
fn main() {
use synwire_agent::vfs::local::LocalProvider;

let vfs: Arc<dyn Vfs> = Arc::new(LocalProvider::new("/home/user/project")?);
let tools = vfs_tools(vfs, OutputFormat::Toon);
}

MemoryProvider — ephemeral in-memory storage

No persistence. Ideal for agent scratchpads and test fixtures.

#![allow(unused)]
fn main() {
use synwire_core::vfs::MemoryProvider;

let vfs: Arc<dyn Vfs> = Arc::new(MemoryProvider::new());
let tools = vfs_tools(vfs, OutputFormat::Toon);
// The LLM can write and read files in memory during its run.
// Everything is lost when the provider is dropped.
}

CompositeProvider — mount multiple providers by path prefix

The LLM sees a unified filesystem. Routes operations to the provider whose prefix is the longest match.

#![allow(unused)]
fn main() {
use synwire_agent::vfs::composite::{CompositeProvider, Mount};
use synwire_agent::vfs::local::LocalProvider;
use synwire_core::vfs::MemoryProvider;

let vfs: Arc<dyn Vfs> = Arc::new(CompositeProvider::new(vec![
    Mount {
        prefix: "/workspace".to_string(),
        backend: Box::new(LocalProvider::new("/home/user/project")?),
    },
    Mount {
        prefix: "/scratch".to_string(),
        backend: Box::new(MemoryProvider::new()),
    },
]));
let tools = vfs_tools(vfs, OutputFormat::Toon);
// /workspace/... → real files     /scratch/... → ephemeral in-memory
}

The LLM can call mount to discover what's available:

Agent: → mount {}
Result:
  /workspace  LocalProvider   [ls, read, write, edit, grep, glob, ...]
  /scratch    MemoryProvider  [ls, read, write, edit, grep, glob, ...]

Cross-boundary operations: cp and mv across mount boundaries work automatically — the composite reads from the source mount and writes to the destination mount. For mv, the source is deleted after the write succeeds.

Root-level operations: ls / shows mount prefixes as virtual directories. grep from root searches all mounts. pwd returns /.

StoreProvider — key-value persistence as a filesystem

Wraps any [BaseStore] implementation. Keys map to paths as /<namespace>/<key>.

#![allow(unused)]
fn main() {
use synwire_agent::vfs::store::{InMemoryStore, StoreProvider};

let vfs: Arc<dyn Vfs> = Arc::new(StoreProvider::new("agent1", InMemoryStore::new()));
let tools = vfs_tools(vfs, OutputFormat::Json);
}

Available tools

vfs_tools generates these tools (only those the provider supports, plus mount which is always available):

Capability checking

Providers declare what they support via VfsCapabilities bitflags. vfs_tools handles this automatically, but you can check manually:

#![allow(unused)]
fn main() {
use synwire_core::vfs::types::VfsCapabilities;

if vfs.capabilities().contains(VfsCapabilities::FIND) {
    // provider supports find
}
}

Sandbox tools (non-VFS)

Command execution, process management, and archive handling live in the sandbox module — useful for coding agents but a different concern from filesystem abstraction.

#![allow(unused)]
fn main() {
use synwire_agent::sandbox::shell::Shell;
use synwire_agent::sandbox::process::ProcessManager;
use synwire_agent::sandbox::archive::ArchiveManager;
}

See also

• How to: Tool Output Formats — JSON vs TOON, setting defaults per agent
• How to: Perform Advanced Search — GrepOptions reference

How to: Configure Tool Output Formats

Goal: Control how structured data from VFS operations and tools is serialized before being passed to the LLM.

Why it matters

When an LLM calls a tool like ls or find, the result is a Rust struct (Vec<DirEntry>, Vec<FindEntry>, etc.). Before the LLM sees it, the data must be serialized to text. The format you choose affects:

• Token usage — TOON can reduce tokens by 30–60 % for tabular data
• Model comprehension — JSON is universally understood; TOON is optimised for LLM consumption
• Debugging — pretty JSON is easiest to read in logs

The three formats

Example — ls returning two files:

JSON (136 tokens):

[
  {"name": "main.rs", "path": "/src/main.rs", "is_dir": false, "size": 1024},
  {"name": "lib.rs", "path": "/src/lib.rs", "is_dir": false, "size": 512}
]

TOON (~40 tokens):

[2]{name,path,is_dir,size}:
  main.rs,/src/main.rs,false,1024
  lib.rs,/src/lib.rs,false,512

Setting the default on an agent

#![allow(unused)]
fn main() {
use synwire_core::vfs::OutputFormat;

let agent = Agent::new()
    .name("coding-agent")
    .model("claude-sonnet-4-20250514")
    .tool_output_format(OutputFormat::Toon)
    .build();
}

All tools on this agent will use TOON by default when formatting their output.

Overriding per-tool

Individual tools can call format_output directly with a different format:

#![allow(unused)]
fn main() {
use synwire_core::vfs::{format_output, OutputFormat};

// Inside a tool implementation:
let entries = vfs.ls(path, opts).await?;

// Use JSON for this specific tool, regardless of the agent default.
let content = format_output(&entries, OutputFormat::Json)?;
}

Using format_output

format_output accepts any Serialize value and an OutputFormat:

#![allow(unused)]
fn main() {
use synwire_core::vfs::{format_output, OutputFormat};

// Serialize a Vec<DirEntry> to TOON.
let text = format_output(&entries, OutputFormat::Toon)?;

// Serialize a TreeEntry to compact JSON.
let text = format_output(&tree, OutputFormat::JsonCompact)?;

// Serialize a DiffResult to pretty JSON.
let text = format_output(&diff, OutputFormat::Json)?;
}

The toon feature is enabled by default. If you compile without it (default-features = false), OutputFormat::Toon falls back to pretty JSON.

See also

• TOON specification
• How to: Use the VFS — VFS providers and operations

How to: Configure the Middleware Stack

Goal: Build a MiddlewareStack, add the provided middleware components, and implement your own custom middleware.

Overview

MiddlewareStack runs its components in insertion order. Each component receives a MiddlewareInput (messages + context metadata) and returns a MiddlewareResult:

• MiddlewareResult::Continue(MiddlewareInput) — pass (possibly modified) input to the next component.
• MiddlewareResult::Terminate(String) — stop the chain immediately and return the given message.

System prompt additions and tools from all components are collected in declaration order.

#![allow(unused)]
fn main() {
use synwire_core::agents::middleware::MiddlewareStack;

let mut stack = MiddlewareStack::new();
// Push components in the order they should run.
stack.push(component_a);
stack.push(component_b);

let result = stack.run(input).await?;
let prompts = stack.system_prompt_additions();
let tools   = stack.tools();
}

FilesystemMiddleware

Advertises filesystem tools (ls, read_file, write_file, edit_file, rm, pwd, cd) and adds a system prompt note about their availability. The runner wires the tools to the configured LocalProvider at start-up.

#![allow(unused)]
fn main() {
use synwire_agent::middleware::filesystem::FilesystemMiddleware;

stack.push(FilesystemMiddleware);
}

GitMiddleware

Advertises git tools and injects a system prompt describing available git operations.

#![allow(unused)]
fn main() {
use synwire_agent::middleware::git::GitMiddleware;

stack.push(GitMiddleware);
}

HttpMiddleware

Advertises HTTP request tools and injects a system prompt describing them.

#![allow(unused)]
fn main() {
use synwire_agent::middleware::http::HttpMiddleware;

stack.push(HttpMiddleware);
}

ProcessMiddleware

Advertises process management tools (list_processes, kill_process, spawn_background, execute, list_jobs).

#![allow(unused)]
fn main() {
use synwire_agent::middleware::process::ProcessMiddleware;

stack.push(ProcessMiddleware);
}

ArchiveMiddleware

Advertises archive tools (create_archive, extract_archive, list_archive).

#![allow(unused)]
fn main() {
use synwire_agent::middleware::archive::ArchiveMiddleware;

stack.push(ArchiveMiddleware);
}

PipelineMiddleware

Advertises the pipeline execution tool.

#![allow(unused)]
fn main() {
use synwire_agent::middleware::pipeline::PipelineMiddleware;

stack.push(PipelineMiddleware);
}

SummarisationMiddleware

Monitors message and token counts. When a threshold is exceeded, it sets summarisation_pending: true in the context metadata so the runner can trigger a summarisation step.

#![allow(unused)]
fn main() {
use synwire_agent::middleware::summarisation::{SummarisationMiddleware, SummarisationThresholds};

let thresholds = SummarisationThresholds {
    max_messages: Some(40),
    max_tokens: Some(60_000),
    max_context_utilisation: Some(0.75),
};
stack.push(SummarisationMiddleware::new(thresholds));

// Use defaults (50 messages / 80,000 tokens / 80% utilisation).
stack.push(SummarisationMiddleware::default());
}

PromptCachingMiddleware

Marks system prompts for provider-side caching. Push it before any middleware that adds large static system prompt additions.

#![allow(unused)]
fn main() {
use synwire_agent::middleware::prompt_caching::PromptCachingMiddleware;

stack.push(PromptCachingMiddleware);
}

PatchToolCallsMiddleware

Repairs malformed tool call JSON emitted by the model (e.g. missing required fields, incorrect types) before the agent attempts to execute them.

#![allow(unused)]
fn main() {
use synwire_agent::middleware::patch_tool_calls::PatchToolCallsMiddleware;

stack.push(PatchToolCallsMiddleware);
}

EnvironmentMiddleware

Injects environment variable tools (get_env, set_env, list_env) and adds a system prompt explaining how to use them.

#![allow(unused)]
fn main() {
use synwire_agent::middleware::environment::EnvironmentMiddleware;

stack.push(EnvironmentMiddleware);
}

Ordering

Middlewares execute in the order they were pushed. Recommended ordering for a typical agent:

1. PromptCachingMiddleware — mark static prompts before any additions accumulate
2. PatchToolCallsMiddleware — fix model output before tools run
3. FilesystemMiddleware / HttpMiddleware / GitMiddleware / … — capability injection
4. SummarisationMiddleware — history compaction last so it sees the full message list

Implementing a custom middleware

Implement the Middleware trait. Only override the methods you need; process defaults to Continue and tools / system_prompt_additions default to empty.

#![allow(unused)]
fn main() {
use synwire_core::agents::middleware::{Middleware, MiddlewareInput, MiddlewareResult};
use synwire_core::agents::error::AgentError;
use synwire_core::BoxFuture;

struct AuditMiddleware {
    log_prefix: String,
}

impl Middleware for AuditMiddleware {
    fn name(&self) -> &str {
        "audit"
    }

    fn process(
        &self,
        input: MiddlewareInput,
    ) -> BoxFuture<'_, Result<MiddlewareResult, AgentError>> {
        let prefix = self.log_prefix.clone();
        Box::pin(async move {
            tracing::info!("{prefix}: {} messages in context", input.messages.len());
            // Return unchanged input to continue the chain.
            Ok(MiddlewareResult::Continue(input))
        })
    }

    fn system_prompt_additions(&self) -> Vec<String> {
        vec!["All operations are audited.".to_string()]
    }
}
}

To terminate the chain early (e.g. a rate-limit guard):

#![allow(unused)]
fn main() {
fn process(
    &self,
    _input: MiddlewareInput,
) -> BoxFuture<'_, Result<MiddlewareResult, AgentError>> {
    Box::pin(async move {
        if self.rate_limit_exceeded() {
            return Ok(MiddlewareResult::Terminate(
                "Rate limit exceeded — request blocked".to_string(),
            ));
        }
        Ok(MiddlewareResult::Continue(_input))
    })
}
}

See also

• How to: Use the Backend Implementations
• How to: Configure Approval Gates
• Explanation: Architecture

How to: Configure Approval Gates

Goal: Control which operations an agent is allowed to perform without user intervention by wiring approval callbacks.

Core types

An ApprovalRequest is passed to the gate whenever a risky operation is about to run:

#![allow(unused)]
fn main() {
pub struct ApprovalRequest {
    pub operation: String,        // e.g. "write_file", "kill_process"
    pub description: String,      // human-readable summary of what will happen
    pub risk: RiskLevel,
    pub timeout_secs: Option<u64>,
    pub context: serde_json::Value, // operation arguments or extra metadata
}
}

RiskLevel is an ordered enum (lower to higher):

The callback returns an ApprovalDecision:

AutoApproveCallback

Approves everything. Use in tests or sandboxed environments where unrestricted execution is acceptable.

#![allow(unused)]
fn main() {
use synwire_core::vfs::approval::AutoApproveCallback;

let gate = AutoApproveCallback;
}

AutoDenyCallback

Denies everything. Use as a safe default when building ThresholdGate with an inner callback that should never actually fire.

#![allow(unused)]
fn main() {
use synwire_core::vfs::approval::AutoDenyCallback;

let gate = AutoDenyCallback;
}

ThresholdGate

Auto-approves any operation whose risk is at or below threshold. Operations above the threshold are delegated to an inner ApprovalCallback. Decisions of AllowAlways are cached per operation name so the inner callback is not called again.

#![allow(unused)]
fn main() {
use synwire_agent::vfs::threshold_gate::ThresholdGate;
use synwire_core::vfs::approval::{AutoDenyCallback, RiskLevel};

// Auto-approve up to Medium risk; deny anything Higher automatically.
let gate = ThresholdGate::new(RiskLevel::Medium, AutoDenyCallback);
}

Use with an interactive callback for production:

#![allow(unused)]
fn main() {
use synwire_core::vfs::approval::{ApprovalCallback, ApprovalDecision, ApprovalRequest};
use synwire_core::BoxFuture;

struct CliPrompt;

impl ApprovalCallback for CliPrompt {
    fn request(&self, req: ApprovalRequest) -> BoxFuture<'_, ApprovalDecision> {
        Box::pin(async move {
            eprintln!("[approval] {} — {:?}", req.description, req.risk);
            eprint!("Allow? [y/N/always] ");
            // Read from stdin in a real implementation.
            ApprovalDecision::Allow
        })
    }
}

let gate = ThresholdGate::new(RiskLevel::Low, CliPrompt);
}

Implementing a custom ApprovalCallback

#![allow(unused)]
fn main() {
use synwire_core::vfs::approval::{ApprovalCallback, ApprovalDecision, ApprovalRequest};
use synwire_core::BoxFuture;

struct PolicyCallback {
    allowed_operations: Vec<String>,
}

impl ApprovalCallback for PolicyCallback {
    fn request(&self, req: ApprovalRequest) -> BoxFuture<'_, ApprovalDecision> {
        Box::pin(async move {
            if self.allowed_operations.iter().any(|op| req.operation.starts_with(op)) {
                ApprovalDecision::Allow
            } else {
                ApprovalDecision::Deny
            }
        })
    }
}
}

The ApprovalCallback trait requires Send + Sync. Use Arc<Mutex<_>> for any mutable internal state.

Interplay with PermissionMode

ThresholdGate enforces risk-based decisions independently of PermissionMode. For rule-based tool-name filtering, see How to: Configure Permission Modes. A typical setup layers both:

1. PermissionRule patterns allow or deny by tool name before the operation is submitted.
2. ThresholdGate intercepts anything that reaches execution and applies risk thresholds.

See also

• How to: Configure Permission Modes
• How to: Configure the Middleware Stack
• Explanation: Architecture

Background: Context Engineering for AI Agents — how to design the context and controls around an AI agent, including approval mechanisms.

How to: Manage Agent Sessions

Goal: Create, persist, resume, fork, rewind, tag, and delete agent sessions using SessionManager.

Core types

#![allow(unused)]
fn main() {
pub struct SessionMetadata {
    pub id: String,           // UUID
    pub name: Option<String>,
    pub tags: Vec<String>,
    pub agent_name: String,
    pub created_at: i64,      // Unix milliseconds
    pub updated_at: i64,      // Unix milliseconds
    pub turn_count: u32,
    pub total_tokens: u64,
}

pub struct Session {
    pub metadata: SessionMetadata,
    pub messages: Vec<serde_json::Value>,  // conversation history
    pub state: serde_json::Value,          // arbitrary agent state
}
}

InMemorySessionManager

The built-in implementation. All data is lost when the process exits. Use it for tests or ephemeral agents; use the checkpoint-backed implementation for persistence.

#![allow(unused)]
fn main() {
use synwire_agent::session::manager::InMemorySessionManager;
use synwire_core::agents::session::{Session, SessionManager, SessionMetadata};

let mgr = InMemorySessionManager::new();
}

Save and resume

#![allow(unused)]
fn main() {
use serde_json::json;

// Construct a new session.
let session = Session {
    metadata: SessionMetadata {
        id: uuid::Uuid::new_v4().to_string(),
        name: Some("my-task".to_string()),
        tags: vec!["production".to_string()],
        agent_name: "code-agent".to_string(),
        created_at: 0,
        updated_at: 0,
        turn_count: 0,
        total_tokens: 0,
    },
    messages: Vec::new(),
    state: json!({"cwd": "/home/user"}),
};

mgr.save(&session).await?;

// Later — in the same or a new call — resume by ID.
let loaded = mgr.resume(&session.metadata.id).await?;
}

save sets updated_at to the current time. Calling save on an existing ID updates it in place.

List sessions

Returns all sessions ordered by updated_at descending (most recently active first).

#![allow(unused)]
fn main() {
let sessions: Vec<SessionMetadata> = mgr.list().await?;
for s in &sessions {
    println!("{} {:?} turns={}", s.id, s.name, s.turn_count);
}
}

Fork a session

Creates an independent copy with a new UUID. The fork shares history up to the fork point but diverges independently afterwards.

#![allow(unused)]
fn main() {
let fork_meta = mgr.fork(&session.metadata.id, Some("experiment-branch".to_string())).await?;
assert_ne!(fork_meta.id, session.metadata.id);
}

Pass None as the name to auto-generate a name of the form "<original name> (fork)".

Rewind to a previous turn

Truncates the message list to turn_index entries (zero-based). Useful for re-running from a specific point without forking.

#![allow(unused)]
fn main() {
// Keep only the first 3 messages.
let rewound = mgr.rewind(&session.metadata.id, 3).await?;
assert_eq!(rewound.messages.len(), 3);
}

Tag a session

Adds one or more tags without duplicates. Existing tags are preserved.

#![allow(unused)]
fn main() {
mgr.tag(&session.metadata.id, vec!["reviewed".to_string(), "archived".to_string()]).await?;
}

Rename a session

#![allow(unused)]
fn main() {
mgr.rename(&session.metadata.id, "final-delivery".to_string()).await?;
}

Delete a session

#![allow(unused)]
fn main() {
mgr.delete(&session.metadata.id).await?;
// Subsequent resume returns AgentError::Session.
}

Implementing SessionManager

To persist sessions to a database or remote store, implement the SessionManager trait. All methods return BoxFuture so async storage drivers are supported.

#![allow(unused)]
fn main() {
use synwire_core::agents::session::{Session, SessionManager, SessionMetadata};
use synwire_core::agents::error::AgentError;
use synwire_core::BoxFuture;

struct RedisSessionManager { /* ... */ }

impl SessionManager for RedisSessionManager {
    fn list(&self) -> BoxFuture<'_, Result<Vec<SessionMetadata>, AgentError>> {
        Box::pin(async move { /* query Redis ZREVRANGE */ todo!() })
    }

    fn resume(&self, session_id: &str) -> BoxFuture<'_, Result<Session, AgentError>> {
        let id = session_id.to_string();
        Box::pin(async move { /* GET id */ todo!() })
    }

    fn save(&self, session: &Session) -> BoxFuture<'_, Result<(), AgentError>> {
        let session = session.clone();
        Box::pin(async move { /* SET id */ todo!() })
    }

    fn delete(&self, session_id: &str) -> BoxFuture<'_, Result<(), AgentError>> {
        let id = session_id.to_string();
        Box::pin(async move { /* DEL id */ todo!() })
    }

    fn fork(&self, session_id: &str, new_name: Option<String>) -> BoxFuture<'_, Result<SessionMetadata, AgentError>> {
        todo!()
    }

    fn rewind(&self, session_id: &str, turn_index: u32) -> BoxFuture<'_, Result<Session, AgentError>> {
        todo!()
    }

    fn tag(&self, session_id: &str, tags: Vec<String>) -> BoxFuture<'_, Result<(), AgentError>> {
        todo!()
    }

    fn rename(&self, session_id: &str, new_name: String) -> BoxFuture<'_, Result<(), AgentError>> {
        todo!()
    }
}
}

See also

• How to: Add Checkpointing
• Explanation: Architecture

How to: Integrate MCP Servers

Using the standalone synwire-mcp-server

The easiest way to expose Synwire tools to an MCP host (Claude Code, GitHub Copilot, Cursor) is the standalone synwire-mcp-server binary.

Install

cargo install synwire-mcp-server

Configure Claude Code

Add to .claude/mcp.json in your project or home directory:

{
  "synwire": {
    "command": "synwire-mcp-server",
    "args": ["--project", "."]
  }
}

With LSP support:

{
  "synwire": {
    "command": "synwire-mcp-server",
    "args": ["--project", ".", "--lsp", "rust-analyzer"]
  }
}

Config file (alternative to CLI flags)

Create synwire.toml in your project root:

project = "."
product_name = "myapp"
lsp = "rust-analyzer"
embedding_model = "bge-small-en-v1.5"
log_level = "info"

{
  "synwire": {
    "command": "synwire-mcp-server",
    "args": ["--config", "synwire.toml"]
  }
}

CLI flags override config file values. See the synwire-mcp-server explanation for all available flags.

Goal: Connect to Model Context Protocol servers via stdio, HTTP, or in-process transports, and manage multiple servers through McpLifecycleManager.

Core trait: McpTransport

All transports implement:

#![allow(unused)]
fn main() {
pub trait McpTransport: Send + Sync {
    fn connect(&self)    -> BoxFuture<'_, Result<(), AgentError>>;
    fn reconnect(&self)  -> BoxFuture<'_, Result<(), AgentError>>;
    fn disconnect(&self) -> BoxFuture<'_, Result<(), AgentError>>;
    fn status(&self)     -> BoxFuture<'_, McpServerStatus>;
    fn list_tools(&self) -> BoxFuture<'_, Result<Vec<McpToolDescriptor>, AgentError>>;
    fn call_tool(&self, tool_name: &str, arguments: Value)
        -> BoxFuture<'_, Result<Value, AgentError>>;
}
}

McpServerStatus carries the server name, McpConnectionState, call success/failure counters, and an enabled flag.

McpConnectionState progression: Disconnected → Connecting → Connected. After a drop: Connected → Reconnecting → Connected (or back to Disconnected on failure). Shutdown is terminal.

StdioMcpTransport

Manages a subprocess and exchanges newline-delimited JSON-RPC over its stdin/stdout.

#![allow(unused)]
fn main() {
use synwire_agent::mcp::stdio::StdioMcpTransport;
use synwire_core::mcp::traits::McpTransport;
use std::collections::HashMap;

let transport = StdioMcpTransport::new(
    "my-mcp-server",
    "npx",
    vec!["-y".to_string(), "@modelcontextprotocol/server-filesystem".to_string()],
    HashMap::from([
        ("MCP_WORKSPACE".to_string(), "/home/user/project".to_string()),
    ]),
);

transport.connect().await?;

let tools = transport.list_tools().await?;
for t in &tools {
    println!("{}: {}", t.name, t.description);
}

let result = transport.call_tool("read_file", serde_json::json!({
    "path": "/home/user/project/README.md"
})).await?;

transport.disconnect().await?;
}

Reconnecting kills the existing subprocess and spawns a new one:

#![allow(unused)]
fn main() {
transport.reconnect().await?;
}

HttpMcpTransport

Connects to an HTTP-based MCP server. The connect call performs a health check by issuing POST /tools/list.

#![allow(unused)]
fn main() {
use synwire_agent::mcp::http::HttpMcpTransport;

let transport = HttpMcpTransport::new(
    "remote-mcp",
    "https://mcp.example.com",
    Some("Bearer sk-...".to_string()),
    Some(30),  // timeout_secs; None defaults to 30
);

transport.connect().await?;

let tools = transport.list_tools().await?;
let result = transport.call_tool("search", serde_json::json!({"query": "rust async"})).await?;
}

InProcessMcpTransport

Registers native Tool implementations and exposes them via the McpTransport interface without any subprocess or network hop. Useful for built-in toolsets that benefit from the MCP lifecycle API.

#![allow(unused)]
fn main() {
use synwire_agent::mcp::in_process::InProcessMcpTransport;
use std::sync::Arc;

let mut transport = InProcessMcpTransport::new("builtin-tools");

// Register any type that implements `synwire_core::tools::Tool`.
transport.register(Arc::new(MyCustomTool)).await;

transport.connect().await?;  // transitions to Connected immediately

let tools = transport.list_tools().await?;
let result = transport.call_tool("my_tool", serde_json::json!({"input": "value"})).await?;
}

reconnect on an in-process transport is equivalent to connect — it simply marks the state as Connected.

McpLifecycleManager

Manages multiple transports: connects all at start, monitors health, and reconnects dropped servers in the background.

#![allow(unused)]
fn main() {
use synwire_agent::mcp::lifecycle::McpLifecycleManager;
use std::sync::Arc;
use std::time::Duration;

let manager = Arc::new(McpLifecycleManager::new());

// Register servers with individual reconnect delays.
manager.register("filesystem", StdioMcpTransport::new(/* ... */), Duration::from_secs(5)).await;
manager.register("web-search",  HttpMcpTransport::new(/* ... */), Duration::from_secs(10)).await;

// Connect all enabled servers.
manager.start_all().await?;

// Spawn background health monitor (polls every 30 s, reconnects as needed).
Arc::clone(&manager).spawn_health_monitor(Duration::from_secs(30));

// Call a tool on a named server — auto-reconnects if needed.
let result = manager.call_tool("filesystem", "read_file", serde_json::json!({
    "path": "/project/src/main.rs"
})).await?;

// Inspect status of all servers.
let statuses = manager.all_status().await;
for s in &statuses {
    println!("{}: {:?} ok={} fail={}", s.name, s.state, s.calls_succeeded, s.calls_failed);
}

// Disable a server at runtime.
manager.disable("web-search").await?;

// Re-enable and reconnect.
manager.enable("web-search").await?;

// Shutdown.
manager.stop_all().await?;
}

Calling call_tool on a disabled server returns AgentError::Backend immediately without attempting to reconnect.

See also

• How to: Configure the Middleware Stack
• How to: Add a Custom Tool
• Explanation: Architecture

How to: Configure Three-Tier Signal Routing

Goal: Define signal routes across strategy, agent, and plugin tiers so incoming signals produce the correct agent actions.

Core types

#![allow(unused)]
fn main() {
pub struct Signal {
    pub kind: SignalKind,
    pub payload: serde_json::Value,
}

pub enum SignalKind {
    Stop,
    UserMessage,
    ToolResult,
    Timer,
    Custom(String),
}

pub enum Action {
    Continue,
    GracefulStop,
    ForceStop,
    Transition(String),   // FSM state name
    Custom(String),
}
}

SignalRoute

A route binds a SignalKind to an Action, with an optional predicate for finer-grained matching and a numeric priority for tie-breaking within the same tier.

#![allow(unused)]
fn main() {
use synwire_core::agents::signal::{Action, Signal, SignalKind, SignalRoute};

// Match all Stop signals.
let route = SignalRoute::new(SignalKind::Stop, Action::GracefulStop, 10);

// Match only non-empty user messages.
fn non_empty(s: &Signal) -> bool {
    s.payload.as_str().is_some_and(|v| !v.is_empty())
}

let guarded = SignalRoute::with_predicate(
    SignalKind::UserMessage,
    non_empty,
    Action::Continue,
    20,  // higher priority — wins over routes with lower values
);
}

Predicates must be plain function pointers (fn(&Signal) -> bool) so SignalRoute remains Clone + Send + Sync.

ComposedRouter

Combines three tiers of routes. Within each tier the highest-priority matching route wins. The strategy tier always beats the agent tier, which always beats the plugin tier — regardless of priority values within tiers.

#![allow(unused)]
fn main() {
use synwire_core::agents::signal::{Action, ComposedRouter, Signal, SignalKind, SignalRoute, SignalRouter};

let strategy_routes = vec![
    // Unconditionally force-stop on Stop signal from strategy level.
    SignalRoute::new(SignalKind::Stop, Action::ForceStop, 0),
];

let agent_routes = vec![
    // Agent prefers graceful stop with higher intra-tier priority.
    SignalRoute::new(SignalKind::Stop, Action::GracefulStop, 100),
    SignalRoute::new(SignalKind::UserMessage, Action::Continue, 0),
    SignalRoute::new(SignalKind::Timer, Action::Transition("tick".to_string()), 0),
];

let plugin_routes = vec![
    SignalRoute::new(SignalKind::Custom("metrics".to_string()), Action::Continue, 0),
];

let router = ComposedRouter::new(strategy_routes, agent_routes, plugin_routes);
}

Routing a signal:

#![allow(unused)]
fn main() {
use serde_json::json;

let signal = Signal::new(SignalKind::Stop, json!(null));

match router.route(&signal) {
    Some(Action::ForceStop)   => { /* strategy tier matched */ }
    Some(Action::GracefulStop) => { /* agent tier matched */ }
    Some(action)              => { /* other action */ }
    None                      => { /* no route — apply default behaviour */ }
}
}

Inspect all registered routes across tiers:

#![allow(unused)]
fn main() {
let all_routes = router.routes();
println!("{} routes registered", all_routes.len());
}

Custom routers

Implement SignalRouter to replace the composed approach entirely:

#![allow(unused)]
fn main() {
use synwire_core::agents::signal::{Action, Signal, SignalRouter, SignalRoute};

struct AlwaysContinueRouter;

impl SignalRouter for AlwaysContinueRouter {
    fn route(&self, _signal: &Signal) -> Option<Action> {
        Some(Action::Continue)
    }

    fn routes(&self) -> Vec<SignalRoute> {
        Vec::new()
    }
}
}

Priority semantics summary

See also

• How to: Configure Permission Modes
• Explanation: Architecture

How to: Configure Permission Modes

Goal: Apply a PermissionMode preset and define PermissionRule patterns to control which tool operations the agent may perform.

PermissionMode presets

PermissionMode is Copy and Default (defaults to Default). It expresses a broad policy for the agent session:

#![allow(unused)]
fn main() {
use synwire_core::agents::permission::PermissionMode;

let mode = PermissionMode::Default;         // prompt for dangerous ops
let mode = PermissionMode::AcceptEdits;     // auto-approve file modifications
let mode = PermissionMode::PlanOnly;        // read-only, no mutations
let mode = PermissionMode::BypassAll;       // auto-approve everything (caution)
let mode = PermissionMode::DenyUnauthorized; // deny unless a pre-approved rule matches
}

PermissionRule

Rules match tool names using glob patterns and assign a PermissionBehavior:

#![allow(unused)]
fn main() {
use synwire_core::agents::permission::{PermissionBehavior, PermissionRule};

let rules = vec![
    // Allow all file reads without prompting.
    PermissionRule {
        tool_pattern: "read_file".to_string(),
        behavior: PermissionBehavior::Allow,
    },
    // Always ask before writing.
    PermissionRule {
        tool_pattern: "write_file".to_string(),
        behavior: PermissionBehavior::Ask,
    },
    // Block process spawning entirely.
    PermissionRule {
        tool_pattern: "spawn_background".to_string(),
        behavior: PermissionBehavior::Deny,
    },
    // Wildcard: allow all git operations.
    PermissionRule {
        tool_pattern: "git_*".to_string(),
        behavior: PermissionBehavior::Allow,
    },
];
}

PermissionBehavior values:

How rules interact with approval callbacks

Rules are evaluated before the operation reaches an approval gate:

1. The runner matches the tool name against all PermissionRule patterns in order.
2. On Deny — the operation is blocked immediately; the approval callback is not called.
3. On Allow — the operation proceeds; the approval callback is not called.
4. On Ask (or no matching rule) — the operation is forwarded to the ApprovalCallback (e.g. ThresholdGate).

Under DenyUnauthorized mode, any tool with no matching rule and no Ask result is blocked as if Deny were returned.

Under BypassAll mode, Ask results are treated as Allow — the approval callback is still invoked but the answer is ignored.

Serialisation

Both types derive Serialize and Deserialize, so rules can be loaded from a config file:

#![allow(unused)]
fn main() {
use synwire_core::agents::permission::{PermissionMode, PermissionRule};

let rules: Vec<PermissionRule> = serde_json::from_str(r#"[
    {"tool_pattern": "read_file", "behavior": "Allow"},
    {"tool_pattern": "write_file", "behavior": "Ask"},
    {"tool_pattern": "rm", "behavior": "Deny"}
]"#)?;

let mode: PermissionMode = serde_json::from_str(r#""AcceptEdits""#)?;
}

See also

• How to: Configure Approval Gates
• How to: Configure Signal Routing
• Explanation: Architecture

Process Sandboxing

Synwire isolates agent-spawned processes using Linux cgroup v2 for resource accounting and OCI container runtimes for namespace isolation. Two runtimes are supported:

Prerequisites

WSL2 note: cgroup v2 is available but user delegation may not be enabled by default — see the WSL2 section below.

Architecture

Synwire uses battle-tested OCI runtimes for namespace isolation instead of a custom init binary. These runtimes handle all namespace, mount, seccomp, and capability setup including hardening against known CVEs.

For each container, synwire:

1. Creates a temporary OCI bundle directory
2. Generates an OCI runtime spec (config.json) from the SandboxConfig
3. Generates /etc/passwd and /etc/group so the current user is resolvable inside the container (whoami, id, ls -la all work)
4. Runs runc run --bundle <dir> <id> (or runsc --rootless run ... for gVisor)
5. Cleans up the bundle when the container exits

Runtime selection

use synwire_sandbox::platform::linux::namespace::NamespaceContainer;

// Standard runc — finds "runc" on $PATH
let container = NamespaceContainer::new()?;

// gVisor — finds "runsc" on $PATH
let container = NamespaceContainer::with_gvisor()?;

// Explicit selection
use synwire_sandbox::platform::linux::namespace::OciRuntime;
let container = NamespaceContainer::with_runtime(OciRuntime::Gvisor)?;

User namespace and UID mapping

Rootless user namespaces only allow a single UID/GID mapping entry (without the setuid newuidmap helper). runc's init process requires UID 0, so synwire maps containerID 0 → hostID <real-uid>. The process runs as UID 0 inside the namespace, which the kernel translates to the real UID for all host-side operations (file ownership in bind mounts, etc.).

A generated /etc/passwd maps UID 0 to the real username — the same trick Podman uses for rootless containers. Inside the container:

$ whoami
naadir
$ id
uid=0(naadir) gid=0(naadir) groups=0(naadir)
$ touch /tmp/test && ls -la /tmp/test
-rw-r--r-- 1 naadir naadir 0 Mar 16 12:00 /tmp/test

Capabilities

The default capability set is intentionally minimal — much tighter than Docker's default:

Dropped from Docker's default: CHOWN, DAC_OVERRIDE, FSETID, FOWNER, SETGID, SETUID, SYS_CHROOT, AUDIT_WRITE. Use capabilities_add in SandboxConfig to grant additional capabilities if a specific use case requires them.

gVisor differences

When using OciRuntime::Gvisor, synwire adjusts its behaviour automatically:

• No user namespace in the OCI spec — runsc manages its own user namespace via --rootless
• No UID/GID mappings — handled internally by runsc
• No seccomp profile — gVisor's sentry kernel provides stronger syscall filtering than BPF-based seccomp; applying both causes compatibility issues
• Platform auto-detected — probes systrap first, falls back to ptrace if needed (see Platform auto-detection below)

cgroup hierarchy

Agent cgroups are placed as siblings of the synwire process's own cgroup:

user@1000.service/
  app.slice/
    code.scope/          ← synwire process lives here
    synwire/
      agents/<uuid>/     ← agent cgroups go here

When the CgroupV2Manager is dropped (agent terminated), it writes 1 to cgroup.kill (Linux 5.14+) or falls back to SIGKILL per PID to ensure immediate cleanup.

Installing runc

# Debian/Ubuntu
sudo apt install runc

# Fedora
sudo dnf install runc

# Arch
sudo pacman -S runc

Verify:

runc --version

Installing gVisor (optional)

gVisor provides a stronger isolation boundary by running a user-space kernel that intercepts syscalls. Install runsc:

# Download and install runsc
ARCH=$(uname -m)
URL="https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}"
wget "${URL}/runsc" "${URL}/runsc.sha512"
sha512sum -c runsc.sha512
chmod a+rx runsc
sudo mv runsc /usr/local/bin/

Or via a package manager (where available):

# Arch (AUR)
yay -S gvisor-bin

Verify:

runsc --version

Platform auto-detection

gVisor supports two syscall interception platforms:

On first use, synwire automatically probes whether systrap works by running a trivial container (/bin/true). If systrap succeeds, it is used for all future containers in the process. If it fails, synwire falls back to ptrace, logs a warning, and caches the decision for the lifetime of the process — no repeated probes.

Why systrap may fail: In rootless mode with --network=host, gVisor has a bug where CAP_SYS_PTRACE is not included in the sandbox's ambient capabilities. ConfigureCmdForRootless() in runsc/sandbox/sandbox.go overwrites AmbientCaps without CAP_SYS_PTRACE (line 1059), and the systrap capability check that would add it back is in the else branch that only runs when host networking is not used (line 1143). This causes systrap's PTRACE_ATTACH on stub threads to fail with EPERM. The ptrace platform uses CLONE_PTRACE from the child instead, avoiding the issue.

When the gVisor bug is fixed upstream, the probe will succeed automatically and synwire will use systrap — no code change needed.

Enabling cgroup v2 delegation

Verify cgroup v2 is mounted

# Should show cgroup2 filesystem
mount | grep cgroup2

# Should list available controllers
cat /sys/fs/cgroup/cgroup.controllers

If /sys/fs/cgroup/cgroup.controllers does not exist, add systemd.unified_cgroup_hierarchy=1 to your kernel command line and reboot.

Verify user delegation

# Show your process's cgroup
cat /proc/self/cgroup
# Output: 0::/user.slice/user-1000.slice/user@1000.service/app.slice/...

# Check the parent is writable
CGROUP_PATH=$(sed -n 's|0::|/sys/fs/cgroup|p' /proc/self/cgroup)
PARENT=$(dirname "$CGROUP_PATH")
ls -la "$PARENT"/cgroup.subtree_control

If the parent cgroup is not writable, ensure systemd user sessions are enabled:

systemctl --user status

# If "Failed to connect to bus":
loginctl enable-linger $USER

Enable controller delegation

If controllers (cpu, memory, pids) are not available in the user cgroup:

sudo mkdir -p /etc/systemd/system/user@.service.d
sudo tee /etc/systemd/system/user@.service.d/delegate.conf <<'EOF'
[Service]
Delegate=cpu cpuset io memory pids
EOF

sudo systemctl daemon-reload
# Log out and back in, or:
sudo systemctl restart user@$(id -u).service

Verify:

cat /sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service/cgroup.subtree_control
# Should show: cpu io memory pids

WSL2

WSL2 runs a custom init by default. Add to /etc/wsl.conf:

[boot]
systemd=true

Then restart WSL (wsl --shutdown from PowerShell).

Isolation levels

macOS sandboxing

macOS lacks Linux namespaces and cgroup v2, so synwire uses platform-native mechanisms: Apple's Seatbelt sandbox for light isolation, and OCI container runtimes (Docker Desktop, Podman, or Colima) for strong isolation.

Seatbelt (light isolation)

Seatbelt uses Apple's sandbox-exec tool with Sandbox Profile Language (SBPL) profiles. Synwire generates an SBPL profile from the SandboxConfig at runtime, applying a deny-by-default model — all operations are denied unless explicitly allowed.

Deprecation note: Apple has deprecated sandbox-exec and the public SBPL interface. It remains functional on current macOS versions and is widely used by build systems (Nix, Bazel). Synwire will migrate to a replacement if Apple provides one.

How profiles are generated

Synwire translates SandboxConfig fields into SBPL rules:

SecurityPreset levels

Example SBPL profile

A Restricted preset with a workdir of /tmp/agent-work produces:

(version 1)
(deny default)

;; Allow basic process execution
(allow process-exec)
(allow process-fork)
(allow sysctl-read)
(allow mach-lookup)

;; Filesystem: workdir read/write
(allow file-read* file-write*
  (subpath "/tmp/agent-work"))

;; Filesystem: system libraries (read-only)
(allow file-read*
  (subpath "/usr/lib")
  (subpath "/usr/share")
  (subpath "/System")
  (subpath "/Library/Frameworks")
  (subpath "/private/var/db/dyld"))

;; Network: denied (restricted preset)
;; Subprocesses: denied (restricted preset)
(deny process-fork (with send-signal SIGKILL))

Usage

use synwire_sandbox::platform::macos::seatbelt::SeatbeltContainer;

let container = SeatbeltContainer::new(config)?;
container.run(command).await?;

Container runtime (strong isolation)

For stronger isolation on macOS, synwire uses a container runtime that runs Linux in a lightweight VM. Synwire auto-detects the available runtime via detect_container_runtime(), using a four-tier priority order:

Apple Container  >  Docker Desktop  >  Podman  >  Colima

use synwire_sandbox::platform::macos::container::detect_container_runtime;

let runtime = detect_container_runtime().await?;
// Returns ContainerRuntime::AppleContainer, ContainerRuntime::DockerDesktop,
// ContainerRuntime::Podman, or ContainerRuntime::Colima

Apple Container (preferred)

Apple Container is Apple's first-party tool for running Linux containers as lightweight VMs using macOS Virtualization.framework. It is the preferred strong-isolation runtime when available.

Requirements: macOS 26+ (Tahoe), Apple Silicon.

Installing Apple Container

# Via Homebrew
brew install apple/container/container

# Or download from GitHub releases
# https://github.com/apple/container/releases

Verify:

container --version

Note: Apple Container is preferred over all other runtimes when available because it is a first-party Apple tool with tighter system integration and lower overhead. If your Mac does not meet the requirements (macOS 26+ and Apple Silicon), synwire falls back to Docker Desktop, then Podman, then Colima.

Docker Desktop (widely installed)

Docker Desktop has the largest install base of any container runtime on macOS, making it the second-priority option. Although synwire does not use Docker on Linux (see the sandbox methodology for details on the daemon model concerns), the macOS situation is different: every macOS container runtime already runs a Linux VM, so the daemon-in-a-VM architecture does not add an extra layer of indirection.

Synwire checks for Docker Desktop by running docker version (not docker --version). The --version flag only checks the CLI binary is installed; docker version queries the daemon and fails if the Docker Desktop VM is not running. This avoids false positives where the CLI is present but the backend is stopped.

Docker Desktop, Podman, and Colima share identical docker run / podman run CLI flag semantics, so synwire translates SandboxConfig into the same set of flags for all three.

Installing Docker Desktop

Download and install from docker.com. Launch Docker Desktop and wait for the engine to start.

Verify:

docker version

Podman (fallback)

Podman runs a lightweight Linux VM (podman machine) and manages OCI containers inside it. It is the fallback runtime when neither Apple Container nor Docker Desktop is available. Synwire invokes Podman with the following flags:

These same flags apply to Docker Desktop and Colima, which share identical CLI semantics.

Installing Podman

brew install podman
podman machine init
podman machine start

Verify:

podman info

Colima (last resort)

Colima wraps Lima to provide a Docker-compatible environment with minimal configuration. Unlike bare Lima, Colima exposes a Docker socket so that the standard docker run CLI works transparently. Synwire detects Colima by running colima status to check that the Colima VM is running, then delegates to docker run for container execution.

Colima is used only when Apple Container, Docker Desktop, and Podman are all unavailable.

Installing Colima

brew install colima
colima start

Verify:

colima status
docker version   # Should succeed via Colima's Docker socket

Isolation levels (macOS)

Check user namespace support

# Should return 1
cat /proc/sys/kernel/unprivileged_userns_clone 2>/dev/null || \
  sysctl kernel.unprivileged_userns_clone

# If 0:
sudo sysctl -w kernel.unprivileged_userns_clone=1
echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-userns.conf

Running the tests

# Unprivileged tests (always work)
cargo test -p synwire-sandbox --test linux_e2e

# cgroup + runc namespace tests (require delegation + runc)
cargo test -p synwire-sandbox --test linux_e2e -- --ignored

# gVisor tests only (require runsc on $PATH)
cargo test -p synwire-sandbox --test linux_e2e gvisor -- --ignored

The cgroup tests gracefully skip if delegation is not available. The namespace tests skip if runc is not found. The gVisor tests skip if runsc is not found.

How to: Perform Advanced Search

Goal: Use Vfs::grep with GrepOptions to run ripgrep-style content searches against any backend.

GrepOptions reference

#![allow(unused)]
fn main() {
use synwire_core::vfs::grep_options::{GrepOptions, GrepOutputMode};

let opts = GrepOptions {
    path: None,                  // search root; None = backend's current working directory
    case_insensitive: false,
    invert: false,               // true = return non-matching lines
    line_numbers: false,         // include line numbers in results
    output_mode: GrepOutputMode::Content,
    before_context: 0,           // lines to include before each match
    after_context: 0,            // lines to include after each match
    context: None,               // symmetric context (overrides before/after when set)
    max_matches: None,           // stop after N total matches
    glob: None,                  // filename glob filter, e.g. "*.rs"
    file_type: None,             // ripgrep-style type: "rust", "python", "go", etc.
    multiline: false,
    fixed_string: false,         // treat pattern as literal, not regex
};
}

All fields have Default implementations. Start from GrepOptions::default() and override only what you need.

GrepMatch fields

#![allow(unused)]
fn main() {
pub struct GrepMatch {
    pub file: String,
    pub line_number: usize,    // 1-indexed when line_numbers: true; 0 otherwise
    pub column: usize,         // 0-indexed byte offset of match start
    pub line_content: String,  // the matching line
    pub before: Vec<String>,   // lines before the match (up to before_context)
    pub after: Vec<String>,    // lines after the match (up to after_context)
}
}

In Count mode, line_number holds the match count for the file and line_content is its string representation.

Case-insensitive search

#![allow(unused)]
fn main() {
use synwire_core::vfs::grep_options::GrepOptions;
use synwire_core::vfs::protocol::Vfs;

let opts = GrepOptions {
    case_insensitive: true,
    line_numbers: true,
    ..Default::default()
};

let matches = backend.grep("todo", opts).await?;
for m in &matches {
    println!("{}:{} {}", m.file, m.line_number, m.line_content);
}
}

Context lines

#![allow(unused)]
fn main() {
let opts = GrepOptions {
    context: Some(2),     // 2 lines before AND after each match
    line_numbers: true,
    ..Default::default()
};

// Or use asymmetric context:
let opts = GrepOptions {
    before_context: 3,
    after_context: 1,
    ..Default::default()
};
}

When both context and before_context/after_context are set, context takes precedence.

File-type filter

Accepts ripgrep-style type names. Supported aliases include rust/rs, python/py, js/javascript, ts/typescript, go, json, yaml/yml, toml, md/markdown, sh/bash.

#![allow(unused)]
fn main() {
let opts = GrepOptions {
    file_type: Some("rust".to_string()),
    ..Default::default()
};

let matches = backend.grep("unwrap", opts).await?;
// Returns only matches in *.rs files.
}

Glob filter

Restricts results to files whose name matches the glob pattern. * matches any sequence of non-separator characters; ** matches anything.

#![allow(unused)]
fn main() {
let opts = GrepOptions {
    glob: Some("*.toml".to_string()),
    ..Default::default()
};

let matches = backend.grep("version", opts).await?;
}

Inverted match

Returns lines that do NOT match the pattern.

#![allow(unused)]
fn main() {
let opts = GrepOptions {
    invert: true,
    ..Default::default()
};

// Lines that do not contain "TODO".
let matches = backend.grep("TODO", opts).await?;
}

Files-with-matches mode

Returns one entry per file (with empty line_content) rather than one entry per matching line.

#![allow(unused)]
fn main() {
use synwire_core::vfs::grep_options::GrepOutputMode;

let opts = GrepOptions {
    output_mode: GrepOutputMode::FilesWithMatches,
    ..Default::default()
};

let matches = backend.grep("panic!", opts).await?;
let files: Vec<&str> = matches.iter().map(|m| m.file.as_str()).collect();
}

Count mode

Returns one entry per file with line_number set to the number of matches in that file.

#![allow(unused)]
fn main() {
let opts = GrepOptions {
    output_mode: GrepOutputMode::Count,
    ..Default::default()
};

let counts = backend.grep("error", opts).await?;
for c in &counts {
    println!("{}: {} occurrences", c.file, c.line_number);
}
}

Limiting results

#![allow(unused)]
fn main() {
let opts = GrepOptions {
    max_matches: Some(50),
    ..Default::default()
};
}

The search stops after max_matches total matches across all files. Useful for large codebases where you only need the first few hits.

Scoped search path

#![allow(unused)]
fn main() {
let opts = GrepOptions {
    path: Some("src/backends".to_string()),
    file_type: Some("rust".to_string()),
    ..Default::default()
};

let matches = backend.grep("VfsError", opts).await?;
}

path is resolved relative to the backend's current working directory.

See also

• How to: Use the Backend Implementations — Vfs operations
• How to: Configure the Middleware Stack
• Reference: Feature Flags

Semantic Search

Task-focused recipes for common semantic search operations.

Enable semantic search

Add the semantic-search feature to your synwire-agent dependency:

[dependencies]
synwire-agent = { version = "0.1", features = ["semantic-search"] }

This is an opt-in feature because it adds heavyweight dependencies (fastembed, LanceDB, tree-sitter grammars). When disabled, LocalProvider omits the INDEX and SEMANTIC_SEARCH capabilities and the corresponding VFS tools are not offered to the LLM.

Index a directory

use synwire_agent::vfs::local::LocalProvider;
use synwire_core::vfs::protocol::Vfs;
use synwire_core::vfs::types::IndexOptions;
use std::path::PathBuf;

let vfs = LocalProvider::new(PathBuf::from("/path/to/project"))?;

let handle = vfs.index("src", IndexOptions {
    force: false,
    include: vec!["**/*.rs".into(), "**/*.py".into()],
    exclude: vec!["target/**".into(), "**/node_modules/**".into()],
    max_file_size: Some(1_048_576),
}).await?;

The include and exclude fields accept glob patterns. If include is empty, all files are included. exclude patterns are always applied.

Wait for indexing to complete

use synwire_core::vfs::types::IndexStatus;

loop {
    match vfs.index_status(&handle.index_id).await? {
        IndexStatus::Ready(result) => {
            println!("{} files, {} chunks", result.files_indexed, result.chunks_produced);
            break;
        }
        IndexStatus::Failed(e) => return Err(e.into()),
        _ => tokio::time::sleep(std::time::Duration::from_millis(500)).await,
    }
}

Search by meaning

use synwire_core::vfs::types::SemanticSearchOptions;

let results = vfs.semantic_search("authentication flow", SemanticSearchOptions {
    top_k: Some(10),
    min_score: None,
    file_filter: vec![],
    rerank: Some(true),
}).await?;

Search within specific files

Use file_filter to restrict search to a subset of indexed files:

let results = vfs.semantic_search("error handling", SemanticSearchOptions {
    top_k: Some(5),
    file_filter: vec!["src/auth/**".into(), "src/middleware/**".into()],
    ..Default::default()
}).await?;

Disable reranking for faster results

Cross-encoder reranking improves accuracy but adds latency. Disable it when speed matters more than precision:

let results = vfs.semantic_search("database queries", SemanticSearchOptions {
    rerank: Some(false),
    ..Default::default()
}).await?;

Force a full re-index

By default, index() reuses cached results if available. To force a fresh index (e.g. after a large merge or branch switch):

let handle = vfs.index("src", IndexOptions {
    force: true,
    ..Default::default()
}).await?;

Configure chunk sizes

The default chunk size (1 500 bytes with 200-byte overlap) works well for most codebases. To adjust for very large or very small files, construct the SemanticIndex directly:

use synwire_index::{SemanticIndex, IndexConfig};

let config = IndexConfig {
    cache_base: None,       // use OS default
    chunk_size: 2000,       // larger chunks for long functions
    chunk_overlap: 300,     // more context between chunks
};

Note: Chunk size only affects the text splitter fallback. AST-chunked code files always use one chunk per definition regardless of size.

Use a custom cache directory

By default, index data is stored under the OS cache directory ($XDG_CACHE_HOME/synwire/indices/ on Linux). To use a project-local cache:

use synwire_index::IndexConfig;
use std::path::PathBuf;

let config = IndexConfig {
    cache_base: Some(PathBuf::from(".synwire-cache")),
    ..Default::default()
};

Stop the file watcher

The background file watcher starts automatically after indexing completes. To stop it (e.g. before shutting down):

// If using SemanticIndex directly:
index.unwatch(&path).await;

// If using LocalProvider, the watcher stops when the provider is dropped.

Combine semantic search with grep

Semantic search and grep serve different purposes. Use both in a complementary workflow:

// Step 1: Find the concept
let semantic_results = vfs.semantic_search(
    "rate limiting middleware",
    SemanticSearchOptions::default(),
).await?;

// Step 2: Find exact usages of the function you discovered
let grep_results = vfs.grep(
    "apply_rate_limit",
    synwire_core::vfs::types::GrepOptions::default(),
).await?;

Handle indexing errors

Individual file failures during indexing are logged and skipped — the pipeline continues with remaining files. To detect these:

• Check IndexResult::files_indexed against expected file count.
• Enable tracing at WARN level to see per-file errors:

// In your application setup:
tracing_subscriber::fmt()
    .with_env_filter("synwire_index=warn")
    .init();

Agentic ignore files

LocalProvider automatically discovers and respects agentic ignore files — .cursorignore, .aiignore, .claudeignore, .aiderignore, .copilotignore, .codeiumignore, .tabbyignore, and .gitignore — by searching upward from the provider's root directory to the filesystem root. Files matching any discovered pattern are excluded from ls, grep, glob, and semantic indexing.

All ignore files use gitignore syntax, including negation (! prefix) and directory-only patterns (trailing /):

# .cursorignore — exclude secrets and build artifacts
.env*
secret/
target/
node_modules/
!.env.example    # but keep the example

To check which ignore files are in effect, create an AgenticIgnore directly:

use synwire_core::vfs::agentic_ignore::AgenticIgnore;
use std::path::Path;

let ai = AgenticIgnore::discover(Path::new("/path/to/project"));
assert!(ai.is_ignored(Path::new("/path/to/project/.env"), false));

Prevent indexing the root filesystem

index("/", ..) is always rejected with VfsError::IndexDenied. This is a safety measure — indexing the entire filesystem would be extremely slow and produce unusable results. Always index specific project directories.

Hybrid search (BM25 + vector)

When synwire-index is built with the hybrid-search feature, you can combine BM25 lexical scoring with vector semantic scoring:

#[cfg(feature = "hybrid-search")]
use synwire_index::{HybridSearchConfig, hybrid_search};

let config = HybridSearchConfig {
    alpha: 0.5,   // 0.0 = pure vector, 1.0 = pure BM25
    top_k: 10,
};

let results = hybrid_search(&bm25_index, &vector_store, &embeddings, "auth", config).await?;

Tuning alpha

Start with alpha = 0.5 and adjust based on your query patterns. If you are searching for exact function names, increase alpha toward 1.0. If you are searching conceptually, decrease it toward 0.0.

See also

• Semantic Search Tutorial — step-by-step walkthrough
• Semantic Search Architecture — design rationale
• VFS Providers — general VFS operations
• Advanced Search (grep) — text pattern search

How to: Integrate Language Servers

Goal: Connect your agent to Language Server Protocol servers for code intelligence -- go-to-definition, hover, diagnostics, completions.

Quick start

Add synwire-lsp to your workspace dependencies and register the LspPlugin on the agent builder.

[dependencies]
synwire-lsp = { version = "0.1" }

use synwire_lsp::plugin::LspPlugin;
use synwire_lsp::registry::LanguageServerRegistry;
use synwire_lsp::config::LspPluginConfig;

let registry = LanguageServerRegistry::default_registry();
let lsp = LspPlugin::new(registry, LspPluginConfig::default());

let agent = Agent::new("coder", "coding assistant")
    .plugin(Box::new(lsp))
    .build()?;

The plugin registers five tools: lsp_hover, lsp_goto_definition, lsp_references, lsp_diagnostics, and lsp_completion. It also injects a system prompt telling the model which language servers are available.

Auto-start

LspPlugin detects language servers on PATH based on file extension. The first time a tool is called for a file, the plugin:

1. Looks up the file extension in the LanguageServerRegistry.
2. Checks whether the server binary is available via which::which().
3. Spawns the server in --stdio mode if found.
4. Performs the LSP initialize / initialized handshake.
5. Sends textDocument/didOpen for the target file.

Subsequent calls to the same server reuse the running process. The plugin shuts down all servers when the agent session ends.

If no server is found for a language, the tool returns a structured error describing which server is expected and how to install it.

Example: hover and go-to-definition

A typical exchange with rust-analyzer:

use synwire_lsp::plugin::LspPlugin;
use synwire_lsp::registry::LanguageServerRegistry;
use synwire_lsp::config::LspPluginConfig;
use synwire_agent::Agent;

let registry = LanguageServerRegistry::default_registry();
let lsp = LspPlugin::new(registry, LspPluginConfig::default());

let agent = Agent::new("coder", "Rust coding assistant")
    .plugin(Box::new(lsp))
    .build()?;

// The model can now call:
//   lsp_hover { path: "src/main.rs", line: 42, column: 10 }
//   lsp_goto_definition { path: "src/main.rs", line: 42, column: 10 }
//   lsp_references { path: "src/lib.rs", line: 15, column: 4 }
//   lsp_diagnostics { path: "src/lib.rs" }
//   lsp_completion { path: "src/main.rs", line: 42, column: 10 }

The model sees structured results containing type signatures, documentation strings, file locations, and severity-tagged diagnostics.

Document sync with VFS

When the agent writes or edits files through VFS tools, the LSP server must know about the changes to provide accurate results. LspPlugin subscribes to VFS write hooks automatically:

• write / append triggers textDocument/didOpen or textDocument/didChange.
• edit triggers textDocument/didChange with incremental edits.
• rm triggers textDocument/didClose.

This means the model can write code via VFS, then immediately call lsp_diagnostics to check for errors -- without manual synchronisation.

use synwire_lsp::config::LspPluginConfig;

// Disable automatic sync if you manage notifications yourself.
let config = LspPluginConfig {
    auto_sync_vfs: false,
    ..Default::default()
};

Multi-server mode

Agents working across multiple languages spawn one server per language automatically. The plugin routes each tool call to the correct server based on file extension.

// The model opens a Go file and a Rust file in the same session.
//   lsp_hover { path: "cmd/main.go", line: 10, column: 5 }   -> gopls
//   lsp_hover { path: "src/lib.rs", line: 20, column: 8 }    -> rust-analyzer

Servers are started lazily. A project touching five languages only spawns servers for the languages the model actually queries.

To cap resource usage:

let config = LspPluginConfig {
    max_concurrent_servers: 3,
    server_idle_timeout: std::time::Duration::from_secs(300),
    ..Default::default()
};

Servers idle beyond server_idle_timeout are shut down and restarted on the next request.

Configuration

Use LspServerConfig for fine-grained control over individual servers.

use synwire_lsp::config::{LspPluginConfig, LspServerConfig};
use synwire_lsp::registry::LanguageServerRegistry;
use std::collections::HashMap;

let mut overrides = HashMap::new();
overrides.insert("rust".to_string(), LspServerConfig {
    command: "rust-analyzer".to_string(),
    args: vec![],
    initialization_options: serde_json::json!({
        "checkOnSave": { "command": "clippy" },
        "cargo": { "allFeatures": true }
    }),
    env: vec![("RUST_LOG".to_string(), "info".to_string())],
    root_uri_override: None,
});

let config = LspPluginConfig {
    server_overrides: overrides,
    ..Default::default()
};

let registry = LanguageServerRegistry::default_registry();
let lsp = LspPlugin::new(registry, config);

LspServerConfig fields:

See also

• Explanation: synwire-lsp -- design rationale and protocol details
• How to: Configure Language Servers -- built-in server list, custom entries, TOML config
• How to: Integrate Debug Adapters -- DAP plugin for debugging support
• How to: Use the Virtual Filesystem (VFS) -- VFS providers and document sync

How to: Integrate Debug Adapters

Goal: Give your agent debugging capabilities -- set breakpoints, step through code, inspect variables -- via the Debug Adapter Protocol (DAP).

Quick start

Add synwire-dap to your workspace dependencies and register the DapPlugin on the agent builder.

[dependencies]
synwire-dap = { version = "0.1" }

use synwire_dap::plugin::DapPlugin;
use synwire_dap::config::DapPluginConfig;

let dap = DapPlugin::new(DapPluginConfig::default());

let agent = Agent::new("debugger", "debugging assistant")
    .plugin(Box::new(dap))
    .build()?;

The plugin registers these tools: debug.launch, debug.attach, debug.set_breakpoints, debug.continue, debug.step_over, debug.step_in, debug.step_out, debug.variables, debug.evaluate, debug.stack_trace, and debug.disconnect.

Launch vs attach

DAP supports two modes for starting a debug session.

Launch mode

The plugin spawns the debug adapter and the target program together.

// The model calls:
//   debug.launch {
//     adapter: "dlv-dap",
//     program: "./cmd/myapp",
//     args: ["--config", "dev.yaml"],
//     cwd: "/home/user/project"
//   }

Attach mode

The plugin connects to an already-running process or a debug adapter listening on a port.

// The model calls:
//   debug.attach {
//     adapter: "dlv-dap",
//     pid: 12345
//   }
//
// Or attach by address:
//   debug.attach {
//     adapter: "dlv-dap",
//     host: "127.0.0.1",
//     port: 2345
//   }

Use launch mode for test debugging. Use attach mode for inspecting running services.

Example: debug a Go test

A typical debugging session with dlv-dap:

use synwire_dap::plugin::DapPlugin;
use synwire_dap::config::{DapPluginConfig, DapAdapterConfig};
use synwire_agent::Agent;

let config = DapPluginConfig {
    adapters: vec![
        DapAdapterConfig {
            name: "dlv-dap".to_string(),
            command: "dlv".to_string(),
            args: vec!["dap".to_string()],
            languages: vec!["go".to_string()],
        },
    ],
    ..Default::default()
};

let dap = DapPlugin::new(config);
let agent = Agent::new("go-debugger", "Go debugging assistant")
    .plugin(Box::new(dap))
    .build()?;

// The model can now orchestrate a debugging session:
//
//   1. debug.launch { adapter: "dlv-dap", mode: "test", program: "./pkg/auth" }
//   2. debug.set_breakpoints { path: "pkg/auth/token_test.go", line: 42 }
//   3. debug.continue {}
//   4. debug.variables { scope: "local" }
//   5. debug.stack_trace {}
//   6. debug.step_over {}
//   7. debug.variables { scope: "local" }
//   8. debug.disconnect {}

The model receives structured data for each response: variable names, types, values, and stack frame locations. It can reason about program state and suggest fixes.

Event handling

When the debuggee hits a breakpoint or throws an exception, the plugin emits a dap_stopped signal. Configure automatic inspection so the model receives context without an extra round-trip:

use synwire_dap::config::DapPluginConfig;

let config = DapPluginConfig {
    on_stopped: synwire_dap::config::StoppedBehaviour::AutoInspect {
        // Automatically fetch locals and the top 5 stack frames on every stop.
        include_locals: true,
        stack_depth: 5,
    },
    ..Default::default()
};

Available StoppedBehaviour variants:

Security: debug.evaluate requires approval

debug.evaluate executes arbitrary expressions in the debuggee's runtime. This is marked as RiskLevel::Critical and requires explicit approval through the configured approval gate.

use synwire_agent::vfs::threshold_gate::ThresholdGate;
use synwire_core::vfs::approval::{RiskLevel, AutoDenyCallback};

// Approve up to High risk automatically; debug.evaluate (Critical) still prompts.
let gate = ThresholdGate::new(RiskLevel::High, CliPrompt);

Other DAP tools are classified as follows:

Configuration

DapAdapterConfig fields:

DapPluginConfig fields:

See also

• Explanation: synwire-dap -- design rationale and DAP protocol mapping
• How to: Integrate Language Servers -- LSP plugin for code intelligence
• How to: Configure Approval Gates -- controlling debug.evaluate approval
• How to: Configure Permission Modes -- tool-level allow/deny rules

How to: Configure Language Servers

Goal: Discover, install, and configure language servers for your agent's LSP integration.

Built-in servers

LanguageServerRegistry::default_registry() ships with 23 entries covering the most common languages. The plugin auto-starts whichever server is found on PATH when the model first queries a file of that language.

Languages with two entries (Python, Ruby) use a priority order. The registry tries the first match and falls back to the second if the binary is not found.

Checking availability

Before starting an agent, verify that the servers you need are installed:

use synwire_lsp::registry::LanguageServerRegistry;

let registry = LanguageServerRegistry::default_registry();

// Check a single language.
if let Some(entry) = registry.lookup("rust") {
    match which::which(&entry.command) {
        Ok(path) => println!("rust-analyzer found at {}", path.display()),
        Err(_) => eprintln!("rust-analyzer not found; install with: {}", entry.install_hint),
    }
}

// Check all registered languages and report missing servers.
for entry in registry.all_entries() {
    let available = which::which(&entry.command).is_ok();
    println!(
        "{:<20} {:<30} {}",
        entry.language,
        entry.server_name,
        if available { "OK" } else { "MISSING" }
    );
}

The LspPlugin performs this check lazily at first use. Missing servers produce a structured tool error rather than a panic.

Custom server config via TOML

Define additional servers or override built-in entries in a TOML file:

# lsp-servers.toml

[[servers]]
language = "nix"
server_name = "nil"
command = "nil"
args = []
install_hint = "nix profile install nixpkgs#nil"
extensions = ["nix"]

[[servers]]
language = "rust"
server_name = "rust-analyzer"
command = "rust-analyzer"
args = []
install_hint = "rustup component add rust-analyzer"
extensions = ["rs"]

[servers.initialization_options]
checkOnSave = { command = "clippy" }
cargo = { allFeatures = true }

Load the file into the registry:

use synwire_lsp::registry::LanguageServerRegistry;
use std::path::Path;

let mut registry = LanguageServerRegistry::default_registry();
registry.load_toml(Path::new("lsp-servers.toml"))?;

Entries with the same (language, server_name) pair replace the built-in entry. New language/server pairs are appended.

Custom server config via API

Add entries programmatically when TOML is not convenient:

use synwire_lsp::registry::{LanguageServerRegistry, ServerEntry};

let mut registry = LanguageServerRegistry::default_registry();

registry.register(ServerEntry {
    language: "nix".to_string(),
    server_name: "nil".to_string(),
    command: "nil".to_string(),
    args: vec![],
    extensions: vec!["nix".to_string()],
    install_hint: "nix profile install nixpkgs#nil".to_string(),
    initialization_options: serde_json::Value::Null,
    priority: 0,
});

Lower priority values are tried first. The default entries use priority 0 for the primary server and 10 for alternatives.

Per-language overrides

When multiple servers are registered for the same language, the registry picks the highest-priority (lowest number) server whose binary exists on PATH. Override the selection explicitly:

use synwire_lsp::registry::LanguageServerRegistry;

let mut registry = LanguageServerRegistry::default_registry();

// Prefer pyright over pylsp for Python files.
registry.set_priority("python", "pyright", 0);
registry.set_priority("python", "pylsp", 10);

// Or disable a server entirely.
registry.disable("python", "pylsp");

The disable method removes the entry from consideration without deleting it. Re-enable with registry.enable("python", "pylsp").

To check which server would be selected for a language:

if let Some(entry) = registry.resolve("python") {
    println!("Python will use: {} ({})", entry.server_name, entry.command);
}

resolve checks both priority and binary availability, returning the best candidate.

ServerEntry fields

See also

• How to: Integrate Language Servers -- using LspPlugin with the agent builder
• Explanation: synwire-lsp -- architecture and protocol handling

Migration Guide

Pre-StorageLayout to StorageLayout paths

Before StorageLayout was introduced, Synwire stored data under ad-hoc paths. This guide covers moving existing data to the new layout.

What changed

The new paths include the product name and (for per-worktree data) a WorktreeId key.

Shell migration

The index cache and graph cache are regenerable — they can be deleted and will be rebuilt on next use. Skills are durable and should be migrated.

# Product name to migrate to (must match --product-name you will use)
PRODUCT="synwire"

# Determine your worktree key
WORKTREE_KEY=$(synwire-mcp-server --project . --product-name "$PRODUCT" --print-worktree-key 2>/dev/null || echo "unknown")

# New base paths (Linux/XDG)
DATA_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/$PRODUCT"
CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/$PRODUCT"

# Migrate skills (durable — copy, verify, then remove old)
if [ -d "$HOME/.local/share/synwire/skills" ]; then
    mkdir -p "$DATA_DIR/skills"
    cp -r "$HOME/.local/share/synwire/skills/." "$DATA_DIR/skills/"
    echo "Skills migrated to $DATA_DIR/skills/"
fi

# Index and graph caches are regenerable — safe to move or delete
# Option A: delete (will be rebuilt on next index)
rm -rf "$HOME/.cache/synwire/indices"
rm -rf "$HOME/.cache/synwire/graphs"

# Option B: move (avoids rebuild, but only works if worktree_key is known)
# mkdir -p "$CACHE_DIR/indices"
# mv "$HOME/.cache/synwire/indices" "$CACHE_DIR/indices/$WORKTREE_KEY"

The --print-worktree-key flag is not implemented in v0.1. Use option A (delete) unless you need to preserve index data, in which case build synwire-storage separately to compute the key programmatically.

Programmatic key derivation

#![allow(unused)]
fn main() {
use synwire_storage::{StorageLayout, WorktreeId};
use std::path::Path;

let layout = StorageLayout::new("synwire")?;
let wid = WorktreeId::for_path(Path::new("."))?;

println!("index cache: {}", layout.index_cache(&wid).display());
println!("graph dir:   {}", layout.graph_dir(&wid).display());
}

Run this small program from your project root to get the exact destination paths for your machine.

Config file migration

If you previously used a custom SYNWIRE_CACHE_DIR or SYNWIRE_DATA_DIR environment variable, these still work in v0.1 and take the highest precedence. No changes are needed if you rely on them.

If you used a project-local config at $PROJECT/.synwire/config.json (pre-StorageLayout), rename it to .$PRODUCT/config.json where $PRODUCT is your product name:

# Rename .synwire to .myapp (if using product name 'myapp')
mv .synwire .myapp

See also

• synwire-storage explanation — layout architecture
• synwire-storage — configuration hierarchy

Architecture

Synwire uses a trait-based architecture where each concern is defined by a trait and implementations are swappable at runtime via trait objects.

Trait hierarchy

graph TD
    RunnableCore --> BaseChatModel
    RunnableCore --> Embeddings
    RunnableCore --> VectorStore
    RunnableCore --> Tool
    RunnableCore --> OutputParser
    BaseChatModel --> ChatOpenAI
    BaseChatModel --> ChatOllama
    BaseChatModel --> FakeChatModel
    Embeddings --> OpenAIEmbeddings
    Embeddings --> OllamaEmbeddings
    Embeddings --> FakeEmbeddings
    VectorStore --> InMemoryVectorStore
    Tool --> StructuredTool

Core traits

BaseChatModel

Defines invoke, batch, stream, model_type, and bind_tools. All methods use BoxFuture for dyn-compatibility. The batch and bind_tools methods have default implementations.

RunnableCore

The universal composition primitive. Uses serde_json::Value as the I/O type for object safety and heterogeneous chaining. Heterogeneous chaining in a statically-typed language requires a common I/O boundary; serde_json::Value provides that boundary without sacrificing Send + Sync or object safety.

Embeddings

Simple trait with embed_documents (batch) and embed_query (single text). Some providers use different models for queries versus documents.

VectorStore

Manages document storage and similarity search. Methods accept an &dyn Embeddings to decouple storage from embedding computation.

Tool

Defines name, description, schema, and invoke. Tools are Send + Sync for use across async tasks.

Design principles

Object safety via BoxFuture

Rust traits with async fn methods are not dyn-compatible. Synwire uses manual BoxFuture desugaring:

fn invoke<'a>(
    &'a self,
    input: &'a [Message],
    config: Option<&'a RunnableConfig>,
) -> BoxFuture<'a, Result<ChatResult, SynwireError>>;

This enables Box<dyn BaseChatModel> and &dyn BaseChatModel usage.

serde_json::Value as universal I/O

RunnableCore uses Value rather than generics because:

• Generic trait parameters prevent Vec<Box<dyn RunnableCore>> for heterogeneous chains
• Any runnable can compose with any other without explicit type conversions
• The trade-off (runtime vs compile-time checking) matches the typical use case

Error hierarchy

SynwireError wraps domain-specific error types (ModelError, ToolError, ParseError, etc.) with #[from] conversions. SynwireErrorKind provides discriminant-based matching for retry and fallback logic without inspecting payloads.

Send + Sync everywhere

All traits require Send + Sync because the primary runtime is Tokio with multi-threaded executor. This enables shared ownership via Arc<dyn BaseChatModel> and spawning across task boundaries.

Layered crate architecture

graph BT
    synwire-core --> synwire-orchestrator
    synwire-core --> synwire-checkpoint
    synwire-core --> synwire-llm-openai
    synwire-core --> synwire-llm-ollama
    synwire-checkpoint --> synwire-checkpoint-sqlite
    synwire-core --> synwire
    synwire-core --> synwire-derive
    synwire-core --> synwire-test-utils
    synwire-checkpoint --> synwire-test-utils
    synwire-orchestrator --> synwire-test-utils

synwire-core has zero dependencies on other Synwire crates. Provider crates depend only on synwire-core. The orchestrator depends on synwire-core for trait definitions.

Pregel Execution Model

The synwire-orchestrator crate executes graphs using a Pregel-inspired superstep model.

What is Pregel?

Pregel is Google's model for large-scale graph processing. In Synwire, it is adapted for sequential state machine execution:

1. Superstep: execute the current node's function with the current state
2. Edge resolution: determine the next node (static or conditional)
3. Repeat until __end__ is reached or the recursion limit is exceeded

Execution flow

sequenceDiagram
    participant C as Client
    participant G as CompiledGraph
    participant N as Node Function

    C->>G: invoke(state)
    loop Each superstep
        G->>N: node_fn(state)
        N-->>G: updated state
        G->>G: resolve next node
        alt Reached __end__
            G-->>C: final state
        else Recursion limit
            G-->>C: GraphError::RecursionLimit
        end
    end

State as serde_json::Value

Graph state is a serde_json::Value, typically a JSON object. Each node receives the full state, transforms it, and returns the updated state.

Edge resolution order

1. Conditional edges are checked first. The condition function inspects the state and returns a key, which is looked up in a mapping to find the target node.
2. Static edges are checked next if no conditional edge exists for the current node.
3. If neither exists, GraphError::CompileError is returned.

Recursion limit

The default limit is defined in constants::DEFAULT_RECURSION_LIMIT. Override it per graph:

let compiled = graph.compile()?.with_recursion_limit(50);

This prevents infinite loops from conditional edges that never reach __end__.

Channels and supersteps