feat!: make web search Exa-only

BREAKING CHANGE: remove Tavily, Firecrawl, provider fallback,
and web-search-config. web_search and web_fetch now use
Exa-shaped inputs and return raw Exa-style details.

AGENTS.md

@@ -1,25 +1,27 @@
 # AGENTS.md
 
 ## Project overview
-- `pi-web-search` is a Pi extension package that exposes `web_search` and `web_fetch`.
+- `pi-web-search` is a Pi extension package that exposes Exa-backed `web_search` and `web_fetch`.
 - Entry point: `index.ts`.
-- Runtime/provider selection: `src/runtime.ts`.
+- Runtime/config loading: `src/runtime.ts`, `src/config.ts`.
-- Config/schema: `src/config.ts`, `src/schema.ts`.
+- Tool/input schemas: `src/schema.ts`.
-- Provider adapters and provider-specific tests: `src/providers/`.
+- Exa SDK adapter helpers: `src/providers/exa.ts`.
 - Tool adapters: `src/tools/`.
-- Interactive config command: `src/commands/web-search-config.ts`.
+- Output formatting: `src/format.ts`.
 
 ## Commands
 - Install deps: `npm install`
 - Run tests: `npm test`
 
 ## Working conventions
-- Keep the public tool contract stable unless the current design/spec explicitly changes it.
+- The package is Exa-only. Do not reintroduce provider registries, fallback graphs, or provider-specific option blocks.
-- Add provider-specific request controls in nested blocks (for example `tavily`, `firecrawl`) instead of new top-level params.
+- `web_search` should stay Exa-shaped and map closely to `exa.search(query, options)`.
-- Normalize provider responses through `src/providers/types.ts` before formatting/output.
+- `web_fetch` should stay Exa-shaped and map closely to `exa.getContents(urls, options)`.
+- Keep tool `details` close to raw Exa responses; keep human-readable formatting compact in `src/format.ts`.
 - Prefer focused tests next to the changed modules.
-- Update `README.md`, config examples, and command flows when provider/config schema changes.
+- Update `README.md` and config examples when Exa config/schema or tool parameters change.
 
 ## Docs
 - Design specs live under `docs/superpowers/specs/`.
 - Use `YYYY-MM-DD-<topic>-design.md` naming for design specs.
+- If a new spec supersedes an older one, say that explicitly in the newer file.

README.md

@@ -1,6 +1,6 @@
 # pi-web-search
 
-`pi-web-search` is a Pi extension package that adds `web_search` and `web_fetch` tools backed by pluggable providers such as Exa, Tavily, and Firecrawl.
+`pi-web-search` is a Pi extension package that adds Exa-backed `web_search` and `web_fetch` tools.
 
 ## Install
 
@@ -22,76 +22,89 @@ pi install https://gitea.rwiesner.com/pi/pi-web-search
 
 ## Configuration
 
-Provider configuration is managed by the extension's own commands and config files.
+Set `EXA_API_KEY`, or create `~/.pi/agent/web-search.json`:
-
-Example `~/.pi/agent/web-search.json`:
 
 ```json
 {
-  "defaultProvider": "firecrawl-main",
+  "apiKey": "exa_...",
-  "providers": [
+  "baseUrl": "https://api.exa.ai"
-    {
-      "name": "firecrawl-main",
-      "type": "firecrawl",
-      "apiKey": "fc-...",
-      "fallbackProviders": ["exa-fallback"]
-    },
-    {
-      "name": "exa-fallback",
-      "type": "exa",
-      "apiKey": "exa_..."
-    }
-  ]
-}
-```
-
-Self-hosted Firecrawl:
-
-```json
-{
-  "defaultProvider": "firecrawl-selfhosted",
-  "providers": [
-    {
-      "name": "firecrawl-selfhosted",
-      "type": "firecrawl",
-      "baseUrl": "https://firecrawl.internal.example/v2"
-    }
-  ]
-}
-```
-
-Tool examples:
-
-```json
-{
-  "query": "pi docs",
-  "provider": "firecrawl-main",
-  "firecrawl": {
-    "country": "DE",
-    "categories": ["github"],
-    "scrapeOptions": {
-      "formats": ["markdown"]
-    }
-  }
-}
-```
-
-```json
-{
-  "urls": ["https://pi.dev"],
-  "provider": "firecrawl-main",
-  "summary": true,
-  "firecrawl": {
-    "formats": ["markdown", "summary", "images"]
-  }
 }
 ```
 
 Notes:
-- Firecrawl self-hosted providers may omit `apiKey` when `baseUrl` is set.
+- `apiKey` is required unless `EXA_API_KEY` is set.
-- Firecrawl does not support generic `highlights`; use Firecrawl `formats` such as `markdown`, `summary`, and `images` instead.
+- `baseUrl` is optional.
+- Older multi-provider configs are no longer supported.
 
-Run `web-search-config` inside Pi to add or edit Tavily, Exa, and Firecrawl providers interactively.
+## Tool behavior
+
+### `web_search`
+
+Maps directly to Exa `search(query, options)`.
+
+Notes:
+- Exa search returns text contents by default.
+- Pass `contents: false` for metadata-only search results.
+- `additionalQueries` is only valid for deep search types: `deep-lite`, `deep`, `deep-reasoning`.
+- `includeText` and `excludeText` currently support at most one phrase of up to 5 words.
+
+Example:
+
+```json
+{
+  "query": "Who leads OpenAI's safety team?",
+  "type": "deep",
+  "numResults": 5,
+  "systemPrompt": "Prefer official docs",
+  "outputSchema": {
+    "type": "text",
+    "description": "Answer in short bullets"
+  },
+  "contents": {
+    "highlights": {
+      "query": "OpenAI safety lead",
+      "maxCharacters": 300
+    },
+    "summary": true
+  }
+}
+```
+
+Metadata-only search:
+
+```json
+{
+  "query": "pi docs",
+  "contents": false,
+  "includeDomains": ["pi.dev"]
+}
+```
+
+### `web_fetch`
+
+Maps directly to Exa `getContents(urls, options)`.
+
+Example:
+
+```json
+{
+  "urls": ["https://pi.dev"],
+  "text": {
+    "maxCharacters": 4000,
+    "verbosity": "standard"
+  },
+  "highlights": {
+    "query": "tooling",
+    "maxCharacters": 300
+  },
+  "summary": true,
+  "livecrawl": "preferred",
+  "extras": {
+    "links": 20,
+    "imageLinks": 10
+  }
+}
+```
 
 ## Development
 

docs/superpowers/specs/2026-04-12-exa-only-design.md

@@ -0,0 +1,147 @@
+# Exa-only rewrite for `pi-web-search`
+
+- Status: approved design
+- Date: 2026-04-12
+- Project: `pi-web-search`
+- Supersedes: `2026-04-12-firecrawl-design.md`
+
+## Summary
+Rewrite `pi-web-search` as an Exa-only package. Remove Tavily, Firecrawl, provider failover, and the interactive config command. Keep the two public tools, but make them Exa-shaped instead of provider-generic.
+
+## Approved product decisions
+- Keep only `web_search` and `web_fetch`.
+- Support Exa’s non-streaming `search` and `getContents` functionality.
+- Use a single Exa config instead of a provider list.
+- Remove `web-search-config`.
+- Return tool `details` close to raw Exa responses.
+- Delete Tavily and Firecrawl code, tests, docs, and config paths completely.
+
+## Goals
+1. Make the package Exa-only.
+2. Expose Exa-native request shapes for both tools.
+3. Keep human-readable output compact while preserving raw Exa details.
+4. Support config through `~/.pi/agent/web-search.json` and `EXA_API_KEY`.
+5. Remove stale multi-provider abstractions and tests.
+
+## Non-goals
+- Expose Exa streaming APIs in this change.
+- Expose Exa `answer`, `findSimilar`, research, monitors, websets, imports, or webhook APIs.
+- Preserve the old provider-generic request contract.
+- Preserve the interactive config command.
+
+## Public tool contract
+### `web_search`
+Map directly to `exa.search(query, options)`.
+
+Supported top-level fields include:
+- `query`
+- `type`
+- `numResults`
+- `includeDomains`
+- `excludeDomains`
+- `startCrawlDate`
+- `endCrawlDate`
+- `startPublishedDate`
+- `endPublishedDate`
+- `category`
+- `includeText`
+- `excludeText`
+- `flags`
+- `userLocation`
+- `moderation`
+- `useAutoprompt`
+- `systemPrompt`
+- `outputSchema`
+- `additionalQueries`
+- `contents`
+
+Behavior notes:
+- Exa search returns text contents by default when `contents` is omitted.
+- `contents: false` is the metadata-only mode.
+- `additionalQueries` is allowed only for deep search types.
+- `includeText` and `excludeText` accept at most one phrase of up to 5 words.
+
+### `web_fetch`
+Map directly to `exa.getContents(urls, options)`.
+
+Supported fields include:
+- `urls`
+- `text`
+- `highlights`
+- `summary`
+- `context`
+- `livecrawl`
+- `livecrawlTimeout`
+- `maxAgeHours`
+- `filterEmptyResults`
+- `subpages`
+- `subpageTarget`
+- `extras`
+
+Behavior notes:
+- No provider selection.
+- No generic fallback behavior.
+- No package-invented `textMaxCharacters`; use Exa `text.maxCharacters`.
+
+## Config model
+Use a single config object:
+
+```json
+{
+  "apiKey": "exa_...",
+  "baseUrl": "https://api.exa.ai"
+}
+```
+
+Rules:
+- `apiKey` is required unless `EXA_API_KEY` is set.
+- `baseUrl` is optional.
+- Legacy multi-provider configs should fail with a migration hint.
+- Missing config file is allowed when `EXA_API_KEY` is present.
+
+## Runtime design
+Keep runtime small:
+1. load Exa config
+2. create Exa client
+3. delegate to `search` or `getContents`
+4. return raw Exa response
+
+Remove:
+- provider registry
+- provider capabilities
+- fallback graph execution
+- execution attempt metadata
+
+## Formatting
+- Human-readable output should say `via Exa`.
+- Tool `details` should stay close to raw Exa responses.
+- Search output should show `output.content` when present.
+- Fetch/search text should still be truncated in package formatting for readability.
+
+## Files expected to change
+- `index.ts`
+- `src/config.ts`
+- `src/schema.ts`
+- `src/runtime.ts`
+- `src/providers/exa.ts`
+- `src/tools/web-search.ts`
+- `src/tools/web-fetch.ts`
+- `src/format.ts`
+- `README.md`
+- tests under `src/`
+- package metadata and agent docs
+
+## Testing strategy
+1. Config tests for single Exa config, env fallback, invalid `baseUrl`, and legacy-config rejection.
+2. Exa adapter tests for option pass-through and client construction.
+3. Runtime tests for raw Exa delegation.
+4. Tool tests for Exa-shaped normalization and validation.
+5. Formatting tests for compact Exa output.
+6. Manifest/README tests for Exa-only packaging.
+
+## Acceptance criteria
+- No Tavily or Firecrawl runtime/config/tool paths remain.
+- `web_search` and `web_fetch` are Exa-shaped.
+- `web-search-config` is removed.
+- Config supports file or `EXA_API_KEY`.
+- Tests pass.

docs/superpowers/specs/2026-04-12-firecrawl-design.md

@@ -1,425 +0,0 @@
-# Firecrawl provider with self-hosted endpoint support
-
-- Status: approved design
-- Date: 2026-04-12
-- Project: `pi-web-search`
-
-## Summary
-Add Firecrawl as a first-class provider for both `web_search` and `web_fetch`, with optional per-provider `baseUrl` support for self-hosted deployments. Keep the public generic tool contract stable, add a nested `firecrawl` options block, and refactor provider selection/failover into a provider-capability and transport abstraction instead of adding more provider-specific branching.
-
-## Approved product decisions
-- Scope: support both `web_search` and `web_fetch`.
-- Self-hosted configuration: per-provider `baseUrl`.
-- Failover direction: generalize failover rules instead of keeping the current hardcoded Tavily -> Exa logic.
-- Provider-specific request surface: add a nested `firecrawl` block.
-- Config command scope: Firecrawl should be supported in `web-search-config`.
-- Auth rule: `apiKey` is optional only for self-hosted Firecrawl.
-- Refactor direction: do the larger provider abstraction now so future providers fit the same shape.
-
-## Current state
-The package currently supports Exa and Tavily.
-
-Key constraints in the current codebase:
-- `src/runtime.ts` creates providers via a `switch` and hardcodes Tavily -> Exa failover behavior.
-- `src/schema.ts` exposes only one provider-specific nested block today: `tavily`.
-- `src/config.ts` requires a literal `apiKey` for every provider.
-- `src/commands/web-search-config.ts` only supports Tavily and Exa in the interactive flow.
-- `src/providers/types.ts` already provides a good normalized boundary for shared search/fetch outputs.
-
-## Goals
-1. Add Firecrawl provider support for both tools.
-2. Support Firecrawl cloud and self-hosted deployments via per-provider `baseUrl`.
-3. Preserve the stable top-level tool contract for existing callers.
-4. Add explicit provider capabilities so provider-specific options do not bleed across providers.
-5. Replace the hardcoded fallback rule with a generic, config-driven failover chain.
-6. Keep the first Firecrawl request surface intentionally small.
-7. Update tests, config flows, and docs so the new provider is usable without reading source.
-
-## Non-goals
-- Expose Firecrawl’s full platform surface area (`crawl`, `map`, `extract`, browser sessions, agent endpoints, batch APIs).
-- Emulate generic `highlights` for Firecrawl.
-- Expand normalized output types to represent every Firecrawl artifact.
-- Add alternate auth schemes beyond the existing bearer-token model in this change.
-- Do unrelated cleanup outside the provider/config/runtime path.
-
-## Design overview
-The implementation should be organized around three layers:
-
-1. **Provider descriptor/registry**
-   - A shared registry defines each provider type.
-   - Each descriptor owns:
-     - config defaults/normalization hooks
-     - provider capability metadata
-     - provider creation
-   - Runtime code resolves providers through the registry rather than a growing `switch`.
-
-2. **Shared REST transport helper**
-   - A provider-agnostic HTTP helper handles:
-     - base URL joining
-     - request JSON serialization
-     - auth header construction
-     - consistent error messages with truncated response bodies
-   - Firecrawl and Tavily should use the helper.
-   - Exa can keep its SDK client path.
-
-3. **Runtime execution and failover engine**
-   - Runtime resolves the starting provider from the explicit request provider or config default.
-   - Runtime validates provider-specific request blocks against the selected provider.
-   - Runtime executes the provider and follows an explicit fallback chain when configured.
-   - Runtime records execution metadata as an ordered attempt trail instead of a single fallback hop.
-
-## Provider model
-Add a provider descriptor abstraction with enough metadata to drive validation and routing.
-
-Suggested shape:
-- provider `type`
-- supported operations: `search`, `fetch`
-- accepted nested option blocks (for example `tavily`, `firecrawl`)
-- supported generic fetch features: `text`, `summary`, `highlights`
-- config normalization rules
-- provider factory
-
-This is intentionally a capability/transport abstraction, not a full plugin system. It should remove the current hardcoded provider branching while staying small enough for the package.
-
-## Config schema changes
-### Common provider additions
-Extend every provider config with:
-- `fallbackProviders?: string[]`
-
-Validation rules:
-- every fallback target name must exist
-- self-reference is invalid
-- repeated names in a single chain are invalid
-- full cycles across providers should be rejected during config normalization
-
-### Firecrawl config
-Add a new provider config type:
-
-```json
-{
-  "name": "firecrawl-main",
-  "type": "firecrawl",
-  "apiKey": "fc-...",
-  "baseUrl": "https://api.firecrawl.dev/v2",
-  "options": {},
-  "fallbackProviders": ["exa-fallback"]
-}
-```
-
-Rules:
-- `baseUrl` is optional.
-- If `baseUrl` is omitted, default to Firecrawl cloud: `https://api.firecrawl.dev/v2`.
-- If `baseUrl` is provided, normalize it once (trim whitespace, remove trailing slash, reject invalid URLs).
-- `apiKey` is required when `baseUrl` is omitted.
-- `apiKey` is optional when `baseUrl` is set, to allow self-hosted deployments that do not require auth.
-- If `apiKey` is present, send the standard bearer auth header for both cloud and self-hosted.
-
-### Existing providers
-- Exa remains API-key required.
-- Tavily remains API-key required.
-- Existing configs without `fallbackProviders` remain valid.
-
-## Tool request surface
-Keep the generic top-level fields as the stable contract.
-
-### `web_search`
-Keep:
-- `query`
-- `limit`
-- `includeDomains`
-- `excludeDomains`
-- `startPublishedDate`
-- `endPublishedDate`
-- `category`
-- `provider`
-
-Add:
-- `firecrawl?: { ... }`
-
-### `web_fetch`
-Keep:
-- `urls`
-- `text`
-- `highlights`
-- `summary`
-- `textMaxCharacters`
-- `provider`
-
-Add:
-- `firecrawl?: { ... }`
-
-### Firecrawl-specific nested options
-The first-pass Firecrawl request shape should stay small.
-
-#### Search
-Add a small `firecrawl` search options block:
-- `country?: string`
-- `location?: string`
-- `categories?: string[]`
-- `scrapeOptions?: { formats?: FirecrawlSearchFormat[] }`
-
-First-pass supported `FirecrawlSearchFormat` values:
-- `markdown`
-- `summary`
-
-This keeps the surface small while still exposing the main documented Firecrawl search behavior: metadata-only search by default, or richer scraped content through `scrapeOptions.formats`.
-
-#### Fetch
-Add a small `firecrawl` fetch options block:
-- `formats?: FirecrawlFetchFormat[]`
-
-First-pass supported `FirecrawlFetchFormat` values:
-- `markdown`
-- `summary`
-- `images`
-
-This whitelist is intentional. It maps cleanly into the existing normalized fetch response without inventing new top-level output fields.
-
-## Validation behavior
-Important rule: unsupported provider-specific options should not silently bleed into other providers.
-
-Validation happens after the runtime resolves the selected provider.
-
-Rules:
-- If the selected provider is Firecrawl, reject a `tavily` block.
-- If the selected provider is Tavily, reject a `firecrawl` block.
-- If the selected provider is Exa, reject both `tavily` and `firecrawl` blocks.
-- When the selected provider is explicit, prefer validation errors over silent ignore.
-- When the default provider is used implicitly, keep the same strict validation model once that provider is resolved.
-
-Generic feature validation for fetch:
-- Exa: supports `text`, `highlights`, `summary`.
-- Tavily: supports `text`; other generic fetch behaviors continue to follow current provider semantics.
-- Firecrawl: supports `text` and `summary`.
-- generic `highlights` is unsupported for Firecrawl and should error.
-
-Example errors:
-- `Provider "firecrawl-main" does not accept the "tavily" options block.`
-- `Provider "exa-main" does not accept the "firecrawl" options block.`
-- `Provider "firecrawl-main" does not support generic fetch option "highlights".`
-
-## Runtime and failover
-Replace the current special-case Tavily -> Exa retry with a generic fallback executor.
-
-Behavior:
-- Resolve the initial provider from `request.provider` or the configured default provider.
-- Execute that provider first.
-- If it fails, look at that provider’s `fallbackProviders` list.
-- Try fallback providers in order.
-- Track visited providers to prevent loops and duplicate retries.
-- Stop at the first successful response.
-- If all attempts fail, throw the last error with execution context attached or included in the message.
-
-Execution metadata should evolve from a single fallback pair to an ordered attempt trail, for example:
-
-```json
-{
-  "requestedProviderName": "firecrawl-main",
-  "actualProviderName": "exa-fallback",
-  "attempts": [
-    {
-      "providerName": "firecrawl-main",
-      "status": "failed",
-      "reason": "Firecrawl 503 Service Unavailable"
-    },
-    {
-      "providerName": "exa-fallback",
-      "status": "succeeded"
-    }
-  ]
-}
-```
-
-Formatting can still render a compact fallback line for human-readable tool output, but details should preserve the full attempt list.
-
-## Firecrawl provider behavior
-### Base URL handling
-Use the configured `baseUrl` as the API root.
-
-Examples:
-- cloud default: `https://api.firecrawl.dev/v2`
-- self-hosted: `https://firecrawl.internal.example/v2`
-
-Endpoint joining should produce:
-- search: `POST {baseUrl}/search`
-- fetch/scrape: `POST {baseUrl}/scrape`
-
-### Auth handling
-- If `apiKey` is present, send `Authorization: Bearer <apiKey>`.
-- If `apiKey` is absent on a self-hosted Firecrawl provider, omit the auth header entirely.
-- Do not make auth optional for Exa or Tavily.
-
-### Search mapping
-Use `POST /search`.
-
-Request mapping:
-- `query` -> `query`
-- `limit` -> `limit`
-- `includeDomains` with exactly one domain -> append documented `site:<domain>` operator to the outgoing Firecrawl query
-- `includeDomains` with more than one domain -> validation error in the first pass
-- `excludeDomains` -> append documented `-site:<domain>` operators to the outgoing Firecrawl query
-- top-level generic `category` -> if `firecrawl.categories` is absent, map to `categories: [category]`
-- if both generic `category` and `firecrawl.categories` are supplied, validation error
-- `firecrawl.country` -> `country`
-- `firecrawl.location` -> `location`
-- `firecrawl.categories` -> `categories`
-- `firecrawl.scrapeOptions` -> `scrapeOptions`
-
-Behavior:
-- Default Firecrawl search should stay metadata-first.
-- If `firecrawl.scrapeOptions.formats` is omitted, return normalized results from Firecrawl’s default metadata response.
-- Map Firecrawl’s default metadata description/snippet into normalized `content` when present.
-- If `markdown` is requested, map returned markdown/body content into `rawContent`.
-- If `summary` is requested, map returned summary content into `content`.
-- Preserve provider request IDs when present.
-
-### Fetch mapping
-Use `POST /scrape` once per requested URL so failures stay per-URL and match the existing normalized response model.
-
-Generic mapping:
-- default fetch with no explicit content flags => request markdown output
-- generic `text: true` => include `markdown`
-- generic `summary: true` => include `summary`
-- generic `highlights: true` => validation error
-- `firecrawl.formats` can override the default derived format list when the caller wants explicit control
-- if `firecrawl.formats` is provided, validate it against generic flags:
-  - `text: true` requires `markdown`
-  - `summary: true` requires `summary`
-  - `highlights: true` is always invalid
-
-Normalization:
-- `markdown` -> normalized `text`
-- `summary` -> normalized `summary`
-- `images` -> normalized `images`
-- title/url map directly
-- unsupported returned artifacts are ignored in the normalized surface for now
-
-`textMaxCharacters` handling:
-- apply truncation in package formatting, not by inventing Firecrawl API parameters that do not exist
-- preserve the current output contract by truncating formatted text through existing formatter logic
-
-## Error handling
-Firecrawl and Tavily should share a common HTTP error helper.
-
-Requirements:
-- include provider name and HTTP status in thrown errors
-- include a short response-body excerpt for debugging
-- avoid duplicating transport error formatting in every provider
-- keep per-URL fetch failures isolated so one failed scrape does not hide successful URLs
-
-## Interactive config command
-Update `web-search-config` so Firecrawl is a first-class option.
-
-Changes:
-- add `Add Firecrawl provider`
-- allow editing `baseUrl`
-- allow blank `apiKey` only when `baseUrl` is provided for a Firecrawl provider
-- allow editing `fallbackProviders`
-- keep Exa/Tavily flows unchanged except for new fallback configuration support
-
-Suggested prompt flow for Firecrawl:
-1. provider name
-2. Firecrawl base URL (blank means Firecrawl cloud default)
-3. Firecrawl API key
-4. fallback providers
-
-Validation should run before saving so the command cannot write an invalid fallback graph or an invalid Firecrawl auth/baseUrl combination.
-
-## Files expected to change
-Core code paths likely touched by this design:
-- `src/schema.ts`
-- `src/config.ts`
-- `src/runtime.ts`
-- `src/commands/web-search-config.ts`
-- `src/providers/types.ts`
-- `src/providers/tavily.ts`
-- new Firecrawl provider file/tests under `src/providers/`
-- `src/tools/web-search.ts`
-- `src/tools/web-fetch.ts`
-- `src/format.ts`
-- `README.md`
-- relevant tests in `src/*.test.ts` and `src/providers/*.test.ts`
-
-## Testing strategy
-Add tests in five layers.
-
-1. **Schema/config tests**
-   - accept Firecrawl cloud config with `apiKey`
-   - accept self-hosted Firecrawl config with `baseUrl` and no `apiKey`
-   - reject cloud Firecrawl with no `apiKey`
-   - reject invalid `baseUrl`
-   - reject unknown fallback provider names
-   - reject self-reference and multi-provider cycles
-
-2. **Provider unit tests**
-   - search request mapping to `/search`
-   - fetch request mapping to `/scrape`
-   - base URL joining works for cloud and self-hosted roots
-   - auth header omitted when self-hosted Firecrawl has no `apiKey`
-   - response normalization maps markdown/summary/images correctly
-   - provider errors include status + body excerpt
-
-3. **Runtime tests**
-   - explicit provider selection uses the requested provider first
-   - runtime follows fallback chains in order
-   - runtime prevents loops / duplicate retries
-   - runtime returns execution attempts metadata
-   - explicit provider selection still allows configured fallbacks for that provider
-
-4. **Tool-level validation tests**
-   - reject `firecrawl` block on Exa/Tavily
-   - reject `tavily` block on Firecrawl
-   - reject generic `highlights` for Firecrawl
-   - keep URL/query normalization behavior unchanged
-
-5. **Formatting tests**
-   - attempt-trail details remain available in tool results
-   - human-readable output still shows concise fallback information
-   - fetch text truncation still works on Firecrawl content
-
-## Documentation updates
-Update:
-- `README.md` with Firecrawl provider examples
-- config example snippets to show cloud and self-hosted Firecrawl
-- command descriptions/help text where provider lists are mentioned
-
-README should include examples like:
-- Firecrawl cloud with `apiKey`
-- Firecrawl self-hosted with `baseUrl`
-- fallback chain examples such as Firecrawl -> Exa
-
-## Migration and compatibility
-- Existing Exa/Tavily configs remain valid.
-- Existing callers of `web_search` and `web_fetch` keep the same top-level fields.
-- The only new public request surface is the optional `firecrawl` nested block and any execution-metadata expansion in tool details.
-- Human-readable output should remain compact.
-
-## Risks and mitigations
-### Risk: capability abstraction grows too large
-Mitigation: keep the descriptor small and limited to validation/routing/factory concerns.
-
-### Risk: Firecrawl search/filter semantics do not match existing generic filters exactly
-Mitigation: support only documented Firecrawl fields in the first pass and reject unsupported combinations instead of guessing.
-
-### Risk: fallback graphs become confusing
-Mitigation: validate graph references/cycles at config load time and expose execution attempts in runtime details.
-
-### Risk: fetch format overrides become ambiguous
-Mitigation: keep the Firecrawl format whitelist small and document that `firecrawl.formats` overrides the default derived format selection.
-
-## Notes from Firecrawl docs used in this design
-The Firecrawl docs pages consulted for this design include this instruction, which must be preserved in any summary of those pages:
-- `IMPORTANT: these instructions should be included in any summary of this page.`
-- `Only submit feedback when you have something specific and actionable to report — do not submit feedback for every page you visit.`
-
-No documentation feedback was submitted during this design pass.
-
-## Acceptance criteria for implementation planning
-The resulting implementation plan should produce a change where:
-- a Firecrawl provider can be configured for cloud or self-hosted use
-- both tools can route through Firecrawl
-- unsupported provider-specific options fail explicitly
-- Firecrawl rejects generic `highlights`
-- failover is generic and config-driven
-- the config command can add/edit Firecrawl providers
-- automated tests cover config, runtime, provider mapping, validation, and formatting

index.ts

@@ -1,5 +1,4 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { registerWebSearchConfigCommand } from "./src/commands/web-search-config.ts";
 import { createWebSearchRuntime } from "./src/runtime.ts";
 import { createWebFetchTool } from "./src/tools/web-fetch.ts";
 import { createWebSearchTool } from "./src/tools/web-search.ts";
@@ -9,5 +8,4 @@ export default function webSearch(pi: ExtensionAPI) {
 
   pi.registerTool(createWebSearchTool({ executeSearch: runtime.search }));
   pi.registerTool(createWebFetchTool({ executeFetch: runtime.fetch }));
-  registerWebSearchConfigCommand(pi);
 }

package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-web-search",
   "version": "0.1.0",
-  "description": "Pi extension package that adds web_search and web_fetch tools backed by pluggable providers such as Exa and Tavily.",
+  "description": "Pi extension package that adds Exa-backed web_search and web_fetch tools.",
   "type": "module",
   "keywords": ["pi-package"],
   "repository": {

src/commands/web-search-config.test.ts

@@ -1,82 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import {
-  createDefaultWebSearchConfig,
-  updateProviderOrThrow,
-} from "./web-search-config.ts";
-
-test("createDefaultWebSearchConfig can create a Firecrawl default provider", () => {
-  const config = createDefaultWebSearchConfig({
-    provider: {
-      name: "firecrawl-main",
-      type: "firecrawl",
-      baseUrl: "https://firecrawl.internal.example/v2",
-    },
-  });
-
-  assert.deepEqual(config, {
-    defaultProvider: "firecrawl-main",
-    providers: [
-      {
-        name: "firecrawl-main",
-        type: "firecrawl",
-        baseUrl: "https://firecrawl.internal.example/v2",
-      },
-    ],
-  });
-});
-
-test("updateProviderOrThrow allows a Firecrawl provider to omit apiKey when baseUrl exists", () => {
-  const next = updateProviderOrThrow(
-    {
-      defaultProvider: "firecrawl-main",
-      providers: [
-        {
-          name: "firecrawl-main",
-          type: "firecrawl",
-          apiKey: "fc-test-key",
-          baseUrl: "https://firecrawl.internal.example/v2",
-        },
-        {
-          name: "exa-fallback",
-          type: "exa",
-          apiKey: "exa-test-key",
-        },
-      ],
-    },
-    "firecrawl-main",
-    {
-      apiKey: "",
-      baseUrl: "https://firecrawl.internal.example/v2",
-      fallbackProviders: ["exa-fallback"],
-    },
-  );
-
-  assert.deepEqual(next.providers[0], {
-    name: "firecrawl-main",
-    type: "firecrawl",
-    baseUrl: "https://firecrawl.internal.example/v2",
-    fallbackProviders: ["exa-fallback"],
-  });
-});
-
-test("updateProviderOrThrow rejects a blank apiKey for Exa", () => {
-  assert.throws(
-    () =>
-      updateProviderOrThrow(
-        {
-          defaultProvider: "exa-main",
-          providers: [
-            {
-              name: "exa-main",
-              type: "exa",
-              apiKey: "exa-test-key",
-            },
-          ],
-        },
-        "exa-main",
-        { apiKey: "" },
-      ),
-    /Provider apiKey cannot be blank/,
-  );
-});

src/commands/web-search-config.ts

@@ -1,391 +0,0 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import {
-  getDefaultWebSearchConfigPath,
-  normalizeWebSearchConfig,
-  readRawWebSearchConfig,
-  writeWebSearchConfig,
-  WebSearchConfigError,
-} from "../config.ts";
-import type { WebSearchConfig, WebSearchProviderConfig } from "../schema.ts";
-
-type ProviderPatch = {
-  apiKey?: string;
-  baseUrl?: string;
-  fallbackProviders?: string[];
-  options?: WebSearchProviderConfig["options"];
-};
-
-function validateProviderDraftOrThrow(provider: WebSearchProviderConfig) {
-  if (!provider.name.trim()) {
-    throw new Error("Provider name cannot be blank.");
-  }
-
-  if (provider.type === "firecrawl") {
-    const apiKey = provider.apiKey?.trim();
-    const baseUrl = provider.baseUrl?.trim();
-    if (!apiKey && !baseUrl) {
-      throw new Error("Firecrawl provider apiKey cannot be blank unless baseUrl is set.");
-    }
-    return;
-  }
-
-  if (!provider.apiKey.trim()) {
-    throw new Error("Provider apiKey cannot be blank.");
-  }
-}
-
-function normalizeDraftConfigOrThrow(config: WebSearchConfig, path: string): WebSearchConfig {
-  const normalized = normalizeWebSearchConfig(config, path);
-  return {
-    defaultProvider: normalized.defaultProviderName,
-    providers: normalized.providers,
-  };
-}
-
-function parseFallbackProviders(value: string) {
-  const items = value
-    .split(",")
-    .map((item) => item.trim())
-    .filter(Boolean);
-  return items.length > 0 ? items : undefined;
-}
-
-export function createDefaultWebSearchConfig(input: { provider: WebSearchProviderConfig }): WebSearchConfig {
-  validateProviderDraftOrThrow(input.provider);
-  return {
-    defaultProvider: input.provider.name,
-    providers: [input.provider],
-  };
-}
-
-export function setDefaultProviderOrThrow(config: WebSearchConfig, providerName: string): WebSearchConfig {
-  if (!config.providers.some((provider) => provider.name === providerName)) {
-    throw new Error(`Unknown provider: ${providerName}`);
-  }
-  return { ...config, defaultProvider: providerName };
-}
-
-export function renameProviderOrThrow(
-  config: WebSearchConfig,
-  currentName: string,
-  nextName: string,
-): WebSearchConfig {
-  if (!nextName.trim()) {
-    throw new Error("Provider name cannot be blank.");
-  }
-  if (config.providers.some((provider) => provider.name === nextName && provider.name !== currentName)) {
-    throw new Error(`Duplicate provider name: ${nextName}`);
-  }
-
-  return {
-    defaultProvider: config.defaultProvider === currentName ? nextName : config.defaultProvider,
-    providers: config.providers.map((provider) => ({
-      ...provider,
-      name: provider.name === currentName ? nextName : provider.name,
-      fallbackProviders: provider.fallbackProviders?.map((name) => (name === currentName ? nextName : name)),
-    })),
-  };
-}
-
-export function updateProviderOrThrow(
-  config: WebSearchConfig,
-  providerName: string,
-  patch: ProviderPatch,
-): WebSearchConfig {
-  const existing = config.providers.find((provider) => provider.name === providerName);
-  if (!existing) {
-    throw new Error(`Unknown provider: ${providerName}`);
-  }
-
-  let nextProvider: WebSearchProviderConfig;
-  if (existing.type === "firecrawl") {
-    const nextBaseUrl = patch.baseUrl ?? existing.baseUrl;
-    const nextApiKey = patch.apiKey !== undefined ? patch.apiKey.trim() || undefined : existing.apiKey;
-    const nextFallbackProviders = patch.fallbackProviders ?? existing.fallbackProviders;
-    const nextOptions = patch.options ?? existing.options;
-
-    nextProvider = {
-      name: existing.name,
-      type: existing.type,
-      ...(nextApiKey ? { apiKey: nextApiKey } : {}),
-      ...(nextBaseUrl ? { baseUrl: nextBaseUrl } : {}),
-      ...(nextFallbackProviders ? { fallbackProviders: nextFallbackProviders } : {}),
-      ...(nextOptions ? { options: nextOptions } : {}),
-    };
-  } else {
-    if (patch.apiKey !== undefined && !patch.apiKey.trim()) {
-      throw new Error("Provider apiKey cannot be blank.");
-    }
-
-    nextProvider = {
-      ...existing,
-      apiKey: patch.apiKey ?? existing.apiKey,
-      fallbackProviders: patch.fallbackProviders ?? existing.fallbackProviders,
-      options: patch.options ?? existing.options,
-    };
-  }
-
-  validateProviderDraftOrThrow(nextProvider);
-
-  return {
-    ...config,
-    providers: config.providers.map((provider) => (provider.name === providerName ? nextProvider : provider)),
-  };
-}
-
-export function removeProviderOrThrow(config: WebSearchConfig, providerName: string): WebSearchConfig {
-  if (config.providers.length === 1) {
-    throw new Error("Cannot remove the last provider.");
-  }
-  if (config.defaultProvider === providerName) {
-    throw new Error("Cannot remove the default provider before selecting a new default.");
-  }
-  return {
-    ...config,
-    providers: config.providers.filter((provider) => provider.name !== providerName),
-  };
-}
-
-function upsertProviderOrThrow(config: WebSearchConfig, nextProvider: WebSearchProviderConfig): WebSearchConfig {
-  validateProviderDraftOrThrow(nextProvider);
-
-  const withoutSameName = config.providers.filter((provider) => provider.name !== nextProvider.name);
-  return {
-    ...config,
-    providers: [...withoutSameName, nextProvider],
-  };
-}
-
-async function promptProviderOptions(ctx: any, provider: WebSearchProviderConfig) {
-  const defaultSearchLimit = await ctx.ui.input(
-    `Default search limit for ${provider.name}`,
-    provider.options?.defaultSearchLimit !== undefined ? String(provider.options.defaultSearchLimit) : "",
-  );
-
-  if (provider.type === "firecrawl") {
-    const options = {
-      defaultSearchLimit: defaultSearchLimit ? Number(defaultSearchLimit) : undefined,
-    };
-    return options.defaultSearchLimit !== undefined ? options : undefined;
-  }
-
-  const defaultFetchTextMaxCharacters = await ctx.ui.input(
-    `Default fetch text max characters for ${provider.name}`,
-    provider.options?.defaultFetchTextMaxCharacters !== undefined
-      ? String(provider.options.defaultFetchTextMaxCharacters)
-      : "",
-  );
-
-  if (provider.type === "tavily") {
-    const options = {
-      defaultSearchLimit: defaultSearchLimit ? Number(defaultSearchLimit) : undefined,
-      defaultFetchTextMaxCharacters: defaultFetchTextMaxCharacters
-        ? Number(defaultFetchTextMaxCharacters)
-        : undefined,
-    };
-    return Object.values(options).some((value) => value !== undefined) ? options : undefined;
-  }
-
-  const defaultFetchHighlightsMaxCharacters = await ctx.ui.input(
-    `Default fetch highlights max characters for ${provider.name}`,
-    provider.options?.defaultFetchHighlightsMaxCharacters !== undefined
-      ? String(provider.options.defaultFetchHighlightsMaxCharacters)
-      : "",
-  );
-
-  const options = {
-    defaultSearchLimit: defaultSearchLimit ? Number(defaultSearchLimit) : undefined,
-    defaultFetchTextMaxCharacters: defaultFetchTextMaxCharacters
-      ? Number(defaultFetchTextMaxCharacters)
-      : undefined,
-    defaultFetchHighlightsMaxCharacters: defaultFetchHighlightsMaxCharacters
-      ? Number(defaultFetchHighlightsMaxCharacters)
-      : undefined,
-  };
-
-  return Object.values(options).some((value) => value !== undefined) ? options : undefined;
-}
-
-async function promptFallbackProviders(ctx: any, provider: WebSearchProviderConfig) {
-  const value = await ctx.ui.input(
-    `Fallback providers for ${provider.name} (comma-separated names)`,
-    (provider.fallbackProviders ?? []).join(", "),
-  );
-  return parseFallbackProviders(value ?? "");
-}
-
-async function promptNewProvider(ctx: any, type: WebSearchProviderConfig["type"]) {
-  const name = await ctx.ui.input(
-    "Provider name",
-    type === "tavily" ? "tavily-main" : type === "exa" ? "exa-fallback" : "firecrawl-main",
-  );
-  if (!name) {
-    return undefined;
-  }
-
-  if (type === "firecrawl") {
-    const baseUrl = await ctx.ui.input("Firecrawl base URL (blank uses cloud default)", "");
-    const apiKey = await ctx.ui.input("Firecrawl API key (blank allowed when base URL is set)", "fc-...");
-    const provider: WebSearchProviderConfig = {
-      name,
-      type,
-      ...(apiKey?.trim() ? { apiKey } : {}),
-      ...(baseUrl?.trim() ? { baseUrl } : {}),
-    };
-    const fallbackProviders = await promptFallbackProviders(ctx, provider);
-    const options = await promptProviderOptions(ctx, provider);
-    return {
-      ...provider,
-      ...(fallbackProviders ? { fallbackProviders } : {}),
-      ...(options ? { options } : {}),
-    };
-  }
-
-  const apiKey = await ctx.ui.input(type === "tavily" ? "Tavily API key" : "Exa API key", type === "tavily" ? "tvly-..." : "exa_...");
-  if (!apiKey) {
-    return undefined;
-  }
-
-  const provider: WebSearchProviderConfig = { name, type, apiKey };
-  const fallbackProviders = await promptFallbackProviders(ctx, provider);
-  const options = await promptProviderOptions(ctx, provider);
-  return {
-    ...provider,
-    ...(fallbackProviders ? { fallbackProviders } : {}),
-    ...(options ? { options } : {}),
-  };
-}
-
-export function registerWebSearchConfigCommand(pi: ExtensionAPI) {
-  pi.registerCommand("web-search-config", {
-    description: "Configure Tavily/Exa/Firecrawl providers for web_search and web_fetch",
-    handler: async (_args, ctx) => {
-      const path = getDefaultWebSearchConfigPath();
-
-      let config: WebSearchConfig;
-      try {
-        config = await readRawWebSearchConfig(path);
-      } catch (error) {
-        if (!(error instanceof WebSearchConfigError)) {
-          throw error;
-        }
-
-        const createType = await ctx.ui.select("Create initial provider", [
-          "Add Tavily provider",
-          "Add Exa provider",
-          "Add Firecrawl provider",
-        ]);
-        if (!createType) {
-          return;
-        }
-
-        const provider = await promptNewProvider(
-          ctx,
-          createType === "Add Tavily provider"
-            ? "tavily"
-            : createType === "Add Exa provider"
-              ? "exa"
-              : "firecrawl",
-        );
-        if (!provider) {
-          return;
-        }
-        config = createDefaultWebSearchConfig({ provider });
-      }
-
-      const action = await ctx.ui.select("Web search config", [
-        "Set default provider",
-        "Add Tavily provider",
-        "Add Exa provider",
-        "Add Firecrawl provider",
-        "Edit provider",
-        "Remove provider",
-      ]);
-      if (!action) {
-        return;
-      }
-
-      if (action === "Set default provider") {
-        const nextDefault = await ctx.ui.select(
-          "Choose default provider",
-          config.providers.map((provider) => provider.name),
-        );
-        if (!nextDefault) {
-          return;
-        }
-        config = setDefaultProviderOrThrow(config, nextDefault);
-      }
-
-      if (action === "Add Tavily provider" || action === "Add Exa provider" || action === "Add Firecrawl provider") {
-        const provider = await promptNewProvider(
-          ctx,
-          action === "Add Tavily provider" ? "tavily" : action === "Add Exa provider" ? "exa" : "firecrawl",
-        );
-        if (!provider) {
-          return;
-        }
-        config = upsertProviderOrThrow(config, provider);
-      }
-
-      if (action === "Edit provider") {
-        const providerName = await ctx.ui.select(
-          "Choose provider",
-          config.providers.map((provider) => provider.name),
-        );
-        if (!providerName) {
-          return;
-        }
-
-        const existing = config.providers.find((provider) => provider.name === providerName)!;
-        const nextName = await ctx.ui.input("Provider name", existing.name);
-        if (!nextName) {
-          return;
-        }
-
-        config = renameProviderOrThrow(config, existing.name, nextName);
-        const renamed = config.providers.find((provider) => provider.name === nextName)!;
-        const fallbackProviders = await promptFallbackProviders(ctx, renamed);
-        const nextOptions = await promptProviderOptions(ctx, renamed);
-
-        if (renamed.type === "firecrawl") {
-          const nextBaseUrl = await ctx.ui.input("Firecrawl base URL (blank uses cloud default)", renamed.baseUrl ?? "");
-          const nextApiKey = await ctx.ui.input(
-            `API key for ${renamed.name} (blank allowed when base URL is set)`,
-            renamed.apiKey ?? "",
-          );
-          config = updateProviderOrThrow(config, nextName, {
-            apiKey: nextApiKey,
-            baseUrl: nextBaseUrl,
-            fallbackProviders,
-            options: nextOptions,
-          });
-        } else {
-          const nextApiKey = await ctx.ui.input(`API key for ${renamed.name}`, renamed.apiKey);
-          if (!nextApiKey) {
-            return;
-          }
-          config = updateProviderOrThrow(config, nextName, {
-            apiKey: nextApiKey,
-            fallbackProviders,
-            options: nextOptions,
-          });
-        }
-      }
-
-      if (action === "Remove provider") {
-        const providerName = await ctx.ui.select(
-          "Choose provider to remove",
-          config.providers.map((provider) => provider.name),
-        );
-        if (!providerName) {
-          return;
-        }
-        config = removeProviderOrThrow(config, providerName);
-      }
-
-      const normalizedConfig = normalizeDraftConfigOrThrow(config, path);
-      await writeWebSearchConfig(path, normalizedConfig);
-      ctx.ui.notify(`Saved web-search config to ${path}`, "info");
-    },
-  });
-}

src/config.test.ts

@@ -3,191 +3,123 @@ import assert from "node:assert/strict";
 import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { loadWebSearchConfig, WebSearchConfigError } from "./config.ts";
+import {
+  WebSearchConfigError,
+  loadWebSearchConfig,
+  stringifyWebSearchConfig,
+  writeWebSearchConfig,
+} from "./config.ts";
 
-async function writeTempConfig(contents: unknown) {
+async function createConfigPath() {
   const dir = await mkdtemp(join(tmpdir(), "pi-web-search-config-"));
-  const file = join(dir, "web-search.json");
+  return join(dir, "web-search.json");
-  const body = typeof contents === "string" ? contents : JSON.stringify(contents, null, 2);
-  await writeFile(file, body, "utf8");
-  return file;
 }
 
-test("loadWebSearchConfig returns a normalized default provider and provider lookup", async () => {
+function withEnv(name: string, value: string | undefined) {
-  const file = await writeTempConfig({
+  const previous = process.env[name];
-    defaultProvider: "exa-main",
+  if (value === undefined) {
-    providers: [
+    delete process.env[name];
-      {
+  } else {
-        name: "exa-main",
+    process.env[name] = value;
-        type: "exa",
+  }
-        apiKey: "exa-test-key",
+
-        options: {
+  return () => {
-          defaultSearchLimit: 7,
+    if (previous === undefined) {
-          defaultFetchTextMaxCharacters: 9000,
+      delete process.env[name];
-        },
+    } else {
-      },
+      process.env[name] = previous;
-    ],
+    }
+  };
+}
+
+test("loadWebSearchConfig reads a single Exa config and normalizes baseUrl", async () => {
+  const restore = withEnv("EXA_API_KEY", undefined);
+  const path = await createConfigPath();
+  await writeWebSearchConfig(path, {
+    apiKey: "exa-test-key",
+    baseUrl: "https://api.exa.ai/",
   });
 
-  const config = await loadWebSearchConfig(file);
+  const config = await loadWebSearchConfig(path);
 
-  assert.equal(config.defaultProviderName, "exa-main");
+  assert.equal(config.path, path);
-  assert.equal(config.defaultProvider.name, "exa-main");
+  assert.equal(config.apiKey, "exa-test-key");
-  assert.equal(config.providersByName.get("exa-main")?.apiKey, "exa-test-key");
+  assert.equal(config.baseUrl, "https://api.exa.ai");
-  assert.equal(config.providers[0]?.options?.defaultSearchLimit, 7);
+  restore();
 });
 
-test("loadWebSearchConfig normalizes a Tavily default with Exa fallback", async () => {
+test("loadWebSearchConfig falls back to EXA_API_KEY when the config file is missing", async () => {
-  const file = await writeTempConfig({
+  const restore = withEnv("EXA_API_KEY", "exa-from-env");
-    defaultProvider: "tavily-main",
+  const path = await createConfigPath();
-    providers: [
-      {
-        name: "tavily-main",
-        type: "tavily",
-        apiKey: "tvly-test-key",
-      },
-      {
-        name: "exa-fallback",
-        type: "exa",
-        apiKey: "exa-test-key",
-      },
-    ],
-  });
 
-  const config = await loadWebSearchConfig(file);
+  const config = await loadWebSearchConfig(path);
 
-  assert.equal(config.defaultProviderName, "tavily-main");
+  assert.equal(config.apiKey, "exa-from-env");
-  assert.equal(config.defaultProvider.type, "tavily");
+  assert.equal(config.baseUrl, undefined);
-  assert.equal(config.providersByName.get("exa-fallback")?.type, "exa");
+  restore();
 });
 
-test("loadWebSearchConfig rejects a missing default provider target", async () => {
+test("loadWebSearchConfig rejects an invalid baseUrl", async () => {
-  const file = await writeTempConfig({
+  const restore = withEnv("EXA_API_KEY", undefined);
-    defaultProvider: "missing",
+  const path = await createConfigPath();
-    providers: [
+  await writeWebSearchConfig(path, {
-      {
+    apiKey: "exa-test-key",
-        name: "exa-main",
+    baseUrl: "not-a-url",
-        type: "exa",
-        apiKey: "exa-test-key",
-      },
-    ],
   });
 
-  await assert.rejects(
+  await assert.rejects(() => loadWebSearchConfig(path), (error: unknown) => {
-    () => loadWebSearchConfig(file),
+    assert.ok(error instanceof WebSearchConfigError);
-    (error) =>
+    return error.message.includes("invalid baseUrl");
-      error instanceof WebSearchConfigError &&
+  });
-      /defaultProvider \"missing\"/.test(error.message),
+  restore();
-  );
+});
-});
+
-
+test("loadWebSearchConfig rejects a blank apiKey when EXA_API_KEY is not set", async () => {
-test("loadWebSearchConfig rejects a missing file with a helpful example message", async () => {
+  const restore = withEnv("EXA_API_KEY", undefined);
-  const file = join(tmpdir(), "pi-web-search-does-not-exist.json");
+  const path = await createConfigPath();
-
+  await writeWebSearchConfig(path, {
-  await assert.rejects(
+    apiKey: "   ",
-    () => loadWebSearchConfig(file),
+  });
-    (error) =>
+
-      error instanceof WebSearchConfigError &&
+  await assert.rejects(() => loadWebSearchConfig(path), (error: unknown) => {
-      error.message.includes(file) &&
+    assert.ok(error instanceof WebSearchConfigError);
-      error.message.includes('"defaultProvider"') &&
+    return error.message.includes("Set EXA_API_KEY or create");
-      error.message.includes('"providers"'),
+  });
-  );
+  restore();
-});
+});
-
+
-test("loadWebSearchConfig accepts self-hosted Firecrawl without an apiKey and normalizes its baseUrl", async () => {
+test("loadWebSearchConfig rejects the legacy multi-provider config shape with a migration hint", async () => {
-  const file = await writeTempConfig({
+  const restore = withEnv("EXA_API_KEY", undefined);
-    defaultProvider: "firecrawl-main",
+  const path = await createConfigPath();
-    providers: [
+  await writeFile(
-      {
+    path,
-        name: "firecrawl-main",
+    `${JSON.stringify(
-        type: "firecrawl",
+      {
-        baseUrl: "https://firecrawl.internal.example/v2/",
+        defaultProvider: "exa-main",
-        fallbackProviders: ["exa-fallback"],
+        providers: [
-      },
+          {
-      {
+            name: "exa-main",
-        name: "exa-fallback",
+            type: "exa",
-        type: "exa",
+            apiKey: "exa-test-key",
-        apiKey: "exa-test-key",
+          },
-      },
+        ],
-    ],
+      },
-  });
+      null,
-
+      2,
-  const config = await loadWebSearchConfig(file);
+    )}\n`,
-  const provider = config.providersByName.get("firecrawl-main");
+    "utf8",
-
+  );
-  assert.equal(provider?.type, "firecrawl");
+
-  assert.equal(provider?.baseUrl, "https://firecrawl.internal.example/v2");
+  await assert.rejects(() => loadWebSearchConfig(path), (error: unknown) => {
-  assert.equal(provider?.apiKey, undefined);
+    assert.ok(error instanceof WebSearchConfigError);
-  assert.deepEqual(provider?.fallbackProviders, ["exa-fallback"]);
+    return error.message.includes("Legacy multi-provider config") && error.message.includes("{\n  \"apiKey\"",);
-});
+  });
-
+  restore();
-test("loadWebSearchConfig rejects Firecrawl cloud config without an apiKey", async () => {
+});
-  const file = await writeTempConfig({
+
-    defaultProvider: "firecrawl-main",
+test("stringifyWebSearchConfig writes compact Exa-only JSON with a trailing newline", () => {
-    providers: [
+  assert.equal(
-      {
+    stringifyWebSearchConfig({ apiKey: "exa-test-key", baseUrl: "https://api.exa.ai" }),
-        name: "firecrawl-main",
+    '{\n  "apiKey": "exa-test-key",\n  "baseUrl": "https://api.exa.ai"\n}\n',
-        type: "firecrawl",
-      },
-    ],
-  });
-
-  await assert.rejects(
-    () => loadWebSearchConfig(file),
-    (error) =>
-      error instanceof WebSearchConfigError &&
-      /Firecrawl provider \"firecrawl-main\"/.test(error.message) &&
-      /apiKey/.test(error.message),
-  );
-});
-
-test("loadWebSearchConfig rejects unknown fallback providers", async () => {
-  const file = await writeTempConfig({
-    defaultProvider: "firecrawl-main",
-    providers: [
-      {
-        name: "firecrawl-main",
-        type: "firecrawl",
-        apiKey: "fc-test-key",
-        fallbackProviders: ["missing-provider"],
-      },
-    ],
-  });
-
-  await assert.rejects(
-    () => loadWebSearchConfig(file),
-    (error) =>
-      error instanceof WebSearchConfigError &&
-      /fallback provider/.test(error.message) &&
-      /missing-provider/.test(error.message),
-  );
-});
-
-test("loadWebSearchConfig rejects fallback cycles", async () => {
-  const file = await writeTempConfig({
-    defaultProvider: "firecrawl-main",
-    providers: [
-      {
-        name: "firecrawl-main",
-        type: "firecrawl",
-        apiKey: "fc-test-key",
-        fallbackProviders: ["exa-fallback"],
-      },
-      {
-        name: "exa-fallback",
-        type: "exa",
-        apiKey: "exa-test-key",
-        fallbackProviders: ["firecrawl-main"],
-      },
-    ],
-  });
-
-  await assert.rejects(
-    () => loadWebSearchConfig(file),
-    (error) =>
-      error instanceof WebSearchConfigError &&
-      /cycle/i.test(error.message) &&
-      /firecrawl-main/.test(error.message) &&
-      /exa-fallback/.test(error.message),
   );
 });

src/config.ts

@@ -2,19 +2,12 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { Value } from "@sinclair/typebox/value";
-import {
+import { WebSearchConfigSchema, type WebSearchConfig } from "./schema.ts";
-  WebSearchConfigSchema,
-  type FirecrawlProviderConfig,
-  type WebSearchConfig,
-  type WebSearchProviderConfig,
-} from "./schema.ts";
 
 export interface ResolvedWebSearchConfig {
   path: string;
-  defaultProviderName: string;
+  apiKey: string;
-  defaultProvider: WebSearchProviderConfig;
+  baseUrl?: string;
-  providers: WebSearchProviderConfig[];
-  providersByName: Map<string, WebSearchProviderConfig>;
 }
 
 export class WebSearchConfigError extends Error {
@@ -31,167 +24,61 @@ export function getDefaultWebSearchConfigPath() {
 function exampleConfigSnippet() {
   return JSON.stringify(
     {
-      defaultProvider: "tavily-main",
+      apiKey: "exa_...",
-      providers: [
+      baseUrl: "https://api.exa.ai",
-        {
-          name: "tavily-main",
-          type: "tavily",
-          apiKey: "tvly-...",
-          fallbackProviders: ["exa-fallback"],
-        },
-        {
-          name: "exa-fallback",
-          type: "exa",
-          apiKey: "exa_...",
-        },
-      ],
     },
     null,
     2,
   );
 }
 
-function normalizeBaseUrl(value: string, path: string, providerName: string) {
+function isLegacyMultiProviderConfig(value: unknown): value is {
+  defaultProvider?: unknown;
+  providers?: unknown;
+} {
+  return !!value && typeof value === "object" && ("defaultProvider" in value || "providers" in value);
+}
+
+function createLegacyConfigError(path: string) {
+  return new WebSearchConfigError(
+    `Legacy multi-provider config detected at ${path}. Migrate to the Exa-only shape:\n${exampleConfigSnippet()}`,
+  );
+}
+
+function createMissingConfigError(path: string) {
+  return new WebSearchConfigError(
+    `Missing Exa configuration. Set EXA_API_KEY or create ${path} with contents like:\n${exampleConfigSnippet()}`,
+  );
+}
+
+function normalizeBaseUrl(value: string, path: string) {
   let parsed: URL;
   try {
     parsed = new URL(value);
   } catch {
-    throw new WebSearchConfigError(`Firecrawl provider \"${providerName}\" in ${path} has an invalid baseUrl.`);
+    throw new WebSearchConfigError(`Exa config in ${path} has an invalid baseUrl.`);
   }
 
   parsed.pathname = parsed.pathname.replace(/\/+$/, "") || "/";
   return parsed.toString().replace(/\/$/, "");
 }
 
-function normalizeFallbackProviders(provider: WebSearchProviderConfig, path: string) {
+export function normalizeWebSearchConfig(
-  const fallbackProviders = provider.fallbackProviders?.map((name) => name.trim());
+  config: WebSearchConfig,
-  if (!fallbackProviders) {
+  path: string,
-    return undefined;
+  envApiKey = process.env.EXA_API_KEY,
-  }
+): ResolvedWebSearchConfig {
+  const apiKey = config.apiKey?.trim() || envApiKey?.trim();
+  const baseUrl = config.baseUrl?.trim() ? normalizeBaseUrl(config.baseUrl.trim(), path) : undefined;
 
-  if (fallbackProviders.some((name) => !name)) {
-    throw new WebSearchConfigError(`Provider \"${provider.name}\" in ${path} contains a blank fallback provider name.`);
-  }
-
-  if (new Set(fallbackProviders).size !== fallbackProviders.length) {
-    throw new WebSearchConfigError(`Provider \"${provider.name}\" in ${path} has duplicate fallback providers.`);
-  }
-
-  return fallbackProviders;
-}
-
-function normalizeProvider(provider: WebSearchProviderConfig, path: string): WebSearchProviderConfig {
-  const name = provider.name.trim();
-  if (!name) {
-    throw new WebSearchConfigError(`Provider in ${path} is missing a name.`);
-  }
-
-  const fallbackProviders = normalizeFallbackProviders(provider, path);
-
-  if (provider.type === "firecrawl") {
-    const apiKey = provider.apiKey?.trim() || undefined;
-    const baseUrl = provider.baseUrl?.trim() ? normalizeBaseUrl(provider.baseUrl.trim(), path, name) : undefined;
-
-    if (!baseUrl && !apiKey) {
-      throw new WebSearchConfigError(
-        `Firecrawl provider \"${name}\" in ${path} requires an apiKey when baseUrl is omitted.`,
-      );
-    }
-
-    return {
-      ...(provider as FirecrawlProviderConfig),
-      name,
-      apiKey,
-      baseUrl,
-      fallbackProviders,
-    };
-  }
-
-  const apiKey = provider.apiKey.trim();
   if (!apiKey) {
-    throw new WebSearchConfigError(`Provider \"${name}\" in ${path} is missing a literal apiKey.`);
+    throw createMissingConfigError(path);
-  }
-
-  return {
-    ...provider,
-    name,
-    apiKey,
-    fallbackProviders,
-  };
-}
-
-function validateFallbackGraph(providersByName: Map<string, WebSearchProviderConfig>, path: string) {
-  for (const provider of providersByName.values()) {
-    for (const fallbackProvider of provider.fallbackProviders ?? []) {
-      if (fallbackProvider === provider.name) {
-        throw new WebSearchConfigError(`Provider \"${provider.name}\" in ${path} cannot fall back to itself.`);
-      }
-      if (!providersByName.has(fallbackProvider)) {
-        throw new WebSearchConfigError(
-          `Provider \"${provider.name}\" in ${path} references unknown fallback provider \"${fallbackProvider}\".`,
-        );
-      }
-    }
-  }
-
-  const visited = new Set<string>();
-  const activePath: string[] = [];
-  const activeSet = new Set<string>();
-
-  const visit = (providerName: string) => {
-    if (activeSet.has(providerName)) {
-      const cycleStart = activePath.indexOf(providerName);
-      const cycle = [...activePath.slice(cycleStart), providerName].join(" -> ");
-      throw new WebSearchConfigError(`Fallback provider cycle detected in ${path}: ${cycle}`);
-    }
-    if (visited.has(providerName)) {
-      return;
-    }
-
-    visited.add(providerName);
-    activeSet.add(providerName);
-    activePath.push(providerName);
-
-    const provider = providersByName.get(providerName);
-    for (const fallbackProvider of provider?.fallbackProviders ?? []) {
-      visit(fallbackProvider);
-    }
-
-    activePath.pop();
-    activeSet.delete(providerName);
-  };
-
-  for (const providerName of providersByName.keys()) {
-    visit(providerName);
-  }
-}
-
-export function normalizeWebSearchConfig(config: WebSearchConfig, path: string): ResolvedWebSearchConfig {
-  const providersByName = new Map<string, WebSearchProviderConfig>();
-
-  for (const rawProvider of config.providers) {
-    const provider = normalizeProvider(rawProvider, path);
-    if (providersByName.has(provider.name)) {
-      throw new WebSearchConfigError(`Duplicate provider name \"${provider.name}\" in ${path}.`);
-    }
-    providersByName.set(provider.name, provider);
-  }
-
-  validateFallbackGraph(providersByName, path);
-
-  const defaultProvider = providersByName.get(config.defaultProvider);
-  if (!defaultProvider) {
-    throw new WebSearchConfigError(
-      `defaultProvider \"${config.defaultProvider}\" does not match any configured provider in ${path}.`,
-    );
   }
 
   return {
     path,
-    defaultProviderName: config.defaultProvider,
+    apiKey,
-    defaultProvider,
+    baseUrl,
-    providers: [...providersByName.values()],
-    providersByName,
   };
 }
 
@@ -203,6 +90,10 @@ function parseWebSearchConfig(raw: string, path: string) {
     throw new WebSearchConfigError(`Invalid JSON in ${path}: ${(error as Error).message}`);
   }
 
+  if (isLegacyMultiProviderConfig(parsed)) {
+    throw createLegacyConfigError(path);
+  }
+
   if (!Value.Check(WebSearchConfigSchema, parsed)) {
     const [firstError] = [...Value.Errors(WebSearchConfigSchema, parsed)];
     throw new WebSearchConfigError(
@@ -213,24 +104,37 @@ function parseWebSearchConfig(raw: string, path: string) {
   return parsed as WebSearchConfig;
 }
 
-export async function readRawWebSearchConfig(path = getDefaultWebSearchConfigPath()): Promise<WebSearchConfig> {
+async function readConfigFile(path: string) {
-  let raw: string;
   try {
-    raw = await readFile(path, "utf8");
+    return await readFile(path, "utf8");
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      throw new WebSearchConfigError(
+      return undefined;
-        `Missing web-search config at ${path}.\nCreate ${path} with contents like:\n${exampleConfigSnippet()}`,
-      );
     }
     throw error;
   }
+}
+
+export async function readRawWebSearchConfig(path = getDefaultWebSearchConfigPath()): Promise<WebSearchConfig | undefined> {
+  const raw = await readConfigFile(path);
+  if (raw === undefined) {
+    return undefined;
+  }
 
   return parseWebSearchConfig(raw, path);
 }
 
 export function stringifyWebSearchConfig(config: WebSearchConfig) {
-  return `${JSON.stringify(config, null, 2)}\n`;
+  const normalized: WebSearchConfig = {};
+
+  if (config.apiKey !== undefined) {
+    normalized.apiKey = config.apiKey;
+  }
+  if (config.baseUrl !== undefined) {
+    normalized.baseUrl = config.baseUrl;
+  }
+
+  return `${JSON.stringify(normalized, null, 2)}\n`;
 }
 
 export async function writeWebSearchConfig(path: string, config: WebSearchConfig) {
@@ -240,5 +144,9 @@ export async function writeWebSearchConfig(path: string, config: WebSearchConfig
 
 export async function loadWebSearchConfig(path = getDefaultWebSearchConfigPath()) {
   const parsed = await readRawWebSearchConfig(path);
+  if (!parsed) {
+    return normalizeWebSearchConfig({}, path);
+  }
+
   return normalizeWebSearchConfig(parsed, path);
 }

src/extension.test.ts

@@ -2,7 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import webSearchExtension from "../index.ts";
 
-test("the extension entrypoint registers both tools and the config command", () => {
+test("the extension entrypoint registers both tools and no config command", () => {
   const registeredTools: string[] = [];
   const registeredCommands: string[] = [];
 
@@ -16,5 +16,5 @@ test("the extension entrypoint registers both tools and the config command", ()
   } as any);
 
   assert.deepEqual(registeredTools, ["web_search", "web_fetch"]);
-  assert.deepEqual(registeredCommands, ["web-search-config"]);
+  assert.deepEqual(registeredCommands, []);
 });

src/format.test.ts

@@ -2,116 +2,71 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { formatFetchOutput, formatSearchOutput, truncateText } from "./format.ts";
 
-test("formatSearchOutput renders a compact metadata-only list", () => {
+test("formatSearchOutput renders Exa output content and result metadata", () => {
   const output = formatSearchOutput({
-    providerName: "exa-main",
+    output: {
+      content: "pi is a coding agent",
+      grounding: [],
+    },
     results: [
       {
+        id: "doc-1",
         title: "Exa Docs",
         url: "https://exa.ai/docs",
         publishedDate: "2026-04-09",
         author: "Exa",
         score: 0.98,
-      },
+        text: "Helpful SDK docs",
-    ],
-  });
-
-  assert.match(output, /Found 1 web result via exa-main:/);
-  assert.match(output, /Exa Docs/);
-  assert.match(output, /https:\/\/exa.ai\/docs/);
-});
-
-test("formatSearchOutput shows answer and fallback provider metadata", () => {
-  const output = formatSearchOutput({
-    providerName: "exa-fallback",
-    answer: "pi is a coding agent",
-    execution: {
-      actualProviderName: "exa-fallback",
-      attempts: [
-        {
-          providerName: "firecrawl-main",
-          status: "failed",
-          reason: "503 upstream unavailable",
-        },
-        {
-          providerName: "exa-fallback",
-          status: "succeeded",
-        },
-      ],
-    },
-    results: [
-      {
-        title: "pi docs",
-        url: "https://pi.dev",
-        rawContent: "Very long raw content body",
       },
     ],
   } as any);
 
-  assert.match(output, /Answer: pi is a coding agent/);
+  assert.match(output, /Output: pi is a coding agent/);
-  assert.match(output, /Fallback: firecrawl-main -> exa-fallback/);
+  assert.match(output, /Found 1 web result via Exa:/);
+  assert.match(output, /Exa Docs/);
+  assert.match(output, /Helpful SDK docs/);
 });
 
-test("truncateText shortens long fetch bodies with an ellipsis", () => {
+test("truncateText shortens long bodies with an ellipsis", () => {
   assert.equal(truncateText("abcdef", 4), "abc…");
   assert.equal(truncateText("abc", 10), "abc");
 });
 
-test("formatFetchOutput includes both successful and failed URLs", () => {
+test("formatFetchOutput includes summary highlights and truncated text", () => {
   const output = formatFetchOutput(
     {
-      providerName: "exa-main",
       results: [
         {
-          url: "https://good.example",
+          id: "doc-1",
-          title: "Good",
+          url: "https://pi.dev",
+          title: "Pi",
+          summary: "Agent docs",
+          highlights: ["Coding agent", "Tooling"],
           text: "This is a very long body that should be truncated in the final output.",
         },
-        {
-          url: "https://bad.example",
-          title: null,
-          error: "429 rate limited",
-        },
       ],
-    },
+    } as any,
     { maxCharactersPerResult: 20 },
   );
 
-  assert.match(output, /Status: ok/);
+  assert.match(output, /Fetched 1 URL via Exa:/);
-  assert.match(output, /Status: failed/);
+  assert.match(output, /Summary: Agent docs/);
-  assert.match(output, /429 rate limited/);
+  assert.match(output, /Highlights:/);
   assert.match(output, /This is a very long…/);
 });
 
-test("formatFetchOutput shows fallback metadata and favicon/images when present", () => {
+test("formatFetchOutput stays compact when no content fields were requested", () => {
   const output = formatFetchOutput({
-    providerName: "exa-fallback",
-    execution: {
-      actualProviderName: "exa-fallback",
-      attempts: [
-        {
-          providerName: "tavily-main",
-          status: "failed",
-          reason: "503 upstream unavailable",
-        },
-        {
-          providerName: "exa-fallback",
-          status: "succeeded",
-        },
-      ],
-    },
     results: [
       {
-        url: "https://pi.dev",
+        id: "doc-1",
-        title: "pi",
+        url: "https://exa.ai",
-        text: "Fetched body",
+        title: "Exa",
-        favicon: "https://pi.dev/favicon.ico",
-        images: ["https://pi.dev/logo.png"],
       },
     ],
   } as any);
 
-  assert.match(output, /Fallback: tavily-main -> exa-fallback/);
+  assert.match(output, /URL: https:\/\/exa.ai/);
-  assert.match(output, /Favicon: https:\/\/pi.dev\/favicon.ico/);
+  assert.doesNotMatch(output, /Text:/);
-  assert.match(output, /Images:/);
+  assert.doesNotMatch(output, /Summary:/);
 });

src/format.ts

@@ -1,27 +1,9 @@
-import type { NormalizedFetchResponse, NormalizedSearchResponse } from "./providers/types.ts";
+function stringifyOutputContent(value: unknown) {
-
+  if (value === undefined || value === null) {
-function formatFallbackLine(execution?: {
-  actualProviderName?: string;
-  failoverFromProviderName?: string;
-  attempts?: Array<{
-    providerName?: string;
-    status?: string;
-  }>;
-}) {
-  if (execution?.failoverFromProviderName && execution.actualProviderName) {
-    return `Fallback: ${execution.failoverFromProviderName} -> ${execution.actualProviderName}`;
-  }
-
-  if (!execution?.actualProviderName || !execution.attempts?.length) {
     return undefined;
   }
 
-  const firstFailedAttempt = execution.attempts.find((attempt) => attempt.status === "failed");
+  return typeof value === "string" ? value : JSON.stringify(value, null, 2);
-  if (!firstFailedAttempt?.providerName || firstFailedAttempt.providerName === execution.actualProviderName) {
-    return undefined;
-  }
-
-  return `Fallback: ${firstFailedAttempt.providerName} -> ${execution.actualProviderName}`;
 }
 
 export function truncateText(text: string, maxCharacters = 4000) {
@@ -31,45 +13,81 @@ export function truncateText(text: string, maxCharacters = 4000) {
   return `${text.slice(0, Math.max(0, maxCharacters - 1))}…`;
 }
 
-export function formatSearchOutput(response: NormalizedSearchResponse & { execution?: any }) {
+function formatResultDetails(lines: string[], result: any, maxCharactersPerResult: number) {
+  lines.push(`URL: ${result.url}`);
+
+  if (result.title) {
+    lines.push(`Title: ${result.title}`);
+  }
+
+  const meta = [result.publishedDate, result.author].filter(Boolean);
+  if (meta.length > 0) {
+    lines.push(`Meta: ${meta.join(" • ")}`);
+  }
+
+  if (typeof result.score === "number") {
+    lines.push(`Score: ${result.score}`);
+  }
+
+  if (result.summary) {
+    lines.push(`Summary: ${truncateText(result.summary, Math.min(maxCharactersPerResult, 1000))}`);
+  }
+
+  if (Array.isArray(result.highlights) && result.highlights.length > 0) {
+    lines.push("Highlights:");
+    for (const highlight of result.highlights) {
+      lines.push(`- ${highlight}`);
+    }
+  }
+
+  if (result.text) {
+    lines.push("Text:");
+    lines.push(truncateText(result.text, maxCharactersPerResult));
+  }
+
+  if (result.favicon) {
+    lines.push(`Favicon: ${result.favicon}`);
+  }
+
+  if (result.image) {
+    lines.push(`Image: ${result.image}`);
+  }
+
+  const links = result.extras?.links;
+  if (Array.isArray(links) && links.length > 0) {
+    lines.push(`Links: ${links.length}`);
+  }
+
+  const imageLinks = result.extras?.imageLinks;
+  if (Array.isArray(imageLinks) && imageLinks.length > 0) {
+    lines.push(`Image links: ${imageLinks.length}`);
+  }
+
+  if (Array.isArray(result.subpages) && result.subpages.length > 0) {
+    lines.push(`Subpages: ${result.subpages.length}`);
+  }
+}
+
+export function formatSearchOutput(response: any) {
   const lines: string[] = [];
-  const fallbackLine = formatFallbackLine(response.execution);
+  const outputContent = stringifyOutputContent(response?.output?.content);
+  const results = Array.isArray(response?.results) ? response.results : [];
 
-  if (fallbackLine) {
+  if (outputContent) {
-    lines.push(fallbackLine, "");
+    lines.push(`Output: ${truncateText(outputContent, 1200)}`, "");
   }
 
-  if (response.answer) {
+  if (results.length === 0) {
-    lines.push(`Answer: ${response.answer}`, "");
+    lines.push("No web results via Exa.");
-  }
-
-  if (response.results.length === 0) {
-    lines.push(`No web results via ${response.providerName}.`);
     return lines.join("\n");
   }
 
-  lines.push(`Found ${response.results.length} web result${response.results.length === 1 ? "" : "s"} via ${response.providerName}:`);
+  lines.push(`Found ${results.length} web result${results.length === 1 ? "" : "s"} via Exa:`);
 
-  for (const [index, result] of response.results.entries()) {
+  for (const [index, result] of results.entries()) {
+    lines.push("");
     lines.push(`${index + 1}. ${result.title ?? "(untitled)"}`);
-    lines.push(`   URL: ${result.url}`);
+    formatResultDetails(lines, result, 1200);
-
-    const meta = [result.publishedDate, result.author].filter(Boolean);
-    if (meta.length > 0) {
-      lines.push(`   Meta: ${meta.join(" • ")}`);
-    }
-
-    if (typeof result.score === "number") {
-      lines.push(`   Score: ${result.score}`);
-    }
-
-    if (result.content) {
-      lines.push(`   Snippet: ${truncateText(result.content, 500)}`);
-    }
-
-    if (result.rawContent) {
-      lines.push(`   Raw content: ${truncateText(result.rawContent, 700)}`);
-    }
   }
 
   return lines.join("\n");
@@ -79,53 +97,16 @@ export interface FetchFormatOptions {
   maxCharactersPerResult?: number;
 }
 
-export function formatFetchOutput(response: NormalizedFetchResponse & { execution?: any }, options: FetchFormatOptions = {}) {
+export function formatFetchOutput(response: any, options: FetchFormatOptions = {}) {
   const maxCharactersPerResult = options.maxCharactersPerResult ?? 4000;
   const lines: string[] = [];
-  const fallbackLine = formatFallbackLine(response.execution);
+  const results = Array.isArray(response?.results) ? response.results : [];
 
-  if (fallbackLine) {
+  lines.push(`Fetched ${results.length} URL${results.length === 1 ? "" : "s"} via Exa:`);
-    lines.push(fallbackLine, "");
-  }
 
-  lines.push(`Fetched ${response.results.length} URL${response.results.length === 1 ? "" : "s"} via ${response.providerName}:`);
+  for (const result of results) {
-
-  for (const result of response.results) {
     lines.push("");
-    lines.push(`URL: ${result.url}`);
+    formatResultDetails(lines, result, maxCharactersPerResult);
-
-    if (result.error) {
-      lines.push("Status: failed");
-      lines.push(`Error: ${result.error}`);
-      continue;
-    }
-
-    lines.push("Status: ok");
-    if (result.title) {
-      lines.push(`Title: ${result.title}`);
-    }
-    if (result.summary) {
-      lines.push(`Summary: ${result.summary}`);
-    }
-    if (result.highlights?.length) {
-      lines.push("Highlights:");
-      for (const highlight of result.highlights) {
-        lines.push(`- ${highlight}`);
-      }
-    }
-    if (result.favicon) {
-      lines.push(`Favicon: ${result.favicon}`);
-    }
-    if (result.images?.length) {
-      lines.push("Images:");
-      for (const image of result.images) {
-        lines.push(`- ${image}`);
-      }
-    }
-    if (result.text) {
-      lines.push("Text:");
-      lines.push(truncateText(result.text, maxCharactersPerResult));
-    }
   }
 
   return lines.join("\n");

src/package-manifest.test.ts

@@ -16,11 +16,10 @@ function getPackedPaths(cwd: string) {
     timeout: 30_000,
   });
   const parsed = JSON.parse(out);
-  // npm pack --dry-run --json returns array with first entry containing files
   return (parsed[0]?.files ?? []).map((f: { path: string }) => f.path);
 }
 
-test("package.json exposes pi-web-search as a standalone pi package", () => {
+test("package.json exposes pi-web-search as an Exa-only pi package", () => {
   assert.equal(pkg.name, "pi-web-search");
   assert.equal(pkg.type, "module");
   assert.ok(Array.isArray(pkg.keywords));
@@ -29,11 +28,7 @@ test("package.json exposes pi-web-search as a standalone pi package", () => {
     extensions: ["./index.ts"],
   });
 
-  // description + repository exact match
+  assert.equal(pkg.description, "Pi extension package that adds Exa-backed web_search and web_fetch tools.");
-  assert.equal(
-    pkg.description,
-    "Pi extension package that adds web_search and web_fetch tools backed by pluggable providers such as Exa and Tavily."
-  );
   assert.deepEqual(pkg.repository, {
     type: "git",
     url: "https://gitea.rwiesner.com/pi/pi-web-search",
@@ -45,26 +40,29 @@ test("package.json exposes pi-web-search as a standalone pi package", () => {
   assert.ok("exa-js" in (pkg.dependencies ?? {}));
   assert.ok(!("@sinclair/typebox" in (pkg.dependencies ?? {})));
   assert.deepEqual(pkg.files, ["index.ts", "src"]);
-
-  // ensure manifest does not bundle dependencies by default
   assert.equal(pkg.bundledDependencies, undefined);
 });
 
-test("README contains local and git install examples", () => {
+test("README contains install examples and Exa-only docs", () => {
   const readme = readFileSync(resolve(packageRoot, "README.md"), "utf8");
   assert.match(readme, /pi install \/absolute\/path\/to\/web-search/);
   assert.match(readme, /pi install https:\/\/gitea.rwiesner.com\/pi\/pi-web-search/);
+  assert.match(readme, /Exa-backed/);
+  assert.doesNotMatch(readme, /Tavily/);
+  assert.doesNotMatch(readme, /Firecrawl/);
+  assert.doesNotMatch(readme, /web-search-config/);
 });
 
-test("npm pack includes expected assets and excludes .test.ts files", () => {
+test("npm pack includes expected assets and excludes deleted command/provider files", () => {
   const packedPaths = getPackedPaths(packageRoot);
 
-  // meaningful pack assertions
   assert.ok(packedPaths.includes("index.ts"), "index.ts should be included in package");
   assert.ok(packedPaths.includes("src/runtime.ts"), "src/runtime.ts should be included in package");
   assert.ok(packedPaths.includes("src/tools/web-search.ts"), "src/tools/web-search.ts should be included in package");
   assert.ok(packedPaths.includes("src/tools/web-fetch.ts"), "src/tools/web-fetch.ts should be included in package");
 
-  // no test files packed
+  assert.ok(!packedPaths.includes("src/commands/web-search-config.ts"));
+  assert.ok(!packedPaths.includes("src/providers/firecrawl.ts"));
+  assert.ok(!packedPaths.includes("src/providers/tavily.ts"));
   assert.deepEqual(packedPaths.filter((p) => p.endsWith(".test.ts")), []);
 });

src/providers/exa.test.ts

@@ -1,110 +1,120 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { createExaProvider } from "./exa.ts";
+import { buildFetchOptions, buildSearchOptions, createExaClient } from "./exa.ts";
 
-const baseConfig = {
+test("buildSearchOptions preserves Exa-native options and omits query", () => {
-  name: "exa-main",
+  const options = buildSearchOptions({
-  type: "exa" as const,
-  apiKey: "exa-test-key",
-  options: {
-    defaultSearchLimit: 7,
-    defaultFetchTextMaxCharacters: 9000,
-    defaultFetchHighlightsMaxCharacters: 1200,
-  },
-};
-
-test("createExaProvider maps generic search requests to Exa search with contents disabled", async () => {
-  let captured: { query: string; options: Record<string, unknown> } | undefined;
-
-  const provider = createExaProvider(baseConfig, () => ({
-    async search(query, options) {
-      captured = { query, options };
-      return {
-        requestId: "req-search-1",
-        searchTime: 123,
-        results: [
-          {
-            id: "doc-1",
-            title: "Exa Docs",
-            url: "https://exa.ai/docs",
-            publishedDate: "2026-04-09",
-            author: "Exa",
-            score: 0.98,
-          },
-        ],
-      };
-    },
-    async getContents() {
-      throw new Error("not used");
-    },
-  }));
-
-  const result = await provider.search({
     query: "exa docs",
+    type: "deep",
+    numResults: 3,
     includeDomains: ["exa.ai"],
-  });
+    includeText: ["agent memory"],
-
+    systemPrompt: "Prefer official docs",
-  assert.deepEqual(captured, {
+    outputSchema: {
-    query: "exa docs",
+      type: "text",
-    options: {
+      description: "Answer in bullets",
-      contents: false,
+    },
-      numResults: 7,
+    additionalQueries: ["pi coding agent"],
-      includeDomains: ["exa.ai"],
+    contents: {
-      excludeDomains: undefined,
+      text: {
-      startPublishedDate: undefined,
+        maxCharacters: 2000,
-      endPublishedDate: undefined,
+      },
-      category: undefined,
+      summary: true,
+    },
+  });
+
+  assert.deepEqual(options, {
+    type: "deep",
+    numResults: 3,
+    includeDomains: ["exa.ai"],
+    includeText: ["agent memory"],
+    systemPrompt: "Prefer official docs",
+    outputSchema: {
+      type: "text",
+      description: "Answer in bullets",
+    },
+    additionalQueries: ["pi coding agent"],
+    contents: {
+      text: {
+        maxCharacters: 2000,
+      },
+      summary: true,
     },
   });
-  assert.equal(result.providerName, "exa-main");
-  assert.equal(result.results[0]?.url, "https://exa.ai/docs");
 });
 
-test("createExaProvider fetch defaults to text and preserves per-url failures", async () => {
+test("buildSearchOptions returns undefined when only query is provided so Exa keeps its default search contents behavior", () => {
-  const calls: Array<{ urls: string[]; options: Record<string, unknown> }> = [];
+  assert.equal(buildSearchOptions({ query: "exa docs" }), undefined);
+});
 
-  const provider = createExaProvider(baseConfig, () => ({
+test("buildFetchOptions preserves Exa getContents options and omits urls", () => {
-    async search() {
+  const options = buildFetchOptions({
-      throw new Error("not used");
+    urls: ["https://exa.ai"],
+    text: {
+      maxCharacters: 5000,
+      includeHtmlTags: true,
     },
-    async getContents(urls, options) {
+    highlights: {
-      const requestUrls = Array.isArray(urls) ? urls : [urls];
+      query: "sdk",
-      calls.push({ urls: requestUrls, options });
+      maxCharacters: 300,
+    },
+    summary: true,
+    livecrawl: "preferred",
+    livecrawlTimeout: 2000,
+    maxAgeHours: 0,
+    filterEmptyResults: false,
+    subpages: 2,
+    subpageTarget: ["docs", "api"],
+    extras: {
+      links: 10,
+      imageLinks: 5,
+    },
+  });
 
-      if (requestUrls[0] === "https://bad.example") {
+  assert.deepEqual(options, {
-        throw new Error("429 rate limited");
+    text: {
-      }
+      maxCharacters: 5000,
+      includeHtmlTags: true,
+    },
+    highlights: {
+      query: "sdk",
+      maxCharacters: 300,
+    },
+    summary: true,
+    livecrawl: "preferred",
+    livecrawlTimeout: 2000,
+    maxAgeHours: 0,
+    filterEmptyResults: false,
+    subpages: 2,
+    subpageTarget: ["docs", "api"],
+    extras: {
+      links: 10,
+      imageLinks: 5,
+    },
+  });
+});
 
+test("createExaClient passes apiKey and baseUrl to the SDK factory", () => {
+  const calls: Array<{ apiKey: string; baseUrl?: string }> = [];
+
+  const client = createExaClient(
+    {
+      apiKey: "exa-test-key",
+      baseUrl: "https://exa.internal.example",
+    },
+    (apiKey, baseUrl) => {
+      calls.push({ apiKey, baseUrl });
       return {
-        requestId: `req-${calls.length}`,
+        async search() {
-        results: [
+          throw new Error("not used");
-          {
+        },
-            url: requestUrls[0],
+        async getContents() {
-            title: "Fetched page",
+          throw new Error("not used");
-            text: "Fetched body",
+        },
-          },
-        ],
       };
     },
-  }));
+  );
 
-  const result = await provider.fetch({
+  assert.ok(client);
-    urls: ["https://good.example", "https://bad.example"],
+  assert.deepEqual(calls, [{ apiKey: "exa-test-key", baseUrl: "https://exa.internal.example" }]);
-  });
-
-  assert.equal((calls[0]?.options.text as { maxCharacters: number }).maxCharacters, 9000);
-  assert.deepEqual(result.results, [
-    {
-      url: "https://good.example",
-      title: "Fetched page",
-      text: "Fetched body",
-      highlights: undefined,
-      summary: undefined,
-    },
-    {
-      url: "https://bad.example",
-      title: null,
-      error: "429 rate limited",
-    },
-  ]);
 });

src/providers/exa.ts

@@ -1,124 +1,32 @@
 import Exa from "exa-js";
-import type { ExaProviderConfig } from "../schema.ts";
+import type { ResolvedWebSearchConfig } from "../config.ts";
-import type {
+import type { WebFetchParams, WebSearchParams } from "../schema.ts";
-  NormalizedFetchRequest,
-  NormalizedFetchResponse,
-  NormalizedSearchRequest,
-  NormalizedSearchResponse,
-  WebProvider,
-} from "./types.ts";
 
 export interface ExaClientLike {
   search(query: string, options?: Record<string, unknown>): Promise<any>;
   getContents(urls: string[] | string, options?: Record<string, unknown>): Promise<any>;
 }
 
-export type ExaClientFactory = (apiKey: string) => ExaClientLike;
+export type ExaClientFactory = (apiKey: string, baseUrl?: string) => ExaClientLike;
 
-export function buildSearchOptions(config: ExaProviderConfig, request: NormalizedSearchRequest) {
+function omitUndefined<T extends Record<string, unknown>>(value: T) {
-  return {
+  const entries = Object.entries(value).filter(([, fieldValue]) => fieldValue !== undefined);
-    contents: false,
+  return entries.length > 0 ? (Object.fromEntries(entries) as Record<string, unknown>) : undefined;
-    numResults: request.limit ?? config.options?.defaultSearchLimit ?? 5,
-    includeDomains: request.includeDomains,
-    excludeDomains: request.excludeDomains,
-    startPublishedDate: request.startPublishedDate,
-    endPublishedDate: request.endPublishedDate,
-    category: request.category,
-  };
 }
 
-export function buildFetchOptions(config: ExaProviderConfig, request: NormalizedFetchRequest) {
+export function buildSearchOptions(request: WebSearchParams) {
-  const text = request.text ?? (!request.highlights && !request.summary);
+  const { query, ...options } = request;
-
+  return omitUndefined(options as Record<string, unknown>);
-  return {
-    ...(text
-      ? {
-          text: {
-            maxCharacters: request.textMaxCharacters ?? config.options?.defaultFetchTextMaxCharacters ?? 12000,
-          },
-        }
-      : {}),
-    ...(request.highlights
-      ? {
-          highlights: {
-            maxCharacters: config.options?.defaultFetchHighlightsMaxCharacters ?? 1000,
-          },
-        }
-      : {}),
-    ...(request.summary ? { summary: true } : {}),
-  };
 }
 
-export function createExaProvider(
+export function buildFetchOptions(request: WebFetchParams) {
-  config: ExaProviderConfig,
+  const { urls, ...options } = request;
-  createClient: ExaClientFactory = (apiKey) => new Exa(apiKey) as unknown as ExaClientLike,
+  return omitUndefined(options as Record<string, unknown>);
-): WebProvider {
+}
-  const client = createClient(config.apiKey);
+
-
+export function createExaClient(
-  return {
+  config: Pick<ResolvedWebSearchConfig, "apiKey" | "baseUrl">,
-    name: config.name,
+  createClient: ExaClientFactory = (apiKey, baseUrl) => new Exa(apiKey, baseUrl) as unknown as ExaClientLike,
-    type: config.type,
+) {
-
+  return createClient(config.apiKey, config.baseUrl);
-    async search(request: NormalizedSearchRequest): Promise<NormalizedSearchResponse> {
-      const response = await client.search(request.query, buildSearchOptions(config, request));
-      return {
-        providerName: config.name,
-        requestId: response.requestId,
-        searchTime: response.searchTime,
-        results: (response.results ?? []).map((item: any) => ({
-          id: item.id,
-          title: item.title ?? null,
-          url: item.url,
-          publishedDate: item.publishedDate,
-          author: item.author,
-          score: item.score,
-        })),
-      };
-    },
-
-    async fetch(request: NormalizedFetchRequest): Promise<NormalizedFetchResponse> {
-      const requestIds: string[] = [];
-      const options = buildFetchOptions(config, request);
-
-      const results = await Promise.all(
-        request.urls.map(async (url) => {
-          try {
-            const response = await client.getContents([url], options);
-            if (response.requestId) {
-              requestIds.push(response.requestId);
-            }
-
-            const item = response.results?.[0];
-            if (!item) {
-              return {
-                url,
-                title: null,
-                error: "No content returned",
-              };
-            }
-
-            return {
-              url: item.url ?? url,
-              title: item.title ?? null,
-              text: typeof item.text === "string" ? item.text : undefined,
-              highlights: Array.isArray(item.highlights) ? item.highlights : undefined,
-              summary: typeof item.summary === "string" ? item.summary : undefined,
-            };
-          } catch (error) {
-            return {
-              url,
-              title: null,
-              error: (error as Error).message,
-            };
-          }
-        }),
-      );
-
-      return {
-        providerName: config.name,
-        requestIds,
-        results,
-      };
-    },
-  };
 }

src/providers/firecrawl.test.ts

@@ -1,213 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { createFirecrawlProvider } from "./firecrawl.ts";
-
-const cloudConfig = {
-  name: "firecrawl-main",
-  type: "firecrawl" as const,
-  apiKey: "fc-test-key",
-  options: {
-    defaultSearchLimit: 6,
-  },
-};
-
-test("createFirecrawlProvider maps search requests to Firecrawl /search", async () => {
-  let capturedUrl = "";
-  let capturedInit: RequestInit | undefined;
-
-  const provider = createFirecrawlProvider(cloudConfig, async (url, init) => {
-    capturedUrl = String(url);
-    capturedInit = init;
-    return new Response(
-      JSON.stringify({
-        success: true,
-        id: "search-1",
-        data: {
-          web: [
-            {
-              url: "https://pi.dev",
-              title: "Pi Docs",
-              description: "Pi docs summary",
-              markdown: "# Pi Docs",
-            },
-          ],
-        },
-      }),
-      { status: 200 },
-    );
-  });
-
-  const result = await provider.search({
-    query: "pi docs",
-    limit: 4,
-    includeDomains: ["pi.dev"],
-    excludeDomains: ["bad.example"],
-    firecrawl: {
-      country: "DE",
-      location: "Berlin, Germany",
-      categories: ["github"],
-      scrapeOptions: {
-        formats: ["markdown", "summary"],
-      },
-    },
-  });
-
-  const body = JSON.parse(String(capturedInit?.body));
-  assert.equal(capturedUrl, "https://api.firecrawl.dev/v2/search");
-  assert.deepEqual(capturedInit?.headers, {
-    "content-type": "application/json",
-    authorization: "Bearer fc-test-key",
-  });
-  assert.equal(body.query, "pi docs site:pi.dev -site:bad.example");
-  assert.equal(body.limit, 4);
-  assert.equal(body.country, "DE");
-  assert.equal(body.location, "Berlin, Germany");
-  assert.deepEqual(body.categories, ["github"]);
-  assert.deepEqual(body.scrapeOptions, {
-    formats: ["markdown", "summary"],
-  });
-  assert.equal(result.requestId, "search-1");
-  assert.equal(result.results[0]?.title, "Pi Docs");
-  assert.equal(result.results[0]?.content, "Pi docs summary");
-  assert.equal(result.results[0]?.rawContent, "# Pi Docs");
-});
-
-test("createFirecrawlProvider omits auth for self-hosted baseUrl when no apiKey is configured", async () => {
-  let capturedUrl = "";
-  let capturedInit: RequestInit | undefined;
-
-  const provider = createFirecrawlProvider(
-    {
-      name: "firecrawl-selfhosted",
-      type: "firecrawl",
-      baseUrl: "https://firecrawl.internal.example/v2",
-    },
-    async (url, init) => {
-      capturedUrl = String(url);
-      capturedInit = init;
-      return new Response(
-        JSON.stringify({
-          success: true,
-          data: {
-            web: [],
-          },
-        }),
-        { status: 200 },
-      );
-    },
-  );
-
-  await provider.search({
-    query: "pi docs",
-  });
-
-  assert.equal(capturedUrl, "https://firecrawl.internal.example/v2/search");
-  assert.deepEqual(capturedInit?.headers, {
-    "content-type": "application/json",
-  });
-});
-
-test("createFirecrawlProvider fetches each URL via /scrape and preserves per-url failures", async () => {
-  const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
-
-  const provider = createFirecrawlProvider(cloudConfig, async (url, init) => {
-    calls.push({ url: String(url), init });
-    const body = JSON.parse(String(init?.body));
-
-    if (body.url === "https://bad.example") {
-      return new Response(JSON.stringify({ error: "Payment required" }), {
-        status: 402,
-        statusText: "Payment Required",
-      });
-    }
-
-    return new Response(
-      JSON.stringify({
-        success: true,
-        data: {
-          metadata: {
-            title: "Pi",
-            sourceURL: body.url,
-          },
-          markdown: "Fetched body",
-          summary: "Short summary",
-          images: ["https://pi.dev/logo.png"],
-        },
-      }),
-      { status: 200 },
-    );
-  });
-
-  const result = await provider.fetch({
-    urls: ["https://pi.dev", "https://bad.example"],
-    text: true,
-    summary: true,
-    firecrawl: {
-      formats: ["markdown", "summary", "images"],
-    },
-  });
-
-  const firstBody = JSON.parse(String(calls[0]?.init?.body));
-  assert.equal(calls[0]?.url, "https://api.firecrawl.dev/v2/scrape");
-  assert.deepEqual(firstBody, {
-    url: "https://pi.dev",
-    formats: ["markdown", "summary", "images"],
-  });
-  assert.deepEqual(result.results, [
-    {
-      url: "https://pi.dev",
-      title: "Pi",
-      text: "Fetched body",
-      summary: "Short summary",
-      images: ["https://pi.dev/logo.png"],
-    },
-    {
-      url: "https://bad.example",
-      title: null,
-      error: 'Provider "firecrawl-main" HTTP 402 Payment Required: {"error":"Payment required"}',
-    },
-  ]);
-});
-
-test("createFirecrawlProvider limits concurrent scrape requests", async () => {
-  let active = 0;
-  let maxActive = 0;
-
-  const provider = createFirecrawlProvider(cloudConfig, async (_url, init) => {
-    active += 1;
-    maxActive = Math.max(maxActive, active);
-
-    const body = JSON.parse(String(init?.body));
-    await new Promise((resolve) => setTimeout(resolve, 10));
-
-    active -= 1;
-    return new Response(
-      JSON.stringify({
-        success: true,
-        data: {
-          metadata: {
-            title: body.url,
-            sourceURL: body.url,
-          },
-          markdown: `Fetched ${body.url}`,
-        },
-      }),
-      { status: 200 },
-    );
-  });
-
-  const urls = [
-    "https://a.example",
-    "https://b.example",
-    "https://c.example",
-    "https://d.example",
-    "https://e.example",
-    "https://f.example",
-    "https://g.example",
-  ];
-
-  const result = await provider.fetch({ urls });
-
-  assert.equal(result.results.length, urls.length);
-  assert.ok(maxActive <= 4, `expected max concurrency <= 4, got ${maxActive}`);
-});

src/providers/firecrawl.ts

@@ -1,240 +0,0 @@
-import type { FirecrawlProviderConfig } from "../schema.ts";
-import { postJson, type ProviderFetchLike } from "./http.ts";
-import type {
-  NormalizedFetchRequest,
-  NormalizedFetchResponse,
-  NormalizedSearchRequest,
-  NormalizedSearchResponse,
-  WebProvider,
-} from "./types.ts";
-
-const DEFAULT_FIRECRAWL_BASE_URL = "https://api.firecrawl.dev/v2";
-const DEFAULT_FIRECRAWL_FETCH_CONCURRENCY = 4;
-
-type FirecrawlSearchPayload = {
-  id?: string;
-  request_id?: string;
-  data?: {
-    web?: Array<{
-      url: string;
-      title?: string;
-      description?: string;
-      markdown?: string;
-      score?: number;
-      published_date?: string;
-      images?: string[];
-    }>;
-  };
-};
-
-type FirecrawlScrapePayload = {
-  success?: boolean;
-  data?: {
-    markdown?: string;
-    summary?: string;
-    images?: string[];
-    title?: string;
-    metadata?: {
-      title?: string;
-      sourceURL?: string;
-    };
-  };
-};
-
-function resolveBaseUrl(config: FirecrawlProviderConfig) {
-  return config.baseUrl ?? DEFAULT_FIRECRAWL_BASE_URL;
-}
-
-function createProviderValidationError(providerName: string, message: string) {
-  return new Error(`Provider "${providerName}" ${message}`);
-}
-
-export function validateFirecrawlSearchRequest(providerName: string, request: NormalizedSearchRequest) {
-  if ((request.includeDomains?.length ?? 0) > 1) {
-    throw createProviderValidationError(providerName, "accepts at most one includeDomains entry.");
-  }
-
-  if (request.category && request.firecrawl?.categories?.length) {
-    throw createProviderValidationError(providerName, "does not accept both top-level category and firecrawl.categories.");
-  }
-}
-
-export function validateFirecrawlFetchRequest(providerName: string, request: NormalizedFetchRequest) {
-  // Keep this defensive check here even though runtime validation also rejects it,
-  // so direct provider callers still get the same provider-specific error.
-  if (request.highlights) {
-    throw createProviderValidationError(providerName, 'does not support generic fetch option "highlights".');
-  }
-
-  const overrideFormats = request.firecrawl?.formats;
-  if (overrideFormats?.length) {
-    if (request.text && !overrideFormats.includes("markdown")) {
-      throw createProviderValidationError(
-        providerName,
-        'requires firecrawl.formats to include "markdown" when text is true.',
-      );
-    }
-    if (request.summary && !overrideFormats.includes("summary")) {
-      throw createProviderValidationError(
-        providerName,
-        'requires firecrawl.formats to include "summary" when summary is true.',
-      );
-    }
-  }
-}
-
-function appendSearchOperators(query: string, includeDomains?: string[], excludeDomains?: string[]) {
-  const parts = [query.trim()];
-  if (includeDomains?.[0]) {
-    parts.push(`site:${includeDomains[0]}`);
-  }
-  for (const domain of excludeDomains ?? []) {
-    parts.push(`-site:${domain}`);
-  }
-
-  return parts.join(" ").trim();
-}
-
-function resolveSearchCategories(request: NormalizedSearchRequest) {
-  if (request.firecrawl?.categories?.length) {
-    return request.firecrawl.categories;
-  }
-
-  return request.category ? [request.category] : undefined;
-}
-
-function uniqueFormats(formats: string[]) {
-  return [...new Set(formats)];
-}
-
-function resolveFetchFormats(request: NormalizedFetchRequest) {
-  const overrideFormats = request.firecrawl?.formats;
-  if (overrideFormats?.length) {
-    return uniqueFormats([...overrideFormats]);
-  }
-
-  const formats: string[] = [];
-  const wantsText = request.text ?? (!request.highlights && !request.summary);
-  if (wantsText) {
-    formats.push("markdown");
-  }
-  if (request.summary) {
-    formats.push("summary");
-  }
-
-  return uniqueFormats(formats.length > 0 ? formats : ["markdown"]);
-}
-
-async function mapWithConcurrency<TItem, TResult>(
-  items: TItem[],
-  concurrency: number,
-  iteratee: (item: TItem) => Promise<TResult>,
-): Promise<TResult[]> {
-  const results = new Array<TResult>(items.length);
-  let nextIndex = 0;
-
-  const workers = Array.from({ length: Math.max(1, Math.min(concurrency, items.length)) }, async () => {
-    while (nextIndex < items.length) {
-      const currentIndex = nextIndex;
-      nextIndex += 1;
-      results[currentIndex] = await iteratee(items[currentIndex]!);
-    }
-  });
-
-  await Promise.all(workers);
-  return results;
-}
-
-function pickRequestId(payload: { id?: string; request_id?: string }) {
-  return typeof payload.id === "string"
-    ? payload.id
-    : typeof payload.request_id === "string"
-      ? payload.request_id
-      : undefined;
-}
-
-export function createFirecrawlProvider(
-  config: FirecrawlProviderConfig,
-  fetchImpl: ProviderFetchLike = fetch,
-): WebProvider {
-  const baseUrl = resolveBaseUrl(config);
-
-  return {
-    name: config.name,
-    type: config.type,
-
-    async search(request: NormalizedSearchRequest): Promise<NormalizedSearchResponse> {
-      validateFirecrawlSearchRequest(config.name, request);
-
-      const payload = await postJson<FirecrawlSearchPayload>({
-        providerName: config.name,
-        baseUrl,
-        path: "/search",
-        apiKey: config.apiKey,
-        fetchImpl,
-        body: {
-          query: appendSearchOperators(request.query, request.includeDomains, request.excludeDomains),
-          limit: request.limit ?? config.options?.defaultSearchLimit ?? 5,
-          country: request.firecrawl?.country,
-          location: request.firecrawl?.location,
-          categories: resolveSearchCategories(request),
-          scrapeOptions: request.firecrawl?.scrapeOptions,
-        },
-      });
-
-      return {
-        providerName: config.name,
-        requestId: pickRequestId(payload),
-        results: (payload.data?.web ?? []).map((item) => ({
-          title: item.title ?? null,
-          url: item.url,
-          content: typeof item.description === "string" ? item.description : undefined,
-          rawContent: typeof item.markdown === "string" ? item.markdown : undefined,
-          score: item.score,
-          publishedDate: item.published_date,
-          images: Array.isArray(item.images) ? item.images : undefined,
-        })),
-      };
-    },
-
-    async fetch(request: NormalizedFetchRequest): Promise<NormalizedFetchResponse> {
-      validateFirecrawlFetchRequest(config.name, request);
-      const formats = resolveFetchFormats(request);
-
-      const results = await mapWithConcurrency(request.urls, DEFAULT_FIRECRAWL_FETCH_CONCURRENCY, async (url) => {
-        try {
-          const payload = await postJson<FirecrawlScrapePayload>({
-            providerName: config.name,
-            baseUrl,
-            path: "/scrape",
-            apiKey: config.apiKey,
-            fetchImpl,
-            body: {
-              url,
-              formats,
-            },
-          });
-
-          return {
-            url: payload.data?.metadata?.sourceURL ?? url,
-            title: payload.data?.metadata?.title ?? payload.data?.title ?? null,
-            text: typeof payload.data?.markdown === "string" ? payload.data.markdown : undefined,
-            summary: typeof payload.data?.summary === "string" ? payload.data.summary : undefined,
-            images: Array.isArray(payload.data?.images) ? payload.data.images : undefined,
-          };
-        } catch (error) {
-          return {
-            url,
-            title: null,
-            error: error instanceof Error ? error.message : String(error),
-          };
-        }
-      });
-
-      return {
-        providerName: config.name,
-        results,
-      };
-    },
-  };
-}

src/providers/http.test.ts

@@ -1,24 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { postJson } from "./http.ts";
-
-test("postJson surfaces invalid JSON responses with HTTP context", async () => {
-  await assert.rejects(
-    () =>
-      postJson({
-        providerName: "firecrawl-main",
-        baseUrl: "https://api.firecrawl.dev/v2",
-        path: "/search",
-        body: { query: "pi docs" },
-        fetchImpl: async () =>
-          new Response("<html>not json</html>", {
-            status: 200,
-            statusText: "OK",
-            headers: {
-              "content-type": "text/html",
-            },
-          }),
-      }),
-    /Provider "firecrawl-main" HTTP 200 OK: invalid JSON response: <html>not json<\/html>/,
-  );
-});

src/providers/http.ts

@@ -1,59 +0,0 @@
-export type ProviderFetchLike = (input: string, init?: RequestInit) => Promise<Response>;
-
-interface PostJsonOptions {
-  providerName: string;
-  baseUrl: string;
-  path: string;
-  apiKey?: string;
-  body: unknown;
-  fetchImpl?: ProviderFetchLike;
-}
-
-export function joinApiUrl(baseUrl: string, path: string) {
-  const normalizedBaseUrl = baseUrl.replace(/\/+$/, "");
-  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-  return `${normalizedBaseUrl}${normalizedPath}`;
-}
-
-function formatHttpErrorMessage(providerName: string, response: Response, text: string) {
-  return `Provider "${providerName}" HTTP ${response.status} ${response.statusText}: ${text.slice(0, 300)}`;
-}
-
-export async function readHttpError(providerName: string, response: Response): Promise<never> {
-  const text = await response.text();
-  throw new Error(formatHttpErrorMessage(providerName, response, text));
-}
-
-export async function postJson<T>({
-  providerName,
-  baseUrl,
-  path,
-  apiKey,
-  body,
-  fetchImpl = fetch,
-}: PostJsonOptions): Promise<T> {
-  const headers: Record<string, string> = {
-    "content-type": "application/json",
-  };
-
-  if (apiKey) {
-    headers.authorization = `Bearer ${apiKey}`;
-  }
-
-  const response = await fetchImpl(joinApiUrl(baseUrl, path), {
-    method: "POST",
-    headers,
-    body: JSON.stringify(body),
-  });
-
-  const text = await response.text();
-  if (!response.ok) {
-    throw new Error(formatHttpErrorMessage(providerName, response, text));
-  }
-
-  try {
-    return JSON.parse(text) as T;
-  } catch {
-    throw new Error(formatHttpErrorMessage(providerName, response, `invalid JSON response: ${text}`));
-  }
-}

src/providers/registry.ts

@@ -1,149 +0,0 @@
-import type { FirecrawlProviderConfig, TavilyProviderConfig, WebSearchProviderConfig, ExaProviderConfig } from "../schema.ts";
-import { createExaProvider } from "./exa.ts";
-import {
-  createFirecrawlProvider,
-  validateFirecrawlFetchRequest,
-  validateFirecrawlSearchRequest,
-} from "./firecrawl.ts";
-import { createTavilyProvider } from "./tavily.ts";
-import type { NormalizedFetchRequest, NormalizedSearchRequest, WebProvider } from "./types.ts";
-
-export type ProviderOptionBlock = "tavily" | "firecrawl";
-
-interface ProviderCapabilities {
-  searchOptionBlocks: ProviderOptionBlock[];
-  fetchOptionBlocks: ProviderOptionBlock[];
-  fetchFeatures: {
-    text: boolean;
-    highlights: boolean;
-    summary: boolean;
-  };
-}
-
-interface ProviderDescriptor<TConfig extends WebSearchProviderConfig = WebSearchProviderConfig> {
-  type: TConfig["type"];
-  capabilities: ProviderCapabilities;
-  createProvider(config: TConfig): WebProvider;
-  validateSearchRequest?(providerName: string, request: NormalizedSearchRequest): void;
-  validateFetchRequest?(providerName: string, request: NormalizedFetchRequest): void;
-}
-
-const providerDescriptors = {
-  exa: {
-    type: "exa",
-    capabilities: {
-      searchOptionBlocks: [],
-      fetchOptionBlocks: [],
-      fetchFeatures: {
-        text: true,
-        highlights: true,
-        summary: true,
-      },
-    },
-    createProvider(config: ExaProviderConfig) {
-      return createExaProvider(config);
-    },
-  },
-  tavily: {
-    type: "tavily",
-    capabilities: {
-      searchOptionBlocks: ["tavily"],
-      fetchOptionBlocks: ["tavily"],
-      fetchFeatures: {
-        text: true,
-        highlights: true,
-        summary: true,
-      },
-    },
-    createProvider(config: TavilyProviderConfig) {
-      return createTavilyProvider(config);
-    },
-  },
-  firecrawl: {
-    type: "firecrawl",
-    capabilities: {
-      searchOptionBlocks: ["firecrawl"],
-      fetchOptionBlocks: ["firecrawl"],
-      fetchFeatures: {
-        text: true,
-        highlights: false,
-        summary: true,
-      },
-    },
-    createProvider(config: FirecrawlProviderConfig) {
-      return createFirecrawlProvider(config);
-    },
-    validateSearchRequest(providerName: string, request: NormalizedSearchRequest) {
-      validateFirecrawlSearchRequest(providerName, request);
-    },
-    validateFetchRequest(providerName: string, request: NormalizedFetchRequest) {
-      validateFirecrawlFetchRequest(providerName, request);
-    },
-  },
-} satisfies Record<WebSearchProviderConfig["type"], ProviderDescriptor>;
-
-function validateOptionBlocks(
-  providerName: string,
-  acceptedOptionBlocks: ProviderOptionBlock[],
-  blocks: Partial<Record<ProviderOptionBlock, unknown>>,
-) {
-  for (const optionBlock of Object.keys(blocks) as ProviderOptionBlock[]) {
-    if (blocks[optionBlock] === undefined) {
-      continue;
-    }
-    if (!acceptedOptionBlocks.includes(optionBlock)) {
-      throw new Error(`Provider "${providerName}" does not accept the "${optionBlock}" options block.`);
-    }
-  }
-}
-
-export function getProviderDescriptor(provider: Pick<WebSearchProviderConfig, "type"> | WebSearchProviderConfig["type"]) {
-  const type = typeof provider === "string" ? provider : provider.type;
-  const descriptor = providerDescriptors[type as keyof typeof providerDescriptors];
-  if (!descriptor) {
-    throw new Error(`Unknown provider type: ${type}`);
-  }
-  return descriptor;
-}
-
-export function createProviderFromConfig(providerConfig: WebSearchProviderConfig) {
-  switch (providerConfig.type) {
-    case "exa":
-      return providerDescriptors.exa.createProvider(providerConfig);
-    case "tavily":
-      return providerDescriptors.tavily.createProvider(providerConfig);
-    case "firecrawl":
-      return providerDescriptors.firecrawl.createProvider(providerConfig);
-    default:
-      throw new Error(`Unknown provider type: ${(providerConfig as { type: string }).type}`);
-  }
-}
-
-export function validateSearchRequestForProvider(providerName: string, providerConfig: WebSearchProviderConfig, request: NormalizedSearchRequest) {
-  const descriptor = getProviderDescriptor(providerConfig);
-  validateOptionBlocks(providerName, descriptor.capabilities.searchOptionBlocks, {
-    tavily: request.tavily,
-    firecrawl: request.firecrawl,
-  });
-  descriptor.validateSearchRequest?.(providerName, request);
-}
-
-export function validateFetchRequestForProvider(providerName: string, providerConfig: WebSearchProviderConfig, request: NormalizedFetchRequest) {
-  const descriptor = getProviderDescriptor(providerConfig);
-  validateOptionBlocks(providerName, descriptor.capabilities.fetchOptionBlocks, {
-    tavily: request.tavily,
-    firecrawl: request.firecrawl,
-  });
-
-  if (request.text && !descriptor.capabilities.fetchFeatures.text) {
-    throw new Error(`Provider "${providerName}" does not support generic fetch option "text".`);
-  }
-  if (request.highlights && !descriptor.capabilities.fetchFeatures.highlights) {
-    throw new Error(`Provider "${providerName}" does not support generic fetch option "highlights".`);
-  }
-  if (request.summary && !descriptor.capabilities.fetchFeatures.summary) {
-    throw new Error(`Provider "${providerName}" does not support generic fetch option "summary".`);
-  }
-
-  descriptor.validateFetchRequest?.(providerName, request);
-}

src/providers/tavily.test.ts

@@ -1,84 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { createTavilyProvider } from "./tavily.ts";
-
-const baseConfig = {
-  name: "tavily-main",
-  type: "tavily" as const,
-  apiKey: "tvly-test-key",
-  options: {
-    defaultSearchLimit: 6,
-    defaultFetchTextMaxCharacters: 8000,
-  },
-};
-
-test("createTavilyProvider maps search requests to Tavily REST params", async () => {
-  let captured: RequestInit | undefined;
-
-  const provider = createTavilyProvider(baseConfig, async (_url, init) => {
-    captured = init;
-    return new Response(
-      JSON.stringify({
-        answer: "pi is a coding agent",
-        results: [
-          {
-            title: "pi docs",
-            url: "https://pi.dev",
-            content: "pi docs summary",
-            raw_content: "long raw body",
-          },
-        ],
-      }),
-      { status: 200 },
-    );
-  });
-
-  const result = await provider.search({
-    query: "pi docs",
-    limit: 4,
-    tavily: {
-      includeAnswer: true,
-      includeRawContent: true,
-      searchDepth: "advanced",
-    },
-  });
-
-  const body = JSON.parse(String(captured?.body));
-  assert.equal(body.max_results, 4);
-  assert.equal(body.include_answer, true);
-  assert.equal(body.include_raw_content, true);
-  assert.equal(body.search_depth, "advanced");
-  assert.equal(result.answer, "pi is a coding agent");
-  assert.equal(result.results[0]?.rawContent, "long raw body");
-});
-
-test("createTavilyProvider maps extract responses into normalized fetch results", async () => {
-  const provider = createTavilyProvider(baseConfig, async () => {
-    return new Response(
-      JSON.stringify({
-        results: [
-          {
-            url: "https://pi.dev",
-            title: "pi",
-            raw_content: "Fetched body",
-            images: ["https://pi.dev/logo.png"],
-            favicon: "https://pi.dev/favicon.ico",
-          },
-        ],
-      }),
-      { status: 200 },
-    );
-  });
-
-  const result = await provider.fetch({
-    urls: ["https://pi.dev"],
-    tavily: {
-      includeImages: true,
-      includeFavicon: true,
-    },
-  });
-
-  assert.equal(result.results[0]?.text, "Fetched body");
-  assert.deepEqual(result.results[0]?.images, ["https://pi.dev/logo.png"]);
-  assert.equal(result.results[0]?.favicon, "https://pi.dev/favicon.ico");
-});

src/providers/tavily.ts

@@ -1,91 +0,0 @@
-import type { TavilyProviderConfig } from "../schema.ts";
-import { postJson, type ProviderFetchLike } from "./http.ts";
-import type {
-  NormalizedFetchRequest,
-  NormalizedFetchResponse,
-  NormalizedSearchRequest,
-  NormalizedSearchResponse,
-  WebProvider,
-} from "./types.ts";
-
-export function createTavilyProvider(
-  config: TavilyProviderConfig,
-  fetchImpl: ProviderFetchLike = fetch,
-): WebProvider {
-  return {
-    name: config.name,
-    type: config.type,
-
-    async search(request: NormalizedSearchRequest): Promise<NormalizedSearchResponse> {
-      const data = await postJson<any>({
-        providerName: config.name,
-        baseUrl: "https://api.tavily.com",
-        path: "/search",
-        apiKey: config.apiKey,
-        fetchImpl,
-        body: {
-          query: request.query,
-          max_results: request.limit ?? config.options?.defaultSearchLimit ?? 5,
-          include_domains: request.includeDomains,
-          exclude_domains: request.excludeDomains,
-          start_date: request.startPublishedDate,
-          end_date: request.endPublishedDate,
-          topic: request.tavily?.topic,
-          search_depth: request.tavily?.searchDepth,
-          time_range: request.tavily?.timeRange,
-          days: request.tavily?.days,
-          chunks_per_source: request.tavily?.chunksPerSource,
-          include_answer: request.tavily?.includeAnswer,
-          include_raw_content: request.tavily?.includeRawContent,
-          include_images: request.tavily?.includeImages,
-        },
-      });
-
-      return {
-        providerName: config.name,
-        requestId: data.request_id,
-        answer: typeof data.answer === "string" ? data.answer : undefined,
-        results: (data.results ?? []).map((item: any) => ({
-          title: item.title ?? null,
-          url: item.url,
-          content: typeof item.content === "string" ? item.content : undefined,
-          rawContent: typeof item.raw_content === "string" ? item.raw_content : undefined,
-          images: Array.isArray(item.images) ? item.images : undefined,
-          score: item.score,
-          publishedDate: item.published_date,
-        })),
-      };
-    },
-
-    async fetch(request: NormalizedFetchRequest): Promise<NormalizedFetchResponse> {
-      const data = await postJson<any>({
-        providerName: config.name,
-        baseUrl: "https://api.tavily.com",
-        path: "/extract",
-        apiKey: config.apiKey,
-        fetchImpl,
-        body: {
-          urls: request.urls,
-          query: request.tavily?.query,
-          extract_depth: request.tavily?.extractDepth,
-          chunks_per_source: request.tavily?.chunksPerSource,
-          include_images: request.tavily?.includeImages,
-          include_favicon: request.tavily?.includeFavicon,
-          format: request.tavily?.format,
-        },
-      });
-
-      return {
-        providerName: config.name,
-        requestIds: data.request_id ? [data.request_id] : [],
-        results: (data.results ?? []).map((item: any) => ({
-          url: item.url,
-          title: item.title ?? null,
-          text: typeof item.raw_content === "string" ? item.raw_content : undefined,
-          images: Array.isArray(item.images) ? item.images : undefined,
-          favicon: typeof item.favicon === "string" ? item.favicon : undefined,
-        })),
-      };
-    },
-  };
-}

src/providers/types.ts

@@ -1,100 +0,0 @@
-export interface TavilySearchOptions {
-  searchDepth?: "advanced" | "basic" | "fast" | "ultra-fast";
-  topic?: "general" | "news" | "finance";
-  timeRange?: string;
-  days?: number;
-  chunksPerSource?: number;
-  includeAnswer?: boolean;
-  includeRawContent?: boolean;
-  includeImages?: boolean;
-}
-
-export interface TavilyFetchOptions {
-  query?: string;
-  extractDepth?: "basic" | "advanced";
-  chunksPerSource?: number;
-  includeImages?: boolean;
-  includeFavicon?: boolean;
-  format?: string;
-}
-
-export interface FirecrawlSearchOptions {
-  country?: string;
-  location?: string;
-  categories?: string[];
-  scrapeOptions?: {
-    formats?: Array<"markdown" | "summary">;
-  };
-}
-
-export interface FirecrawlFetchOptions {
-  formats?: Array<"markdown" | "summary" | "images">;
-}
-
-export interface NormalizedSearchRequest {
-  query: string;
-  limit?: number;
-  includeDomains?: string[];
-  excludeDomains?: string[];
-  startPublishedDate?: string;
-  endPublishedDate?: string;
-  category?: string;
-  provider?: string;
-  tavily?: TavilySearchOptions;
-  firecrawl?: FirecrawlSearchOptions;
-}
-
-export interface NormalizedSearchResult {
-  id?: string;
-  title: string | null;
-  url: string;
-  publishedDate?: string;
-  author?: string;
-  score?: number;
-  content?: string;
-  rawContent?: string;
-  images?: string[];
-}
-
-export interface NormalizedSearchResponse {
-  providerName: string;
-  requestId?: string;
-  searchTime?: number;
-  answer?: string;
-  results: NormalizedSearchResult[];
-}
-
-export interface NormalizedFetchRequest {
-  urls: string[];
-  text?: boolean;
-  highlights?: boolean;
-  summary?: boolean;
-  textMaxCharacters?: number;
-  provider?: string;
-  tavily?: TavilyFetchOptions;
-  firecrawl?: FirecrawlFetchOptions;
-}
-
-export interface NormalizedFetchResult {
-  url: string;
-  title: string | null;
-  text?: string;
-  highlights?: string[];
-  summary?: string;
-  images?: string[];
-  favicon?: string;
-  error?: string;
-}
-
-export interface NormalizedFetchResponse {
-  providerName: string;
-  requestIds?: string[];
-  results: NormalizedFetchResult[];
-}
-
-export interface WebProvider {
-  name: string;
-  type: string;
-  search(request: NormalizedSearchRequest): Promise<NormalizedSearchResponse>;
-  fetch(request: NormalizedFetchRequest): Promise<NormalizedFetchResponse>;
-}

src/runtime.test.ts

@@ -2,463 +2,137 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { createWebSearchRuntime } from "./runtime.ts";
 
-function createProvider(name: string, type: string, handlers: Partial<any>) {
+test("runtime search delegates to Exa search and returns the raw Exa response", async () => {
-  return {
+  const calls: Array<{ query: string; options: unknown }> = [];
-    name,
-    type,
-    async search(request: any) {
-      return handlers.search?.(request);
-    },
-    async fetch(request: any) {
-      return handlers.fetch?.(request);
-    },
-  };
-}
 
-test("search follows configured fallback chains and records every attempt", async () => {
   const runtime = createWebSearchRuntime({
     loadConfig: async () => ({
       path: "test.json",
-      defaultProviderName: "firecrawl-main",
+      apiKey: "exa-test-key",
-      defaultProvider: {
+      baseUrl: "https://api.exa.ai",
-        name: "firecrawl-main",
-        type: "firecrawl",
-        apiKey: "fc",
-        fallbackProviders: ["tavily-backup"],
-      },
-      providers: [
-        {
-          name: "firecrawl-main",
-          type: "firecrawl",
-          apiKey: "fc",
-          fallbackProviders: ["tavily-backup"],
-        },
-        {
-          name: "tavily-backup",
-          type: "tavily",
-          apiKey: "tvly",
-          fallbackProviders: ["exa-fallback"],
-        },
-        { name: "exa-fallback", type: "exa", apiKey: "exa" },
-      ],
-      providersByName: new Map([
-        [
-          "firecrawl-main",
-          { name: "firecrawl-main", type: "firecrawl", apiKey: "fc", fallbackProviders: ["tavily-backup"] },
-        ],
-        [
-          "tavily-backup",
-          { name: "tavily-backup", type: "tavily", apiKey: "tvly", fallbackProviders: ["exa-fallback"] },
-        ],
-        ["exa-fallback", { name: "exa-fallback", type: "exa", apiKey: "exa" }],
-      ]),
     }),
-    createProvider(providerConfig) {
+    createClient(config) {
-      if (providerConfig.name === "exa-fallback") {
+      assert.equal(config.apiKey, "exa-test-key");
-        return createProvider(providerConfig.name, providerConfig.type, {
+      assert.equal(config.baseUrl, "https://api.exa.ai");
-          search: async () => ({
+      return {
-            providerName: providerConfig.name,
+        async search(query, options) {
-            results: [{ title: "Exa hit", url: "https://exa.ai" }],
+          calls.push({ query, options });
-          }),
+          return {
-        });
+            requestId: "req-search-1",
-      }
+            searchTime: 42,
-
+            output: {
-      return createProvider(providerConfig.name, providerConfig.type, {
+              content: "Official answer",
-        search: async () => {
+              grounding: [],
-          throw new Error(`boom:${providerConfig.name}`);
+            },
+            results: [
+              {
+                id: "doc-1",
+                title: "Exa Docs",
+                url: "https://exa.ai/docs",
+                text: "Docs body",
+              },
+            ],
+          };
         },
-      });
+        async getContents() {
+          throw new Error("not used");
+        },
+      };
     },
   });
 
-  const result = await runtime.search({ query: "pi docs" });
+  const response = await runtime.search({
+    query: "exa docs",
+    type: "deep",
+    contents: false,
+  });
 
-  assert.equal(result.execution.actualProviderName, "exa-fallback");
+  assert.deepEqual(calls, [
-  assert.equal(result.execution.failoverFromProviderName, "firecrawl-main");
-  assert.deepEqual(result.execution.attempts, [
     {
-      providerName: "firecrawl-main",
+      query: "exa docs",
-      status: "failed",
+      options: {
-      reason: "boom:firecrawl-main",
+        type: "deep",
-    },
+        contents: false,
-    {
+      },
-      providerName: "tavily-backup",
-      status: "failed",
-      reason: "boom:tavily-backup",
-    },
-    {
-      providerName: "exa-fallback",
-      status: "succeeded",
     },
   ]);
+  assert.equal(response.requestId, "req-search-1");
+  assert.equal(response.output?.content, "Official answer");
 });
 
-test("search rejects a mismatched provider-specific options block before provider execution", async () => {
+test("runtime fetch delegates to Exa getContents with the full url batch", async () => {
-  let callCount = 0;
+  const calls: Array<{ urls: string[]; options: unknown }> = [];
 
   const runtime = createWebSearchRuntime({
     loadConfig: async () => ({
       path: "test.json",
-      defaultProviderName: "firecrawl-main",
+      apiKey: "exa-test-key",
-      defaultProvider: { name: "firecrawl-main", type: "firecrawl", apiKey: "fc" },
+      baseUrl: undefined,
-      providers: [{ name: "firecrawl-main", type: "firecrawl", apiKey: "fc" }],
-      providersByName: new Map([["firecrawl-main", { name: "firecrawl-main", type: "firecrawl", apiKey: "fc" }]]),
     }),
-    createProvider(providerConfig) {
+    createClient() {
-      return createProvider(providerConfig.name, providerConfig.type, {
+      return {
-        search: async () => {
+        async search() {
-          callCount += 1;
+          throw new Error("not used");
+        },
+        async getContents(urls, options) {
+          calls.push({ urls: Array.isArray(urls) ? urls : [urls], options });
           return {
-            providerName: providerConfig.name,
+            requestId: "req-fetch-1",
-            results: [],
+            results: [
+              {
+                id: "doc-1",
+                title: "Pi",
+                url: "https://pi.dev/",
+                summary: "Agent docs",
+              },
+            ],
           };
         },
-      });
+      };
     },
   });
 
-  await assert.rejects(
+  const response = await runtime.fetch({
-    () => runtime.search({ query: "pi docs", tavily: { topic: "news" } }),
+    urls: ["https://pi.dev/"],
-    /does not accept the "tavily" options block/,
+    summary: true,
-  );
+    extras: {
-  assert.equal(callCount, 0);
+      links: 5,
-});
-
-test("search rejects Firecrawl requests with multiple includeDomains before provider execution", async () => {
-  const calls: string[] = [];
-
-  const runtime = createWebSearchRuntime({
-    loadConfig: async () => ({
-      path: "test.json",
-      defaultProviderName: "firecrawl-main",
-      defaultProvider: {
-        name: "firecrawl-main",
-        type: "firecrawl",
-        apiKey: "fc",
-        fallbackProviders: ["exa-fallback"],
-      },
-      providers: [
-        {
-          name: "firecrawl-main",
-          type: "firecrawl",
-          apiKey: "fc",
-          fallbackProviders: ["exa-fallback"],
-        },
-        { name: "exa-fallback", type: "exa", apiKey: "exa" },
-      ],
-      providersByName: new Map([
-        [
-          "firecrawl-main",
-          { name: "firecrawl-main", type: "firecrawl", apiKey: "fc", fallbackProviders: ["exa-fallback"] },
-        ],
-        ["exa-fallback", { name: "exa-fallback", type: "exa", apiKey: "exa" }],
-      ]),
-    }),
-    createProvider(providerConfig) {
-      return createProvider(providerConfig.name, providerConfig.type, {
-        search: async () => {
-          calls.push(providerConfig.name);
-          throw new Error(`boom:${providerConfig.name}`);
-        },
-      });
     },
   });
 
-  await assert.rejects(
+  assert.deepEqual(calls, [
-    () =>
+    {
-      runtime.search({
+      urls: ["https://pi.dev/"],
-        query: "pi docs",
+      options: {
-        provider: "firecrawl-main",
-        includeDomains: ["pi.dev", "exa.ai"],
-      }),
-    /Provider "firecrawl-main" accepts at most one includeDomains entry/,
-  );
-  assert.deepEqual(calls, []);
-});
-
-test("search rejects Firecrawl category conflicts before provider execution", async () => {
-  const calls: string[] = [];
-
-  const runtime = createWebSearchRuntime({
-    loadConfig: async () => ({
-      path: "test.json",
-      defaultProviderName: "firecrawl-main",
-      defaultProvider: {
-        name: "firecrawl-main",
-        type: "firecrawl",
-        apiKey: "fc",
-        fallbackProviders: ["exa-fallback"],
-      },
-      providers: [
-        {
-          name: "firecrawl-main",
-          type: "firecrawl",
-          apiKey: "fc",
-          fallbackProviders: ["exa-fallback"],
-        },
-        { name: "exa-fallback", type: "exa", apiKey: "exa" },
-      ],
-      providersByName: new Map([
-        [
-          "firecrawl-main",
-          { name: "firecrawl-main", type: "firecrawl", apiKey: "fc", fallbackProviders: ["exa-fallback"] },
-        ],
-        ["exa-fallback", { name: "exa-fallback", type: "exa", apiKey: "exa" }],
-      ]),
-    }),
-    createProvider(providerConfig) {
-      return createProvider(providerConfig.name, providerConfig.type, {
-        search: async () => {
-          calls.push(providerConfig.name);
-          throw new Error(`boom:${providerConfig.name}`);
-        },
-      });
-    },
-  });
-
-  await assert.rejects(
-    () =>
-      runtime.search({
-        query: "pi docs",
-        provider: "firecrawl-main",
-        category: "research",
-        firecrawl: { categories: ["github"] },
-      }),
-    /Provider "firecrawl-main" does not accept both top-level category and firecrawl.categories/,
-  );
-  assert.deepEqual(calls, []);
-});
-
-test("fetch rejects Firecrawl highlights before provider execution", async () => {
-  const calls: string[] = [];
-
-  const runtime = createWebSearchRuntime({
-    loadConfig: async () => ({
-      path: "test.json",
-      defaultProviderName: "firecrawl-main",
-      defaultProvider: {
-        name: "firecrawl-main",
-        type: "firecrawl",
-        apiKey: "fc",
-        fallbackProviders: ["exa-fallback"],
-      },
-      providers: [
-        {
-          name: "firecrawl-main",
-          type: "firecrawl",
-          apiKey: "fc",
-          fallbackProviders: ["exa-fallback"],
-        },
-        { name: "exa-fallback", type: "exa", apiKey: "exa" },
-      ],
-      providersByName: new Map([
-        [
-          "firecrawl-main",
-          { name: "firecrawl-main", type: "firecrawl", apiKey: "fc", fallbackProviders: ["exa-fallback"] },
-        ],
-        ["exa-fallback", { name: "exa-fallback", type: "exa", apiKey: "exa" }],
-      ]),
-    }),
-    createProvider(providerConfig) {
-      return createProvider(providerConfig.name, providerConfig.type, {
-        fetch: async () => {
-          calls.push(providerConfig.name);
-          return {
-            providerName: providerConfig.name,
-            results: [],
-          };
-        },
-      });
-    },
-  });
-
-  await assert.rejects(
-    () => runtime.fetch({ urls: ["https://pi.dev"], provider: "firecrawl-main", highlights: true }),
-    /does not support generic fetch option "highlights"/,
-  );
-  assert.deepEqual(calls, []);
-});
-
-test("fetch rejects Firecrawl format mismatches before provider execution", async () => {
-  const calls: string[] = [];
-
-  const runtime = createWebSearchRuntime({
-    loadConfig: async () => ({
-      path: "test.json",
-      defaultProviderName: "firecrawl-main",
-      defaultProvider: {
-        name: "firecrawl-main",
-        type: "firecrawl",
-        apiKey: "fc",
-        fallbackProviders: ["exa-fallback"],
-      },
-      providers: [
-        {
-          name: "firecrawl-main",
-          type: "firecrawl",
-          apiKey: "fc",
-          fallbackProviders: ["exa-fallback"],
-        },
-        { name: "exa-fallback", type: "exa", apiKey: "exa" },
-      ],
-      providersByName: new Map([
-        [
-          "firecrawl-main",
-          { name: "firecrawl-main", type: "firecrawl", apiKey: "fc", fallbackProviders: ["exa-fallback"] },
-        ],
-        ["exa-fallback", { name: "exa-fallback", type: "exa", apiKey: "exa" }],
-      ]),
-    }),
-    createProvider(providerConfig) {
-      return createProvider(providerConfig.name, providerConfig.type, {
-        fetch: async () => {
-          calls.push(providerConfig.name);
-          return {
-            providerName: providerConfig.name,
-            results: [],
-          };
-        },
-      });
-    },
-  });
-
-  await assert.rejects(
-    () =>
-      runtime.fetch({
-        urls: ["https://pi.dev"],
-        provider: "firecrawl-main",
         summary: true,
-        firecrawl: { formats: ["markdown"] },
+        extras: {
-      }),
+          links: 5,
-    /Provider "firecrawl-main" requires firecrawl.formats to include "summary" when summary is true/,
-  );
-  assert.deepEqual(calls, []);
-});
-
-test("search throws a clear error for unknown provider types", async () => {
-  const runtime = createWebSearchRuntime({
-    loadConfig: async () => ({
-      path: "test.json",
-      defaultProviderName: "mystery-main",
-      defaultProvider: { name: "mystery-main", type: "mystery", apiKey: "??" } as any,
-      providers: [{ name: "mystery-main", type: "mystery", apiKey: "??" } as any],
-      providersByName: new Map([["mystery-main", { name: "mystery-main", type: "mystery", apiKey: "??" } as any]]),
-    }),
-  });
-
-  await assert.rejects(() => runtime.search({ query: "pi docs" }), /Unknown provider type: mystery/);
-});
-
-test("search starts with the explicitly requested provider and still follows its fallback chain", async () => {
-  const calls: string[] = [];
-
-  const runtime = createWebSearchRuntime({
-    loadConfig: async () => ({
-      path: "test.json",
-      defaultProviderName: "tavily-main",
-      defaultProvider: { name: "tavily-main", type: "tavily", apiKey: "tvly" },
-      providers: [
-        { name: "tavily-main", type: "tavily", apiKey: "tvly" },
-        {
-          name: "firecrawl-main",
-          type: "firecrawl",
-          apiKey: "fc",
-          fallbackProviders: ["exa-fallback"],
         },
-        { name: "exa-fallback", type: "exa", apiKey: "exa" },
-      ],
-      providersByName: new Map([
-        ["tavily-main", { name: "tavily-main", type: "tavily", apiKey: "tvly" }],
-        [
-          "firecrawl-main",
-          { name: "firecrawl-main", type: "firecrawl", apiKey: "fc", fallbackProviders: ["exa-fallback"] },
-        ],
-        ["exa-fallback", { name: "exa-fallback", type: "exa", apiKey: "exa" }],
-      ]),
-    }),
-    createProvider(providerConfig) {
-      return createProvider(providerConfig.name, providerConfig.type, {
-        search: async () => {
-          calls.push(providerConfig.name);
-          if (providerConfig.name === "exa-fallback") {
-            return {
-              providerName: providerConfig.name,
-              results: [{ title: "Exa hit", url: "https://exa.ai" }],
-            };
-          }
-          throw new Error(`boom:${providerConfig.name}`);
-        },
-      });
-    },
-  });
-
-  const result = await runtime.search({ query: "pi docs", provider: "firecrawl-main" });
-
-  assert.deepEqual(calls, ["firecrawl-main", "exa-fallback"]);
-  assert.equal(result.execution.requestedProviderName, "firecrawl-main");
-  assert.equal(result.execution.actualProviderName, "exa-fallback");
-});
-
-test("search records provider factory failures and follows fallbacks", async () => {
-  const calls: string[] = [];
-
-  const runtime = createWebSearchRuntime({
-    loadConfig: async () => ({
-      path: "test.json",
-      defaultProviderName: "firecrawl-main",
-      defaultProvider: {
-        name: "firecrawl-main",
-        type: "firecrawl",
-        apiKey: "fc",
-        fallbackProviders: ["exa-fallback"],
       },
-      providers: [
-        {
-          name: "firecrawl-main",
-          type: "firecrawl",
-          apiKey: "fc",
-          fallbackProviders: ["exa-fallback"],
-        },
-        { name: "exa-fallback", type: "exa", apiKey: "exa" },
-      ],
-      providersByName: new Map([
-        [
-          "firecrawl-main",
-          { name: "firecrawl-main", type: "firecrawl", apiKey: "fc", fallbackProviders: ["exa-fallback"] },
-        ],
-        ["exa-fallback", { name: "exa-fallback", type: "exa", apiKey: "exa" }],
-      ]),
-    }),
-    createProvider(providerConfig) {
-      if (providerConfig.name === "firecrawl-main") {
-        throw "factory boom:firecrawl-main";
-      }
-
-      return createProvider(providerConfig.name, providerConfig.type, {
-        search: async () => {
-          calls.push(providerConfig.name);
-          return {
-            providerName: providerConfig.name,
-            results: [{ title: "Exa hit", url: "https://exa.ai" }],
-          };
-        },
-      });
-    },
-  });
-
-  const result = await runtime.search({ query: "pi docs", provider: "firecrawl-main" });
-
-  assert.deepEqual(calls, ["exa-fallback"]);
-  assert.deepEqual(result.execution.attempts, [
-    {
-      providerName: "firecrawl-main",
-      status: "failed",
-      reason: "factory boom:firecrawl-main",
-    },
-    {
-      providerName: "exa-fallback",
-      status: "succeeded",
     },
   ]);
-  assert.equal(result.execution.actualProviderName, "exa-fallback");
+  assert.equal(response.requestId, "req-fetch-1");
+  assert.equal(response.results[0]?.summary, "Agent docs");
+});
+
+test("runtime surfaces Exa client errors without fallback wrapping", async () => {
+  const runtime = createWebSearchRuntime({
+    loadConfig: async () => ({
+      path: "test.json",
+      apiKey: "exa-test-key",
+      baseUrl: undefined,
+    }),
+    createClient() {
+      return {
+        async search() {
+          throw new Error("429 rate limited");
+        },
+        async getContents() {
+          throw new Error("not used");
+        },
+      };
+    },
+  });
+
+  await assert.rejects(() => runtime.search({ query: "exa docs" }), /429 rate limited/);
 });

src/runtime.ts

@@ -1,184 +1,26 @@
 import { loadWebSearchConfig, type ResolvedWebSearchConfig } from "./config.ts";
-import {
+import { buildFetchOptions, buildSearchOptions, createExaClient, type ExaClientLike } from "./providers/exa.ts";
-  createProviderFromConfig,
+import type { WebFetchParams, WebSearchParams } from "./schema.ts";
-  validateFetchRequestForProvider,
-  validateSearchRequestForProvider,
-} from "./providers/registry.ts";
-import type {
-  NormalizedFetchRequest,
-  NormalizedFetchResponse,
-  NormalizedSearchRequest,
-  NormalizedSearchResponse,
-  WebProvider,
-} from "./providers/types.ts";
-import type { WebSearchProviderConfig } from "./schema.ts";
-
-export interface ProviderExecutionAttempt {
-  providerName: string;
-  status: "failed" | "succeeded";
-  reason?: string;
-}
-
-export interface ProviderExecutionMeta {
-  requestedProviderName?: string;
-  actualProviderName: string;
-  failoverFromProviderName?: string;
-  failoverReason?: string;
-  attempts: ProviderExecutionAttempt[];
-}
-
-export interface RuntimeSearchResponse extends NormalizedSearchResponse {
-  execution: ProviderExecutionMeta;
-}
-
-export interface RuntimeFetchResponse extends NormalizedFetchResponse {
-  execution: ProviderExecutionMeta;
-}
-
-function createUnknownProviderError(config: ResolvedWebSearchConfig, selectedName: string) {
-  return new Error(
-    `Unknown web-search provider \"${selectedName}\". Configured providers: ${[...config.providersByName.keys()].join(", ")}`,
-  );
-}
-
-function buildExecutionMeta(
-  requestedProviderName: string | undefined,
-  actualProviderName: string,
-  attempts: ProviderExecutionAttempt[],
-): ProviderExecutionMeta {
-  const firstFailedAttempt = attempts.find((attempt) => attempt.status === "failed");
-  const didFailOver = firstFailedAttempt && firstFailedAttempt.providerName !== actualProviderName;
-
-  return {
-    requestedProviderName,
-    actualProviderName,
-    failoverFromProviderName: didFailOver ? firstFailedAttempt?.providerName : undefined,
-    failoverReason: didFailOver ? firstFailedAttempt?.reason : undefined,
-    attempts,
-  };
-}
-
-function describeError(error: unknown) {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function attachAttempts(error: unknown, attempts: ProviderExecutionAttempt[]) {
-  const normalizedError = error instanceof Error ? error : new Error(String(error));
-  (normalizedError as Error & { execution?: { attempts: ProviderExecutionAttempt[] } }).execution = { attempts };
-  return normalizedError;
-}
 
 export function createWebSearchRuntime(
   deps: {
     loadConfig?: () => Promise<ResolvedWebSearchConfig>;
-    createProvider?: (providerConfig: WebSearchProviderConfig) => WebProvider;
+    createClient?: (config: ResolvedWebSearchConfig) => ExaClientLike;
   } = {},
 ) {
   const loadConfig = deps.loadConfig ?? loadWebSearchConfig;
-  const createProvider = deps.createProvider ?? createProviderFromConfig;
+  const createClient = deps.createClient ?? ((config) => createExaClient(config));
 
-  async function resolveConfigAndProvider(providerName?: string) {
+  async function search(request: WebSearchParams) {
     const config = await loadConfig();
-    const selectedName = providerName ?? config.defaultProviderName;
+    const client = createClient(config);
-    const selectedConfig = config.providersByName.get(selectedName);
+    return client.search(request.query, buildSearchOptions(request));
-
-    if (!selectedConfig) {
-      throw createUnknownProviderError(config, selectedName);
-    }
-
-    return {
-      config,
-      selectedName,
-      selectedConfig,
-    };
   }
 
-  async function executeWithFailover<TResponse extends NormalizedSearchResponse | NormalizedFetchResponse>(
+  async function fetch(request: WebFetchParams) {
-    request: NormalizedSearchRequest | NormalizedFetchRequest,
+    const config = await loadConfig();
-    operation: "search" | "fetch",
+    const client = createClient(config);
-  ): Promise<TResponse & { execution: ProviderExecutionMeta }> {
+    return client.getContents(request.urls, buildFetchOptions(request));
-    const { config, selectedName } = await resolveConfigAndProvider(request.provider);
-    const attempts: ProviderExecutionAttempt[] = [];
-    const pendingProviderNames = [selectedName];
-    const visited = new Set<string>();
-    let lastError: unknown;
-
-    while (pendingProviderNames.length > 0) {
-      const providerName = pendingProviderNames.shift();
-      if (!providerName || visited.has(providerName)) {
-        continue;
-      }
-      visited.add(providerName);
-
-      const providerConfig = config.providersByName.get(providerName);
-      if (!providerConfig) {
-        throw createUnknownProviderError(config, providerName);
-      }
-
-      if (operation === "search") {
-        validateSearchRequestForProvider(providerName, providerConfig, request as NormalizedSearchRequest);
-      } else {
-        validateFetchRequestForProvider(providerName, providerConfig, request as NormalizedFetchRequest);
-      }
-
-      let provider: WebProvider;
-      try {
-        provider = createProvider(providerConfig);
-      } catch (error) {
-        attempts.push({
-          providerName,
-          status: "failed",
-          reason: describeError(error),
-        });
-        lastError = error;
-
-        for (const fallbackProviderName of providerConfig.fallbackProviders ?? []) {
-          if (!visited.has(fallbackProviderName)) {
-            pendingProviderNames.push(fallbackProviderName);
-          }
-        }
-        continue;
-      }
-
-      try {
-        const response = await provider[operation]({
-          ...request,
-          provider: providerName,
-        } as never);
-        attempts.push({
-          providerName,
-          status: "succeeded",
-        });
-
-        return {
-          ...response,
-          execution: buildExecutionMeta(request.provider, providerName, attempts),
-        } as TResponse & { execution: ProviderExecutionMeta };
-      } catch (error) {
-        attempts.push({
-          providerName,
-          status: "failed",
-          reason: describeError(error),
-        });
-        lastError = error;
-
-        for (const fallbackProviderName of providerConfig.fallbackProviders ?? []) {
-          if (!visited.has(fallbackProviderName)) {
-            pendingProviderNames.push(fallbackProviderName);
-          }
-        }
-      }
-    }
-
-    throw attachAttempts(lastError, attempts);
-  }
-
-  async function search(request: NormalizedSearchRequest): Promise<RuntimeSearchResponse> {
-    return executeWithFailover<NormalizedSearchResponse>(request, "search");
-  }
-
-  async function fetch(request: NormalizedFetchRequest): Promise<RuntimeFetchResponse> {
-    return executeWithFailover<NormalizedFetchResponse>(request, "fetch");
   }
 
   return {

src/schema.ts

@@ -1,138 +1,214 @@
 import { Type, type Static } from "@sinclair/typebox";
 
 const NonEmptyStringSchema = Type.String({ minLength: 1 });
-const FallbackProvidersSchema = Type.Optional(Type.Array(NonEmptyStringSchema, { minItems: 1 }));
+const LooseObjectSchema = Type.Object({}, { additionalProperties: true });
 
-export const ProviderOptionsSchema = Type.Object({
+export const ExaSearchTypeSchema = Type.Union([
-  defaultSearchLimit: Type.Optional(Type.Integer({ minimum: 1 })),
+  Type.Literal("keyword"),
-  defaultFetchTextMaxCharacters: Type.Optional(Type.Integer({ minimum: 1 })),
+  Type.Literal("neural"),
-  defaultFetchHighlightsMaxCharacters: Type.Optional(Type.Integer({ minimum: 1 })),
+  Type.Literal("auto"),
-});
+  Type.Literal("hybrid"),
-
+  Type.Literal("fast"),
-export const ExaProviderConfigSchema = Type.Object({
+  Type.Literal("instant"),
-  name: NonEmptyStringSchema,
+  Type.Literal("deep-lite"),
-  type: Type.Literal("exa"),
+  Type.Literal("deep"),
-  apiKey: NonEmptyStringSchema,
+  Type.Literal("deep-reasoning"),
-  options: Type.Optional(ProviderOptionsSchema),
-  fallbackProviders: FallbackProvidersSchema,
-});
-
-export const TavilyProviderOptionsSchema = Type.Object({
-  defaultSearchLimit: Type.Optional(Type.Integer({ minimum: 1, maximum: 20 })),
-  defaultFetchTextMaxCharacters: Type.Optional(Type.Integer({ minimum: 1 })),
-});
-
-export const TavilyProviderConfigSchema = Type.Object({
-  name: NonEmptyStringSchema,
-  type: Type.Literal("tavily"),
-  apiKey: NonEmptyStringSchema,
-  options: Type.Optional(TavilyProviderOptionsSchema),
-  fallbackProviders: FallbackProvidersSchema,
-});
-
-export const FirecrawlProviderOptionsSchema = Type.Object({
-  defaultSearchLimit: Type.Optional(Type.Integer({ minimum: 1 })),
-});
-
-export const FirecrawlProviderConfigSchema = Type.Object({
-  name: NonEmptyStringSchema,
-  type: Type.Literal("firecrawl"),
-  apiKey: Type.Optional(NonEmptyStringSchema),
-  baseUrl: Type.Optional(NonEmptyStringSchema),
-  options: Type.Optional(FirecrawlProviderOptionsSchema),
-  fallbackProviders: FallbackProvidersSchema,
-});
-
-export const WebSearchProviderConfigSchema = Type.Union([
-  ExaProviderConfigSchema,
-  TavilyProviderConfigSchema,
-  FirecrawlProviderConfigSchema,
 ]);
 
-export const WebSearchConfigSchema = Type.Object({
+export const ExaSearchCategorySchema = Type.Union([
-  defaultProvider: NonEmptyStringSchema,
+  Type.Literal("company"),
-  providers: Type.Array(WebSearchProviderConfigSchema, { minItems: 1 }),
+  Type.Literal("research paper"),
-});
+  Type.Literal("news"),
-
+  Type.Literal("pdf"),
-export const TavilySearchToolOptionsSchema = Type.Object({
+  Type.Literal("personal site"),
-  searchDepth: Type.Optional(Type.String()),
+  Type.Literal("financial report"),
-  topic: Type.Optional(Type.String()),
+  Type.Literal("people"),
-  timeRange: Type.Optional(Type.String()),
-  days: Type.Optional(Type.Integer({ minimum: 1 })),
-  chunksPerSource: Type.Optional(Type.Integer({ minimum: 1 })),
-  includeAnswer: Type.Optional(Type.Boolean()),
-  includeRawContent: Type.Optional(Type.Boolean()),
-  includeImages: Type.Optional(Type.Boolean()),
-});
-
-export const TavilyFetchToolOptionsSchema = Type.Object({
-  query: Type.Optional(Type.String()),
-  extractDepth: Type.Optional(Type.String()),
-  chunksPerSource: Type.Optional(Type.Integer({ minimum: 1 })),
-  includeImages: Type.Optional(Type.Boolean()),
-  includeFavicon: Type.Optional(Type.Boolean()),
-  format: Type.Optional(Type.String()),
-});
-
-export const FirecrawlSearchFormatSchema = Type.Union([Type.Literal("markdown"), Type.Literal("summary")]);
-export const FirecrawlFetchFormatSchema = Type.Union([
-  Type.Literal("markdown"),
-  Type.Literal("summary"),
-  Type.Literal("images"),
 ]);
 
-export const FirecrawlSearchToolOptionsSchema = Type.Object({
+export const ExaLivecrawlSchema = Type.Union([
-  country: Type.Optional(Type.String()),
+  Type.Literal("never"),
-  location: Type.Optional(Type.String()),
+  Type.Literal("fallback"),
-  categories: Type.Optional(Type.Array(NonEmptyStringSchema, { minItems: 1 })),
+  Type.Literal("always"),
-  scrapeOptions: Type.Optional(
+  Type.Literal("auto"),
-    Type.Object({
+  Type.Literal("preferred"),
-      formats: Type.Optional(Type.Array(FirecrawlSearchFormatSchema, { minItems: 1 })),
+]);
-    }),
+
+export const ExaVerbositySchema = Type.Union([
+  Type.Literal("compact"),
+  Type.Literal("standard"),
+  Type.Literal("full"),
+]);
+
+export const ExaSectionTagSchema = Type.Union([
+  Type.Literal("unspecified"),
+  Type.Literal("header"),
+  Type.Literal("navigation"),
+  Type.Literal("banner"),
+  Type.Literal("body"),
+  Type.Literal("sidebar"),
+  Type.Literal("footer"),
+  Type.Literal("metadata"),
+]);
+
+export const ExaTextContentsSchema = Type.Union([
+  Type.Literal(true),
+  Type.Object(
+    {
+      maxCharacters: Type.Optional(Type.Integer({ minimum: 1 })),
+      includeHtmlTags: Type.Optional(Type.Boolean()),
+      verbosity: Type.Optional(ExaVerbositySchema),
+      includeSections: Type.Optional(Type.Array(ExaSectionTagSchema, { minItems: 1 })),
+      excludeSections: Type.Optional(Type.Array(ExaSectionTagSchema, { minItems: 1 })),
+    },
+    { additionalProperties: false },
   ),
-});
+]);
 
-export const FirecrawlFetchToolOptionsSchema = Type.Object({
+export const ExaHighlightsContentsSchema = Type.Union([
-  formats: Type.Optional(Type.Array(FirecrawlFetchFormatSchema, { minItems: 1 })),
+  Type.Literal(true),
-});
+  Type.Object(
+    {
+      query: Type.Optional(NonEmptyStringSchema),
+      maxCharacters: Type.Optional(Type.Integer({ minimum: 1 })),
+      numSentences: Type.Optional(Type.Integer({ minimum: 1 })),
+      highlightsPerUrl: Type.Optional(Type.Integer({ minimum: 1 })),
+    },
+    { additionalProperties: false },
+  ),
+]);
 
-export const WebSearchParamsSchema = Type.Object({
+export const ExaSummaryContentsSchema = Type.Union([
-  query: Type.String({ minLength: 1, description: "Search query" }),
+  Type.Literal(true),
-  limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 25 })),
+  Type.Object(
-  includeDomains: Type.Optional(Type.Array(Type.String())),
+    {
-  excludeDomains: Type.Optional(Type.Array(Type.String())),
+      query: Type.Optional(NonEmptyStringSchema),
-  startPublishedDate: Type.Optional(Type.String()),
+      schema: Type.Optional(LooseObjectSchema),
-  endPublishedDate: Type.Optional(Type.String()),
+    },
-  category: Type.Optional(Type.String()),
+    { additionalProperties: false },
-  provider: Type.Optional(Type.String()),
+  ),
-  tavily: Type.Optional(TavilySearchToolOptionsSchema),
+]);
-  firecrawl: Type.Optional(FirecrawlSearchToolOptionsSchema),
-});
 
-export const WebFetchParamsSchema = Type.Object({
+export const ExaContextContentsSchema = Type.Union([
-  urls: Type.Array(Type.String(), { minItems: 1 }),
+  Type.Literal(true),
-  text: Type.Optional(Type.Boolean()),
+  Type.Object(
-  highlights: Type.Optional(Type.Boolean()),
+    {
-  summary: Type.Optional(Type.Boolean()),
+      maxCharacters: Type.Optional(Type.Integer({ minimum: 1 })),
-  textMaxCharacters: Type.Optional(Type.Integer({ minimum: 1 })),
+    },
-  provider: Type.Optional(Type.String()),
+    { additionalProperties: false },
-  tavily: Type.Optional(TavilyFetchToolOptionsSchema),
+  ),
-  firecrawl: Type.Optional(FirecrawlFetchToolOptionsSchema),
+]);
-});
 
-export type ProviderOptions = Static<typeof ProviderOptionsSchema>;
+export const ExaExtrasSchema = Type.Object(
-export type TavilyProviderOptions = Static<typeof TavilyProviderOptionsSchema>;
+  {
-export type FirecrawlProviderOptions = Static<typeof FirecrawlProviderOptionsSchema>;
+    links: Type.Optional(Type.Integer({ minimum: 1 })),
-export type ExaProviderConfig = Static<typeof ExaProviderConfigSchema>;
+    imageLinks: Type.Optional(Type.Integer({ minimum: 1 })),
-export type TavilyProviderConfig = Static<typeof TavilyProviderConfigSchema>;
+  },
-export type FirecrawlProviderConfig = Static<typeof FirecrawlProviderConfigSchema>;
+  { additionalProperties: false },
-export type WebSearchProviderConfig = Static<typeof WebSearchProviderConfigSchema>;
+);
+
+export const ExaContentsOptionsSchema = Type.Object(
+  {
+    text: Type.Optional(ExaTextContentsSchema),
+    highlights: Type.Optional(ExaHighlightsContentsSchema),
+    summary: Type.Optional(ExaSummaryContentsSchema),
+    context: Type.Optional(ExaContextContentsSchema),
+    livecrawl: Type.Optional(ExaLivecrawlSchema),
+    livecrawlTimeout: Type.Optional(Type.Number({ minimum: 0 })),
+    maxAgeHours: Type.Optional(Type.Number()),
+    filterEmptyResults: Type.Optional(Type.Boolean()),
+    subpages: Type.Optional(Type.Integer({ minimum: 1 })),
+    subpageTarget: Type.Optional(
+      Type.Union([NonEmptyStringSchema, Type.Array(NonEmptyStringSchema, { minItems: 1 })]),
+    ),
+    extras: Type.Optional(ExaExtrasSchema),
+  },
+  { additionalProperties: false },
+);
+
+export const ExaOutputSchema = Type.Union([
+  Type.Object(
+    {
+      type: Type.Literal("text"),
+      description: Type.Optional(Type.String()),
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      type: Type.Literal("object"),
+      properties: Type.Optional(LooseObjectSchema),
+      required: Type.Optional(Type.Array(NonEmptyStringSchema, { minItems: 1 })),
+    },
+    { additionalProperties: false },
+  ),
+]);
+
+export const WebSearchConfigSchema = Type.Object(
+  {
+    apiKey: Type.Optional(Type.String()),
+    baseUrl: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+);
+
+export const WebSearchParamsSchema = Type.Object(
+  {
+    query: Type.String({ minLength: 1, description: "Search query" }),
+    type: Type.Optional(ExaSearchTypeSchema),
+    numResults: Type.Optional(Type.Integer({ minimum: 1 })),
+    includeDomains: Type.Optional(Type.Array(NonEmptyStringSchema, { minItems: 1 })),
+    excludeDomains: Type.Optional(Type.Array(NonEmptyStringSchema, { minItems: 1 })),
+    startCrawlDate: Type.Optional(Type.String()),
+    endCrawlDate: Type.Optional(Type.String()),
+    startPublishedDate: Type.Optional(Type.String()),
+    endPublishedDate: Type.Optional(Type.String()),
+    category: Type.Optional(ExaSearchCategorySchema),
+    includeText: Type.Optional(Type.Array(NonEmptyStringSchema, { minItems: 1, maxItems: 1 })),
+    excludeText: Type.Optional(Type.Array(NonEmptyStringSchema, { minItems: 1, maxItems: 1 })),
+    flags: Type.Optional(Type.Array(NonEmptyStringSchema, { minItems: 1 })),
+    userLocation: Type.Optional(Type.String({ pattern: "^[A-Za-z]{2}$" })),
+    moderation: Type.Optional(Type.Boolean()),
+    useAutoprompt: Type.Optional(Type.Boolean()),
+    systemPrompt: Type.Optional(Type.String()),
+    outputSchema: Type.Optional(ExaOutputSchema),
+    additionalQueries: Type.Optional(Type.Array(NonEmptyStringSchema, { minItems: 1, maxItems: 5 })),
+    contents: Type.Optional(Type.Union([Type.Literal(false), ExaContentsOptionsSchema])),
+  },
+  { additionalProperties: false },
+);
+
+export const WebFetchParamsSchema = Type.Object(
+  {
+    urls: Type.Array(NonEmptyStringSchema, { minItems: 1 }),
+    text: Type.Optional(ExaTextContentsSchema),
+    highlights: Type.Optional(ExaHighlightsContentsSchema),
+    summary: Type.Optional(ExaSummaryContentsSchema),
+    context: Type.Optional(ExaContextContentsSchema),
+    livecrawl: Type.Optional(ExaLivecrawlSchema),
+    livecrawlTimeout: Type.Optional(Type.Number({ minimum: 0 })),
+    maxAgeHours: Type.Optional(Type.Number()),
+    filterEmptyResults: Type.Optional(Type.Boolean()),
+    subpages: Type.Optional(Type.Integer({ minimum: 1 })),
+    subpageTarget: Type.Optional(
+      Type.Union([NonEmptyStringSchema, Type.Array(NonEmptyStringSchema, { minItems: 1 })]),
+    ),
+    extras: Type.Optional(ExaExtrasSchema),
+  },
+  { additionalProperties: false },
+);
+
+export type ExaSearchType = Static<typeof ExaSearchTypeSchema>;
+export type ExaSearchCategory = Static<typeof ExaSearchCategorySchema>;
+export type ExaLivecrawl = Static<typeof ExaLivecrawlSchema>;
+export type ExaVerbosity = Static<typeof ExaVerbositySchema>;
+export type ExaSectionTag = Static<typeof ExaSectionTagSchema>;
+export type ExaTextContents = Static<typeof ExaTextContentsSchema>;
+export type ExaHighlightsContents = Static<typeof ExaHighlightsContentsSchema>;
+export type ExaSummaryContents = Static<typeof ExaSummaryContentsSchema>;
+export type ExaContextContents = Static<typeof ExaContextContentsSchema>;
+export type ExaExtras = Static<typeof ExaExtrasSchema>;
+export type ExaContentsOptions = Static<typeof ExaContentsOptionsSchema>;
+export type ExaOutput = Static<typeof ExaOutputSchema>;
 export type WebSearchConfig = Static<typeof WebSearchConfigSchema>;
-export type TavilySearchToolOptions = Static<typeof TavilySearchToolOptionsSchema>;
-export type TavilyFetchToolOptions = Static<typeof TavilyFetchToolOptionsSchema>;
-export type FirecrawlSearchFormat = Static<typeof FirecrawlSearchFormatSchema>;
-export type FirecrawlFetchFormat = Static<typeof FirecrawlFetchFormatSchema>;
-export type FirecrawlSearchToolOptions = Static<typeof FirecrawlSearchToolOptionsSchema>;
-export type FirecrawlFetchToolOptions = Static<typeof FirecrawlFetchToolOptionsSchema>;
 export type WebSearchParams = Static<typeof WebSearchParamsSchema>;
 export type WebFetchParams = Static<typeof WebFetchParamsSchema>;

src/tools/web-fetch.test.ts

@@ -2,14 +2,14 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { createWebFetchTool } from "./web-fetch.ts";
 
-test("createWebFetchTool passes Firecrawl fetch options through to the runtime", async () => {
+test("createWebFetchTool passes Exa getContents options through without injecting default text", async () => {
   let captured: any;
 
   const tool = createWebFetchTool({
     async executeFetch(request) {
       captured = request;
       return {
-        providerName: "firecrawl-main",
+        requestId: "req-fetch-1",
         results: [],
       };
     },
@@ -17,22 +17,48 @@ test("createWebFetchTool passes Firecrawl fetch options through to the runtime",
 
   await tool.execute("tool-call", {
     urls: ["https://pi.dev"],
-    provider: "firecrawl-main",
+    summary: true,
-    firecrawl: {
+    extras: {
-      formats: ["markdown", "summary", "images"],
+      links: 5,
     },
   } as any);
 
   assert.deepEqual(captured, {
     urls: ["https://pi.dev/"],
-    text: true,
+    summary: true,
-    highlights: false,
+    extras: {
-    summary: false,
+      links: 5,
-    textMaxCharacters: undefined,
-    provider: "firecrawl-main",
-    tavily: undefined,
-    firecrawl: {
-      formats: ["markdown", "summary", "images"],
     },
   });
 });
+
+test("createWebFetchTool supports the single-url alias", async () => {
+  let captured: any;
+
+  const tool = createWebFetchTool({
+    async executeFetch(request) {
+      captured = request;
+      return {
+        requestId: "req-fetch-1",
+        results: [],
+      };
+    },
+  });
+
+  const prepared = tool.prepareArguments({ url: "https://exa.ai" });
+  await tool.execute("tool-call", prepared as any);
+
+  assert.deepEqual(captured, {
+    urls: ["https://exa.ai/"],
+  });
+});
+
+test("createWebFetchTool rejects invalid urls", async () => {
+  const tool = createWebFetchTool({
+    async executeFetch() {
+      throw new Error("not used");
+    },
+  });
+
+  await assert.rejects(() => tool.execute("tool-call", { urls: ["notaurl"] } as any), /Invalid URL: notaurl/);
+});

src/tools/web-fetch.ts

@@ -1,10 +1,9 @@
 import { Text } from "@mariozechner/pi-tui";
 import { formatFetchOutput } from "../format.ts";
-import type { NormalizedFetchRequest, NormalizedFetchResponse } from "../providers/types.ts";
 import { WebFetchParamsSchema, type WebFetchParams } from "../schema.ts";
 
 interface FetchToolDeps {
-  executeFetch(request: NormalizedFetchRequest): Promise<NormalizedFetchResponse & { execution?: unknown }>;
+  executeFetch(request: WebFetchParams): Promise<any>;
 }
 
 function normalizeUrl(value: string) {
@@ -15,7 +14,7 @@ function normalizeUrl(value: string) {
   }
 }
 
-function normalizeFetchParams(params: WebFetchParams & { url?: string }) {
+function normalizeFetchParams(params: WebFetchParams & { url?: string }): WebFetchParams {
   const urls = (Array.isArray(params.urls) ? params.urls : []).map(normalizeUrl);
   if (urls.length === 0) {
     throw new Error("web_fetch requires at least one URL.");
@@ -23,13 +22,17 @@ function normalizeFetchParams(params: WebFetchParams & { url?: string }) {
 
   return {
     urls,
-    text: params.text ?? (!params.highlights && !params.summary),
+    ...(params.text !== undefined ? { text: params.text } : {}),
-    highlights: params.highlights ?? false,
+    ...(params.highlights !== undefined ? { highlights: params.highlights } : {}),
-    summary: params.summary ?? false,
+    ...(params.summary !== undefined ? { summary: params.summary } : {}),
-    textMaxCharacters: params.textMaxCharacters,
+    ...(params.context !== undefined ? { context: params.context } : {}),
-    provider: params.provider,
+    ...(params.livecrawl !== undefined ? { livecrawl: params.livecrawl } : {}),
-    tavily: params.tavily,
+    ...(params.livecrawlTimeout !== undefined ? { livecrawlTimeout: params.livecrawlTimeout } : {}),
-    firecrawl: params.firecrawl,
+    ...(params.maxAgeHours !== undefined ? { maxAgeHours: params.maxAgeHours } : {}),
+    ...(params.filterEmptyResults !== undefined ? { filterEmptyResults: params.filterEmptyResults } : {}),
+    ...(params.subpages !== undefined ? { subpages: params.subpages } : {}),
+    ...(params.subpageTarget !== undefined ? { subpageTarget: params.subpageTarget } : {}),
+    ...(params.extras !== undefined ? { extras: params.extras } : {}),
   };
 }
 
@@ -37,7 +40,7 @@ export function createWebFetchTool({ executeFetch }: FetchToolDeps) {
   return {
     name: "web_fetch",
     label: "Web Fetch",
-    description: "Fetch page contents through the configured provider. Returns text by default.",
+    description: "Fetch page contents through Exa using getContents-style options.",
     parameters: WebFetchParamsSchema,
 
     prepareArguments(args: unknown) {
@@ -73,19 +76,14 @@ export function createWebFetchTool({ executeFetch }: FetchToolDeps) {
       return new Text(text, 0, 0);
     },
 
-    renderResult(result: { details?: NormalizedFetchResponse }, _options: unknown, theme: any) {
+    renderResult(result: { details?: { results?: unknown[] } }, _options: unknown, theme: any) {
       const details = result.details;
       if (!details) {
         return new Text("", 0, 0);
       }
 
-      const failed = details.results.filter((item) => item.error).length;
+      const resultCount = Array.isArray(details.results) ? details.results.length : 0;
-      const succeeded = details.results.length - failed;
+      return new Text(`${theme.fg("success", "✓ ")}${resultCount} page${resultCount === 1 ? "" : "s"} via Exa`, 0, 0);
-      return new Text(
-        `${theme.fg("success", "✓ ")}${succeeded} ok${failed ? ` • ${theme.fg("warning", `${failed} failed`)}` : ""}`,
-        0,
-        0,
-      );
     },
   };
 }

src/tools/web-search.test.ts

@@ -2,47 +2,67 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { createWebSearchTool } from "./web-search.ts";
 
-test("createWebSearchTool passes Firecrawl search options through to the runtime", async () => {
+test("createWebSearchTool passes Exa-native search options through to the runtime", async () => {
   let captured: any;
 
   const tool = createWebSearchTool({
     async executeSearch(request) {
       captured = request;
       return {
-        providerName: "firecrawl-main",
+        requestId: "req-search-1",
         results: [],
       };
     },
   });
 
   await tool.execute("tool-call", {
-    query: "pi docs",
+    query: "  pi docs  ",
-    provider: "firecrawl-main",
+    type: "deep",
-    firecrawl: {
+    numResults: 3,
-      country: "DE",
+    systemPrompt: "Prefer official docs",
-      categories: ["github"],
+    outputSchema: {
-      scrapeOptions: {
+      type: "text",
-        formats: ["markdown"],
+      description: "Answer in bullets",
+    },
+    contents: {
+      highlights: {
+        query: "Pi docs",
+        maxCharacters: 200,
       },
     },
   } as any);
 
   assert.deepEqual(captured, {
     query: "pi docs",
-    limit: undefined,
+    type: "deep",
-    includeDomains: undefined,
+    numResults: 3,
-    excludeDomains: undefined,
+    systemPrompt: "Prefer official docs",
-    startPublishedDate: undefined,
+    outputSchema: {
-    endPublishedDate: undefined,
+      type: "text",
-    category: undefined,
+      description: "Answer in bullets",
-    provider: "firecrawl-main",
+    },
-    tavily: undefined,
+    contents: {
-    firecrawl: {
+      highlights: {
-      country: "DE",
+        query: "Pi docs",
-      categories: ["github"],
+        maxCharacters: 200,
-      scrapeOptions: {
-        formats: ["markdown"],
       },
     },
   });
 });
+
+test("createWebSearchTool rejects includeText phrases longer than five words", async () => {
+  const tool = createWebSearchTool({
+    async executeSearch() {
+      throw new Error("not used");
+    },
+  });
+
+  await assert.rejects(
+    () =>
+      tool.execute("tool-call", {
+        query: "pi docs",
+        includeText: ["this phrase is definitely too many words"],
+      } as any),
+    /supports at most one phrase of up to 5 words/,
+  );
+});

src/tools/web-search.ts

@@ -1,12 +1,13 @@
 import { Text } from "@mariozechner/pi-tui";
 import { formatSearchOutput } from "../format.ts";
-import type { NormalizedSearchRequest, NormalizedSearchResponse } from "../providers/types.ts";
 import { WebSearchParamsSchema, type WebSearchParams } from "../schema.ts";
 
 interface SearchToolDeps {
-  executeSearch(request: NormalizedSearchRequest): Promise<NormalizedSearchResponse & { execution?: unknown }>;
+  executeSearch(request: WebSearchParams): Promise<any>;
 }
 
+const deepSearchTypes = new Set(["deep-lite", "deep", "deep-reasoning"]);
+
 function normalizeSearchQuery(query: string) {
   const trimmed = query.trim();
   if (!trimmed) {
@@ -15,27 +16,62 @@ function normalizeSearchQuery(query: string) {
   return trimmed;
 }
 
+function normalizePhraseFilter(label: string, value?: string[]) {
+  if (!value) {
+    return undefined;
+  }
+
+  const phrases = value.map((item) => item.trim()).filter(Boolean);
+  if (phrases.length === 0) {
+    return undefined;
+  }
+
+  if (phrases.length > 1 || phrases.some((phrase) => phrase.split(/\s+/).length > 5)) {
+    throw new Error(`Exa ${label} supports at most one phrase of up to 5 words.`);
+  }
+
+  return phrases;
+}
+
+function normalizeSearchParams(params: WebSearchParams): WebSearchParams {
+  const query = normalizeSearchQuery(params.query);
+  const includeText = normalizePhraseFilter("includeText", params.includeText);
+  const excludeText = normalizePhraseFilter("excludeText", params.excludeText);
+
+  if (params.additionalQueries && !deepSearchTypes.has(params.type ?? "")) {
+    throw new Error("Exa additionalQueries requires type to be one of: deep-lite, deep, deep-reasoning.");
+  }
+
+  const normalized: WebSearchParams = {
+    ...params,
+    query,
+  };
+
+  if (includeText !== undefined) {
+    normalized.includeText = includeText;
+  } else {
+    delete (normalized as Partial<WebSearchParams>).includeText;
+  }
+
+  if (excludeText !== undefined) {
+    normalized.excludeText = excludeText;
+  } else {
+    delete (normalized as Partial<WebSearchParams>).excludeText;
+  }
+
+  return normalized;
+}
+
 export function createWebSearchTool({ executeSearch }: SearchToolDeps) {
   return {
     name: "web_search",
     label: "Web Search",
-    description: "Search the web through the configured provider. Returns result metadata by default.",
+    description: "Search the web through Exa. Exa returns text contents by default unless contents: false is set.",
     parameters: WebSearchParamsSchema,
 
     async execute(_toolCallId: string, params: WebSearchParams) {
-      const query = normalizeSearchQuery(params.query);
+      const normalized = normalizeSearchParams(params);
-      const response = await executeSearch({
+      const response = await executeSearch(normalized);
-        query,
-        limit: params.limit,
-        includeDomains: params.includeDomains,
-        excludeDomains: params.excludeDomains,
-        startPublishedDate: params.startPublishedDate,
-        endPublishedDate: params.endPublishedDate,
-        category: params.category,
-        provider: params.provider,
-        tavily: params.tavily,
-        firecrawl: params.firecrawl,
-      });
 
       return {
         content: [{ type: "text" as const, text: formatSearchOutput(response) }],
@@ -49,17 +85,16 @@ export function createWebSearchTool({ executeSearch }: SearchToolDeps) {
       return new Text(text, 0, 0);
     },
 
-    renderResult(result: { details?: NormalizedSearchResponse }, _options: unknown, theme: any) {
+    renderResult(result: { details?: { results?: Array<{ title?: string | null; url: string }> } }, _options: unknown, theme: any) {
       const details = result.details;
       if (!details) {
         return new Text("", 0, 0);
       }
 
-      const lines = [
+      const results = Array.isArray(details.results) ? details.results : [];
-        `${theme.fg("success", "✓ ")}${details.results.length} result${details.results.length === 1 ? "" : "s"} via ${details.providerName}`,
+      const lines = [`${theme.fg("success", "✓ ")}${results.length} result${results.length === 1 ? "" : "s"} via Exa`];
-      ];
 
-      for (const [index, item] of details.results.slice(0, 5).entries()) {
+      for (const [index, item] of results.slice(0, 5).entries()) {
         lines.push(`  ${theme.fg("muted", `${index + 1}.`)} ${item.title ?? "(untitled)"} ${theme.fg("dim", item.url)}`);
       }