Crate harness

Expand description

harness-rs — facade re-exporting the public surface of the harness-rs agent framework.

Most users depend only on this crate. It re-exports harness-core (traits + types), the procedural macros from harness-macros, and exposes harness-skills under the skills module. The lower-level crates remain available individually for anyone who wants a minimal dependency footprint.

§What is a harness?

An agent in this framework is a Model + a harness — the surrounding scaffold that decides what the model can see (Guide), what tools it can call (Tool), what feedback signals come back to it (Sensor), what policies wrap each step (Hook), and how its context is kept small (Compactor). The AgentLoop in harness-rs-loop ties these together in a ReAct loop with self-correction.

See DESIGN.md at the workspace root for the architectural intent.

§Quick start

Define a tool with #[tool], point the model adapter at any OpenAI-compatible endpoint, and run the loop:

use harness::{tool, ToolError};
use harness_loop::AgentLoop;
use harness_models::OpenAiCompat;
use harness_context::default_world;
use harness_core::{Policy, Task};
use std::sync::Arc;

/// Add two integers.
#[tool(name = "add", risk = "Safe")]
async fn add(a: i64, b: i64) -> Result<i64, ToolError> {
    Ok(a + b)
}

let model = OpenAiCompat::with_key(
    "https://api.deepseek.com",
    "deepseek-chat",
    std::env::var("DEEPSEEK_API_KEY")?,
);
let loop_ = AgentLoop::new(model).with_tool(Arc::new(add()));
let mut world = default_world(std::env::current_dir()?);
let outcome = loop_
    .run(
        Task { description: "What is 2 + 3?".into(),
               source: None, deadline: None },
        &mut world,
    )
    .await?;
println!("{outcome:?}");

§Examples

Worked examples live at https://github.com/liliang-cn/harness-rs/tree/main/examples:

deepseek-hello — smallest possible Hello-world.
crate-keeper — MockModel smoke test (no network).
personal-assistant — scheduling agent with UserProfile, REPL, brief mode.
investor-bot — autonomous web research with multi-engine search + retry.

§Crate map

harness_core — Model / Tool / Guide / Sensor / Hook / Compactor / Skill traits, World, Context, Event, error types.
harness_macros — #[skill] / #[tool] / #[guide] / #[sensor] / #[hook] proc-macros.
harness_loop — AgentLoop ReAct executor with auto-fix sensors.
harness_hooks — HookBus over 27 lifecycle events.
harness_blueprint — hybrid deterministic + agent state machine.
harness_compactor — five-stage progressive context compaction.
harness_sandbox — WorktreeSandbox (default) + container/VM stubs.
harness_models — OpenAiCompat / AnthropicNative / MockModel.
harness_mcp — MCP stdio JSON-RPC server.
skills — agentskills.io-compliant skill loader + validator.
harness_tools_fs / harness_tools_shell — built-in toolsets.
harness_sensors_rust / harness_sensors_common — built-in sensors.

Modules§

compactor
context
embed: Optional embeddings trait. Strictly opt-in — nothing in Model, AgentLoop, Hook, Guide, Sensor, or Memory references this. Code that wants semantic search / vector recall holds an Arc<dyn Embedder> explicitly; everything else compiles without ever touching this module.
error
event
guide
hook
memory: Long-term, cross-session memory.
model
prelude
profile: User profile — ambient context every agent inherits.
recall: Cross-session conversation recall.
recall_testkit: Reusable conformance suite for crate::RecallStore backends. Each backend crate calls recall_contract(store) from a #[tokio::test] so all impls are held to identical behaviour — including the privacy-critical owner isolation.
sensor
signal
skill: Skill trait — strictly aligned with the agentskills.io specification.
skills: agentskills.io-compliant skill loading.
tool
world

Structs§

Action: One action the agent has asked to take, paired with the originating tool call.
Budget
CodeSpan
Context: The model-visible state of an in-progress agent run.
DynModel: A concrete newtype wrapping a boxed model, so an Arc<dyn Model> can be used where a concrete M: Model is required (e.g. Subagent::new / AgentLoop<M>).
GuideEntry
HarnessExt: Optional metadata.harness.* sub-tree. Spec-compliant: keys other agents don’t recognise are simply ignored.
HookEntry: inventory slot for compile-time hook registration via #[hook].
MemoryEntry: One persisted memory record.
ModelInfo: Information about a configured model — uniform across providers.
ModelOutput
Policy
ProcessOutput
RecallMessage: One transcript message in a recall session.
RepoView: Runtime view of the filesystem / repo the agent operates on.
Resource: A non-SKILL.md resource bundled with the skill (scripts/*, references/*, assets/*).
SensorEntry
SessionHit: A search hit: the matched session plus enough surrounding messages for the agent to orient (Hermes-style bookends + a window around the anchor).
SessionMeta: Metadata about one session.
Signal: A feedback signal from a sensor — optimised for LLM consumption.
SignalSet: A bundle of signals, with helpers for the agent loop.
SkillEntry: inventory slot for compile-time skill registration via #[skill].
SkillManifest: The frontmatter of a SKILL.md, exactly as specified.
Task
ToolCall
ToolEntry: inventory slot for compile-time tool registration via #[tool].
ToolResult
ToolSchema
Turn: A single conversation turn (assistant or user).
Usage
UserProfile: Ambient information about who the agent is working for.
World: Things the agent and its sensors can do that aren’t covered by a Tool.

Enums§

Block: A single block of content within the assembled prompt.
CompactError
CompactionStage: The 5 progressive compaction stages (DESIGN.md §9 — borrowed from Claude Code).
EmbedError: Failures from an Embedder::embed call. Kept separate from ModelError because the surfaces differ (no thinking, no tools, no streaming) and we don’t want adapters reaching across modules.
Event: All 27 lifecycle events the framework emits (DESIGN.md §10).
Execution: How a control-plane component executes:
FixPatch: A direct patch a sensor can apply without going through the model.
GuideError
GuideScope: What kind of work this guide applies to. Determines when apply runs.
HarnessError
HookOutcome: What a hook tells the runtime to do after firing.
MemoryError
ModelDelta: Streaming delta — incremental output from the model.
ModelError
NotificationKind
RecallError
ResourceKind
ResponseFormat: Constrain the model’s terminal (non-tool-call) reply shape. Default = Free.
SensorError
SessionSource
Severity
SkillError
Stage: When in the change lifecycle a sensor runs (DESIGN.md §3, lifecycle distribution).
StopReason
SubagentStatus: Subagent self-report (Superpowers convention).
ToolError
ToolRisk: Risk class for a tool — drives sandbox / permission decisions.
TurnRole

Constants§

VERSION: Crate version for diagnostic logging.

Traits§

Clock
Compactor
Embedder: Producer of fixed-dimension float vectors for input text. Batched.
EmbedderExt: Convenience: one-shot single-string embed. Default impl wraps embed.
Guide
Hook
KvStore
Memory: The open-memory primitive.
Model
ProcessRunner
RecallStore: Cross-session transcript store. All methods are owner-scoped: a given owner can never see another owner’s sessions.
Sensor
Skill
Tool

Functions§

dot: Plain dot product. With both vectors L2-normalised this equals cosine similarity. Bounded by ±1 in that case; outside that for raw vectors.
iter_macro_guides
iter_macro_hooks: Enumerate every #[hook]-registered hook.
iter_macro_sensors
iter_macro_skills: Enumerate every #[skill]-registered skill (filesystem-loaded skills are separate — see harness-skills for scan_skills_root).
iter_macro_tools
l2_normalize: Mutate v in place to unit length (L2). No-op on zero vector. Callers that want cosine similarity should normalise both query and corpus once, then use dot product.
recall_contract: Run the full contract against a fresh, empty store.

Type Aliases§

GuideId
Result
SensorId
SkillHandler: Optional in-process handler attached to a skill (only #[skill]-generated skills carry one).

Attribute Macros§

guide
hook
sensor
skill
tool

Crate harness

Crate harness Copy item path

§What is a harness?

§Quick start

§Examples

§Crate map

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate harness