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 agent::MockAgentConfig;

pub use agent::AnthropicAgentConfig;

pub use agent::OpenAiAgentConfig;

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::mock::MockConnection;

pub use backends::mock::MockConnectionBuilder;

pub use backends::mock::MockConnectionStrategy;

pub use backends::mock::MockRunners;

pub use backends::mock::ScriptedTurn;

pub use backends::anthropic::AnthropicBackendConfig;

pub use backends::anthropic::AnthropicConnection;

pub use backends::anthropic::AnthropicConnectionStrategy;

pub use backends::anthropic::AnthropicRunners;

pub use backends::openai::OpenAiBackendConfig;

pub use backends::openai::OpenAiConnection;

pub use backends::openai::OpenAiConnectionStrategy;

pub use backends::openai::OpenAiRunners;

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::HookResult;

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.

builtins

The crate-wide built-in tool registry (fs tools, ask_question, finish, call_agent, …) — backend-neutral; every backend registers from here. Formerly backends::gemini::tools (a re-export shim remains there). The crate-wide built-in tool registry — backend-NEUTRAL.

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.

confirm

Pure typed-confirmation challenge gate for destructive tools (native-testable, turn_flow hoisting pattern): single-use random nonce bound to exact tool+args, valid only when typed by the USER. Enforced by app::chat::confirm_guard at the dispatch layer. See src/confirm.rs. Typed-confirmation challenge gate — the pure core of the destructive-action convention, enforced at the DISPATCH layer.

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.

error_codes

The one LHxxxx error-code registry (compile / runtime / tx-revert). The one LHxxxx error-code registry — a single source of truth spanning the three failure families an agent (or a user) hits on this platform:

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.

kv_reduce

Pure Last-Writer-Wins key/value CRDT for SessionRoom shared state (#22): folds a set of decrypted ops into a converged map (order-independent, idempotent, optional TTL). Native-testable. See src/kv_reduce.rs. Last-Writer-Wins key/value CRDT for SessionRoom shared state (GitHub #22).

kv_room

SessionRoom op sealing/opening + deterministic per-room key derivation (#22): AES-256-GCM confidentiality under K_room inside a writer-signed, room-bound signaling_seal envelope. Needs wallet for k256/keccak. Native-testable. See src/kv_room.rs. SessionRoom op sealing + per-room key derivation (GitHub #22).

lessons

Pure lessons-blob merging + prompt-section composition for the agent LESSONS LOOP (native-testable). The browser record_lesson tool, the headless CLI call, and the proxy scheduler worker all fold its output into the system prompt. See src/lessons.rs. Self-recorded agent lessons — the native-testable core of the LESSONS LOOP.

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).

registry

JSON-RPC client for the on-chain registry diamond. JSON-RPC client for LocalharnessRegistry — read AND write.

rustlite

Rust-subset to wasm compiler.

sharedfs_reconcile

Pure, deterministic CONVERGENT reconcile for cross-device shared-folder sync (native-testable). Hoisted out of app::sharedfs_sync so the convergence / symmetry property runs under cargo test. See src/sharedfs_reconcile.rs. Pure, deterministic CONVERGENT reconcile for the cross-device shared-folder sync (crate::app::sharedfs_sync — cfg-gated out of non-browser doc builds, so plain code formatting here, not links).

signaling_seal

Pure signed-envelope layer for on-chain WebRTC signaling blobs — the SDP sealing/sender-authentication core (native-testable; needs wallet for k256). Hoisted out of app::teams_sync so the seal/unseal round-trip and tamper/forgery rejection run under cargo test. See src/signaling_seal.rs. Pure, native-testable envelope layer for on-chain WebRTC signaling blobs (the P2P teams layer’s SDP exchange over SignalingFacet.postSignal).

subdomain

Pure subdomain-name validation (native-testable) — the single source of truth shared by the browser create tools and kept in sync with the on-chain LocalharnessRegistryFacet._isValidName rule. See src/subdomain.rs. Pure subdomain-name validation — the single source of truth for the browser create tools, kept in sync with the on-chain LocalharnessRegistryFacet._isValidName rule. Native-tested (this is why it lives at the crate root, not inside the wasm-only app module).

tempo_tx

Tempo Transaction (tx type 0x76) encoder for native account abstraction. Tempo Transaction encoder (tx type 0x76).

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.

turn_flow

Pure turn-outcome classification for the continuous-execution chat loop (native-testable). Hoisted out of app::chat so its guard tests run under cargo test. See src/turn_flow.rs. Pure turn-outcome classification for the in-tab agent’s continuous-execution loop — native-testable, no DOM, no state, no async.

turn_stage

Pure state machine for the turn-stage micro-pipeline (“paying → thinking → streaming”) shown inside a pending assistant turn (native-testable, same hoisting pattern as turn_flow). See src/turn_stage.rs. Pure state machine for the turn-stage micro-pipeline — the terse “paying → thinking → streaming” line shown inside a PENDING assistant turn (GitHub #19: the $LH-payment → execution transition was opaque; a visitor paid and then stared at an unexplained pause).

types

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

wallet

Secp256k1 keypair, BIP-39 mnemonics, and RLP encoding. In-browser secp256k1 keypair — k256 + sha3 directly.

x402_hook

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