Rig v0.41.0 released!

[gold-silver-copper]

43 PRs merged since 0.40. THANK YOU to everyone who contributed, tested, reported issues, and provided feedback on the API changes 🫡

The highlights of 0.41 are as follows: Rig's monolithic core is now split into a portable contracts crate and a runtime crate behind the rig facade. Truly local inference via rig-candle. Tool execution and hooks collapsed from several parallel APIs into one. AgentRunner became the single execution path. Browser WASM is a supported target with a documented matrix, and sensitive telemetry content is opt-in rather than absent.

This is a big release for architecture, so We wrote a full migration guide for it — MIGRATING.md — covering 0.38 through 0.41. We will start providing a full migration guide for each release going forward.

The Crate Split

The most important change of 0.41 is the split of the monolithic core into two crates presented behind the rig facade (#2197).

• rig-core — portable, runtime-independent contracts: provider and model clients, canonical messages and completion values, streaming values, portable tool contracts, memory and vector-store traits, telemetry, and WASM support.
• rig-agent — the classic agent runtime: the builder, run state machine, typed hooks, contextual tools, memory orchestration, extraction, and the blocking and streaming drivers.
• rig — the facade you depend on, re-exporting both at their familiar rig::… paths.

If you depend on the rig facade, you need essentially no source changes. rig::… paths, rig::prelude::*, and rig::tool::{Tool, ToolContext} all keep working. The split matters if you depended on rig-core directly: it is portable-only now, so agent construction moved to rig-agent.

The portable, context-free tool contract is now named PortableTool, freeing rig::tool::Tool to unambiguously mean the classic contextual trait. And provider clients no longer carry inherent agent() / extractor() methods (#2205): there is one canonical CompletionClient in rig-core providing completion_model, with the classic constructors on a new AgentClientExt. use rig::prelude::*; brings both into scope, so the pre-split client surface is still one import. Portable items are reached through the explicit rig_agent::core namespace.

Local Inference with rig-candle

rig-candle is a Candle-backed local inference runtime supporting Llama, SmolLM2, and Qwen3, shipping with a browser WASM chat example (#2155, #2214). This is a very exciting addition, because it unlocks truly local inference for Rig. Other local model providers such as Ollama require the user to run a local server which... serves... the model. This is acceptable and even preferred for many use cases, but less than ideal or even untenable for others. Candle allows users to embed model weights directly into their application, no server required, and it even works in your browser through WASM!

The current state of rig-candle is experimental, but we are very excited about the possibilities that it unlocks, and look forward to developing it further. Candle supports a number of interesting model types beyond LLMs and Image Generation models, and we hope to support them too!

Browser WASM

The WASM support matrix is now explicit and true (#2213):

• wasm32-unknown-unknown (browser) is supported, with no feature flags at all. Every wasm feature flag in the workspace is gone — building for the target is the entire opt-in. Drop features = ["wasm"] from your dependency lines; nothing replaces it.
• WASI is not supported. Not "untested" — its dependency graph has never built, and the docs now say so with the reason.

Telemetry

Sensitive span content is opt-in rather than simply absent (#2151). 0.40 stopped recording GenAI input and output messages to avoid accidental content disclosure; 0.41 gives that an explicit switch for the people who need it.

The completion-parent contract also has a single declarative source (#2115, #2208). This fixes a genuinely nasty failure mode: tracing bakes a span's field set into static metadata and Span::record silently no-ops on undeclared fields, so a hand-mirrored field list that dropped one field lost that telemetry with no error — and the contract had been duplicated in six places. The new completion_parent_span! macro declares the marker and every required gen_ai.* field in one place, exact-set tests pin it so the lists cannot drift, and a parent carrying the marker but missing a field now emits a warn! naming what is missing instead of degrading silently.

One Tool Path, One Hook Vocabulary

0.40 introduced structured tool results. 0.41 removes the parallel APIs that had grown around them (#2132).

Typed tools now implement exactly one method: Tool::call(&mut ToolContext, Args) -> Result<Output, Error>. Author-facing errors stay typed for ordinary ? propagation until private runtime erasure normalizes them into ToolExecutionError. classify_error, call_with_extensions, and call_structured are gone. ToolCallExtensions and ToolResultExtensions collapse into a single ToolContext that carries inbound values and host-only result metadata, snapshotted once per dispatch.

Dispatch consolidated too: ToolSet::execute and ToolServerHandle::execute replace the three-way call / call_with_extensions / call_structured split on each. ToolDyn left the public API in favor of DynamicTool, and ToolSet is now the single ordered registry — its get_tool_definitions and documents are synchronous and infallible, and registration no longer returns an artificial Result.

Serializable outputs convert once into canonical ToolOutput content blocks: strings stay literal text, explicit serde_json::Value stays JSON, and multimodal tools return typed ToolResultContent. MCP responses preserve ordered text and image content, retain unsupported and future blocks as typed JSON, and attach the raw CallToolResult and structuredContent to ToolContext.

Hooks moved in the same direction. AgentHook::on_event, StepEvent, and the single Flow enum are replaced by event-specific methods with their own action types — CompletionCallAction, ToolCallAction, ToolResultAction, InvalidToolCallAction, ObservationAction — which makes invalid event/action combinations unrepresentable rather than a runtime failure.

Hooks are also provider-independent now (#2176). AgentHook and HookStack no longer carry a completion-model type parameter, and CompletionResponseEvent / StreamResponseFinish expose canonical Rig content, usage, prompt, and message IDs instead of typed provider responses:

// Before
impl<M: CompletionModel> AgentHook<M> for TelemetryHook { /* ... */ }

// After
impl AgentHook for TelemetryHook { /* ... */ }

Passive RAG now runs on that same lifecycle. AgentBuilder::dynamic_context and ExtractorBuilder::dynamic_context are unchanged at the call site, but they are backed by a hook rather than a separate retrieval pipeline inside request construction (#2219). Query selection, sample forwarding, document formatting, ordering, and failure-before-I/O all behave as before. Two consequences follow from it being an ordinary hook: register a stop policy before dynamic_context if it should be able to suppress retrieval, and multiple registrations run sequentially through HookStack rather than concurrently. Anything beyond the built-in behavior — filtering, reranking, caching, per-turn policy — is your own AgentHook.

New in 0.41: response retry hooks (#2182), so retry policy is expressible in the same vocabulary as everything else.

AgentRunner Is the Only Execution Path

Configured agents now execute through one path (#2161). The raw Completion and StreamingCompletion traits and their Agent implementations are removed, agent execution state is private, and Extractor routes through the full hook lifecycle like everything else.

// Before
agent.completion(prompt, history).await?.send().await?;

// After — pick a turn budget large enough for tool follow-ups
agent.runner(prompt).history(history).max_turns(3).run().await?;

The reason is that the old raw path silently bypassed hooks, so whether your guardrails ran depended on which method you happened to call. Hook-free transport is still available — deliberately and explicitly — by starting from model.completion_request(prompt) on the provider CompletionModel.

Derive Macros

#[rig_tool] required-ness is now derived from the parameter types, and the advertised schema always agrees with the deserializer (#2207). Previously a parameter left out of an explicit required(...) was advertised as optional while the generated deserializer still demanded it — failing at runtime whenever the model legitimately omitted it.

Now, without an explicit required(...), non-Option parameters are required and Option<T> parameters are optional. Several silent failures became compile errors: listing an Option<T> in required(...), naming a parameter that does not exist, malformed or duplicate attribute entries, and a field carrying two embed_with attributes where the first previously won silently.

Dependency hygiene improved as well. Macro-generated code resolves serde, serde_json, and schemars through rig-core's re-exports, so crates using #[rig_tool] or #[derive(Embed)] no longer need direct serde / serde_json dependencies. Embed emits fully qualified impls and no longer needs the trait imported at the call site. Generated parameters() builds its schema once via LazyLock and contains no expect, so downstream crates denying clippy::expect_used are unaffected.

Providers

Doubleword joins as a new provider with cassette coverage from day one (#2163).

OpenAI gained support for GPT-5.6 models and reasoning controls (#2106) and now exposes complete Responses reasoning metadata (#2112).

0.40 consolidated the OpenAI-compatible completion models onto one shared engine. 0.41 does the same for embeddings (#2157). Together, OpenRouter, and Mistral embeddings now run on a shared generic transport behind an explicit OpenAIEmbeddingsCompatible capability that carries each provider's real policy — endpoint selection, supported fields, usage requirements, and dimension spelling — instead of every provider hand-mutating a serde_json::Value. That policy is specific where the APIs are: Together rejects inherited encoding_format / user fields, OpenRouter serves /api/v1/embeddings, and Mistral emits output_dimension only for the Codestral embed models, capped at the documented 3072. Base64 response encoding is now rejected consistently before the HTTP call across OpenAI, OpenRouter, Together, Mistral, and Llamafile, since the shared response parser reads numeric vectors.

Provider correctness fixes worth calling out:

• Ollama sends max_tokens as options.num_predict in native requests (#2185). The native /api/chat API has no top-level max_tokens, so the value was being discarded — if you set it previously and saw no effect, it starts applying now.
• Anthropic supports URL-backed PDF documents (#2215) and code execution tool results (#2158).
• OpenAI omits filename for URL-backed PDFs in Responses requests (#2166), which the API had been rejecting outright with a 400.
• Streaming consumers no longer receive duplicate reasoning events (#2196). OpenAI-compatible Responses providers may return encrypted_content as an empty string on completed reasoning items; Rig treated any present value as encrypted reasoning and emitted a second, empty event alongside the visible one. Empty encrypted reasoning is now filtered on both the streaming and non-streaming paths (#2209), and non-empty encrypted payloads are untouched.
• OpenAI accepts strict: null in Responses tool definitions and maps it to false (#2178); deserializing it directly as bool had been rejecting otherwise-valid responses.
• Gemini image-generation and embedding error envelopes returned with a 2xx status now surface through ProviderResponse with the provider's status and body intact (#2147). Untagged deserialization had been accepting an error object as an empty success response, so what you got back was a generic missing-image error with the real cause discarded.

On the security side, the AWS Bedrock and S3 Vectors integrations no longer enable the AWS SDK's legacy Rustls connector (#2152), removing vulnerable rustls-webpki 0.101 from their active dependency graphs while keeping the modern default HTTPS client. rmcp was also bumped to latest (#2103).

Three Fixes That Change Behavior

These are worth reading even if nothing in your code stops compiling.

Extractor usage accounting was undercounting spend (#2109). extract_with_usage documents that usage accumulates across retry attempts, but no ExtractionError variant carried usage — so a completion that billed tokens and then failed extraction (the model never called submit, or the arguments failed to deserialize) silently dropped its usage. With retries(3) and two failed attempts before success, anyone metering spend was undercounting by two full completions. Usage now survives extraction failure and accumulates on every attempt. Attempts whose completion call itself errors contribute zero, and when every attempt fails the error carries no usage; both caveats are now stated in the docs rather than implied. Single-attempt extractions — the common case — report identical numbers to before.

Two smaller notes from the same work, which followed collapsing the extractor's four near-identical retry loops into one helper (#2107): the retry loop no longer deep-copies the entire chat history on every attempt, which matters with long multimodal histories; and one log string changed — "Multiple submit calls detected, using the last one" is now "using the first one", because the code has always deserialized the first. If you match that string in log tooling, update it.

Structured-output tools could shadow real tools (#2146). Tool output mode pins its synthetic tool name for the lifetime of a run. If a mutable tool server, retrieval, or an MCP refresh later made a real tool effective under that reserved name, Rig detected the collision but only logged a warning — then advertised both definitions and intercepted any matching call as final structured output. A call intended for the real tool could therefore end the run. Request preparation now fails closed with an actionable CompletionError::RequestError before any provider I/O, naming the reserved tool. A colliding tool that is filtered out by active_tools is not a false positive; the run fails only once it actually becomes effective.

Multipart tool results reach OpenAI intact (#2217). Conversion was concatenating multipart tool results before provider-specific wire normalization, destroying the original block boundaries — so tool_result_array_content emitted a single already-flattened item. Ordered text, JSON, and image blocks are now preserved in the Responses API, and Chat Completions keeps separate text parts when array-form results are enabled. Single text or JSON results keep their compact string form, and the newline-flattened behavior remains for providers that require string content. If you tuned prompts against the flattened shape, they are worth re-checking.

API Cleanup

Rig is still pre-1.0, so we continue removing stale APIs rather than carrying permanent aliases.

PromptError, StructuredOutputError, and VectorStoreError are now #[non_exhaustive] (#2114), so downstream match expressions need a wildcard arm. Conversation memory load failures surface as the typed PromptError::MemoryError rather than being flattened into CompletionError::RequestError.

Internally, the HttpClientExt implementations for reqwest::Client and ClientWithMiddleware are now generated from one macro with shared response conversion, removing 139 net lines while preserving request, error, header, body, and streaming behavior (#2113).

One note for contributors: CONTRIBUTING.md no longer asks PR authors to add AI-assistance disclosure boilerplate (#2159). The same review, quality, and testing standards apply to every contribution regardless of how it was written.

Upgrading

Six breaking changes ship in 0.41: the crate split, the client trait consolidation, the tool and hook API rework, AgentRunner as the only execution path, non-exhaustive core errors, and the wasm feature-flag removal.

Please read the new MIGRATING.md. It covers 0.38 through 0.41 with per-release sections, before-and-after code, and a symbol reference table for anything you cannot find by name anymore.

Huge thank you to everyone who made 0.41 happen:

• @alshdavid
• @arnold-jr
• @BANG404
• @boondocklabs
• @bugprone
• @christoph-wulf
• @dgrijalva
• @gold-silver-copper
• @hacctarr
• @joshua-mo-143
• @KaasPeer1
• @macaujack
• @Niedzwiedzw
• @suxiaoshao
• @Sytten
• @ThomasMarches
• @xiao-e-yun