Skip to content

feat(search): fall back to credential-free providers for web search - #364

Merged
liuedcson merged 2 commits into
mainfrom
feat/search-web-multi-provider
Nov 21, 2026
Merged

liuedcson merged 2 commits into
mainfrom
feat/search-web-multi-provider

Conversation

@liuedcson

@liuedcson liuedcson commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

What

search_web now resolves its backend on every call and walks an ordered candidate chain instead of binding one StepFun endpoint at tool-creation time.

Why

A session using a self-configured model could not search at all. search_web required a StepFun search credential, so it either failed with requires a credential or used a stale key against the StepFun endpoint and received 401/402. Because the endpoint and credential were computed in createSearchWebTool, logging in during a session had no effect either.

How

Chain construction

  • When the current login resolves a search credential, the StepFun endpoint is the first candidate. A quota, auth, network or timeout failure falls through to the free providers rather than failing the tool.
  • Without a credential the paid endpoint is absent from the chain, not attempted and failed. This skips a call that cannot succeed (~4.1s measured).
  • The free providers are Exa, Firecrawl, Tavily, Parallel, and TinyFish. They are called without a credential and in a per-call shuffled order, so traffic spreads across their independent free allowances instead of always spending the first one's.

Failure classification

isError first, then the HTTP status, then the body text. Several providers answer HTTP 200 with an error body, and treating that as "no results" would stop the chain while hiding an exhausted quota. A daily ceiling reported under 429 is classified as a quota, not a burst limit.

Scheduling

One shared 25s deadline covers every attempt including the handshake fallback, cooldowns skip known-bad candidates, a rejected credential-free provider is skipped for the rest of the process, and a caller cancellation stops the walk immediately.

Configuration

STEPCODE_SEARCH_PROVIDER > [search] provider in config.toml > auto. Supported values are auto, off, step, and the five free provider ids; any other value is treated as auto. Selection is re-read per call, so an edit applies to the next search.

Compatibility

The tool contract is unchanged: same name, same {query} input, same markdown rendering with the Sources convention, same details fields (plus provider and degraded), same read-only permission entry, same executionMode: "parallel".

Stepping back to the previous behaviour needs no code change: STEPCODE_SEARCH_PROVIDER=step pins the paid endpoint as a single-candidate chain.

Validation

Measured against the live endpoints after the fix:

provider hits latency
Exa 10 768ms
Firecrawl 10 806ms
Tavily 10 2589ms
Parallel 10 1458ms
TinyFish 10 703ms

Scenario runs through createSearchWebTool().execute() — 13/13 passed: each pinned provider, auto without a credential, repeated calls on one instance, config.toml selection, an unknown config value, off, an empty config, and a pinned step without a credential.

Tests: 148 cases across 7 related files, including 11 end-to-end scenario cases that drive the tool rather than the chain builder.

pnpm run check passes (biome, type checks, all boundary checks).

Notes

  • No new telemetry event: tool_call_completed is registered but has no producer in this repository, so a new event would be equally unreachable. The result details carry provider and degraded instead.
  • Free providers are credential-free by design. A Step credential is only valid against the StepFun endpoint, and these endpoints do not accept one. Availability therefore tracks their free allowances, which have no SLA.

Review follow-up

Two review nits, both now fixed:

  • The provider option JSDoc listed config.toml before the environment variable. The implementation is explicit ?? env ?? config, so the doc is corrected rather than the code.
  • The rewrite rendered results strictly by array index and dropped entries without a URL. That silently changed what the model sees for the paid endpoint: a provider-assigned position was renumbered, and a URL-less entry disappeared instead of being shown as position. title. Both are restored, and a test now pins the numbering, the URL-less entry and the index fallback.

`search_web` required a StepFun search credential, so a session using a
self-configured model could not search at all: it failed with "requires a
credential", or used a stale key against the StepFun endpoint and received
401/402. Search was also bound at tool creation time, so logging in during
a session had no effect.

Resolve the backend on every call and walk an ordered candidate chain:

- The StepFun endpoint stays first whenever the current login resolves a
  search credential, which keeps paid users on the better path. A quota,
  auth, network or timeout failure falls through to the free providers
  instead of failing the tool.
- Without a credential the paid endpoint is absent from the chain rather
  than attempted and failed, which skips a call that cannot succeed.
- The free providers (Exa, Firecrawl, Tavily, Parallel, TinyFish) are
  called without a credential, in a per-call shuffled order so traffic is
  spread across their independent free allowances.
- Selection is re-read per call from STEPCODE_SEARCH_PROVIDER, then
  [search] provider, then auto. An unrecognized value degrades to auto.

Failures are classified by the provider's `isError` flag first, then the
status code, then the body text: several providers answer HTTP 200 with an
error body, and treating that as "no results" would stop the chain and hide
an exhausted quota. Each failure is attributed to its provider, cooldowns
skip known-bad candidates, and a rejected credential-free provider is
skipped for the rest of the process.

The tool contract is unchanged: same name, same input, same rendering and
details fields, same permission entry.
…ntries

The rewrite rendered results strictly by array index and dropped entries
without a URL. Both changed what the model sees for the paid endpoint:

- a provider-assigned `position` was replaced with the array index, so a
  numbering gap was silently renumbered;
- an entry without a URL was removed instead of being shown under its
  position and title.

Restore both, and correct the `provider` option JSDoc: the environment
variable takes precedence over config.toml, not the other way round.

The added case pins the numbering, the URL-less entry, and the index
fallback so a later refactor cannot quietly drop them again.
@liuedcson
liuedcson merged commit 414416e into main Nov 21, 2026
2 checks passed
@liuedcson
liuedcson deleted the feat/search-web-multi-provider branch November 21, 2026 03:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant