owlen/docs/CHANGELOG_v1.0.md

# Changelog for v1.0.0 - MCP-Only Architecture

## Summary

Version 1.0.0 marks the completion of the MCP-only architecture migration, removing all legacy code paths and fully embracing the Model Context Protocol for all LLM interactions and tool executions.

## Breaking Changes

### 1. MCP mode defaults to remote-preferred (legacy retained)

**What changed:**
- The `[mcp]` section in `config.toml` keeps a `mode` setting but now defaults to `remote_preferred`.
- Legacy values such as `"legacy"` map to the `local_only` runtime and emit a warning instead of failing.
- New toggles (`allow_fallback`, `warn_on_legacy`) give administrators explicit control over graceful degradation.

**Migration:**
```toml
[mcp]
mode = "remote_preferred"
allow_fallback = true
warn_on_legacy = true
```

To opt out of remote MCP servers temporarily:

```toml
[mcp]
mode = "local_only"  # or "legacy" for backwards compatibility
```

**Code changes:**
- `crates/owlen-core/src/config.rs`: Reintroduced `McpMode` with compatibility aliases and new settings.
- `crates/owlen-core/src/mcp/factory.rs`: Respects the configured mode, including strict remote-only and local-only paths.
- `crates/owlen-cli/src/main.rs`: Chooses between remote MCP providers and the direct Ollama provider based on the mode.

### 2. Updated MCP Client Factory

**What changed:**
- `McpClientFactory::create()` now enforces the configured mode (`remote_only`, `remote_preferred`, `local_only`, or `legacy`).
- Helpful configuration errors are surfaced when remote-only mode lacks servers or fallback is disabled.
- CLI users in `local_only`/`legacy` mode receive the direct Ollama provider instead of a failing MCP stub.

**Before:**
```rust
match self.config.mcp.mode {
    McpMode::Legacy => { /* use local */ },
    McpMode::Enabled => { /* use remote or fallback */ },
}
```

**After:**
```rust
match self.config.mcp.mode {
    McpMode::RemoteOnly => start_remote()?,
    McpMode::RemotePreferred => try_remote_or_fallback()?,
    McpMode::LocalOnly | McpMode::Legacy => use_local(),
    McpMode::Disabled => bail!("unsupported"),
}
```

## New Features

### Test Infrastructure

Added comprehensive mock implementations for testing:

1. **MockProvider** (`crates/owlen-core/src/provider.rs`)
   - Located in `provider::test_utils` module
   - Provides a simple provider for unit tests
   - Implements all required `Provider` trait methods

2. **MockMcpClient** (`crates/owlen-core/src/mcp.rs`)
   - Located in `mcp::test_utils` module
   - Provides a simple MCP client for unit tests
   - Returns mock tool descriptors and responses

### Documentation

1. **Migration Guide** (`docs/migration-guide.md`)
   - Comprehensive guide for migrating from v0.x to v1.0
   - Step-by-step configuration update instructions
   - Common issues and troubleshooting
   - Rollback procedures if needed

2. **Updated Configuration Reference**
   - Documented the new `remote_preferred` default and fallback controls
   - Clarified MCP server configuration with remote-only expectations
   - Added examples for local and cloud Ollama usage

## Bug Fixes

- Fixed test compilation errors due to missing mock implementations
- Resolved ambiguous glob re-export warnings (non-critical, test-only)

## Internal Changes

### Configuration System

- `McpSettings` gained `mode`, `allow_fallback`, and `warn_on_legacy` knobs.
- `McpMode` enum restored with explicit aliases for historical values.
- Default configuration now prefers remote servers but still works out-of-the-box with local tooling.

### MCP Factory

- Simplified factory logic by removing mode branching
- Improved fallback behavior with better error messages
- Test renamed to reflect new behavior: `test_factory_creates_local_client_when_no_servers_configured`

## Performance

No performance regressions expected. The MCP architecture may actually improve performance by:
- Removing unnecessary mode checks
- Streamlining the client creation process
- Better error handling reduces retry overhead

## Compatibility

### Backwards Compatibility

- Existing `mode = "legacy"` configs keep working (now mapped to `local_only`) but trigger a startup warning.
- Users who relied on remote-only behaviour should set `mode = "remote_only"` explicitly.

### Forward Compatibility

The `McpSettings` struct now provides a stable surface to grow additional MCP-specific options such as:
- Connection pooling strategies
- Remote health-check cadence
- Adaptive retry controls

## Testing

All tests passing:
```
test result: ok. 29 passed; 0 failed; 0 ignored
```

Key test areas:
- Agent ReAct pattern parsing
- MCP client factory creation
- Configuration loading and validation
- Mode-based tool filtering
- Permission and consent handling

## Upgrade Instructions

See [Migration Guide](migration-guide.md) for detailed instructions.

**Quick upgrade:**

1. Update your `~/.config/owlen/config.toml`:
   ```bash
   # Remove the 'mode' line from [mcp] section
   sed -i '/^mode = /d' ~/.config/owlen/config.toml
   ```

2. Rebuild Owlen:
   ```bash
   cargo build --release
   ```

3. Test with a simple query:
   ```bash
   owlen
   ```

## Known Issues

1. **Warning about ambiguous glob re-exports** - Non-critical, only affects test builds
2. **First inference may be slow** - Ollama loads models on first use (expected behavior)
3. **Cloud model 404 errors** - Ensure model names match Ollama Cloud's naming (remove `-cloud` suffix from model names)

## Contributors

This release completes the Phase 10 migration plan documented in `.agents/new_phases.md`.

## Related Issues

- Closes: Legacy mode removal
- Implements: Phase 10 cleanup and production polish
- References: MCP architecture migration phases 1-10