Crate salvor_tools 

Salvor tools: the typed tool-contract layer for the agent runtime.

A tool is a typed, effect-classified operation a model may call. This crate defines what a tool is and how the runtime dispatches one; it declares contracts and performs no IO. Persisting tool-call events and driving the dispatch is the runtime’s job, built on the seam this crate exposes.

The layers

• The typed contract. ToolMeta carries a tool’s identity and Effect; ToolHandler adds its typed Input, Output, and async call. The split is the seam the future #[derive(Tool)] macro cuts: the macro generates ToolMeta, the user writes ToolHandler. See ToolMeta’s docs for the exact contract.
• The tool outcome. ToolHandler::call returns a ToolOutcome: either an Output, or a Suspension that parks the run for a human. Suspension is a return value in v0.1, not a runtime call.
• Type-erased dispatch. DynTool is the Value-in/Value-out, dyn-compatible trait the runtime dispatches through. TypedTool adapts any ToolHandler into a DynTool, validating the model’s JSON against the input type before the handler runs. MCP-backed tools (a later task) implement DynTool directly.
• The registry. ToolSet registers tools by name, looks them up, and enumerates them as ToolDescriptors for a model. Duplicate names are a RegistryError.
• Retry policy. RetryPolicy encodes the per-effect rule for retrying a failed live execution. It classifies; the runtime loop enforces.
• MCP tools. Behind the mcp cargo feature (on by default), the mcp module connects to an MCP server over stdio and surfaces each of its tools as a DynTool, registering alongside native tools. All of the MCP dependency surface (the rmcp SDK, a Tokio runtime) is gated behind that feature, so the contract layer above still builds with --no-default-features. MCP stays isolated to that one module by design: rmcp/MCP protocol churn is a standing risk.

Errors

A tool’s own failure is a HandlerError. The erased layer’s error is a ToolError, whose InvalidInput variant (the model sent malformed arguments, and the handler never ran) is deliberately distinct from Handler (the tool ran and failed), so the runtime loop can route them differently.

Modules

mcp

Model Context Protocol (MCP) integration: connect to an MCP server over stdio (a spawned child process) or streamable HTTP (a remote server by URL), and surface each tool it reports as a DynTool the runtime dispatches through like any native tool.

Structs

HandlerError

The error a ToolHandler returns from its own code.

Suspension

A tool’s request to park the run and wait for a human (or any out-of-band) input before continuing.

ToolCtx

What the runtime hands a tool for one execution attempt.

ToolDescriptor

The metadata a ToolSet exposes for one tool when enumerating tools for a model: everything the model needs to decide whether and how to call it.

ToolSet

A collection of tools keyed by name.

TypedTool

Wraps a typed ToolHandler as a type-erased DynTool.

Enums

Effect

The side-effect classification a tool declares, re-exported from salvor_core so a tool author needs only this crate. Both the hand-written ToolMeta::EFFECT and the Tool derive name it through here. How a tool call may be retried and how it behaves on replay.

RegistryError

The error ToolSet registration returns.

RetryPolicy

Whether and how a failed live tool execution may be retried, as a function of the tool’s Effect.

ToolError

The error the type-erased dispatch layer (DynTool::call_json) returns.

ToolOutcome

The Ok side of a tool call: either the tool’s normal output, or a Suspension.

Traits

DynTool

A tool with its types erased: Value in, Value out, dispatched by name.

ToolHandler

The behavior half of the tool contract: typed input, typed output, and the async call that turns one into the other.

ToolMeta

A tool’s static identity: the name a model calls it by, a human description, and its side-effect Effect class.

Derive Macros

Tool

Derives the ToolMeta impl for a tool struct from #[tool(...)] attributes. See the macro’s own documentation for the attribute keys, the default-name rule, and what it rejects. Derives the ToolMeta half of the tool contract from struct attributes.