From d60196431c2cf3a31cc57b8975126008719271b6 Mon Sep 17 00:00:00 2001 From: Tianning Li Date: Sun, 1 Nov 2026 20:13:03 +0800 Subject: [PATCH 1/2] docs: fix a stale source path and spelling errors Point the RPC guide at packages/agent-core/src/types.ts, which is where AgentMessage and AgentEvent live now, and correct the spelling mistakes reported in SECURITY.md and the OpenAI-completions adapter comment. Refs #144 --- SECURITY.md | 4 ++-- packages/providers/src/api/openai-completions.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 2bc281a80..36e2e466b 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -48,14 +48,14 @@ repository code are in scope. - Behavior of StepCode extensions or skills installed by the user - Risks from working in untrusted repositories - Risks from installing untrusted extensions, skills, packages, or tools -- Isuses caused by non trustworthy MITM proxies +- Issues caused by non-trustworthy MITM proxies - Public internet exposure of a StepCode installation - Prompt injection attacks - Exposed secrets that are third-party/user-controlled credentials - Reports requiring the ability to create, modify, delete, or replace files, directories, symlinks, environment variables, shell configuration, or other user-controlled local state on the target machine. This includes `~/.stepcode`, - `~/.stepcode/agent/models.json`, workspace files, `AGENTS.md`, skills, extensions, + `~/.stepcode/models.json`, workspace files, `AGENTS.md`, skills, extensions, extension configuration, dotfiles, and files synchronized through NFS, roaming profiles, or dotfile managers, unless the report shows how StepCode itself grants that access. diff --git a/packages/providers/src/api/openai-completions.ts b/packages/providers/src/api/openai-completions.ts index 1be207270..f502987f7 100644 --- a/packages/providers/src/api/openai-completions.ts +++ b/packages/providers/src/api/openai-completions.ts @@ -486,7 +486,7 @@ export const stream: StreamFunction<"openai-completions", OpenAICompletionsOptio } if (!block) { // Note: the "input" fallback here should/must not be taken. in case the LLM makes up - // a tool we don't knwo about, we at least have a place to stash our stuff. + // a tool we don't know about, we at least have a place to stash our stuff. const customInputProperty = toolCall.custom && !toolCall.function ? (grammarToolInputProperties.get(name) ?? "input") : undefined; const hasCustomInput = customInputProperty !== undefined; From fee8435db23790fed9bc91138f9925f382696896 Mon Sep 17 00:00:00 2001 From: Tianning Li Date: Sun, 1 Nov 2026 20:13:10 +0800 Subject: [PATCH 2/2] docs: correct config-root paths and the Step provider dialect models.json, auth.json and models-store.json live in the config root (~/.stepcode, or the parent of STEP_CODING_AGENT_DIR), not under agent/. Update every page that still documents the old location. The built-in Step provider uses openai-completions, not anthropic-messages: the OpenAI adapter appends /chat/completions to {profile base}/v1, stale /v1/messages and /v1 suffixes are stripped before re-appending, and every Step model is pinned to the active profile's dialect with supportsDeveloperRole disabled. Refs #139 --- packages/coding-agent/README.md | 4 ++-- packages/coding-agent/docs/custom-provider.md | 2 +- packages/coding-agent/docs/models.md | 2 +- packages/coding-agent/docs/providers.md | 6 ++--- packages/coding-agent/docs/quickstart.md | 2 +- packages/coding-agent/docs/sdk.md | 4 ++-- .../coding-agent/docs/step-integration.md | 24 ++++++++++--------- packages/providers/README.md | 4 ++-- scripts/smoke/README.md | 2 +- 9 files changed, 26 insertions(+), 24 deletions(-) diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md index 1d58c1e56..df56e43e1 100644 --- a/packages/coding-agent/README.md +++ b/packages/coding-agent/README.md @@ -78,11 +78,11 @@ Then just talk to StepCode. By default, it gives the model four tools: `read`, ` The shipped build authenticates against the **Step provider** by default. Log in with `/login` (or set `STEP_API_KEY`), then select a Step model via `/model` (or Ctrl+L). Press Enter in the model picker to select the highlighted model and save it as the startup default. -No other provider catalog is bundled. Add OpenAI- or Anthropic-compatible providers yourself via `~/.stepcode/agent/models.json`; configured catalogs refresh automatically, and `step update --models` forces an immediate refresh. For custom APIs or OAuth, use extensions. +No other provider catalog is bundled. Add OpenAI- or Anthropic-compatible providers yourself via `~/.stepcode/models.json`; configured catalogs refresh automatically, and `step update --models` forces an immediate refresh. For custom APIs or OAuth, use extensions. StepCode also supports the llama.cpp router server. Configure it with `/login llama.cpp`, manage downloads and loaded models with `/llama`, then select a loaded model with `/model`. See [docs/llama-cpp.md](docs/llama-cpp.md) for setup and usage. -**Custom providers & models:** Add providers via `~/.stepcode/agent/models.json` if they speak a supported API (OpenAI or Anthropic). See [docs/models.md](docs/models.md) and [docs/custom-provider.md](docs/custom-provider.md), or [@step-harness/providers](../providers/README.md) for the underlying protocols. +**Custom providers & models:** Add providers via `~/.stepcode/models.json` if they speak a supported API (OpenAI or Anthropic). See [docs/models.md](docs/models.md) and [docs/custom-provider.md](docs/custom-provider.md), or [@step-harness/providers](../providers/README.md) for the underlying protocols. --- diff --git a/packages/coding-agent/docs/custom-provider.md b/packages/coding-agent/docs/custom-provider.md index f92b507a5..da1f66f8e 100644 --- a/packages/coding-agent/docs/custom-provider.md +++ b/packages/coding-agent/docs/custom-provider.md @@ -381,7 +381,7 @@ interface OAuthLoginCallbacks { ### OAuthCredentials -Credentials are persisted in `~/.stepcode/agent/auth.json`: +Credentials are persisted in `~/.stepcode/auth.json`: ```typescript interface OAuthCredentials { diff --git a/packages/coding-agent/docs/models.md b/packages/coding-agent/docs/models.md index 42d42eeec..992bf1c23 100644 --- a/packages/coding-agent/docs/models.md +++ b/packages/coding-agent/docs/models.md @@ -1,6 +1,6 @@ # Custom Models -Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.stepcode/agent/models.json`. +Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.stepcode/models.json`. ## Table of Contents diff --git a/packages/coding-agent/docs/providers.md b/packages/coding-agent/docs/providers.md index d110e861e..019f531b2 100644 --- a/packages/coding-agent/docs/providers.md +++ b/packages/coding-agent/docs/providers.md @@ -1,6 +1,6 @@ # Providers -Step supports subscription-based providers via OAuth and API key providers via environment variables or auth file. Built-in catalogs ship with step; configured providers may refresh newer catalogs and cache them in `~/.stepcode/agent/models-store.json` for offline use. +Step supports subscription-based providers via OAuth and API key providers via environment variables or auth file. Built-in catalogs ship with step; configured providers may refresh newer catalogs and cache them in `~/.stepcode/models-store.json` for offline use. ## Table of Contents @@ -22,7 +22,7 @@ Use `/login` in interactive mode, then select a provider: - xAI (Grok/X subscription) - OpenRouter (OAuth-minted API key billed from OpenRouter credits) -Use `/logout` to clear credentials. Tokens are stored in `~/.stepcode/agent/auth.json` and auto-refresh when expired. OpenRouter instead mints a user-controlled API key that does not expire automatically. +Use `/logout` to clear credentials. Tokens are stored in `~/.stepcode/auth.json` and auto-refresh when expired. OpenRouter instead mints a user-controlled API key that does not expire automatically. ### OpenAI Codex @@ -102,7 +102,7 @@ Reference for environment variables and `auth.json` keys: [`const envMap`](https #### Auth File -Store credentials in `~/.stepcode/agent/auth.json`: +Store credentials in `~/.stepcode/auth.json`: ```json { diff --git a/packages/coding-agent/docs/quickstart.md b/packages/coding-agent/docs/quickstart.md index 1bf9eed0f..9e0e3a1af 100644 --- a/packages/coding-agent/docs/quickstart.md +++ b/packages/coding-agent/docs/quickstart.md @@ -62,7 +62,7 @@ export ANTHROPIC_API_KEY=sk-ant-... step ``` -You can also run `/login` and select an API-key provider to store the key in `~/.stepcode/agent/auth.json`. +You can also run `/login` and select an API-key provider to store the key in `~/.stepcode/auth.json`. See [Providers](providers.md) for all supported providers, environment variables, and cloud-provider setup. diff --git a/packages/coding-agent/docs/sdk.md b/packages/coding-agent/docs/sdk.md index c74ed179a..572f8a0d4 100644 --- a/packages/coding-agent/docs/sdk.md +++ b/packages/coding-agent/docs/sdk.md @@ -442,7 +442,7 @@ If no model is provided: 2. Uses default from settings 3. Falls back to first available model -Remote catalogs are persisted locally so later runtimes can restore them without a network request. The default file is `~/.stepcode/agent/models-store.json`; set `modelsStorePath` to choose another location, or inject `modelsStore` to control persistence. Network refreshes are throttled to once per provider every four hours unless forced. To force an immediate refresh, call `await modelRuntime.refresh({ allowNetwork: true, force: true, signal })`. +Remote catalogs are persisted locally so later runtimes can restore them without a network request. The default file is `~/.stepcode/models-store.json`; set `modelsStorePath` to choose another location, or inject `modelsStore` to control persistence. Network refreshes are throttled to once per provider every four hours unless forced. To force an immediate refresh, call `await modelRuntime.refresh({ allowNetwork: true, force: true, signal })`. To match CLI model parsing, use the exported resolver helpers: @@ -484,7 +484,7 @@ Authentication resolution priority (handled by `ModelRuntime`): import { InMemoryCredentialStore } from "@step-harness/providers"; import { createAgentSession, ModelRuntime } from "@step-harness/coding-agent"; -// Default: uses ~/.stepcode/agent/auth.json and ~/.stepcode/agent/models.json +// Default: uses ~/.stepcode/auth.json and ~/.stepcode/models.json const modelRuntime = await ModelRuntime.create(); // Provider-owned auth methods and current status diff --git a/packages/coding-agent/docs/step-integration.md b/packages/coding-agent/docs/step-integration.md index 917756d85..479ff5f73 100644 --- a/packages/coding-agent/docs/step-integration.md +++ b/packages/coding-agent/docs/step-integration.md @@ -62,17 +62,19 @@ OpenAI-compatible providers share this normalized event path. The `thinking` label follows thinking events and clears when text or tool output begins. The native presentation does not run this tracker or display these metrics. -The built-in Step provider uses the `anthropic-messages` adapter, which appends -`/v1/messages` to the configured base URL, so the canonical Step base is -`https://api.stepfun.com/step_plan`. For compatibility, `STEP_BASE_URL` also -accepts the older `.../v1` and `.../v1/messages` spellings; the provider -normalizes them before registering the model so the version segment is never -sent twice. Startup also repairs the same stale spellings in an existing -`.stepcode/agent/models.json`, including model-level overrides. If an older -legacy Step projection recorded a built-in Step id as an OpenAI-compatible -model, startup restores its `anthropic-messages` API and Step endpoint as well. -Upgrading from an earlier Step build therefore does not require signing -in again. +The built-in Step provider uses the `openai-completions` adapter, which appends +`/chat/completions` to the profile's OpenAI base (`{profile base}/v1`, for +example `https://api.stepfun.com/step_plan/v1`), so the canonical Step base +remains `https://api.stepfun.com/step_plan`. For compatibility, `STEP_BASE_URL` +and stored endpoints also accept the older `.../v1` and `.../v1/messages` +spellings; the provider strips any trailing `/v1/messages`, `/messages`, or +`/v1` segment before re-appending `/v1`, so the version segment is never sent +twice. Startup also repairs the same stale spellings in an existing +`~/.stepcode/models.json`, including model-level overrides. Every Step model is +forced onto the active profile's OpenAI dialect and base URL with +`supportsDeveloperRole: false`, so a stale models.json overlay cannot misroute +a Step model or send an unsupported `developer` role. Upgrading from an earlier +Step build therefore does not require signing in again. The login page offers one profile per plan and region. Each profile owns its model endpoint, its developer-center login page and the environment variables diff --git a/packages/providers/README.md b/packages/providers/README.md index f33d33a0c..8ad676135 100644 --- a/packages/providers/README.md +++ b/packages/providers/README.md @@ -69,7 +69,7 @@ DeepSeek, ZAI, Qwen, Kimi, OpenRouter, Ant Ling, and OpenCode. Configure providers and models at runtime against any OpenAI- or Anthropic-compatible endpoint on those protocols: -- Declare custom providers in `~/.stepcode/agent/models.json`. +- Declare custom providers in `~/.stepcode/models.json`. - Fetch a live catalog from a provider's `/v1/models` endpoint (for example the Step provider registered by the product). - Build a provider from parts with `createProvider()` (see [Custom Providers](#custom-providers)). @@ -1413,7 +1413,7 @@ Compat is a strict superset of the root entrypoint, so a file can switch its imp ### Adding a New Provider -> The Step-only build ships no built-in providers; the supported way to add one is [`createProvider()`](#createprovider) / a `~/.stepcode/agent/models.json` entry, no package changes required. +> The Step-only build ships no built-in providers; the supported way to add one is [`createProvider()`](#createprovider) / a `~/.stepcode/models.json` entry, no package changes required. Adding a new LLM provider requires changes across multiple files. The layered layout: API implementations live in `src/api/`, provider factories in `src/providers/`, stable generated catalog wrappers live in `src/providers/.models.ts`, and `src/models.generated.ts` registers them. This checklist covers all necessary steps: diff --git a/scripts/smoke/README.md b/scripts/smoke/README.md index b785b25d4..2542870f7 100644 --- a/scripts/smoke/README.md +++ b/scripts/smoke/README.md @@ -10,7 +10,7 @@ npm install # node_modules/dist 随 HEAD 漂移;跑前先装(实 export STEP_PROVIDER=step STEP_MODEL=step-3.7-flash # 固定走 Step,避开默认 anthropic 404 ``` -认证:已 `step login`(OAuth,凭据在 `~/.stepcode/agent/auth.json`)即可;或走 key 链路 `export STEP_API_KEY=`。 +认证:已 `step login`(OAuth,凭据在 `~/.stepcode/auth.json`)即可;或走 key 链路 `export STEP_API_KEY=`。 `step auth check --provider step --json` 因内置静态凭据恒报 `authType:"oauth"`,但真实打模型仍需 OAuth 或 `STEP_API_KEY`。 ## 脚本