Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions docs/step-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -209,6 +209,30 @@ the prompt; deleting that line asks again. `/theme` changes the theme later, and
launches that already carry work (an initial prompt, a resumed session) skip the
prompt entirely.

## Web search backend selection

`search_web` picks its backend from `[search] provider` in `config.toml`, or the
`STEPCODE_SEARCH_PROVIDER` environment variable, which takes precedence:

```toml
[search]
provider = "auto" # auto | step | exa | firecrawl | parallel | tavily | tinyfish | off
```

`auto` walks an ordered chain. The Step search endpoint comes first when the
current login resolves a search credential; otherwise the credential-free
providers are used directly, without attempting the paid endpoint. A paid-tier
failure falls through to the free providers. A provider id pins that backend and
never falls back, and `off` keeps the tool registered but refuses the call.
Any other value is treated as `auto`, so an older configuration or a removed
provider never disables search. Selection is read on every call, so an edit
applies to the next search rather than requiring a new session.

The free providers are called without a credential. They have no configured key
and do not accept a Step credential, so their free allowance is the ceiling.
Their order is shuffled per call, which spreads traffic across the per-provider
allowances rather than always spending the first provider's.

## MCP startup in the terminal

Interactive Step sessions start MCP discovery and connections in the background.
Expand Down
55 changes: 41 additions & 14 deletions packages/coding-agent/docs/step-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,12 +94,15 @@ from it, and `step login status` validates the credential against that profile's
binary updates and the steppage plugin still use mainland endpoints regardless of
profile.

The Step tool profile also registers `search_web`, backed by the remote
`stepsearch.web_search` Streamable HTTP MCP tool. The search credential is
resolved from an explicit `step --api-key`, then `STEPCODE_SEARCH_API_KEY`,
then the Step login entry in `auth.json`; it is sent only as a Bearer header.
Each login profile has its own endpoint, because the endpoint decides which
account the search is billed to: `step_plan` uses
The Step tool profile also registers `search_web`, which resolves an ordered
candidate chain on every call instead of binding one endpoint when the session
starts.

The paid tier is the remote `stepsearch.web_search` Streamable HTTP MCP tool.
Its credential is resolved from an explicit `step --api-key`, then
`STEPCODE_SEARCH_API_KEY`, then the Step login entry in `auth.json`; it is sent
only as a Bearer header. Each login profile has its own endpoint, because the
endpoint decides which account the search is billed to: `step_plan` uses
`https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp` and
`step_plan_oversea` uses `https://api.stepfun.ai/step_plan/v1/mcp/web_search/mcp`,
both billed to the Step Plan quota; `platform_cn` uses
Expand All @@ -112,13 +115,37 @@ a Step Plan credential is never one of those, since it only comes from `/login`,
which always records a profile. `STEPCODE_SEARCH_WEB_MCP_URL` overrides this
profile-based selection; an override that supplies only an origin keeps the path
of the profile's own endpoint, so redirecting the host cannot move a plan user's
searches onto the billed platform path. This adapter does not add a separate
search credential store or `integrations.search` settings surface. The
`STEP_API_KEY` environment variable is deliberately excluded from that
chain: StepCode injects it together with `STEP_BASE_URL` to reach its own
model gateway, and because the search endpoint never follows that base URL,
reusing the value would authenticate a gateway key against
`api.stepfun.com` and fail.
searches onto the billed platform path.

When the credential resolves, the paid endpoint is the first candidate. When it
does not, the paid endpoint is not attempted at all: the free candidates are
used directly, so a call that could only fail is never made. A paid-tier failure
(quota exhausted, rejected credential, unreachable endpoint) advances to the
free candidates instead of failing the tool, and the answer records which
backend served it.

The free candidates are Exa, Firecrawl, Tavily, Parallel, and TinyFish, all
called without a credential: these endpoints do not accept a Step credential and
none of them is configured with one. They answer a single stateless
`tools/call`, skipping the handshake and catalog listing the paid endpoint
performs; a provider that refuses the stateless form is retried once through the
MCP client. Their order is shuffled per call with a deterministic fallback, so
traffic is spread across per-provider free allowances instead of always spending
the first one's. A failed candidate is skipped for a cooldown instead of being
retried on the next call, the whole walk shares one 25-second budget, and a
caller cancellation stops it immediately.

Selection comes from `STEPCODE_SEARCH_PROVIDER`, then `[search] provider` in
`config.toml`, then `auto`. `auto` walks the chain; a provider id pins that one
backend and never falls back; `off` keeps the tool registered but refuses the
call. Any other value is treated as `auto`, so an older configuration or a
removed provider never disables search; selection is read on every call. This
adapter does not add a separate search credential store or
`integrations.search` settings surface. The `STEP_API_KEY` environment variable
is deliberately excluded from that chain: StepCode injects it together with
`STEP_BASE_URL` to reach its own model gateway, and because the search endpoint
never follows that base URL, reusing the value would authenticate a gateway key
against `api.stepfun.com` and fail.

Session storage is also selected through the Step wrapper. The wrapper keeps
the native `SessionManager` class, JSONL format, and tree operations unchanged,
Expand Down Expand Up @@ -457,7 +484,7 @@ service and are not silently faked by this fork.
| StepCode OAuth login/logout and legacy credential normalization | `features/step-provider`, `step/auth.ts`, `step/models-endpoint-repair.ts` | aligned; endpoint repair is tested |
| Global/project settings and session paths | Native managers wrapped by `step/settings-manager.ts` and `step/session.ts` | aligned; writes use `.stepcode` |
| Step permissions, `/permissions`, `/init` | Step extension/facades over native selectors and hooks | aligned; `/effort` replaces the native `/thinking`, while `/permission` and `/mode` remain absent |
| Built-in `search_web` | Step tool profile backed by `stepsearch.web_search` over Streamable HTTP MCP | aligned; uses search-specific environment overrides and the Step login credential fallback |
| Built-in `search_web` | Step tool profile backed by an ordered candidate chain: `stepsearch.web_search` over Streamable HTTP MCP, then credential-free providers | aligned; uses search-specific environment overrides, the Step login credential, and a shared failure budget |
| Top-level `step feedback` and TUI `/feedback` | `step/feedback/`, `stepcode.ts`, and the Step extension over the current session/UI | aligned; the body and optional session bundle use separate Step collector requests |
| `/status`, self-memory/skills governance, `/refresh`, `/rewind`, `/copy` full-transcript semantics | Previous gateway/TUI product layer | not yet ported; no misleading alias is registered |
| `/multi-agent`, `/connect`, `/trace`, gateway/cron | Previous gateway and external channel services | separate product; requires an explicit Step service implementation |
Expand Down
7 changes: 7 additions & 0 deletions packages/coding-agent/src/step/config-toml.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,15 @@ export interface StepMcpServerConfig {
oauth?: { client_id?: string; client_secret?: string; scopes?: string[]; callback_port?: number };
}

/** Search backend selection; see `search-web-tool.ts` for the resolution order. */
export interface StepSearchConfig {
/** `auto` walks the ordered candidate chain; a provider id pins one backend. */
provider?: string;
}

export interface StepConfigDocument {
mcp_servers?: Record<string, StepMcpServerConfig>;
search?: StepSearchConfig;
[key: string]: unknown;
}

Expand Down
Loading