Crate molo

Expand description

molo — an embeddable Rust agent runtime and harness framework.

The molo crate is the facade over the molo workspace crates. It keeps the ergonomic molo::... import path while the implementation is split into focused crates:

molo-core: message, run, provider, tool, and effect protocols.
molo-agent: agent runtime, memory, channels, and tool registry.
molo-harness: governed effect execution.
molo-coding: coding-workload primitives.
molo-mcp: MCP adapter.
molo-skills: Agent Skills protocol.
molo-openai: OpenAI-compatible provider.

§Feature Flags

The default surface stays lightweight. Enable optional layers explicitly:

openai: OpenAiProvider and OpenAI-compatible HTTP/SSE support.
structured: typed output and JSON Schema validation.
macros: the #[molo::tool] attribute macro; also enables structured.
skills: Agent Skills protocol support.
mcp: MCP client/tool adapter support.
harness: governed effect execution.
coding: coding-workload primitives on top of harness.
cli-channel: stdin/stdout message channel.
tracing: internal tracing spans and logs.
full: all optional capabilities above.

§Quick Start

A minimal agent needs a Provider, memory, and an optional ToolRegistry. The react_agent! macro assembles the default ReAct runtime while keeping the familiar molo::... path:

use molo::{react_agent, Agent, FakeProvider, FakeReply};

let mut agent = react_agent!(
    FakeProvider::new([FakeReply::Text("Hello".into())]),
    "You are a helpful assistant",
);

let answer = agent.run("Are you there?").await?;
assert_eq!(answer, "Hello");

Applications can keep using the facade crate, or depend on focused crates such as molo-core, molo-agent, and molo-harness when they need a smaller dependency surface.

Modules§

agent: Agent runtime facade.
coding: Coding-workload primitives facade.
effect: Effect protocol facade.
event_channel: Event channel facade.
harness: Harness runtime facade.
mcp: MCP adapter facade.
memory: Memory facade.
message: Message model facade.
message_channel: Message channel facade.
observability: Observability facade.
provider: Provider facade.
run: Run protocol facade.
skill: Agent Skills facade.
tool: Tool protocol and registry facade.

Macros§

react_agent: Convenience assembly macro: registers a list of tools (possibly heterogeneous) with automatic boxing, creating a ToolRegistry internally. The system prompt is optional (omitted = no system prompt). Six arms:

Structs§

AgentChangeTracker: Tracks files changed by the agent layer.
AgentConfig: Optional behavior configuration for an Agent.
AgentEventRecord: Serializable, redacted event record for out-of-process observers.
AllowedTool: Tool dependencies declared by a skill: tool name + optional scope (execution belongs to the application layer; this struct only parses and matches).
AlwaysAllowApprovalBroker: Approval broker that always allows requests.
AlwaysDenyApprovalBroker: Approval broker that always denies requests.
ApplyPatchPayload: Typed payload for applying a structured patch.
ApplyPatchTool: Model-visible adapter that requests a governed structured patch.
ApprovalRequest: Approval request passed to an ApprovalBroker.
Artifact: A handle to an artifact produced by a run.
BasicHarness: Minimal in-process harness implementation.
BroadcastChannel: A one-to-many broadcast channel: messages are broadcast to all subscribers (BroadcastChannel::subscribe).
BroadcastEventChannel: A broadcast event channel: multiple subscribers, each consuming independently; slow subscribers drop the oldest.
BroadcastReceiver: The receive end of a broadcast channel: one per subscriber, each consuming independently.
Budget: Window budget: token and round limits (both optional; when both are set, the smaller window wins).
CancellationToken: A token which can be used to signal a cancellation request to one or more tasks.
CharTokenCounter: Default counter: CJK characters count as 1 token each, other characters count as 1 token per 4 characters (rounded up).
ChatRequest: A single conversation request.
ChatResponse: The reply to one conversation.
ClassifiedEffect: Classified effect request.
CliGitInspector: Git inspector implemented by invoking read-only git commands.
CliMessageChannel: A command-line message channel: prints messages to the terminal and reads one line from stdin as the reply.
CodingContextBundle: Context bundle returned by a CodingContextProvider.
CodingContextInclude: Flags controlling which context sources are gathered.
CodingContextRequest: Coding context request.
CodingEffectExecutor: Effect executor that routes typed coding payloads to coding primitives.
CodingExecutorConfig: Configuration for CodingEffectExecutor.
CodingPolicyEngine: Conservative coding policy wrapper around a host policy engine.
CodingPolicyInput: Typed input produced for coding policy evaluation.
CommandExecutorCapabilities: Executor capability report.
CommandExecutorIdentity: Executor identity included in capability and execution reports.
CommandOutput: Command output.
CommandOutputLimit: Per-stream output limit.
CommandPattern: Prefix pattern used by CommandTaxonomy allowlists.
CommandPayload: Typed payload for command execution.
CommandRequest: Command execution request.
CommandTaxonomy: Command taxonomy and host-provided allowlists for coding policy.
CommandTestRunner: Test runner backed by a CommandExecutor.
ContentDigest: Stable content digest used in file version preconditions.
ContextBudget: Context budget for repository context gathering.
DefaultCodingContextProvider: Baseline context provider that combines workspace, search, git, and instruction primitives.
DefaultInstructionResolver: Default resolver that searches for AGENTS.md-style files from root to target parent directories.
DefaultPolicyEngine: Risk-based default policy.
DefaultRiskClassifier: Conservative default risk classifier.
DependencyMetadata: Dependency manifest metadata discovered by context gathering.
DiffRequest: Request to diff two snapshots.
DisplayOutput: Output intended for host/UI display.
EffectObservation: Observation returned to an agent after an effect request is governed and executed by an outer harness.
EffectOutput: Output produced by an executed effect.
EffectRequest: Request for an outer harness to govern and execute a side effect.
EffectSource: Source tool call that produced an effect request.
EventChannelStats: Diagnostic counters for best-effort event channels.
ExecutionPolicy: Execution policy passed to an EffectExecutor.
ExecutionPolicySummary: Serializable summary of an execution policy.
FakeProvider: A programmable fake Provider — a script is a sequence of per-turn replies, consumed in order by chat / stream_chat.
FileContent: File content returned by a workspace read.
FilePatch: Patch for one file.
FileReadOptions: Options for workspace file reads.
FileVersion: File version used to detect stale writes and patch conflicts.
FileWriteResult: Result of a successful workspace write.
GitChangedFile: Changed git file.
GitChangedFilesRequest: Changed-files request.
GitDiffRequest: Git diff request.
GitHead: Current git head.
GitPayload: Typed payload for read-only git inspection.
GitStatus: Parsed git status.
GitStatusRequest: Git status request.
GitStatusTool: Model-visible adapter that requests read-only git status.
HarnessConfig: Harness configuration.
HarnessRuntime: Outer runtime that drives an AgentKernel with a Provider and governed Harness.
HarnessRuntimeConfig: Runtime loop configuration.
ImageContent: Raw image data carried in a ContentBlock::Image.
InMemoryMemory: In-memory implementation: stores all messages verbatim.
IncomingMessage: A message received from the channel: the text content, plus a reply slot that only questions have.
InstructionBundle: Resolved project instructions.
InstructionFile: One resolved instruction file.
InstructionFileSpec: Instruction file candidate.
InstructionRequest: Instruction resolution request.
LimitedOutput: Output after limiting and redaction.
ListFilesPayload: Typed payload for listing workspace files.
ListFilesQuery: Query for deterministic workspace listing.
ListFilesTool: Model-visible adapter that requests a governed workspace listing.
LoadSkillReferenceTool: Tool that loads text references for already active skills.
LoadSkillTool: Skill loading tool: reads the SKILL.md body by name; the second step of progressive disclosure.
LocalCommandExecutor: Local non-PTY, one-shot command executor backed by host process spawning.
LocalWorkspace: Local filesystem implementation of Workspace.
LocalWorkspaceConfig: Local filesystem workspace configuration.
McpCacheHint: Cache hint for an MCP tool catalog.
McpCallPayload: Payload carried inside an EffectKind::Mcp request.
McpClient: MCP client adapter: connects to an MCP server and converts its tools into molo tools.
McpDirectTool: Direct adapter tool produced by McpClient::tools: implements molo’s Tool trait and proxies calls to the MCP server.
McpEffectExecutor: Effect executor for EffectKind::Mcp requests.
McpEffectTool: MCP tool wrapper for harness-governed execution.
McpPermissionBridge: MCP permission bridge usable as a harness PolicyEngine.
McpServerId: Stable host-assigned MCP server id.
McpServerPolicy: Policy for one MCP server.
McpToolCallOutput: Output returned by a host-owned MCP client provider.
McpToolCatalog: Snapshot of a server’s MCP tool catalog.
McpToolDescriptor: Description of one MCP tool discovered from a server.
McpToolId: MCP tool id scoped to one server.
MissingTools: Tool names in a ToolRegistry::subset allowlist that do not exist in the main registry.
ModelObservation: Successful provider response observed by a step-wise agent kernel.
ModelOptions: Model options for one conversation.
ModelRequest: Provider request emitted by a step-wise agent kernel.
ModelSummary: Summary of a model observation.
MpscChannel: A one-to-one dialogue channel between two Agents (or a program and a human).
MpscEventChannel: A single-queue event channel: one subscriber, strictly ordered and lossless within capacity, dropping new events when full.
NoopAuditSink: Explicit opt-out audit sink.
NoopEffectExecutor: Executor that refuses every effect without performing side effects.
NoopRedactor: Redactor that leaves output unchanged.
NoopTranscriptStore: Transcript store that drops all records.
OpenAiProvider: Provider implementation for OpenAI-compatible APIs.
OutputLimit: Output size limits.
OutputText: Text output with truncation metadata.
Patch: Structured patch containing one or more file patches.
PatchConflict: Patch conflict with model-safe details.
PatchHunk: Text hunk used by the local workspace patch applier.
PatchRequest: Request to apply or dry-run a patch.
PatchResult: Result from applying or dry-running a patch.
PatternRedactor: Secret-pattern redactor for examples and tests.
PolicyEnforcementReport: Report describing which policies were enforced by the command executor.
ProviderCapabilities: Provider capability metadata used by hosts and conformance tests.
ProviderRequestContext: Request-scoped provider context.
RawEffectOutput: Raw executor output before limiter/redactor processing.
ReActAgent: The classic ReAct reasoning loop: conversation → tool execution fed back → until the model answers directly.
ReActAgentBuilder: Builder for assembling a ReActAgent from the same components used by ReActAgent::new, plus optional runtime configuration.
ReadFilePayload: Typed payload for reading a workspace file.
ReadFileTool: Model-visible adapter that requests a governed workspace file read.
RedactedText: Redacted text and metadata.
RedactionRecord: A redaction that was applied to an exported record or text field.
RepoSearchRequest: Repository search request.
RepoSearchResults: Repository search results.
ResolvedPath: Resolved workspace path with canonicalization metadata.
RetryPolicy: Retry policy (with defaults; Default is “exponential backoff + jitter, 3 attempts”).
RetryProvider: Retry wrapper: implements Provider and retries inner failures per RetryPolicy.
RipgrepSearcher: Repository searcher that invokes rg through a CommandExecutor.
RouterEffectExecutor: Executor that dispatches by EffectKind.
RunCommandTool: Model-visible adapter that requests governed command execution.
RunContext: Execution controls and host-owned metadata for one run.
RunOutput: Structured result of one non-streaming run.
RunRequest: Input and model parameters for one run.
RunSummary: Execution summary for one run.
SearchMatch: One repository search match.
SearchPayload: Typed payload for repository search.
SearchRepoTool: Model-visible adapter that requests governed repository search.
SharedState: Shared state: a heterogeneous container accessed by type.
Skill: A parsed SKILL.md (a data packet, immutable; Clone copies by value).
SkillActivationState: Session activation state for a skill layer.
SkillLayer: Optional Agent Skills extension layer.
SkillLayerAssembly: Assembled output of a SkillLayer.
SkillLayerConfig: Configuration for SkillLayer assembly.
SkillLayerManifest: Skill layer manifest for transcript/debug use.
SkillRegistry: Skill registry: holds a collection of skills, responsible for lookup and disclosure by name.
SkillResourceStore: Skill resource loading limits.
SnapshotRequest: Request for a lightweight workspace snapshot.
StaticApprovalBroker: Static approval broker configured with a single decision.
StaticEffectExecutor: Test executor that returns preconfigured outputs by effect id.
StructuredValidator: Structured output validator: schema validation of the model’s answer + independent retry budget + feedback messages.
SummarizeStrategy: Summarization trim strategy: over-budget old messages → summarizer → one System summary message.
TestRunRequest: Test run request.
ToolCall: A tool call requested by the model.
ToolContext: Context passed to a tool call.
ToolNamespace: Namespace assigned to a tool by the host application or extension layer.
ToolOutput: Model-visible output produced by a tool.
ToolPolicy: Tool policy metadata declared by the tool author.
ToolRegistry: Tool registry: holds tools, responsible for lookup and dispatch by name.
ToolSchema: The definition of a tool.
ToolSource: Host-facing metadata describing where a provider-visible tool came from.
TrimResult: Output of a trim strategy: the trimmed message sequence + how the result is handled.
TypedRunOutput: Typed-output result paired with the raw structured run output.
Usage: Token usage for one conversation.
VecAuditSink: In-memory audit sink useful for tests.
VecTranscriptStore: In-memory transcript store useful for tests.
VerificationResult: Structured verification result.
WatchChannel: Observes changes of the latest state value: holds and updates one value, and all observers (WatchChannel::subscribe) are notified when it changes.
WatchReceiver: The receive end of a watch channel: observes value changes.
WindowDrop: Default trim strategy: drops the earliest complete rounds until the remaining sequence fits the budget.
WindowMemory: Window memory: stores all messages; context() trims to the budget on retrieval.
WorkspaceDiff: Workspace diff summary.
WorkspaceEntry: Workspace entry returned by listing.
WorkspacePath: A root-relative path validated for workspace operations.
WorkspaceRoot: Canonical root directory that bounds workspace filesystem access.
WorkspaceSearcher: In-process fallback searcher based on Workspace reads.
WriteFilePayload: Typed payload for writing a workspace file.
WriteFileRequest: Request to write a workspace file.

Enums§

AgentAction: Next action requested by a step-wise agent kernel.
AgentActionSummary: Summary of an agent action for transcript records.
AgentError: Reasons an Agent run can fail.
ApprovalDecision: Approval decision.
ApprovalError: Approval errors.
AuditError: Audit errors.
AuditEvent: Reliable effect-governance audit event.
Backoff: Backoff strategy: how long to wait after each failure before the next attempt.
ChannelError: The reason a message channel failed.
CodingContextError: Coding context errors.
CodingError: Errors returned by typed coding payload adapters and executor routing.
CodingPolicyClass: Coding-specific operation class used by conservative policy presets.
CommandError: Command execution errors.
CommandExecutorBackend: Command executor backend family.
CommandStatus: Terminal command status.
ContentBlock: A content block within a message.
DisplayFormat: Display output format.
EffectKind: Kind of side effect requested by an agent.
EffectStatus: Terminal status of an executed effect.
EnvPolicy: Environment variable handling for command execution.
EventSeverity: Severity for a serializable agent event record.
ExecutionError: Executor errors.
FakeReply: One turn of reply from the script.
FileBody: File body with text and binary separated explicitly.
FileWriteContent: Content to write into a workspace file.
FinishReason: Why the model ended its reply.
GitError: Git inspection errors.
GitOperation: Read-only git operation for typed git effects.
HarnessError: Errors returned by a harness.
HarnessRuntimeError: Errors returned by HarnessRuntime.
InstructionError: Instruction resolver errors.
McpError: Assembly-time errors (connect / list tools); call-time errors go through ToolError::Execution.
McpToolMode: MCP tool execution mode.
MemoryError: Context access failed.
Message: A single message in a conversation.
MessageChunk: Message chunks for a streaming run — the streaming output of one run, sliced into pieces.
NetworkPolicy: Network access policy requested of an executor.
Observation: Observation fed back to a step-wise agent kernel.
PatchOperation: File patch operation.
PolicyCapabilityMode: How strictly policy/capability mismatches are handled.
PolicyDecision: Policy decision for a classified effect.
PolicyEnforcementStatus: Structured enforcement status for a policy dimension.
ProviderError: Why a Provider call failed.
PtyMode: PTY mode requested for a command.
ReActEvent: A single event from ReActAgent (application level; the event name is provided per variant via AgentEvent::name).
RegistryError: Reasons a tool execution fails (registry level, defined by the framework).
ResolvedPathKind: Filesystem kind observed when resolving a workspace path.
Retryable: Retry judgment: which errors are worth retrying.
RiskLevel: Request-declared risk level.
SandboxPolicy: Filesystem/process sandbox policy requested of an executor.
SearchError: Search errors.
SearchMode: Repository search mode.
SideEffectLevel: Declared side-effect level for a tool.
SkillError: Reasons a skill parse / load fails.
SkillMode: Skill assembly mode.
SkillSourceTrust: Trust assigned by the host to skill packages.
StreamEvent: An event in a streamed conversation reply.
StructuredOutcome: The outcome of a single validation (StructuredValidator::validate return value).
StructuredOutputMode: Transport shape for structured output (an OpenAiProvider construction setting): decides how response_format is sent.
SymlinkPolicy: Symlink behavior for local workspace operations.
TestRunError: Test run errors.
TextEncoding: Encoding of text file content.
ToolError: Reasons a tool call fails.
ToolMemoryPolicy: Memory handling policy for model-visible tool/effect output.
ToolNamespaceKind: Kind of tool namespace.
ToolResult: Result of a tool call.
ToolTrustLevel: Trust level assigned to a tool source.
TranscriptError: Transcript errors.
TranscriptRecord: Transcript record for run replay and debugging.
UserInput: User input accepted by a run.
WorkspaceAccess: Requested workspace access mode.
WorkspaceError: Workspace operation errors.

Traits§

Agent: Reasoning-loop interface: one run takes the user input, drives the reasoning loop, and returns the final answer.
AgentEvent: Application-level event abstraction.
AgentKernel: Step-wise agent kernel boundary.
ApprovalBroker: Broker that obtains approval from an application-specific authority.
AuditSink: Reliable audit sink.
CodingContextProvider: Provides repository context outside chat memory.
CommandExecutor: Executes approved command requests.
EffectExecutor: Executes an already approved effect.
EventChannel: The observation channel abstraction: the Agent publishes events internally, and the environment side subscribes.
EventReceiver: The unified receive-end interface: the environment side takes subscribed events out one by one.
GitInspector: Read-only git inspector.
Harness: Governs and executes one or more effect requests.
InstructionResolver: Resolves project instruction files.
McpClientProvider: Host-owned MCP client provider used by McpEffectExecutor.
Memory: Manages the agent’s context: decides which messages the model sees on each turn.
MessageChannel: Sends a question to the outside world and waits for a reply, or sends a one-way notification.
PolicyEngine: Evaluates host policy for a classified effect.
Provider: The interface for chatting with an LLM.
Redactor: Redacts executor output before model/audit/transcript use.
RepoSearcher: Search implementation for repositories.
TestRunner: Convenience adapter for test commands.
TokenCounter: Counts the token number of a text.
Tool: A tool an agent can invoke.
TranscriptStore: Transcript store for resumable run traces.
TrimStrategy: Trim strategy: decides “how to trim” — window dropping, summarization, LLM compaction, etc. Users can inject custom implementations.
TypedAgent: Optional capability: typed output (opt-in — implementations that don’t need it don’t implement it; the method doesn’t even exist at compile time).
Workspace: Workspace abstraction for coding workloads.

Type Aliases§

RunMetadata: Request, context, or output metadata for one run.

Attribute Macros§

async_trait
tool: Compiles an async function into a molo::tool::Tool implementation.

Crate molo

Crate molo Copy item path

§Feature Flags

§Quick Start

Modules§

Macros§

Structs§

Enums§

Traits§

Type Aliases§

Attribute Macros§

Crate molo