Crate loopctl 

A trait-based framework for building agent loops with pluggable LLM clients, tools, and memory.

Module Overview

Foundational Types

• message — Core conversation types: messages, parts, tool results.
• error — Central error enum (LoopError) for all framework operations.
• config — Session configuration (SessionConfig).
• cancel — Cooperative cancellation signal (CancelSignal).

Subsystems

• observer — Lifecycle event observation (LoopObserver, ObserverHost).
• memory — Agent memory trait (LoopMemory) and entry types.
• reflection — Failure reflection and recovery strategies.
• detection — Loop and convergence detection (DetectionManager).
• fallback — Circuit breaker pattern for automatic API model fallback.
• compact — Context management and compaction (threshold detection, pluggable strategies).
• stream — Streaming event types for LLM API responses.
• middleware — Tool dispatch middleware pipeline (timeouts, permissions, output limits).
• tool — Tool trait, registry, and supporting types.
• tool::health — Per-tool health monitoring, circuit breakers, and self-healing routing. Requires tool_health feature.
• mcp — MCP client + server adapters (McpToolProvider adapts foreign MCP servers; McpServerAdapter serves a ToolRegistry over MCP). Requires mcp feature.

API Layer

• api — LLM API client trait (ApiClient) and error types.

Runtime & Capabilities

• capabilities — Capability traits (Observable, Detectable, etc.).
• managers — LoopManagers — the default infrastructure bundle.

Engine

• engine — The core agentic loop (BareLoop) that orchestrates the full agent lifecycle.

Support

• memory::builtin — Reference InMemoryStore implementation.
• hooks — Bidirectional lifecycle control (allow/block/ask before tool use, compaction). Requires hooks feature.
• testing — Test utilities and fixtures. Requires testing feature.

Re-exports

pub use tool::Tool;

Modules

api

API client and error types — interface for LLM provider communication.

cancel

Cooperative cancellation signal for agent loops.

capabilities

Capability traits for the agent loop runtime.

compact

Context management and compaction for agent conversations.

config

Agent session configuration.

contributor

Turn-boundary context injection.

detection

Detection — loop and convergence detection for agent loops.

engine

Engine module — the core agentic loop that ties all components together.

error

Error types for the agent framework.

fallback

Fallback manager — circuit breaker pattern for automatic API model fallback.

hooks

Hook system — bidirectional lifecycle control for agent loops.

managers

Manager bundle — capability traits and runtime infrastructure for agent loops.

mcp

MCP client + server adapters — bridge loopctl and the Model Context Protocol in both directions.

memory

Agent memory trait — interface for agent memory systems.

message

Message types for agent conversations.

middleware

Tool dispatch middleware pipeline.

observer

Typed lifecycle observer for agent loops.

presets

Named runtime profiles for BareLoop.

provider

LLM provider clients.

reflection

Reflection and recovery for failed agent turns.

stream

Streaming event types for LLM API responses.

structured

Structured output — request guaranteed-schema JSON responses from the model.

testing

Testing utilities — mock components and fixture factories for loopctl tests.

tool

Tool trait and registry — the framework-level abstraction for agent tools.

Derive Macros

Tool

Derive loopctl::tool::Tool for a struct.