@researai/deepscientist 1.5.16 → 1.5.17

package/docs/en/00_QUICK_START.md

@@ -37,7 +37,7 @@ Prepare these first:
 
 - Node.js `>=18.18` and npm `>=9`; install them from the official download page: https://nodejs.org/en/download
 - one working Codex path:
-  - default OpenAI login path: `codex --login` (or `codex`)
+  - default OpenAI login path: `codex login` (or just `codex`)
   - provider-backed path: one working Codex profile such as `minimax`, `glm`, `ark`, or `bailian`
 - a model or API credential if your project needs external inference
 - GPU or server access if your experiments are compute-heavy
@@ -47,6 +47,7 @@ Prepare these first:
 
 If you are still choosing a coding plan or subscription, these are practical starting points:
 
+- If you just want one simple starting recommendation, start with GPT-5.4 using `xhigh` reasoning effort, or Gemini 3 Pro using `gemini-3-pro-preview`.
 - ChatGPT pricing: https://openai.com/chatgpt/pricing/
 - ChatGPT Plus help: https://help.openai.com/en/articles/6950777-what-is-chatgpt-plus%3F.eps
 - MiniMax Coding Plan: https://platform.minimaxi.com/docs/guides/pricing-codingplan
@@ -54,6 +55,8 @@ If you are still choosing a coding plan or subscription, these are practical sta
 - Alibaba Cloud Bailian Coding Plan: https://help.aliyun.com/zh/model-studio/coding-plan
 - Volcengine Ark Coding Plan: https://www.volcengine.com/docs/82379/1925115?lang=zh
 
+If you plan to use Qwen through Alibaba Bailian, use the Bailian **Coding Plan** endpoint only. The generic Bailian or DashScope Qwen API is not supported in the Codex-backed DeepScientist path.
+
 If you plan to use a provider-backed Codex profile instead of the default OpenAI login flow, read this next:
 
 - [15 Codex Provider Setup](./15_CODEX_PROVIDER_SETUP.md)
@@ -89,7 +92,7 @@ If you want the most reliable path, verify the command immediately:
 
 ```bash
 which codex
-codex --login
+codex login
 ```
 
 If `which codex` prints nothing, the issue is usually the npm global bin path rather than DeepScientist itself. Fix the shell PATH first, then rerun `npm install -g @openai/codex`.
@@ -111,10 +114,10 @@ Choose one of these two paths.
 Run:
 
 ```bash
-codex --login
+codex login
 ```
 
-If your Codex CLI version does not expose `--login`, run:
+If you prefer the interactive first-run flow, run:
 
 ```bash
 codex
@@ -130,7 +133,7 @@ ds doctor
 
 ### 2.2 Provider-backed Codex profile path
 
-If you already use a named Codex profile for MiniMax, GLM, Volcengine Ark, Alibaba Bailian, or another provider-backed path, verify that profile first in a terminal:
+If you already use a named Codex profile for MiniMax, GLM, Volcengine Ark, Alibaba Bailian Coding Plan, or another provider-backed path, verify that profile first in a terminal:
 
 ```bash
 codex --profile m27
@@ -204,6 +207,18 @@ ds --here
 
 This is equivalent to `ds --home "$PWD/DeepScientist"`.
 
+Important:  
+* if you start DeepScientist with `ds --here` or an explicit `--home <path>`, later management commands such as `ds --status` and `ds --stop` should use the same DeepScientist home  
+* using the same `DEEPSCIENTIST_HOME` or `DS_HOME` environment variable for those commands is also fine
+* otherwise, the CLI may fall back to the default `~/DeepScientist`, which can make a reachable daemon look like an unverified one  
+  
+For example, when using a non-default home, run:  
+
+```bash
+ds --status --home /path/to/DeepScientist  
+ds --stop --home /path/to/DeepScientist
+```
+
 If you want another port, run:
 
 ```bash
@@ -421,6 +436,12 @@ Check status:
 ds --status
 ```
 
+If you started DeepScientist with a non-default home, specify it explicitly:  
+
+```bash
+ds --status --home /path/to/DeepScientist
+```
+
 This shows whether the local runtime is up.
 
 Stop the daemon:
@@ -429,8 +450,47 @@ Stop the daemon:
 ds --stop
 ```
 
+If you started DeepScientist with a non-default home, specify it explicitly:  
+
+```bash
+ds --stop --home /path/to/DeepScientist
+```
+
 This stops the local DeepScientist daemon.
 
+Uninstall code and runtime, but keep local data:
+
+```bash
+ds uninstall
+```
+
+If you started DeepScientist with a non-default home, specify it explicitly:
+
+```bash
+ds uninstall --home /path/to/DeepScientist --yes
+```
+
+This removes launcher wrappers, local runtime code, and install-local code trees, but preserves:
+
+- `quests/`
+- `memory/`
+- `config/`
+- `logs/`
+- `plugins/`
+- `cache/`
+
+If you installed DeepScientist from npm and also want to remove the global npm package itself, run this after `ds uninstall`:
+
+```bash
+npm uninstall -g @researai/deepscientist
+```
+
+If you really want to delete local data too, remove the DeepScientist home manually after uninstall:
+
+```bash
+rm -rf /path/to/DeepScientist
+```
+
 Run diagnostics:
 
 ```bash

package/docs/en/01_SETTINGS_REFERENCE.md

@@ -465,7 +465,7 @@ claude:
 - `Test` behavior: checks whether the binary is on `PATH`.
 - Resolution order for `codex`: env override, explicit path, local `PATH`, then bundled fallback.
 - One-off note: you can temporarily override this with `ds --codex /absolute/path/to/codex`.
-- First-run note: DeepScientist does not finish Codex authentication for you. Before the first `ds`, make sure `codex --login` (or `codex`) has completed successfully.
+- First-run note: DeepScientist does not finish Codex authentication for you. Before the first `ds`, make sure `codex login` (or just `codex`) has completed successfully.
 - Repair note: if the bundled dependency is missing after `npm install -g @researai/deepscientist`, install Codex explicitly with `npm install -g @openai/codex`.
 
 **`config_dir`**

package/docs/en/09_DOCTOR.md

@@ -15,7 +15,7 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
    Default OpenAI path:
 
    ```bash
-   codex --login
+   codex login
    ```
 
    Provider-backed profile path:
@@ -55,10 +55,18 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
 - whether required config files are valid
 - whether the current release is still using `codex` as the runnable runner
 - whether the Codex CLI can be found and passes a startup probe
+- whether a recent quest runtime failure already points to a known provider / protocol / retry problem
 - whether an optional local `pdflatex` runtime is available for paper PDF compilation
 - whether the web and TUI bundles exist
 - whether the configured web port is free or already running the correct daemon
 
+`ds doctor` now tries to render failed checks in a more operational form:
+
+- `Problem`: what failed
+- `Why`: why DeepScientist believes it failed
+- `Fix`: the concrete next steps to try
+- `Evidence`: the quest/run/request clues that matched the diagnosis
+
 ## Common fixes
 
 ### Codex is missing
@@ -80,10 +88,10 @@ npm install -g @openai/codex
 Run:
 
 ```bash
-codex --login
+codex login
 ```
 
-If your Codex CLI version does not expose `--login`, run `codex` and finish the interactive setup there.
+If you prefer the interactive first-run flow, run `codex` and finish the setup there.
 
 Finish login once, then rerun `ds doctor`.
 
@@ -109,6 +117,7 @@ Also check:
 
 - the same shell still exports the provider API key
 - the profile points at the provider's Coding Plan endpoint, not the generic API endpoint
+- if you are using Qwen through Alibaba Bailian, use the Bailian Coding Plan endpoint only; the generic Bailian or DashScope Qwen API is not supported here
 - `~/DeepScientist/config/runners.yaml` uses `model: inherit` if the provider expects the model to come from the profile itself
 
 MiniMax-specific note:
@@ -125,6 +134,8 @@ MiniMax-specific note:
 - DeepScientist also strips conflicting `OPENAI_*` auth variables automatically for providers that set `requires_openai_auth = false`
 - if you also want plain terminal `codex --profile <name>` to work directly, put `model_provider = "minimax"` and the matching top-level model such as `MiniMax-M2.7` or `MiniMax-M2.5` in `~/.codex/config.toml`
 - DeepScientist automatically downgrades `xhigh` to `high` when it detects a Codex CLI older than `0.63.0`
+- if the provider returns `tool call result does not follow tool call (2013)`, treat it as a request-ordering/protocol error rather than a transient network failure
+- if the provider returns malformed tool-call argument errors such as `invalid function arguments json string` or `failed to parse tool call arguments`, fix the tool-call serialization path before retrying again
 
 ### The configured Codex model is unavailable
 

package/docs/en/15_CODEX_PROVIDER_SETUP.md

@@ -2,6 +2,8 @@
 
 DeepScientist does not implement separate provider adapters for MiniMax, GLM, Volcengine Ark, or Alibaba Bailian.
 
+For Qwen on Alibaba Bailian, DeepScientist only supports the **Coding Plan** path. The generic Bailian or DashScope Qwen platform API is not supported here.
+
 Instead, it reuses the same Codex CLI setup that already works in your terminal.
 
 The recommended order is always:
@@ -18,7 +20,7 @@ The recommended order is always:
 Use this when your Codex CLI works through the standard OpenAI login flow.
 
 ```bash
-codex --login
+codex login
 ds doctor
 ds
 ```
@@ -62,6 +64,7 @@ Important:
 
 - keep `model: inherit` for provider-backed Codex profiles unless you are certain the provider accepts the explicit model id you plan to send
 - DeepScientist now launches Codex from an isolated runtime home under `.ds/codex-home`, but that runtime copy inherits your configured `~/.codex` auth, config, skills, agents, and prompts first
+- if the active provider uses `wire_api = "chat"`, DeepScientist now auto-checks that the selected Codex binary is exactly `0.57.0` during startup probe
 
 ## Provider matrix
 
@@ -71,14 +74,14 @@ Important:
 | MiniMax | [MiniMax Codex CLI](https://platform.minimaxi.com/docs/coding-plan/codex-cli) | No | your Codex profile, for example `ds --codex-profile m27` |
 | GLM | [GLM Coding Plan: Other Tools](https://docs.bigmodel.cn/cn/coding-plan/tool/others) | No | a Codex profile that targets the GLM coding endpoint |
 | Volcengine Ark | [Ark Coding Plan Overview](https://www.volcengine.com/docs/82379/1925114?lang=zh) | No | a Codex profile that targets the Ark coding endpoint |
-| Alibaba Bailian | [Bailian Coding Plan: Other Tools](https://help.aliyun.com/zh/model-studio/other-tools-coding-plan) | No | a Codex profile that targets the Bailian coding endpoint |
+| Alibaba Bailian | [Bailian Coding Plan: Other Tools](https://help.aliyun.com/zh/model-studio/other-tools-coding-plan) | No | a Codex profile that targets the Bailian Coding Plan endpoint; do not use the generic Bailian or DashScope Qwen API |
 
 ## OpenAI
 
 ### What to prepare
 
 - a normal Codex CLI install
-- a successful `codex --login` or `codex` interactive first-run setup
+- a successful `codex login` or `codex` interactive first-run setup
 
 ### DeepScientist commands
 
@@ -201,6 +204,7 @@ What DeepScientist supports now:
 - if you use this profile-only MiniMax config with Codex CLI `0.57.0`, DeepScientist automatically promotes the selected profile's `model_provider` and `model` to the top level inside its probe/runtime copy of `config.toml`
 - DeepScientist forces provider-backed MiniMax runs to use `model: inherit`, so it does not accidentally override the profile with a hard-coded OpenAI model
 - when `requires_openai_auth = false`, DeepScientist strips conflicting `OPENAI_API_KEY` and `OPENAI_BASE_URL` values from the probe/runtime environment
+- for chat-wire provider sessions such as MiniMax on Codex CLI `0.57.0`, DeepScientist now injects a compatibility guard that tells Codex to serialize MCP tool calls one at a time instead of bundling multiple tool calls into the same response
 - this means DeepScientist can start even when plain terminal `codex --profile m27` still fails on that exact profile-only shape
 
 If you want plain terminal `codex --profile <name>` to work too, use the explicit top-level compatibility form instead:
@@ -350,6 +354,11 @@ codex:
 
 Bailian documents Coding Plan as an OpenAI-compatible coding endpoint. It requires the Coding Plan-specific key and endpoint, not the generic platform endpoint.
 
+For Qwen specifically:
+
+- supported: Qwen through the Bailian **Coding Plan** endpoint
+- not supported: the generic Bailian or DashScope Qwen platform API
+
 Official docs:
 
 - <https://help.aliyun.com/zh/model-studio/other-tools-coding-plan>

package/docs/en/21_LOCAL_MODEL_BACKENDS_GUIDE.md

@@ -0,0 +1,283 @@
+# 21 Local Model Backends Guide: vLLM, Ollama, and SGLang
+
+This guide explains how to run DeepScientist against a local OpenAI-compatible model backend through Codex.
+
+The key point is simple:
+
+- current Codex CLI requires `wire_api = "responses"`
+- a backend that only works through `/v1/chat/completions` is not enough
+- you must verify `/v1/responses` before expecting `ds` or `ds doctor` to succeed
+
+There is one practical fallback:
+
+- if your backend is chat-only, you may still be able to use it through **Codex CLI `0.57.0`**
+- that older path can still work with `wire_api = "chat"` when the provider is configured at the top level
+- DeepScientist now checks this automatically during the Codex startup probe; if it sees `wire_api = "chat"` on any active provider config, it requires `codex-cli 0.57.0` before continuing
+
+## 1. What DeepScientist actually depends on
+
+DeepScientist does not talk to vLLM, Ollama, or SGLang directly.
+
+It talks to:
+
+- `codex`
+- and `codex` talks to your configured provider profile in `~/.codex/config.toml`
+
+So the compatibility chain is:
+
+1. your local backend
+2. Codex profile
+3. Codex startup probe
+4. DeepScientist runner
+
+If step 2 or step 3 fails, DeepScientist cannot start the Codex runner successfully.
+
+## 2. The current Codex rule you must know
+
+On the current Codex CLI:
+
+- `wire_api = "responses"` is supported
+- `wire_api = "chat"` is rejected
+
+In practice that means:
+
+- `vLLM`: recommended if its OpenAI-compatible server exposes `/v1/responses`
+- `Ollama`: only use it if your installed version exposes `/v1/responses`
+- `SGLang`: if your deployment only supports `/v1/chat/completions`, it is not compatible with the latest Codex runner
+
+## 2.1 Support summary
+
+| Backend | `/v1/chat/completions` | `/v1/responses` | Latest Codex | Codex `0.57.0` fallback |
+|---|---|---|---|---|
+| vLLM | yes | yes | supported | usually unnecessary |
+| Ollama | yes | depends on version | supported only when `/v1/responses` works | possible if it is chat-only |
+| SGLang | yes | often missing or incomplete | not supported when it is chat-only | possible fallback path |
+
+## 3. Test the backend first
+
+Before touching DeepScientist, verify the backend directly.
+
+### Step 1: list models
+
+```bash
+curl http://127.0.0.1:8004/v1/models \
+  -H "Authorization: Bearer 1234"
+```
+
+You need one real model id from this output, for example:
+
+```text
+/model/gpt-oss-120b
+```
+
+### Step 2: test chat completions
+
+```bash
+curl http://127.0.0.1:8004/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer 1234" \
+  -d '{
+    "model": "/model/gpt-oss-120b",
+    "messages": [
+      { "role": "user", "content": "Reply with exactly HELLO." }
+    ]
+  }'
+```
+
+If this works, the backend is at least OpenAI-chat-compatible.
+
+### Step 3: test Responses API
+
+```bash
+curl http://127.0.0.1:8004/v1/responses \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer 1234" \
+  -d '{
+    "model": "/model/gpt-oss-120b",
+    "input": "Reply with exactly HELLO."
+  }'
+```
+
+This is the decisive test.
+
+If `/v1/responses` fails, the latest Codex CLI will not work with this backend profile.
+
+## 4. What we actually observed on this server
+
+We tested the local backend at `http://127.0.0.1:8004/v1`.
+
+Observed behavior:
+
+- `GET /v1/models` succeeded
+- `POST /v1/chat/completions` succeeded
+- `POST /v1/responses` returned `500 Internal Server Error`
+- the `/v1/models` payload reported `owned_by: "sglang"`
+
+So this specific `8004` deployment behaves like a chat-compatible SGLang-style server, not a Codex-compatible Responses backend.
+
+That means:
+
+- it can answer raw chat requests
+- but it cannot currently be used by the latest Codex runner
+- and therefore DeepScientist cannot use it through the normal Codex path
+
+We also tested an older Codex path:
+
+- latest Codex + `wire_api = "responses"` failed against this backend
+- Codex `0.57.0` + top-level `model_provider` / `model` + `wire_api = "chat"` succeeded
+
+So for this server specifically:
+
+- **latest Codex path**: no
+- **Codex `0.57.0` fallback**: yes
+
+## 5. Codex profile example for a local Responses-compatible backend
+
+If your backend really supports `/v1/responses`, create a profile like this:
+
+```toml
+[model_providers.local_vllm]
+name = "local_vllm"
+base_url = "http://127.0.0.1:8004/v1"
+env_key = "LOCAL_API_KEY"
+wire_api = "responses"
+requires_openai_auth = false
+
+[profiles.local_vllm]
+model = "/model/gpt-oss-120b"
+model_provider = "local_vllm"
+```
+
+Then test Codex directly first:
+
+```bash
+export LOCAL_API_KEY=1234
+codex exec --profile local_vllm --json --cd /tmp --skip-git-repo-check - <<'EOF'
+Reply with exactly HELLO.
+EOF
+```
+
+If this fails, do not continue to DeepScientist yet.
+
+## 5.1 Chat-only fallback for Codex `0.57.0`
+
+If your backend only supports `/v1/chat/completions`, you can try this fallback path:
+
+1. install Codex `0.57.0`
+2. use `wire_api = "chat"`
+3. put `model_provider` and `model` at the top level
+
+Example:
+
+```toml
+model = "/model/gpt-oss-120b"
+model_provider = "localchat"
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+
+[model_providers.localchat]
+name = "localchat"
+base_url = "http://127.0.0.1:8004/v1"
+env_key = "LOCAL_API_KEY"
+wire_api = "chat"
+requires_openai_auth = false
+```
+
+Then test:
+
+```bash
+export LOCAL_API_KEY=1234
+codex exec --json --cd /tmp --skip-git-repo-check - <<'EOF'
+Reply with exactly HELLO.
+EOF
+```
+
+If this older Codex path works, DeepScientist can usually reuse it with the same runner binary and profile strategy.
+
+## 6. DeepScientist commands after Codex works
+
+Once the direct Codex check works, run:
+
+```bash
+ds doctor --codex-profile local_vllm
+ds --codex-profile local_vllm
+```
+
+`ds doctor` is the canonical command.
+
+`ds docker` is only a legacy alias for `ds doctor`; it is not a Docker deployment command.
+
+If you want to persist it in DeepScientist:
+
+```yaml
+codex:
+  enabled: true
+  binary: codex
+  config_dir: ~/.codex
+  profile: local_vllm
+  model: inherit
+  model_reasoning_effort: high
+  approval_policy: never
+  sandbox_mode: danger-full-access
+```
+
+## 7. Backend compatibility summary
+
+### vLLM
+
+Recommended.
+
+Use it when:
+
+- `/v1/models` works
+- `/v1/responses` works
+- the model id is visible and stable
+
+If those are true, vLLM is the cleanest current local path for Codex + DeepScientist.
+
+### Ollama
+
+Conditionally supported.
+
+Use it only when:
+
+- your Ollama version exposes `/v1/responses`
+- your target model works through that endpoint
+
+If Ollama only gives you chat-completions semantics, it is not enough for the latest Codex CLI, but it may still be usable through Codex `0.57.0`.
+
+### SGLang
+
+Be careful.
+
+If your SGLang deployment behaves like this:
+
+- `/v1/chat/completions` works
+- `/v1/responses` fails
+
+then it is not currently compatible with the latest Codex runner.
+
+If you must use that backend anyway, the realistic fallback is Codex `0.57.0` with `wire_api = "chat"`.
+
+## 8. What to do if you only have chat-completions
+
+If your backend only supports `/v1/chat/completions`, you currently have three practical options:
+
+1. switch to a Responses-compatible backend such as vLLM
+2. upgrade to an Ollama release that really exposes `/v1/responses`
+3. downgrade the Codex CLI path to `0.57.0` and use `wire_api = "chat"`
+4. place a Responses-compatible proxy in front of the backend
+
+Right now, this is a Codex CLI limitation, not a DeepScientist-only setting mistake.
+
+## 9. Recommended workflow
+
+Use this order every time:
+
+1. test `/v1/models`
+2. test `/v1/responses`
+3. test `codex exec --profile <name>`
+4. test `ds doctor --codex-profile <name>`
+5. only then launch `ds --codex-profile <name>`
+
+If step 2 fails, stop there. Do not expect DeepScientist to succeed through the latest Codex path.