Docs / Migration guide

Migration Guide

Breaking changes and migration paths between RavenClaws versions. RavenClaws follows Semantic Versioning — breaking changes only occur in major versions (v0.x → v1.0, v1.0 → v2.0, etc.). For pre-1.0 versions (v0.x), breaking changes may occur in minor versions but are documented here with migration instructions.

v0.9 → v1.0

v1.0 is the first stable release. The public API is now covered by semver guarantees. Key changes:

• #[non_exhaustive] on all public enums and structs
• Deprecated types removed
• Library crate (ravenclaws) stabilized

#[non_exhaustive] on public types

All public enums and structs now have #[non_exhaustive]. This means:

• Enums: Match statements must include a wildcard arm (_ => ...).
• Structs: Cannot be constructed with struct literal syntax outside the crate. Use the provided ::new() or ::default() methods instead.

Affected types:

Before (v0.9):

match error {
    RavenClawsError::Config(e) => ...,
    RavenClawsError::LLM(e) => ...,
    RavenClawsError::Tool(e) => ...,
    RavenClawsError::Network(e) => ...,
    RavenClawsError::Io(e) => ...,
    RavenClawsError::SecurityViolation => ...,
    RavenClawsError::RavenFabric(e) => ...,
}

After (v1.0):

match error {
    RavenClawsError::Config(e) => ...,
    RavenClawsError::LLM(e) => ...,
    RavenClawsError::Tool(e) => ...,
    RavenClawsError::Network(e) => ...,
    RavenClawsError::Io(e) => ...,
    RavenClawsError::SecurityViolation => ...,
    RavenClawsError::RavenFabric(e) => ...,
    _ => ...,  // future-proof
}

Deprecated LLM client types removed

The following types (deprecated since v0.5.0) have been removed:

Before (v0.9):

use ravenclaws::LiteLLMClient;
let client = LiteLLMClient::new(config);

After (v1.0):

use ravenclaws::{OpenAICompatibleClient, OpenAICompatibleProvider};
let client = OpenAICompatibleClient::new(
    OpenAICompatibleProvider::LiteLLM,
    config,
);

execute_tool_call removed

The legacy execute_tool_call function (deprecated since v0.4) has been removed. Use execute_tool_call_with_security instead, which integrates with PolicyEngine, Sandbox, and AuditLog.

Before (v0.9):

let result = execute_tool_call(&tool_call, &tool_registry).await;

After (v1.0):

let result = execute_tool_call_with_security(
    &tool_call,
    &tool_registry,
    &policy_engine,
    &sandbox,
    &audit_log,
).await;

run_exec_stream removed

The unused run_exec_stream function has been removed. Streaming exec functionality is handled internally by the agent loop.

v0.8 → v0.9

MultiModelManager now implements Clone

MultiModelManager now implements Clone to support sub-orchestrator spawning in swarm mode. If you were storing MultiModelManager in a context that doesn't support Clone, wrap it in Arc instead.

New [swarm] config section

Swarm orchestration configuration is now under [swarm] in ravenclaws.toml:

[swarm]
max_depth = 3
max_workers = 100
topology = "hierarchical"
dynamic_role_assignment = true

New [heartbeat] config section

Heartbeat agent configuration is now under [heartbeat]:

[heartbeat]
tick_interval_secs = 60
max_ticks = 0  # 0 = unlimited
goal = "Monitor system health"

v0.7 → v0.8

BackgroundTaskManager API

The background task manager now persists tasks to disk. The API has changed:

Before (v0.7):

let manager = BackgroundTaskManager::new();
let id = manager.spawn(task).await;

After (v0.8):

let manager = BackgroundTaskManager::new(workdir);
let id = manager.spawn(task).await;
// Tasks are persisted to <workdir>/tasks/<id>.json

--require-approval flag

The --require-approval flag now gates sensitive tool calls. When set, the agent prompts for approval before executing tools in the requires_approval category. See --help for details.

zeroize integration

API keys in LLMConfig and HMAC secret keys in AuditLog are now zeroized on drop. This is transparent to most users but may affect debugging if you were inspecting key values after use.

v0.6 → v0.7

MCP Server mode (--mcp-server)

The --mcp-server flag runs RavenClaws as an MCP server over stdio. In this mode, the binary does not accept prompts — it exposes tools via the MCP protocol.

HTTP Server mode (--serve)

The --serve flag starts a long-running HTTP server with /health, /ready, and /metrics endpoints. This is the recommended deployment mode for Kubernetes.

OpenTelemetry tracing (opt-in)

Tracing is disabled by default. Enable with --otel-endpoint or RAVENCLAWS_OTEL_ENDPOINT. The otel-grpc feature is enabled by default; otel-stdout is optional.

Helm chart

The official Helm chart is at charts/ravenclaws/. See charts/ravenclaws/values.yaml for configuration options.

v0.5 → v0.6

Swarm and Supervisor modes

Swarm and supervisor modes are now fully implemented. The --mode swarm and --mode supervisor flags now execute real multi-agent workflows instead of returning "not yet implemented" errors.

RavenFabric integration

RavenFabric is now wired into all agent modes. If you have [ravenfabric] configuration, it will be used for remote agent execution. Set enabled = false to disable.

v0.4 → v0.5

Unified OpenAI-Compatible Client

LiteLLMClient, OpenRouterClient, and OpenAIClient are deprecated. Use OpenAICompatibleClient with the appropriate OpenAICompatibleProvider variant.

Before (v0.4):

let client = LiteLLMClient::new(config);

After (v0.5):

let client = OpenAICompatibleClient::new(
    OpenAICompatibleProvider::LiteLLM,
    config,
);

Retry and Fallback

The LLMConfig now includes retry and fallback settings:

[llm]
retry_max_attempts = 3
retry_base_delay_ms = 100
retry_max_delay_ms = 10000
fallback_provider = "ollama"

Token Budget

Use --token-budget <N> or RAVENCLAW_TOKEN_BUDGET to set a token budget. The agent will stop when the budget is consumed.

v0.3 → v0.4

Tool system

The tool system is now based on structured function calling (OpenAI Tools format) instead of pattern-matching TOOL_CALL: / ARGS: in the prompt. If you were manually constructing tool call prompts, switch to the ToolRegistry API.