feat(plugins): add pluggable WebSearchTool with DuckDuckGo and Brave …

[Alkamal01]

📋 Summary

This PR implements a robust, pluggable WebSearchTool with support for multiple search providers (DuckDuckGo and Brave). It replaces the deprecated and non-compliant duck_search implementation, which relied on fragile HTML scraping and violated DuckDuckGo's Terms of Service.

🔗 Related Issues

Closes #1446

---

🧠 Context

The previous duck_search.rs implementation was entirely commented-out dead code. It attempted to scrape duckduckgo.com/html/ directly, which is forbidden by their ToS and highly fragile.

This PR introduces a vendor-neutral SearchProvider trait that allows MoFA to support multiple search backends while adhering to professional engineering standards and provider policies.

---

🛠️ Changes

mofa-plugins

• Implemented the SearchProvider trait and concrete providers:

  • DuckDuckGoProvider
  • BraveSearchProvider

• Added WebSearchTool as a ToolExecutor

• Registered the tool in the built-in tool plugin

mofa-foundation

• Implemented the WebSearchTool as a SimpleTool adapter for high-level agent interaction
• Exposed the tool in the foundation layer tool registry

mofa-extra / mofa-sdk

• Applied workspace-wide formatting fixes (cargo fmt) to ensure CI compliance

---

🧪 How You Tested

1. Unit Tests (Mocks)

Added deterministic tests using a MockSearchProvider to verify provider selection logic and error handling.

cargo test -p mofa-plugins --lib tools::web_search::tests
cargo test -p mofa-foundation --lib agent::tools::web_search::tests

2. Integration Tests (Manual)

Added ignored tests that perform real network calls to live APIs.

# Requires BRAVE_SEARCH_API_KEY env var
cargo test -p mofa-plugins --lib tools::web_search::tests -- --ignored

3. Linting

Verified that the workspace is clippy-clean and properly formatted.

cargo clippy --workspace --all-features -- -D errors
cargo fmt --check

---

📸 Screenshots / Logs (if applicable)

Mock Test Execution

test tools::web_search::tests::test_web_search_tool_missing_query ... ok
test tools::web_search::tests::test_web_search_tool_provider_selection ... ok
test agent::tools::web_search::tests::test_foundation_web_search_tool_metadata ... ok

---

⚠️ Breaking Changes

• None

---

🧹 Checklist

Code Quality

• Code follows Rust idioms and project conventions
• cargo fmt run
• cargo clippy passes without warnings

Testing

• Tests added/updated
• cargo test passes locally without any error

Documentation

• Public APIs documented
• README / docs updated (if needed)

PR Hygiene

• PR is small and focused (one logical change)
• Branch is up to date with main
• No unrelated commits
• Commit messages explain why, not only what

---

🚀 Deployment Notes

• Environment Variables:
  To use the Brave Search provider, the BRAVE_SEARCH_API_KEY must be set in the deployment environment.
  Otherwise, the tool will automatically fall back to DuckDuckGo.

---

🧩 Additional Notes for Reviewers

The DuckDuckGoProvider uses the official public "Instant Answer" API, which is compliant with their Terms of Service and does not require an API key. This makes the tool immediately usable out-of-the-box.