Add the searxng extension (web_search tool over a self-hosted SearXNG instance) #282

New issue

Closed

opened 2026-09-26 02:54:33 +00:00 by yousuf · 0 comments

yousuf commented

2026-09-26 02:54:33 +00:00

Collaborator

Summary

Add a searxng extension registering a single web_search tool that queries a self-hosted SearXNG instance and returns shaped JSON results (title, url, snippet, engine).

Background

The other network-backed extensions in this repo (victorialogs, mongodb, vision) each wrap one external service behind a small tool surface. Web search is the remaining gap: there is currently no way for an agent in this package to find a page before reading it with fetch/read.

Self-hosting SearXNG keeps queries off third-party search APIs and avoids per-call billing, at the cost of running a container.

Implementation details

src/env.ts — resolve SEARXNG_URL (and optional auth) from the project .env
src/client.ts — searxngRequest, always forcing format=json since the HTML default is unparseable here
src/defaults.ts — default limit/page handling
src/errors.ts — typed HttpError
src/tools/search.ts — the web_search tool: shapes results, caps hits at 50, surfaces unresponsive_engines in details
docker-compose.yml + config/settings.yml — local instance; settings.yml must enable the json format, which SearXNG disables by default
Manifest entry in root package.json
Root README.md rows (extensions table, prerequisites, extension notes, repo layout)

Acceptance criteria

web_search returns shaped hits as pretty-printed JSON with a matching resultCount
format=json is always requested regardless of caller input
categories, engines, language, time_range and page are forwarded when supplied and omitted when not
Results are capped at 50 with the response flagged as truncated, and totalBeforeLimit reports the pre-limit count
A 403 raises a ToolError naming the settings.yml fix (the JSON format is off by default)
A connection failure raises a ToolError asking whether the container is running
A malformed body degrades to an empty hit list rather than throwing
The extension is listed in the root README.md
.env is never committed

Test plan

bun test in extensions/searxng/, covering client, defaults, env, errors and tools/search with a stubbed fetch — no live instance required.

## Summary Add a `searxng` extension registering a single `web_search` tool that queries a self-hosted [SearXNG](https://docs.searxng.org/) instance and returns shaped JSON results (title, url, snippet, engine). ## Background The other network-backed extensions in this repo (`victorialogs`, `mongodb`, `vision`) each wrap one external service behind a small tool surface. Web search is the remaining gap: there is currently no way for an agent in this package to find a page before reading it with `fetch`/`read`. Self-hosting SearXNG keeps queries off third-party search APIs and avoids per-call billing, at the cost of running a container. ## Implementation details - `src/env.ts` — resolve `SEARXNG_URL` (and optional auth) from the project `.env` - `src/client.ts` — `searxngRequest`, always forcing `format=json` since the HTML default is unparseable here - `src/defaults.ts` — default limit/page handling - `src/errors.ts` — typed `HttpError` - `src/tools/search.ts` — the `web_search` tool: shapes results, caps hits at 50, surfaces `unresponsive_engines` in details - `docker-compose.yml` + `config/settings.yml` — local instance; `settings.yml` must enable the `json` format, which SearXNG disables by default - Manifest entry in root `package.json` - Root `README.md` rows (extensions table, prerequisites, extension notes, repo layout) ## Acceptance criteria - [ ] `web_search` returns shaped hits as pretty-printed JSON with a matching `resultCount` - [ ] `format=json` is always requested regardless of caller input - [ ] `categories`, `engines`, `language`, `time_range` and `page` are forwarded when supplied and omitted when not - [ ] Results are capped at 50 with the response flagged as truncated, and `totalBeforeLimit` reports the pre-limit count - [ ] A 403 raises a `ToolError` naming the `settings.yml` fix (the JSON format is off by default) - [ ] A connection failure raises a `ToolError` asking whether the container is running - [ ] A malformed body degrades to an empty hit list rather than throwing - [ ] The extension is listed in the root `README.md` - [ ] `.env` is never committed ## Test plan `bun test` in `extensions/searxng/`, covering `client`, `defaults`, `env`, `errors` and `tools/search` with a stubbed fetch — no live instance required.

yousuf added the

feature

label

2026-09-26 02:54:33 +00:00

yousuf referenced this issue from a pull request that will close it,

2026-09-26 02:55:23 +00:00

issue-282: add searxng extension #283