Types Reference

All public structs, enums, and type aliases. Enums marked #[non_exhaustive] cannot be exhaustively matched outside this crate — always include a _ arm.

Agent Builder — synwire_core::agents::agent_node

Agent<O>

Builder for configuring and constructing a runnable agent. O is the optional structured output type; use () for unstructured text.

#![allow(unused)]
fn main() {
pub struct Agent<O: Serialize + Send + Sync + 'static = ()> { /* private */ }
}

Builder methods (all #[must_use], all return Self):

Agent<O> implements AgentNode.

RunContext

Runtime context made available during agent execution.

#![allow(unused)]
fn main() {
pub struct RunContext {
    pub session_id: Option<String>,
    pub model: String,
    pub retry_count: u32,
    pub cumulative_cost_usd: f64,
    pub metadata: HashMap<String, Value>,
}
}

ModelErrorAction

Recovery action returned by an OnModelErrorCallback. #[non_exhaustive]

Runner — synwire_core::agents::runner

Runner<O>

Drives the agent execution loop. Stateless between runs.

#![allow(unused)]
fn main() {
pub struct Runner<O: Serialize + Send + Sync + 'static = ()> { /* private */ }
}

RunnerConfig

Configuration for a single runner execution.

#![allow(unused)]
fn main() {
pub struct RunnerConfig {
    pub model_override: Option<String>,
    pub session_id: Option<String>,
    pub max_retries: u32,          // default: 3
}
}

StopKind

#![allow(unused)]
fn main() {
pub enum StopKind {
    Graceful,
    Force,
}
}

RunErrorAction

Action taken by the runner when an error occurs. #[non_exhaustive]

Directive System — synwire_core::agents::directive

Directive

Typed effect description returned by agent nodes. Directives describe side effects without executing them, enabling pure unit tests. #[non_exhaustive]

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type")]
#[non_exhaustive]
pub enum Directive { ... }
}

DirectiveResult<S>

Combines a state update with zero or more directives. S must implement synwire_core::State.

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

Constructors:

Errors

AgentError

Top-level error for agent operations. #[non_exhaustive]

ModelError

LLM API error with retryability metadata. #[non_exhaustive]

Methods:

StrategyError

Execution strategy error. #[non_exhaustive]

DirectiveError

Error from DirectiveExecutor. #[non_exhaustive]

FilterDecision

Decision returned by DirectiveFilter::decision. #[non_exhaustive]

FilterChain

Ordered sequence of DirectiveFilter implementations.

VfsError

Backend operation error. #[non_exhaustive]

Streaming — synwire_core::agents::streaming

AgentEvent

Streaming event produced during an agent run. #[non_exhaustive]

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type")]
#[non_exhaustive]
pub enum AgentEvent { ... }
}

Method:

AgentEventStream

#![allow(unused)]
fn main() {
pub type AgentEventStream =
    Pin<Box<dyn Stream<Item = Result<AgentEvent, AgentError>> + Send>>;
}

Type alias for the stream returned by AgentNode::run.

TerminationReason

Why a turn ended. #[non_exhaustive]

TaskEventKind

Lifecycle event for background tasks. #[non_exhaustive]

Session — synwire_core::agents::session

Session

Full snapshot of a conversation, persisted by SessionManager.

#![allow(unused)]
fn main() {
pub struct Session {
    pub metadata: SessionMetadata,
    pub messages: Vec<Value>,
    pub state: Value,
}
}

SessionMetadata

#![allow(unused)]
fn main() {
pub struct SessionMetadata {
    pub id: String,
    pub name: Option<String>,
    pub tags: Vec<String>,
    pub agent_name: String,
    pub created_at: i64,
    pub updated_at: i64,
    pub turn_count: u32,
    pub total_tokens: u64,
}
}

Model and Config — synwire_core::agents

ModelInfo

#![allow(unused)]
fn main() {
pub struct ModelInfo {
    pub id: String,
    pub display_name: String,
    pub description: String,
    pub capabilities: ModelCapabilities,
    pub context_window: u32,
    pub max_output_tokens: u32,
    pub supported_effort_levels: Vec<EffortLevel>,
}
}

ModelCapabilities

#![allow(unused)]
fn main() {
pub struct ModelCapabilities {
    pub tool_calling: bool,
    pub vision: bool,
    pub streaming: bool,
    pub structured_output: bool,
    pub effort_levels: bool,
}
}

EffortLevel

Reasoning effort hint. #[non_exhaustive]

ThinkingConfig

Extended thinking / chain-of-thought configuration. #[non_exhaustive]

Usage

Token usage and cost for a single turn.

#![allow(unused)]
fn main() {
pub struct Usage {
    pub input_tokens: u64,
    pub output_tokens: u64,
    pub cache_read_tokens: u64,
    pub cache_creation_tokens: u64,
    pub cost_usd: f64,
    pub context_utilization_pct: f32,
}
}

context_utilization_pct is in the range 0.0–1.0.

OutputMode

How the agent extracts structured output from the model response. #[non_exhaustive]

SystemPromptConfig

#[non_exhaustive]

PermissionMode

#[non_exhaustive]

PermissionBehavior

#[non_exhaustive]

PermissionRule

Declarative permission rule.

#![allow(unused)]
fn main() {
pub struct PermissionRule {
    pub tool_pattern: String,
    pub behavior: PermissionBehavior,
}
}

tool_pattern is a glob matched against tool names.

SandboxConfig

#![allow(unused)]
fn main() {
pub struct SandboxConfig {
    pub enabled: bool,
    pub network: Option<NetworkConfig>,
    pub filesystem: Option<FilesystemConfig>,
    pub allowed_commands: Option<Vec<String>>,
    pub denied_commands: Vec<String>,
}
}

NetworkConfig

#![allow(unused)]
fn main() {
pub struct NetworkConfig {
    pub enabled: bool,
    pub allowed_domains: Option<Vec<String>>,
    pub denied_domains: Vec<String>,
}
}

allowed_domains = None means all domains are permitted.

FilesystemConfig

#![allow(unused)]
fn main() {
pub struct FilesystemConfig {
    pub allowed_roots: Vec<String>,
    pub denied_paths: Vec<String>,
}
}

Signals — synwire_core::agents::signal

Signal

#![allow(unused)]
fn main() {
pub struct Signal {
    pub kind: SignalKind,
    pub payload: Value,
}
}

Constructor: Signal::new(kind, payload) — both fields are public but the constructor is provided for convenience.

SignalKind

#[non_exhaustive]

SignalRoute

Maps a signal kind (with optional predicate) to an action.

#![allow(unused)]
fn main() {
pub struct SignalRoute {
    pub kind: SignalKind,
    pub predicate: Option<fn(&Signal) -> bool>,
    pub action: Action,
    pub priority: i32,
}
}

The predicate field uses a function pointer (not a closure) so SignalRoute remains Clone + Send + Sync.

Constructors:

Action

Action resulting from signal routing. #[non_exhaustive]

ComposedRouter

Three-tier signal router (strategy > agent > plugin). Within a tier, the route with the highest priority value wins.

#![allow(unused)]
fn main() {
pub struct ComposedRouter { /* private */ }
}

Implements SignalRouter.

Hooks — synwire_core::agents::hooks

HookRegistry

Registry of lifecycle hooks with typed registration and per-hook timeout enforcement. Hooks that exceed their timeout are skipped with a warn! log and treated as HookResult::Continue.

Registration methods:

Hook functions have signature Fn(ContextType) -> BoxFuture<'static, HookResult>.

HookMatcher

Selects which events a hook applies to.

#![allow(unused)]
fn main() {
pub struct HookMatcher {
    pub tool_name_pattern: Option<String>,
    pub timeout: Duration,                  // default: 30 seconds
}
}

tool_name_pattern supports * as a wildcard. None matches all events. timeout is enforced per-hook invocation.

HookResult

#[non_exhaustive]

Plugin System — synwire_core::agents::plugin

PluginStateMap

Type-keyed map for isolated plugin state. Access is via PluginStateKey implementations; plugins cannot read each other's state.

PluginHandle<P>

Zero-sized proof token returned by PluginStateMap::register. Holding a PluginHandle<P> proves that plugin P has been registered. Implements Copy + Clone + Debug.

PluginInput

Context passed to plugin lifecycle hooks.

#![allow(unused)]
fn main() {
pub struct PluginInput {
    pub turn: u32,
    pub message: Option<String>,
}
}

Middleware — synwire_core::agents::middleware

MiddlewareInput

#![allow(unused)]
fn main() {
pub struct MiddlewareInput {
    pub messages: Vec<Value>,
    pub context: Value,
}
}

MiddlewareResult

#[non_exhaustive]

MiddlewareStack

Ordered collection of Middleware implementations.

Execution Strategies — synwire_core::agents::execution_strategy

FsmStateId

Newtype wrapping String for FSM state identifiers. Implements From<&str> + From<String> + Hash + Eq.

ActionId

Newtype wrapping String for action identifiers. Implements From<&str> + From<String> + Hash + Eq.

ClosureGuard

Adapter wrapping Fn(&Value) -> bool as a GuardCondition.

#![allow(unused)]
fn main() {
pub struct ClosureGuard { /* private */ }
}

synwire_agent — Implementations

FsmStrategy

FSM-constrained execution strategy. Actions must be valid transitions from the current state; guard conditions further restrict which transitions fire.

Implements ExecutionStrategy.

FsmStrategyWithRoutes

FsmStrategy bundled with associated signal routes (produced by FsmStrategyBuilder::build).

Fields:

• strategy: FsmStrategy — public for direct state inspection.

Implements ExecutionStrategy.

FsmStrategyBuilder

Builder for FsmStrategyWithRoutes.

FsmTransition

#![allow(unused)]
fn main() {
pub struct FsmTransition {
    pub target: FsmStateId,
    pub guard: Option<Box<dyn GuardCondition>>,
    pub priority: i32,
}
}

DirectStrategy

Executes actions immediately without state constraints. Input is passed through unchanged.

#![allow(unused)]
fn main() {
pub struct DirectStrategy;  // Clone + Default
}

DirectStrategy::new() is equivalent to DirectStrategy::default(). Implements ExecutionStrategy.

InMemorySessionManager

Ephemeral SessionManager backed by a tokio::sync::RwLock<HashMap>. All data is lost when the process exits. See synwire-checkpoint for persistence.

InMemoryStore

In-memory BaseStore backed by RwLock<BTreeMap<String, Vec<u8>>>.

StoreProvider

Wraps a BaseStore and exposes it as Vfs. Keys are paths of the form /<namespace>/<key>. Supports only READ, WRITE, RM.

CompositeProvider

Routes Vfs operations to the backend whose prefix is the longest segment-boundary match. /store matches /store/foo but not /storefront.

#![allow(unused)]
fn main() {
pub struct CompositeProvider { /* private */ }
}

For grep: delegates to the first mount that advertises VfsCapabilities::GREP. For glob: aggregates results from all mounts that advertise VfsCapabilities::GLOB.

Mount

#![allow(unused)]
fn main() {
pub struct Mount {
    pub prefix: String,
    pub backend: Box<dyn Vfs>,
}
}

ThresholdGate

ApprovalCallback that auto-approves operations at or below a RiskLevel threshold and delegates higher-risk operations to an inner callback. Caches AllowAlways decisions for subsequent calls to the same operation.

McpLifecycleManager

Manages multiple named MCP server connections: connects on start, reconnects on disconnect, and supports runtime enable/disable.

Stdio / Http / InProcess MCP Transports

All three implement McpTransport.

SummarisationMiddleware

Detects when conversation history exceeds configured thresholds and marks the context for summarisation. The actual LLM summarisation call is injected by provider crates.

SummarisationThresholds

#![allow(unused)]
fn main() {
pub struct SummarisationThresholds {
    pub max_messages: Option<usize>,
    pub max_tokens: Option<usize>,
    pub max_context_utilisation: Option<f32>,
}
}

Any threshold set to None is not checked. max_context_utilisation is in the range 0.0–1.0.

Backend Types — synwire_core::vfs::types

VfsCapabilities

Bitflags struct. Individual flags:

DirEntry

#![allow(unused)]
fn main() {
pub struct DirEntry {
    pub name: String,
    pub path: String,
    pub is_dir: bool,
    pub size: Option<u64>,
    pub modified: Option<DateTime<Utc>>,
}
}

FileContent

#![allow(unused)]
fn main() {
pub struct FileContent {
    pub content: Vec<u8>,
    pub mime_type: Option<String>,
}
}

WriteResult

#![allow(unused)]
fn main() {
pub struct WriteResult {
    pub path: String,
    pub bytes_written: u64,
}
}

EditResult

#![allow(unused)]
fn main() {
pub struct EditResult {
    pub path: String,
    pub edits_applied: usize,
    pub content_after: Option<String>,
}
}

edits_applied is 0 when the old string was not found; 1 when the first occurrence was replaced.

GrepMatch

#![allow(unused)]
fn main() {
pub struct GrepMatch {
    pub file: String,
    pub line_number: usize,   // 1-indexed; 0 when line_numbers is false
    pub column: usize,        // 0-indexed byte offset of match start
    pub line_content: String,
    pub before: Vec<String>,
    pub after: Vec<String>,
}
}

In GrepOutputMode::Count mode, line_number holds the match count and line_content holds its string representation.

GlobEntry

#![allow(unused)]
fn main() {
pub struct GlobEntry {
    pub path: String,
    pub is_dir: bool,
    pub size: Option<u64>,
}
}

TransferResult

#![allow(unused)]
fn main() {
pub struct TransferResult {
    pub path: String,
    pub bytes_transferred: u64,
}
}

Used by upload, download, cp, and mv_file.

FileInfo

#![allow(unused)]
fn main() {
pub struct FileInfo {
    pub path: String,
    pub size: u64,
    pub is_dir: bool,
    pub is_symlink: bool,
    pub modified: Option<DateTime<Utc>>,
    pub permissions: Option<u32>,    // Unix mode bits
}
}

ExecuteResponse

#![allow(unused)]
fn main() {
pub struct ExecuteResponse {
    pub exit_code: i32,
    pub stdout: String,
    pub stderr: String,
}
}

ProcessInfo

#![allow(unused)]
fn main() {
pub struct ProcessInfo {
    pub pid: u32,
    pub command: String,
    pub cpu_pct: Option<f32>,
    pub mem_bytes: Option<u64>,
    pub parent_pid: Option<u32>,
    pub state: String,
}
}

JobInfo

Background job information.

#![allow(unused)]
fn main() {
pub struct JobInfo {
    pub id: String,
    pub pid: Option<u32>,
    pub command: String,
    pub status: String,
}
}

ArchiveEntry

#![allow(unused)]
fn main() {
pub struct ArchiveEntry {
    pub path: String,
    pub is_dir: bool,
    pub size: u64,             // uncompressed size
}
}

ArchiveInfo

#![allow(unused)]
fn main() {
pub struct ArchiveInfo {
    pub entries: Vec<ArchiveEntry>,
    pub format: String,
    pub compressed_size: u64,
}
}

PipelineStage

One stage in a multi-command pipeline.

#![allow(unused)]
fn main() {
pub struct PipelineStage {
    pub command: String,
    pub args: Vec<String>,
    pub stderr_to_stdout: bool,
    pub timeout_secs: Option<u64>,
}
}

Used by SandboxVfs::execute_pipeline.

GrepOptions — synwire_core::vfs::grep_options

GrepOptions

Ripgrep-style search configuration. All fields have zero-value defaults.

#![allow(unused)]
fn main() {
pub struct GrepOptions {
    pub path: Option<String>,
    pub after_context: u32,
    pub before_context: u32,
    pub context: Option<u32>,     // symmetric; overrides before/after if set
    pub case_insensitive: bool,
    pub glob: Option<String>,
    pub file_type: Option<String>,
    pub max_matches: Option<usize>,
    pub output_mode: GrepOutputMode,
    pub multiline: bool,
    pub line_numbers: bool,
    pub invert: bool,
    pub fixed_string: bool,
}
}

path = None searches from the current working directory. file_type accepts ripgrep-style type names: rust, python, js, typescript, json, yaml, toml, markdown, go, sh.

GrepOutputMode

#[non_exhaustive]

Approval — synwire_core::vfs::approval

ApprovalRequest

#![allow(unused)]
fn main() {
pub struct ApprovalRequest {
    pub operation: String,
    pub description: String,
    pub risk: RiskLevel,
    pub timeout_secs: Option<u64>,
    pub context: Value,
}
}

ApprovalDecision

#[non_exhaustive]

RiskLevel

Ordered (PartialOrd) risk classification. #[non_exhaustive]

AutoApprove / AutoDeny Callbacks

Both implement ApprovalCallback + Clone + Default + Debug.

MemoryProvider

Ephemeral in-memory implementation of Vfs. All data lives for the lifetime of the backend instance. Suitable for agent scratchpads and test fixtures.

Supports: LS, READ, WRITE, EDIT, GREP, GLOB, PWD, CD, RM, CP, MV.

MCP Types — synwire_core::mcp

McpServerConfig

Connection configuration for an MCP server. #[non_exhaustive]

Method: transport_kind() -> &'static str — returns "stdio", "http", "sse", or "in-process".

McpServerStatus

#![allow(unused)]
fn main() {
pub struct McpServerStatus {
    pub name: String,
    pub state: McpConnectionState,
    pub calls_succeeded: u64,
    pub calls_failed: u64,
    pub enabled: bool,
}
}

McpToolDescriptor

#![allow(unused)]
fn main() {
pub struct McpToolDescriptor {
    pub name: String,
    pub description: String,
    pub input_schema: Value,   // JSON Schema
}
}

McpConnectionState

#[non_exhaustive]

ElicitationRequest

#![allow(unused)]
fn main() {
pub struct ElicitationRequest {
    pub request_id: String,
    pub message: String,
    pub response_schema: Value,   // JSON Schema for the expected response
    pub required: bool,
}
}

ElicitationResult

#[non_exhaustive]

CancelAllElicitations

Default OnElicitation implementation. Cancels every request without prompting. Implements Default + Debug.