#20445: fix(tools): restore Firecrawl config schema and add FIRECRAWL_BASE_URL env fallback
agents
size: S
trusted-contributor
Cluster:
Configuration Fixes and Enhancements
## Summary
`tools.web.fetch.firecrawl` is documented and actively used by `web_fetch`, but the runtime config schema no longer accepts it. That creates a bad user experience: valid Firecrawl config gets rejected up front, and users cannot configure self-hosted Firecrawl endpoints through normal config and env patterns.
This PR restores that path and closes a gap in fallback behavior for Firecrawl base URLs.
## What Changed
### Firecrawl config schema and base URL fallback
- `src/config/zod-schema.agent-runtime.ts`: Restored `tools.web.fetch.firecrawl` in the runtime schema with expected fields (`enabled`, `apiKey`, `baseUrl`, `onlyMainContent`, `maxAgeMs`, `timeoutSeconds`).
- `src/config/config.schema-regressions.test.ts`: Added a schema regression test to lock this shape in place.
- `src/agents/tools/web-fetch.ts`: Updated `resolveFirecrawlBaseUrl` to use explicit fallback precedence: `tools.web.fetch.firecrawl.baseUrl` (config), then `FIRECRAWL_BASE_URL` (env), then `DEFAULT_FIRECRAWL_BASE_URL`.
- `src/agents/tools/web-fetch.base-url.test.ts`: Added dedicated unit coverage for base URL fallback behavior.
- `src/agents/tools/web-tools.fetch.e2e.test.ts`: Added integrated assertions for fallback behavior through the tool execution path.
## Design Notes
- The fallback order preserves explicit config as highest priority while still supporting deployment-time env configuration.
- The schema update is strict and scoped to known Firecrawl fields, which avoids broadening accepted config unexpectedly.
- Coverage is split intentionally between deterministic unit validation and end-to-end execution checks.
## Testing
- `pnpm test -- src/agents/tools/web-fetch.base-url.test.ts src/config/config.schema-regressions.test.ts` (Passed: `2` files, `9` tests)
- `pnpm exec vitest run --config vitest.e2e.config.ts src/agents/tools/web-tools.fetch.e2e.test.ts -t "(uses FIRECRAWL_BASE_URL env var when firecrawl.baseUrl is unset|falls back to DEFAULT_FIRECRAWL_BASE_URL when config and env are unset)"` (Passed: `2` targeted tests)
## AI Disclosure
- [x] AI-assisted
- [x] Fully tested
## Related Issues
- #2527
- #13146
- #3817
---
Closes #20442
Closes #22256
Most Similar PRs
#12794: fix: catch firecrawl fallback errors in web_fetch to prevent unhand...
by zerone0x · 2026-02-09
76.8%
#23534: fix(config): add firecrawl and readability fields to ToolsWebFetchS...
by slayoffer · 2026-02-22
76.4%
#16412: fix(config): align tools.web.fetch schema with firecrawl/readabilit...
by ciberponk · 2026-02-14
76.2%
#19510: fix(config): preserve configured values on invalid config validatio...
by yash27-lab · 2026-02-17
66.5%
#22644: feat(web-fetch): add allowPrivateNetwork config for web_fetch
by qingxuecc · 2026-02-21
66.2%
#23221: fix(cron): recover flat patch params for update action and fix schema
by charojo · 2026-02-22
65.2%
#20249: fix(schema): ensure normalizeToolParameters always includes propert...
by aldoeliacim · 2026-02-18
65.0%
#22660: feat(agents): prioritize fallback-chain recovery and configurable r...
by sauerdaniel · 2026-02-21
65.0%
#19042: Security: add URL allowlist for web_search and web_fetch
by smartprogrammer93 · 2026-02-17
64.9%
#19314: feat: add Brave web_search baseUrl override (AI-assisted)
by mrutunjay-kinagi · 2026-02-17
63.9%