dsh-web-search-ddg

Keyless DuckDuckGo web search for DeepSeek Harness. No API key. No account. No credit card. No tokens burned — the search runs as a plain HTTP scrape of DuckDuckGo's lite results page, registered through the harness's public ctx.web provider seam.

Why

DeepSeek Harness is free software. The agent running inside it can be free. Everything a coding agent actually needs — files, shell, git, planning, subagents — is local and costs nothing. Web search was the one wall: every shipped provider requires a paid account (DeepSeek platform key, Exa, Perplexity), while closed tools like Claude Code and ChatGPT bundle live search into their subscriptions.

This plugin exists because "free" shouldn't mean "free, except the internet." Search should not be the feature that forces your first API signup and your first metered bill. It runs on the same public page your browser uses — no quota to exhaust, no key to rotate, nothing to cancel when the trial ends. And because it lives in your checkout rather than someone's endpoint, it is yours to audit, patch, and keep: free software deserves free search.

Features

• Zero credentials — available() is a pure config-shape check; nothing to store in the credential vault
• Zero model tokens — unlike the in-box DeepSeek provider, one search never costs an auxiliary model turn
• Strict mode — zero parsed results raises WEB_PROVIDER_ERROR (anomaly challenge / markup change), never a silent empty success
• Redirect-aware parsing — /l/?uddg= wrappers unwrapped to real targets; internal duckduckgo.com links dropped; duplicate URLs deduplicated
• Entity-safe text — numeric/hex/named entities decoded with & last, so escaped text never double-decodes
• GET and POST — POST form fallback for deployments where GET trips anomaly checks
• Snippet pairing done right — each snippet attaches to its preceding anchor only

Install

Into a profile (recommended)

dsh plugin --profile my-profile add github:tatselkrik/dsh-web-search-ddg

Built artifacts are committed under lib/, so no build-script allowance is needed. The bundle inserts itself into the ctx.web registry; when it is the only usable search provider it is auto-selected. To pin it explicitly, add to your profile's cordis.patch.yml:

- id: web
  name: '@deepseek-ai/dsh-web'
  config:
    searchProvider: duckduckgo

Then start with your profile:

dsh --profile my-profile web

Inside a source checkout (in-tree variant)

Copy src/ into packages/web/web-search-ddg/src/, add the package folder's package.json + tsconfig.json, wire the three files described in the announcement post — or simply copy this repo's src/ over an existing clone of the in-tree version.

Config

Key	Default	Meaning
baseURL	https://lite.duckduckgo.com/lite/	The lite results page; q is appended. Extra params on the base (e.g. ?kl=us-en) are preserved.
limit	10	Provider-level cap on sources per search; the seam still enforces the tool request's maxResults.
method	get	Query verb. post sends q as a URL-encoded form body.
timeoutMs	15000	Wall-clock cap per request, independent of caller cancellation; timeouts surface as WEB_PROVIDER_ERROR.

Override any of them via a patch row:

- id: web-search-ddg
  name: dsh-web-search-ddg
  config:
    limit: 5
    method: post

Security and performance notes

Security

• No secrets, no vault access — the provider reads nothing from the credentials domain; there is nothing to leak.
• No install-time code execution — no prepare/postinstall scripts; lib/ ships committed, so installs run zero build scripts (the supply-chain vector the harness docs warn about).
• Pinned dependency ranges — ^0.1.0 against the published @deepseek-ai/* packages, never *; align them with your running harness version if you prefer exactness.
• Input handling — queries travel only inside the encoded q parameter to your configured baseURL; results are parsed as inert text (never evaluated), and internal/non-http targets are rejected before they can become citations.
• Parser honesty — extraction is regex-based, not a full HTML parser: adequate for the lite page's flat markup, and it only ever sees what DuckDuckGo returns. Treat result titles/snippets like any search tool's output — untrusted text entering model context.
• Privacy — each query is visible to DuckDuckGo Inc. (that's how searching works); nothing else receives anything, and no telemetry exists in this package.

Performance

• One small HTTP round trip per search (~20–60 KB lite page); parsing is a single linear token pass.
• Stateless between calls; per-request wall clock capped at timeoutMs (default 15 s) even if a consumer forgets cancellation.
• Result count bounded by limit before the seam applies its own maxResults, so context cost stays predictable.
• Contrast: the in-box DeepSeek provider pays a full auxiliary model turn (seconds + tokens) per search; this pays one fetch.

Known limitations

• Unofficial endpoint — no SLA. Aggressive bursts can earn 403s/CAPTCHAs; markup changes break parsing loudly until patched.
• No published dates — the lite page does not expose them.
• Bing-index depth — result quality tracks DuckDuckGo's index, slightly behind Google for niche technical queries.
• Peer dependency versions — declared with loose ranges against the harness packages; if you hit class-identity issues (WebError instanceof) between a registry-installed copy and an in-box copy, pin dependencies to match your running harness version.

Development

pnpm install          # inside a DeepSeek Harness checkout that provides the peer packages
pnpm exec tsc -b .    # emit lib/types
pnpm exec vitest run packages/web/web-search-ddg   # from the checkout root: 19 tests

lib/ is committed so end users never need a build step.

License

MIT