@researai/deepscientist 1.5.7 → 1.5.8

package/README.md

@@ -17,6 +17,8 @@ Install DeepScientist:
 npm install -g @researai/deepscientist
 ```
 
+For the best experience, we recommend using GPT-5.4 in `xhigh` mode (for example, via the $20 GPT Plus plan or the $200 GPT Pro plan); if you are in China, we recommend the MiniMax-M2.7 Token Plan (Max plan): https://platform.minimaxi.com/subscribe/token-plan
+
 ## Start
 
 ```bash
@@ -124,6 +126,8 @@ This installs a lightweight TinyTeX `pdflatex` runtime for local paper compilati
 - [快速开始（中文）](docs/zh/00_QUICK_START.md)
 - [QQ Connector Guide (English)](docs/en/03_QQ_CONNECTOR_GUIDE.md)
 - [QQ Connector Guide (中文)](docs/zh/03_QQ_CONNECTOR_GUIDE.md)
+- [Memory and MCP Guide (English)](docs/en/07_MEMORY_AND_MCP.md)
+- [Memory 与 MCP 指南（中文）](docs/zh/07_MEMORY_AND_MCP.md)
 
 ## Maintainers
 

package/bin/ds.js

@@ -220,6 +220,17 @@ function compareVersions(left, right) {
   return 0;
 }
 
+function hasActiveBusyUpdate(state, currentVersion) {
+  if (!state || !state.busy) {
+    return false;
+  }
+  const targetVersion = normalizeVersion(state.target_version || state.latest_version || '');
+  if (!targetVersion) {
+    return false;
+  }
+  return compareVersions(targetVersion, currentVersion) > 0;
+}
+
 function detectInstallMode(rootPath = repoRoot) {
   const normalized = String(rootPath || '');
   return normalized.includes(`${path.sep}node_modules${path.sep}`) ? 'npm-package' : 'source-checkout';
@@ -326,6 +337,8 @@ function buildUpdateStatus(home, statePatch = {}) {
   const support = updateSupportSummary(installMode, npmBinary, launcherPath);
   const currentVersion = normalizeVersion(state.current_version || packageJson.version);
   const latestVersion = normalizeVersion(state.latest_version || '');
+  const targetVersion = normalizeVersion(state.target_version || '');
+  const busy = hasActiveBusyUpdate(state, currentVersion);
   const promptedVersion = normalizeVersion(state.last_prompted_version || '');
   const updateAvailable = Boolean(latestVersion) && compareVersions(latestVersion, currentVersion) > 0;
   const skippedVersion = normalizeVersion(state.last_skipped_version || '');
@@ -333,7 +346,7 @@ function buildUpdateStatus(home, statePatch = {}) {
   const skippedCurrentTarget = Boolean(updateAvailable && skippedVersion && skippedVersion === latestVersion);
   const promptRecommended =
     Boolean(updateAvailable)
-    && !Boolean(state.busy)
+    && !busy
     && !promptedCurrentTarget
     && !skippedCurrentTarget
     ;
@@ -348,7 +361,7 @@ function buildUpdateStatus(home, statePatch = {}) {
     latest_version: latestVersion || null,
     update_available: updateAvailable,
     prompt_recommended: promptRecommended,
-    busy: Boolean(state.busy),
+    busy,
     last_checked_at: state.last_checked_at || null,
     last_check_error: state.last_check_error || null,
     last_prompted_at: state.last_prompted_at || null,
@@ -358,7 +371,7 @@ function buildUpdateStatus(home, statePatch = {}) {
     last_update_started_at: state.last_update_started_at || null,
     last_update_finished_at: state.last_update_finished_at || null,
     last_update_result: state.last_update_result || null,
-    target_version: normalizeVersion(state.target_version || '') || null,
+    target_version: busy ? targetVersion || latestVersion || null : null,
     manual_update_command: updateManualCommand(installMode),
     reason: support.reason,
   };
@@ -371,8 +384,16 @@ function checkForUpdates(home, { force = false, timeoutMs = 3500 } = {}) {
   const npmBinary = resolveNpmBinary();
   const launcherPath = resolveLauncherPath();
   const support = updateSupportSummary(installMode, npmBinary, launcherPath);
+  const existingBusyIsStale = Boolean(existing.busy) && !hasActiveBusyUpdate(existing, currentVersion);
 
   if (!force && existing.current_version === currentVersion && !isExpired(existing.last_checked_at, UPDATE_CHECK_TTL_MS)) {
+    if (existingBusyIsStale) {
+      const repaired = mergeUpdateState(home, {
+        busy: false,
+        target_version: null,
+      });
+      return buildUpdateStatus(home, repaired);
+    }
     return buildUpdateStatus(home);
   }
 
@@ -392,6 +413,13 @@ function checkForUpdates(home, { force = false, timeoutMs = 3500 } = {}) {
     last_checked_at: new Date().toISOString(),
     last_check_error: probe.ok ? null : probe.error,
   });
+  if (Boolean(patched.busy) && !hasActiveBusyUpdate(patched, currentVersion)) {
+    const repaired = mergeUpdateState(home, {
+      busy: false,
+      target_version: null,
+    });
+    return buildUpdateStatus(home, repaired);
+  }
   return buildUpdateStatus(home, patched);
 }
 
@@ -1142,6 +1170,40 @@ function buildGlobalWrapperScript({ installDir, home, commandName }) {
   return [
     '#!/usr/bin/env bash',
     'set -euo pipefail',
+    'WRAPPER_PATH="${BASH_SOURCE[0]}"',
+    'WRAPPER_DIR="$(cd "$(dirname "$WRAPPER_PATH")" && pwd)"',
+    `PREFERRED_COMMAND="${commandName}"`,
+    'LOOKUP_PATH=""',
+    'OLD_IFS="$IFS"',
+    'IFS=:',
+    'for ENTRY in $PATH; do',
+    '  if [ -z "$ENTRY" ]; then',
+    '    continue',
+    '  fi',
+    '  ENTRY_REAL="$ENTRY"',
+    '  if ENTRY_CANONICAL="$(cd "$ENTRY" 2>/dev/null && pwd)"; then',
+    '    ENTRY_REAL="$ENTRY_CANONICAL"',
+    '  fi',
+    '  if [ "$ENTRY_REAL" = "$WRAPPER_DIR" ]; then',
+    '    continue',
+    '  fi',
+    '  if [ -z "$LOOKUP_PATH" ]; then',
+    '    LOOKUP_PATH="$ENTRY"',
+    '  else',
+    '    LOOKUP_PATH="$LOOKUP_PATH:$ENTRY"',
+    '  fi',
+    'done',
+    'IFS="$OLD_IFS"',
+    'if [ -n "$LOOKUP_PATH" ]; then',
+    '  if RESOLVED_LAUNCHER="$(PATH="$LOOKUP_PATH" command -v "$PREFERRED_COMMAND" 2>/dev/null)"; then',
+    '    if [ -n "$RESOLVED_LAUNCHER" ] && [ "$RESOLVED_LAUNCHER" != "$WRAPPER_PATH" ]; then',
+    '      if [ -z "${DEEPSCIENTIST_HOME:-}" ]; then',
+    `        export DEEPSCIENTIST_HOME="${home}"`,
+    '      fi',
+    '      exec "$RESOLVED_LAUNCHER" "$@"',
+    '    fi',
+    '  fi',
+    'fi',
     'if [ -z "${DEEPSCIENTIST_HOME:-}" ]; then',
     `  export DEEPSCIENTIST_HOME="${home}"`,
     'fi',
@@ -1150,6 +1212,18 @@ function buildGlobalWrapperScript({ installDir, home, commandName }) {
   ].join('\n');
 }
 
+function buildLauncherWrapperScript({ launcherPath, home }) {
+  return [
+    '#!/usr/bin/env bash',
+    'set -euo pipefail',
+    'if [ -z "${DEEPSCIENTIST_HOME:-}" ]; then',
+    `  export DEEPSCIENTIST_HOME="${home}"`,
+    'fi',
+    `exec "${launcherPath}" "$@"`,
+    '',
+  ].join('\n');
+}
+
 function writeExecutableScript(targetPath, content) {
   ensureDir(path.dirname(targetPath));
   fs.writeFileSync(targetPath, content, { encoding: 'utf8', mode: 0o755 });
@@ -1186,6 +1260,94 @@ function candidateWrapperPathsForCommand(commandName) {
   return candidates;
 }
 
+function parseLegacyWrapperCandidate(candidatePath) {
+  let stat = null;
+  try {
+    stat = fs.lstatSync(candidatePath);
+  } catch {
+    return null;
+  }
+
+  if (stat.isSymbolicLink()) {
+    let resolved = null;
+    try {
+      resolved = fs.realpathSync(candidatePath);
+    } catch {
+      return null;
+    }
+    if (!/[\\/]cli[\\/]bin[\\/](?:ds|ds-cli|research|resear)(?:\.cmd)?$/.test(resolved)) {
+      return null;
+    }
+    return {
+      source: 'symlink',
+      execPath: resolved,
+      home: path.dirname(path.dirname(path.dirname(resolved))),
+    };
+  }
+
+  if (!stat.isFile()) {
+    return null;
+  }
+
+  let text = '';
+  try {
+    text = fs.readFileSync(candidatePath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  const execMatch = text.match(/exec "([^"\n]+[\\/]bin[\\/](?:ds|ds-cli|research|resear))" "\$@"/);
+  if (!execMatch) {
+    return null;
+  }
+  const execPath = execMatch[1];
+  if (!/[\\/]cli[\\/]bin[\\/](?:ds|ds-cli|research|resear)$/.test(execPath)) {
+    return null;
+  }
+  const homeMatch = text.match(/export DEEPSCIENTIST_HOME="([^"\n]+)"/);
+  return {
+    source: 'script',
+    execPath,
+    home: homeMatch ? homeMatch[1] : path.dirname(path.dirname(path.dirname(execPath))),
+  };
+}
+
+function repairLegacyPathWrappers({ home, launcherPath, force = false }) {
+  if (process.platform === 'win32') {
+    return [];
+  }
+  if (!launcherPath || !fs.existsSync(launcherPath)) {
+    return [];
+  }
+  if (!force && detectInstallMode(repoRoot) !== 'npm-package') {
+    return [];
+  }
+
+  const rewritten = [];
+  const seen = new Set();
+  for (const commandName of launcherWrapperCommands) {
+    for (const candidate of candidateWrapperPathsForCommand(commandName)) {
+      if (seen.has(candidate)) {
+        continue;
+      }
+      seen.add(candidate);
+      const legacy = parseLegacyWrapperCandidate(candidate);
+      if (!legacy) {
+        continue;
+      }
+      writeExecutableScript(
+        candidate,
+        buildLauncherWrapperScript({
+          launcherPath,
+          home: legacy.home || home,
+        })
+      );
+      rewritten.push(candidate);
+    }
+  }
+  return rewritten;
+}
+
 function rewriteLauncherWrappersIfPointingAtSource({ sourceHome, targetHome }) {
   if (process.platform === 'win32') {
     return [];
@@ -2622,19 +2784,45 @@ function spawnDetachedNode(args, options = {}) {
 async function performSelfUpdate(home, options = {}) {
   const status = checkForUpdates(home, { force: true });
   if (!status.update_available) {
+    const message = `DeepScientist is already on the latest version (${status.current_version}).`;
+    mergeUpdateState(home, {
+      current_version: status.current_version,
+      latest_version: status.latest_version,
+      busy: false,
+      target_version: null,
+      last_update_finished_at: new Date().toISOString(),
+      last_update_result: {
+        ok: true,
+        target_version: null,
+        message,
+      },
+    });
     return {
       ok: true,
       updated: false,
       status,
-      message: `DeepScientist is already on the latest version (${status.current_version}).`,
+      message,
     };
   }
   if (!status.can_self_update) {
+    const message = status.reason || `Manual update required: ${status.manual_update_command}`;
+    mergeUpdateState(home, {
+      current_version: status.current_version,
+      latest_version: status.latest_version,
+      busy: false,
+      target_version: null,
+      last_update_finished_at: new Date().toISOString(),
+      last_update_result: {
+        ok: false,
+        target_version: status.latest_version || null,
+        message,
+      },
+    });
     return {
       ok: false,
       updated: false,
       status,
-      message: status.reason || `Manual update required: ${status.manual_update_command}`,
+      message,
     };
   }
 
@@ -2697,6 +2885,11 @@ async function performSelfUpdate(home, options = {}) {
     };
   }
 
+  repairLegacyPathWrappers({
+    home,
+    launcherPath: resolveLauncherPath(),
+  });
+
   const restartDaemon =
     options.restartDaemon === true
     || (options.restartDaemon !== false && Boolean(daemonState?.pid || daemonState?.daemon_id));
@@ -2799,6 +2992,22 @@ async function startBackgroundUpdateWorker(home, options = {}) {
     };
   }
   const status = checkForUpdates(home, { force: false });
+  if (!status.update_available) {
+    return {
+      ok: true,
+      started: false,
+      message: `DeepScientist is already on the latest version (${status.current_version}).`,
+      status,
+    };
+  }
+  if (!status.can_self_update) {
+    return {
+      ok: false,
+      started: false,
+      message: status.reason || `Manual update required: ${status.manual_update_command}`,
+      status,
+    };
+  }
   mergeUpdateState(home, {
     current_version: status.current_version,
     latest_version: status.latest_version,
@@ -3311,6 +3520,10 @@ async function launcherMain(rawArgs) {
   const home = options.home || resolveHome(rawArgs);
   applyLauncherProxy(options.proxy);
   ensureDir(home);
+  repairLegacyPathWrappers({
+    home,
+    launcherPath: resolveLauncherPath(),
+  });
 
   if (options.stop) {
     await stopDaemon(home);
@@ -3460,6 +3673,8 @@ module.exports = {
     parseLauncherArgs,
     normalizeProxyUrl,
     parseMigrateArgs,
+    parseLegacyWrapperCandidate,
+    repairLegacyPathWrappers,
     useEditableProjectInstall,
     compareVersions,
     detectInstallMode,

package/docs/en/07_MEMORY_AND_MCP.md

@@ -209,7 +209,44 @@ Example:
 Do not replace an experiment artifact with a memory card.
 Do not replace a reusable lesson with a progress artifact.
 
-## 4. Bash exec usage
+## 4. Artifact metric-contract rules
+
+Use `artifact` as the authoritative submission surface for baseline and main-experiment metrics.
+
+### `artifact.confirm_baseline(...)`
+
+For a confirmed baseline:
+
+- the canonical metric contract should live in `<baseline_root>/json/metric_contract.json`
+- the canonical `metrics_summary` should be a flat top-level dictionary keyed by the paper-facing metric ids
+- if the raw evaluator output is nested, map each required canonical metric through explicit `origin_path` fields inside `metric_contract.metrics`
+- every canonical baseline metric entry should explain where the number came from:
+  - `description`
+  - either `derivation` or `origin_path`
+  - `source_ref`
+- keep `primary_metric` as the headline metric only; do not use it to erase the rest of the accepted paper-facing comparison surface
+
+### `artifact.record_main_experiment(...)`
+
+For a main experiment recorded against a confirmed baseline:
+
+- use the confirmed baseline metric-contract JSON as the canonical comparison contract
+- report every required baseline metric id in the main experiment submission
+- extra metrics are allowed, but missing required baseline metrics are not
+- keep the original evaluation code and metric definitions for the canonical baseline metrics
+- if an extra evaluator is genuinely necessary, record it as supplementary evidence instead of replacing the canonical comparator
+
+### Validation and temporary notes
+
+- when the MCP tool runs strict validation, contract failures return structured error payloads such as:
+  - `missing_metric_ids`
+  - `baseline_metric_ids`
+  - `baseline_metric_details`
+  - `evaluation_protocol_mismatch`
+- `Result/metric.md` may be used as temporary scratch memory while working, but it is optional and not authoritative
+- if `Result/metric.md` exists, reconcile it against the final baseline or main-experiment submission before calling the artifact tool
+
+## 5. Bash exec usage
 
 Use `bash_exec` for monitored commands:
 
@@ -226,7 +263,7 @@ bash_exec.bash_exec(mode="read", id="<bash_id>")
 
 Use `kill` only when the quest truly needs to stop the session.
 
-## 5. Prompt-level expectations
+## 6. Prompt-level expectations
 
 The agent should normally follow this discipline:
 
@@ -237,7 +274,7 @@ The agent should normally follow this discipline:
 5. `bash_exec` for durable shell work
 6. `memory.write(...)` only after a real durable finding appears
 
-## 6. UI expectation
+## 7. UI expectation
 
 In `/projects/{id}` Studio trace:
 

package/docs/en/99_ACKNOWLEDGEMENTS.md

@@ -11,6 +11,7 @@ We especially thank the following projects for their ideas, research direction,
 - AlphaEvolve
 - OpenEvolve
 - EvoScientist
+- Orchestra-Research
 - Orchestra-Research/AI-Research-SKILLs
 
 These projects have been important references for thinking about automated research, open-ended exploration, evolutionary search, experiment organization, and long-horizon research agents.

package/docs/zh/07_MEMORY_AND_MCP.md

@@ -192,7 +192,44 @@ updated_at: 2026-03-11T18:00:00+00:00
 不要用 memory 代替实验 artifact。
 不要用 artifact 代替可复用知识卡。
 
-## 4. Bash exec 的基本用法
+## 4. Artifact 指标契约规则
+
+baseline 与主实验的正式指标提交，应以 `artifact` 为唯一权威入口。
+
+### `artifact.confirm_baseline(...)`
+
+对于已确认的 baseline：
+
+- canonical metric contract 应保存在 `<baseline_root>/json/metric_contract.json`
+- canonical `metrics_summary` 应是顶层扁平字典，key 直接使用论文面对比时的 metric id
+- 如果原始评测输出是嵌套结构，应在 `metric_contract.metrics` 中为每个必需 canonical metric 提供显式 `origin_path`，而不是直接提交嵌套 blob
+- 每个 canonical baseline metric 都应说明数值来源，至少包含：
+  - `description`
+  - `derivation` 或 `origin_path`
+  - `source_ref`
+- `primary_metric` 只是 headline metric，不能借此删掉其他论文面对比所需指标
+
+### `artifact.record_main_experiment(...)`
+
+对于基于已确认 baseline 的主实验：
+
+- 默认以已确认 baseline 的 metric-contract JSON 作为 canonical comparison contract
+- 主实验提交时必须覆盖 baseline 的全部必需 metric id
+- 可以多报额外指标，但不能缺少 baseline 的必需指标
+- canonical baseline metrics 应继续使用原有评测代码和指标定义
+- 如果确实需要额外评测器，应把它作为 supplementary evidence 记录，而不是替换 canonical comparator
+
+### 校验失败与临时记录
+
+- 当 MCP 工具开启严格校验时，失败会返回结构化错误字段，例如：
+  - `missing_metric_ids`
+  - `baseline_metric_ids`
+  - `baseline_metric_details`
+  - `evaluation_protocol_mismatch`
+- `Result/metric.md` 只可作为工作过程中的临时草稿/记忆文件，不是必需文件，也不是权威来源
+- 如果存在 `Result/metric.md`，请在调用 artifact 提交前用它核对最终 baseline 或主实验提交内容，避免遗漏或写错
+
+## 5. Bash exec 的基本用法
 
 用于可监控命令：
 
@@ -209,7 +246,7 @@ bash_exec.bash_exec(mode="read", id="<bash_id>")
 
 只有在确实需要停止时才使用 `kill`。
 
-## 5. Prompt 级纪律（建议）
+## 6. Prompt 级纪律（建议）
 
 通常推荐遵循：
 
@@ -220,7 +257,7 @@ bash_exec.bash_exec(mode="read", id="<bash_id>")
 5. 长任务 shell 用 `bash_exec`
 6. 有真正的可复用发现才 `memory.write(...)`
 
-## 6. UI 期望
+## 7. UI 期望
 
 在 `/projects/{id}` 的 Studio trace 中：
 

package/docs/zh/99_ACKNOWLEDGEMENTS.md

@@ -11,6 +11,7 @@ DeepScientist 的构思、架构设计与实现过程中，受到了许多优秀
 - AlphaEvolve
 - OpenEvolve
 - EvoScientist
+- Orchestra-Research
 - Orchestra-Research/AI-Research-SKILLs
 
 这些项目在自动化科研、开放式探索、进化式搜索、实验组织与智能研究代理等方向上的探索，为 DeepScientist 的设计提供了重要参照。

package/install.sh

@@ -421,6 +421,40 @@ write_global_wrapper() {
   cat >"$target_path" <<EOF
 #!/usr/bin/env bash
 set -euo pipefail
+WRAPPER_PATH="\${BASH_SOURCE[0]}"
+WRAPPER_DIR="\$(cd "\$(dirname "\$WRAPPER_PATH")" && pwd)"
+PREFERRED_COMMAND="$command_name"
+LOOKUP_PATH=""
+OLD_IFS="\$IFS"
+IFS=:
+for ENTRY in \$PATH; do
+  if [ -z "\$ENTRY" ]; then
+    continue
+  fi
+  ENTRY_REAL="\$ENTRY"
+  if ENTRY_CANONICAL="\$(cd "\$ENTRY" 2>/dev/null && pwd)"; then
+    ENTRY_REAL="\$ENTRY_CANONICAL"
+  fi
+  if [ "\$ENTRY_REAL" = "\$WRAPPER_DIR" ]; then
+    continue
+  fi
+  if [ -z "\$LOOKUP_PATH" ]; then
+    LOOKUP_PATH="\$ENTRY"
+  else
+    LOOKUP_PATH="\$LOOKUP_PATH:\$ENTRY"
+  fi
+done
+IFS="\$OLD_IFS"
+if [ -n "\$LOOKUP_PATH" ]; then
+  if RESOLVED_LAUNCHER="\$(PATH="\$LOOKUP_PATH" command -v "\$PREFERRED_COMMAND" 2>/dev/null)"; then
+    if [ -n "\$RESOLVED_LAUNCHER" ] && [ "\$RESOLVED_LAUNCHER" != "\$WRAPPER_PATH" ]; then
+      if [ -z "\${DEEPSCIENTIST_HOME:-}" ]; then
+        export DEEPSCIENTIST_HOME="$BASE_DIR"
+      fi
+      exec "\$RESOLVED_LAUNCHER" "\$@"
+    fi
+  fi
+fi
 if [ -z "\${DEEPSCIENTIST_HOME:-}" ]; then
   export DEEPSCIENTIST_HOME="$BASE_DIR"
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@researai/deepscientist",
-  "version": "1.5.7",
+  "version": "1.5.8",
   "description": "Local-first research operating system with a Python runtime and npm launcher",
   "license": "MIT",
   "files": [

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepscientist"
-version = "1.5.7"
+version = "1.5.8"
 description = "DeepScientist Core skeleton"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/deepscientist/__init__.py

@@ -5,4 +5,4 @@ __all__ = ["__version__"]
 try:
     __version__ = _package_version("deepscientist")
 except PackageNotFoundError:  # pragma: no cover - source checkout fallback
-    __version__ = "1.5.7"
+    __version__ = "1.5.8"

package/src/deepscientist/acp/envelope.py

@@ -85,6 +85,7 @@ def build_session_descriptor(
         "mcp_servers": [
             {"name": "memory", "transport": "stdio", "scope": "quest-local"},
             {"name": "artifact", "transport": "stdio", "scope": "quest-local"},
+            {"name": "bash_exec", "transport": "stdio", "scope": "quest-local"},
         ],
         "slash_commands": build_slash_commands(quest_id),
         "meta": {