Crate localharness 

localharness — Rust-native, model-agnostic agent SDK

Build production agents with streaming text, custom tools, safety policies, and background triggers — all from a single cargo add, zero external binaries.

Quick start

use localharness::{Agent, GeminiAgentConfig};

let cfg = GeminiAgentConfig::new(std::env::var("GEMINI_API_KEY").unwrap())
    .with_system_instructions("You are a concise code reviewer.");

let agent = Agent::start_gemini(cfg).await?;
let response = agent.chat("What is 2+2?").await?;
println!("{}", response.text().await?);
agent.shutdown().await?;

Layers

Layer	Type	Purpose
1	Agent	High-level facade: connect, chat, shutdown.
2	Conversation / ChatResponse	Stateful session, multi-cursor streams.
3	connections::Connection	Transport abstraction.
aux	Filesystem	What the 6 fs-shaped built-in tools call into; swap the impl to target OPFS, an in-memory FS, etc.

Re-exports

pub use agent::Agent;

pub use agent::AgentConfig;

pub use agent::GeminiAgentConfig;

pub use backends::gemini::decode_transcript_bytes;

pub use backends::gemini::GeminiBackendConfig;

pub use backends::gemini::GeminiConnection;

pub use backends::gemini::GeminiConnectionStrategy;

pub use backends::mcp::McpBridge;

pub use backends::mcp::McpClient;

pub use backends::mcp::McpToolDecl;

pub use connections::Connection;

pub use connections::ConnectionStrategy;

pub use content::Content;

pub use content::Media;

pub use content::MediaKind;

pub use content::Part;

pub use conversation::ChatCursor;

pub use conversation::ChatResponse;

pub use conversation::Conversation;

pub use error::Error;

pub use error::Result;

pub use filesystem::DirEntry;

pub use filesystem::EntryKind;

pub use filesystem::Filesystem;

pub use filesystem::Metadata;

pub use filesystem::SharedFilesystem;

pub use filesystem::WalkEntry;

pub use filesystem::NativeFilesystem;

pub use hooks::HookContext;

pub use hooks::HookRunner;

pub use hooks::OnSessionEndHook;

pub use hooks::OnSessionStartHook;

pub use hooks::OperationContext;

pub use hooks::PostToolCallHook;

pub use hooks::PostTurnHook;

pub use hooks::PreToolCallDecideHook;

pub use hooks::PreTurnHook;

pub use hooks::SessionContext;

pub use hooks::TurnContext;

pub use policy::allow_all;

pub use policy::deny_all;

pub use policy::enforce;

pub use policy::evaluate;

pub use policy::is_path_in_workspace;

pub use policy::secure_normalize_path;

pub use policy::workspace_only;

pub use policy::AskUserHandler;

pub use policy::Decision;

pub use policy::Policy;

pub use policy::Predicate;

pub use tools::ClosureTool;

pub use tools::Tool;

pub use tools::ToolContext;

pub use tools::ToolRunner;

pub use triggers::every;

pub use triggers::Trigger;

pub use triggers::TriggerContext;

pub use triggers::TriggerRunner;

pub use types::BuiltinTool;

pub use types::CapabilitiesConfig;

pub use types::GeminiConfig;

pub use types::GenerationConfig;

pub use types::HookResult;

pub use types::ModelConfig;

pub use types::ModelEntry;

pub use types::Step;

pub use types::StepSource;

pub use types::StepStatus;

pub use types::StepTarget;

pub use types::StepType;

pub use types::StreamChunk;

pub use types::SystemInstructions;

pub use types::ThinkingLevel;

pub use types::ToolCall;

pub use types::ToolResult;

pub use types::TranscriptEntry;

pub use types::TranscriptRole;

pub use types::TriggerDelivery;

pub use types::UsageMetadata;

Modules

agent

Layer-1 agent facade: connect, chat, shutdown. Layer-1 Agent facade.

backends

Backend implementations (Gemini, MCP). Backend implementations of the Connection trait.

compose

Compositor scheduling for host::compose — the deferred-mutation module table (native-testable control flow). See src/compose.rs. Compositor scheduling for host::compose (roadmap Track A / Phase 1a) — the part that is pure control flow, so it lives here and is native-tested, independent of the wasm Instance/Memory it will hold in app::display.

connections

Transport abstraction traits. Transport abstraction.

content

Multimodal input primitives (text, images, documents, audio, video). Multimodal input primitives (text, images, documents, audio, video).

conversation

Stateful conversation session with multi-cursor streaming. Stateful conversation session.

encoding

Pure hex / address / amount encoding helpers (native-testable). Hoisted out of app::events so they run under cargo test. See src/encoding.rs. Pure hex / address / amount encoding helpers — native-testable, no DOM, no state, no async.

error

Typed error hierarchy. Typed error hierarchy for the SDK.

filesystem

Filesystem abstraction for built-in fs tools. Filesystem abstraction for the built-in fs tools.

hooks

Hook traits for observing and gating agent events. Hook traits and the runner that dispatches them.

policy

Declarative tool-execution policy engine. Declarative tool-execution policy engine.

raster

Pure framebuffer rasterization + Viewport (the host::compose geometry foundation; native-testable, used by app::display). See src/raster.rs. Pure, native-testable framebuffer rasterization with a viewport — the geometry foundation for host::compose (roadmap Phase 0a, design/host- compose.md).

rustlite

Rust-subset to wasm compiler.

tools

Custom tool registration and dispatch. Host-side custom tools.

triggers

Background triggers that push messages into the agent. Background triggers — fire-and-forget tasks that push messages into the agent. Each trigger runs in its own tokio task; the runner owns the task handles and aborts them on shutdown.

types

Public boundary types (steps, tool calls, usage, config, etc.). Public boundary types for the SDK.

x402_hook

App-injected x402 payment-signing hook (lets the backend call_agent tool sign payments using the app-layer wallet). App-injected x402 signing hook.