Sync
Filesystem sync in AgentFS — sync state machines, conflict markers, and reconciliation across registered agent contexts.
Purpose
Local agent filesystem with contexts, registry, permissions, metadata hooks, sync, watchers, and atomic writes.
This page follows the real source shape for Agentfs and explains the workflow a developer is likely to use first.
Developer workflow
Start from the smallest constructor or builder, perform one meaningful operation, inspect the returned state, then add the relevant policy, storage, or network integration. The examples below should be expanded whenever the crate API changes.
Sync conflicts produce explicit conflict markers — they are never resolved silently. Applications must read the conflict, choose a winner (or merge), and acknowledge resolution before further writes proceed on the affected path.
Primary types to know
AgentContext— local/agentfs/src/agent.rsAgentContext— local/agentfs/src/agent_refactored.rsAgentFS— local/agentfs/src/fs.rsAgentFS— local/agentfs/src/fs_refactored.rsAgentFSConfig— local/agentfs/src/config.rsAgentPermission— local/agentfs/src/permissions.rsAgentPermission— local/agentfs/src/permissions_refactored.rsAgentRegistry— local/agentfs/src/agent.rsAgentRegistry— local/agentfs/src/agent_refactored.rsConflictInfo— local/agentfs/src/sync_refactored.rsFsckReport— local/agentfs/src/fs.rsFsMetrics— local/agentfs/src/fs.rs
Example shape
use agentfs::{SyncDirection, SyncManager, SyncOptions};
use agentfs::sync::ConflictStrategy;
use std::sync::Arc;
use weave_identity::{Ed25519Adapter, Identity};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let adapter: Arc<dyn weave_identity::WeaveIdentityAdapter> = Arc::new(Ed25519Adapter::new());
let agent = Identity::agent_from_public_key(vec![0u8; 32], Some("sync-bot"))?;
// SyncManager tracks per-path state and runs Push/Pull/Bidirectional passes.
let manager = SyncManager::new(agent, adapter);
let options = SyncOptions {
direction: SyncDirection::Bidirectional,
include_patterns: vec!["**/*.md".into(), "**/*.json".into()],
exclude_patterns: vec!["**/.cache/**".into()],
conflict_strategy: ConflictStrategy::PreferNewer,
dry_run: true,
};
// The first sync seeds the status table even in dry_run mode.
manager
.sync(std::path::Path::new("/tmp/agentfs-local"), std::path::Path::new("/tmp/agentfs-remote"), options)
.await?;
let statuses = manager.list_statuses().await;
println!("dry-run sync produced {} status rows", statuses.len());
Ok(())
}