@researai/deepscientist 1.5.15 → 1.5.17

package/src/deepscientist/diagnostics/__init__.py

@@ -0,0 +1,6 @@
+from .runner_failures import FailureDiagnosis, diagnose_runner_failure
+
+__all__ = [
+    "FailureDiagnosis",
+    "diagnose_runner_failure",
+]

package/src/deepscientist/diagnostics/runner_failures.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class FailureDiagnosis:
+    code: str
+    problem: str
+    why: str
+    guidance: tuple[str, ...]
+    retriable: bool
+    matched_text: str | None = None
+
+
+_MODEL_UNAVAILABLE_MARKERS = (
+    "unknown model",
+    "invalid model",
+    "model not found",
+    "unsupported model",
+    "model is not available",
+    "not authorized to use model",
+    "you do not have access",
+    "access to model",
+    "model access",
+    "unrecognized model",
+)
+
+
+def _build_haystack(*values: object) -> str:
+    return "\n".join(str(value or "") for value in values if str(value or "").strip())
+
+
+def _contains(text: str, marker: str) -> bool:
+    return marker in text.lower()
+
+
+def diagnose_runner_failure(
+    *,
+    runner_name: str,
+    summary: str = "",
+    stderr_text: str = "",
+    output_text: str = "",
+) -> FailureDiagnosis | None:
+    haystack = _build_haystack(summary, stderr_text, output_text)
+    lower = haystack.lower()
+    normalized_runner = str(runner_name or "").strip().lower()
+
+    if (
+        "tool call result does not follow tool call (2013)" in lower
+        or "tool result's tool id" in lower
+    ):
+        return FailureDiagnosis(
+            code="minimax_tool_result_sequence_error",
+            problem="MiniMax rejected the tool result sequence.",
+            why=(
+                "The tool result did not immediately follow the corresponding tool call, "
+                "or the tool result referenced a tool call id that was no longer valid."
+            ),
+            guidance=(
+                "Keep each tool result immediately after its matching tool call.",
+                "Do not insert an extra assistant message between a tool call and its tool result.",
+                "For MiniMax chat-wire sessions, serialize tool use one call at a time.",
+            ),
+            retriable=False,
+            matched_text="2013",
+        )
+
+    if (
+        "invalid function arguments json string" in lower
+        or "failed to parse tool call arguments" in lower
+        or "trailing characters at line 1 column" in lower
+    ):
+        return FailureDiagnosis(
+            code="chat_wire_tool_argument_parse_error",
+            problem="The runner emitted malformed tool-call arguments.",
+            why=(
+                "The tool-call arguments were not a single valid JSON object. "
+                "This usually happens when multiple tool calls are batched into one response "
+                "or when the arguments string contains trailing characters."
+            ),
+            guidance=(
+                "Serialize tool calls one at a time instead of batching multiple MCP calls together.",
+                "Make sure each tool call emits exactly one complete JSON object for its arguments.",
+                "If this is a MiniMax chat-wire path, stay on the serialized single-tool compatibility route.",
+            ),
+            retriable=False,
+            matched_text="tool-call arguments",
+        )
+
+    if "missing environment variable" in lower:
+        return FailureDiagnosis(
+            code="provider_env_missing",
+            problem="A required provider environment variable is missing.",
+            why="The configured model provider expects an API key or env var that was not present in the runner environment.",
+            guidance=(
+                "Set the required key in `~/DeepScientist/config/runners.yaml` under `runners.codex.env`.",
+                "If you launch from a shell, export the provider key in that same shell before starting `ds`.",
+            ),
+            retriable=False,
+            matched_text="missing environment variable",
+        )
+
+    if any(marker in lower for marker in _MODEL_UNAVAILABLE_MARKERS):
+        return FailureDiagnosis(
+            code="runner_model_unavailable",
+            problem="The configured runner model is not available.",
+            why="The selected provider or Codex account could not access the requested model id.",
+            guidance=(
+                "Set `model: inherit` for provider-backed Codex profiles unless the provider explicitly supports the model id.",
+                "If you need a fixed model, verify that the same model works in plain `codex exec` before retrying DeepScientist.",
+            ),
+            retriable=False,
+            matched_text="model unavailable",
+        )
+
+    if normalized_runner == "codex" and "invalid params" in lower and "bad_request_error" in lower:
+        return FailureDiagnosis(
+            code="provider_invalid_params",
+            problem="The provider rejected the request parameters.",
+            why="The upstream provider returned a deterministic request-shape error instead of a transient transport failure.",
+            guidance=(
+                "Inspect the immediately preceding tool call / tool result sequence for protocol ordering or JSON-shape mistakes.",
+                "Do not keep retrying the same request until the request payload or provider config is corrected.",
+            ),
+            retriable=False,
+            matched_text="invalid params",
+        )
+
+    return None

package/src/deepscientist/doctor.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from datetime import UTC, datetime, timedelta
 import os
 import socket
 import subprocess
@@ -13,9 +14,13 @@ from urllib.request import Request, urlopen
 
 from .bash_exec.shells import build_exec_shell_launch, build_terminal_shell_launch
 from .config import ConfigManager
+from .diagnostics import diagnose_runner_failure
 from .home import ensure_home_layout
 from .runtime_tools import RuntimeToolService
-from .shared import resolve_runner_binary, utc_now
+from .shared import read_json, read_jsonl_tail, resolve_runner_binary, utc_now
+
+
+_RUNTIME_FAILURE_LOOKBACK = timedelta(hours=24)
 
 
 def _browser_ui_url(host: str, port: int) -> str:
@@ -42,6 +47,10 @@ def _make_check(
     errors: list[str] | None = None,
     guidance: list[str] | None = None,
     details: dict[str, Any] | None = None,
+    problem: str | None = None,
+    why: str | None = None,
+    fix: list[str] | None = None,
+    evidence: list[str] | None = None,
 ) -> dict[str, Any]:
     normalized_warnings = list(warnings or [])
     normalized_errors = list(errors or [])
@@ -55,6 +64,10 @@ def _make_check(
         "errors": normalized_errors,
         "guidance": list(guidance or []),
         "details": dict(details or {}),
+        "problem": str(problem or "").strip() or None,
+        "why": str(why or "").strip() or None,
+        "fix": [str(line) for line in (fix or []) if str(line).strip()],
+        "evidence": [str(line) for line in (evidence or []) if str(line).strip()],
     }
 
 
@@ -273,6 +286,13 @@ def _check_codex(config_manager: ConfigManager) -> dict[str, Any]:
     probe_warnings = [str(value) for value in probe.get("warnings") or []]
     probe_guidance = [str(value) for value in probe.get("guidance") or []]
     summary = str(probe.get("summary") or "Codex startup probe completed.")
+    probe_details = probe.get("details") if isinstance(probe.get("details"), dict) else {}
+    diagnosis = diagnose_runner_failure(
+        runner_name="codex",
+        summary="\n".join([summary, *probe_errors]),
+        stderr_text=str(probe_details.get("stderr_excerpt") or ""),
+        output_text=str(probe_details.get("stdout_excerpt") or ""),
+    )
     if probe.get("ok"):
         return _make_check(
             check_id="codex",
@@ -284,17 +304,188 @@ def _check_codex(config_manager: ConfigManager) -> dict[str, Any]:
         )
     if not probe_guidance:
         probe_guidance = [
-            "Run `codex --login` (or `codex`) manually once and complete login, then retry `ds doctor`.",
+            "Run `codex login` (or just `codex`) manually once and complete login, then retry `ds doctor`.",
         ]
     return _make_check(
         check_id="codex",
         label="Codex CLI",
         ok=False,
-        summary=summary,
+        summary=diagnosis.problem if diagnosis is not None else summary,
         warnings=probe_warnings,
         errors=probe_errors or ["Codex startup probe did not succeed."],
         guidance=probe_guidance,
         details={"resolved_binary": resolved_binary},
+        problem=diagnosis.problem if diagnosis is not None else None,
+        why=diagnosis.why if diagnosis is not None else None,
+        fix=list(diagnosis.guidance) if diagnosis is not None else None,
+        evidence=(
+            [f"matched: {diagnosis.matched_text}"] if diagnosis is not None and diagnosis.matched_text else None
+        ),
+    )
+
+
+def _parse_timestamp(value: object) -> datetime | None:
+    normalized = str(value or "").strip()
+    if not normalized:
+        return None
+    candidate = normalized.replace("Z", "+00:00")
+    try:
+        parsed = datetime.fromisoformat(candidate)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)
+
+
+def _read_runtime_failure_record(home: Path) -> dict[str, Any] | None:
+    quests_root = home / "quests"
+    if not quests_root.exists():
+        return None
+
+    latest: dict[str, Any] | None = None
+    latest_at: datetime | None = None
+    cutoff = datetime.now(UTC) - _RUNTIME_FAILURE_LOOKBACK
+    interesting_types = {
+        "runner.turn_error",
+        "runner.turn_retry_exhausted",
+        "quest.runtime_auto_resume_suppressed",
+    }
+
+    for quest_root in sorted(quests_root.glob("*/")):
+        events = read_jsonl_tail(quest_root / ".ds" / "events.jsonl", 300)
+        for event in reversed(events):
+            event_type = str(event.get("type") or "").strip()
+            if event_type not in interesting_types:
+                continue
+            created_at = _parse_timestamp(event.get("created_at"))
+            if created_at is None or created_at < cutoff:
+                continue
+            run_id = str(event.get("run_id") or "").strip() or None
+            stderr_text = ""
+            output_text = ""
+            if run_id:
+                run_root = quest_root / ".ds" / "runs" / run_id
+                result_payload = read_json(run_root / "result.json", {})
+                if isinstance(result_payload, dict):
+                    stderr_text = str(result_payload.get("stderr_text") or "").strip()
+                    output_text = str(result_payload.get("output_text") or "").strip()
+                stderr_path = run_root / "stderr.txt"
+                if not stderr_text and stderr_path.exists():
+                    try:
+                        stderr_text = stderr_path.read_text(encoding="utf-8")
+                    except OSError:
+                        stderr_text = ""
+            candidate = {
+                "quest_id": quest_root.name,
+                "run_id": run_id,
+                "event_type": event_type,
+                "summary": str(event.get("summary") or "").strip(),
+                "created_at": created_at.isoformat(),
+                "stderr_text": stderr_text,
+                "output_text": output_text,
+                "recent_attempts": event.get("recent_attempts"),
+            }
+            if latest_at is None or created_at > latest_at:
+                latest = candidate
+                latest_at = created_at
+            break
+    return latest
+
+
+def _check_recent_runtime_failures(home: Path) -> dict[str, Any]:
+    record = _read_runtime_failure_record(home)
+    if record is None:
+        return _make_check(
+            check_id="recent_runtime_failures",
+            label="Recent runtime failures",
+            ok=True,
+            summary="No recent quest runtime failures were found.",
+        )
+
+    event_type = str(record.get("event_type") or "").strip()
+    quest_id = str(record.get("quest_id") or "").strip() or None
+    run_id = str(record.get("run_id") or "").strip() or None
+    summary = str(record.get("summary") or "").strip()
+    details = {
+        "quest_id": quest_id,
+        "run_id": run_id,
+        "event_type": event_type,
+        "observed_at": record.get("created_at"),
+    }
+
+    if event_type == "quest.runtime_auto_resume_suppressed":
+        recent_attempts = int(record.get("recent_attempts") or 0)
+        return _make_check(
+            check_id="recent_runtime_failures",
+            label="Recent runtime failures",
+            ok=True,
+            summary="DeepScientist recently suppressed auto-resume to avoid a crash loop.",
+            warnings=["Automatic continuation was paused after repeated recovery attempts in a short window."],
+            guidance=[
+                "Inspect the most recent failing runner path before using `/resume` again.",
+                "If the failure was a provider-side 400/protocol error, fix that request path first instead of retrying immediately.",
+            ],
+            details=details,
+            problem="Automatic crash recovery was suppressed.",
+            why="The same quest hit repeated recovery attempts in a short window, so DeepScientist parked it instead of looping forever.",
+            fix=[
+                "Open the latest failing quest logs and identify the deterministic runner/provider error.",
+                "Resume manually only after the underlying runner or provider issue is corrected.",
+            ],
+            evidence=[
+                *( [f"quest: {quest_id}"] if quest_id else [] ),
+                f"recent recovery attempts: {recent_attempts}",
+            ],
+        )
+
+    diagnosis = diagnose_runner_failure(
+        runner_name="codex",
+        summary=summary,
+        stderr_text=str(record.get("stderr_text") or ""),
+        output_text=str(record.get("output_text") or ""),
+    )
+    if diagnosis is None:
+        return _make_check(
+            check_id="recent_runtime_failures",
+            label="Recent runtime failures",
+            ok=True,
+            summary="A recent quest runtime failure was found.",
+            warnings=[summary or "The latest quest run failed, but doctor could not classify it precisely yet."],
+            guidance=[
+                "Open the latest run stderr and events journal for the failing quest.",
+                "If the same failure repeats, capture the run_id and provider response text before retrying again.",
+            ],
+            details=details,
+            problem="A recent quest run failed.",
+            why="Doctor found a recent runtime failure event but could not match it to a known deterministic error pattern.",
+            fix=[
+                "Inspect the failing run's stderr and provider response text.",
+                "If the error is deterministic, avoid burning the retry budget until the request shape or config is fixed.",
+            ],
+            evidence=[
+                *( [f"quest: {quest_id}"] if quest_id else [] ),
+                *( [f"run: {run_id}"] if run_id else [] ),
+                *( [f"summary: {summary}"] if summary else [] ),
+            ],
+        )
+
+    return _make_check(
+        check_id="recent_runtime_failures",
+        label="Recent runtime failures",
+        ok=True,
+        summary=diagnosis.problem,
+        warnings=[summary] if summary and summary != diagnosis.problem else [],
+        guidance=list(diagnosis.guidance),
+        details=details,
+        problem=diagnosis.problem,
+        why=diagnosis.why,
+        fix=list(diagnosis.guidance),
+        evidence=[
+            *( [f"quest: {quest_id}"] if quest_id else [] ),
+            *( [f"run: {run_id}"] if run_id else [] ),
+            *( [f"matched: {diagnosis.matched_text}"] if diagnosis.matched_text else [] ),
+        ],
     )
 
 
@@ -491,6 +682,7 @@ def run_doctor(home: Path, *, repo_root: Path) -> dict[str, Any]:
         _check_config_validation(config_manager),
         _check_runner_support(config_manager),
         _check_codex(config_manager),
+        _check_recent_runtime_failures(home),
         _check_latex_runtime(home),
         _check_bundles(repo_root),
         _check_ui_port(home, config_manager),
@@ -519,6 +711,18 @@ def render_doctor_report(report: dict[str, Any]) -> str:
         status = str(item.get("status") or "ok").upper()
         icon = {"OK": "[ok]", "WARN": "[warn]", "ERROR": "[fail]"}.get(status, "[info]")
         lines.append(f"{icon} {item.get('label')}: {item.get('summary')}")
+        problem = str(item.get("problem") or "").strip()
+        why = str(item.get("why") or "").strip()
+        fix_lines = [str(line) for line in item.get("fix") or [] if str(line).strip()]
+        evidence_lines = [str(line) for line in item.get("evidence") or [] if str(line).strip()]
+        if problem:
+            lines.append(f"  problem: {problem}")
+        if why:
+            lines.append(f"  why: {why}")
+        for line in fix_lines:
+            lines.append(f"  fix: {line}")
+        for line in evidence_lines:
+            lines.append(f"  evidence: {line}")
         for warning in item.get("warnings") or []:
             lines.append(f"  warning: {warning}")
         for error in item.get("errors") or []:

package/src/deepscientist/gitops/__init__.py

@@ -1,4 +1,12 @@
-from .diff import commit_detail, compare_refs, diff_file_between_refs, diff_file_for_commit, list_branch_canvas, log_ref_history
+from .diff import (
+    commit_detail,
+    compare_refs,
+    diff_file_between_refs,
+    diff_file_for_commit,
+    list_branch_canvas,
+    list_commit_canvas,
+    log_ref_history,
+)
 from .graph import export_git_graph
 from .service import (
     branch_exists,
@@ -26,5 +34,6 @@ __all__ = [
     "head_commit",
     "init_repo",
     "list_branch_canvas",
+    "list_commit_canvas",
     "log_ref_history",
 ]

package/src/deepscientist/gitops/diff.py

@@ -113,6 +113,67 @@ def list_branch_canvas(repo: Path, *, quest_id: str) -> dict[str, Any]:
     }
 
 
+def list_commit_canvas(repo: Path, *, quest_id: str, limit: int = 80) -> dict[str, Any]:
+    resolved_limit = max(1, min(int(limit), 200))
+    head = head_commit(repo)
+    current_ref = current_branch(repo)
+    commits = _git_commit_canvas_log(repo, limit=resolved_limit)
+    nodes: list[dict[str, Any]] = []
+    edges: list[dict[str, Any]] = []
+    seen_shas = {item["sha"] for item in commits if str(item.get("sha") or "").strip()}
+
+    for commit in commits:
+        sha = str(commit.get("sha") or "").strip()
+        if not sha:
+            continue
+        detail = commit_detail(repo, sha=sha)
+        parents = [str(item).strip() for item in (detail.get("parents") or []) if str(item).strip()]
+        files = detail.get("files") or []
+        changed_paths = [
+            str(item.get("path") or "").strip()
+            for item in files
+            if str(item.get("path") or "").strip()
+        ]
+        node = {
+            "sha": sha,
+            "short_sha": str(detail.get("short_sha") or commit.get("short_sha") or sha[:7]).strip(),
+            "parents": parents,
+            "subject": str(detail.get("subject") or commit.get("subject") or "").strip() or sha[:7],
+            "body_preview": _body_preview(str(detail.get("body") or "").strip()),
+            "authored_at": str(detail.get("authored_at") or commit.get("authored_at") or "").strip() or None,
+            "author_name": str(detail.get("author_name") or commit.get("author_name") or "").strip() or None,
+            "branch_refs": _normalize_branch_refs(commit.get("decorations")),
+            "current": bool(head and sha == head),
+            "active_workspace": bool(head and sha == head),
+            "changed_paths": changed_paths,
+            "file_count": int(detail.get("file_count") or len(files)),
+            "added": int(((detail.get("stats") or {}) if isinstance(detail.get("stats"), dict) else {}).get("added") or 0),
+            "removed": int(((detail.get("stats") or {}) if isinstance(detail.get("stats"), dict) else {}).get("removed") or 0),
+            "compare_base": parents[0] if parents else None,
+            "compare_head": sha,
+            "selection_type": "git_commit_node",
+        }
+        nodes.append(node)
+        for parent in parents:
+            if parent in seen_shas:
+                edges.append(
+                    {
+                        "from": parent,
+                        "to": sha,
+                        "relation": "parent",
+                    }
+                )
+
+    return {
+        "quest_id": quest_id,
+        "workspace_mode": "copilot",
+        "head": head,
+        "current_ref": current_ref,
+        "nodes": nodes,
+        "edges": edges,
+    }
+
+
 def compare_refs(repo: Path, *, base: str, head: str) -> dict[str, Any]:
     _require_ref(repo, base)
     _require_ref(repo, head)
@@ -775,6 +836,74 @@ def _git_log(repo: Path, *, revspec: str, limit: int = 30) -> list[dict[str, Any
     return commits
 
 
+def _git_commit_canvas_log(repo: Path, *, limit: int = 80) -> list[dict[str, Any]]:
+    result = _git_stdout(
+        repo,
+        [
+            "log",
+            "--all",
+            "--topo-order",
+            "--date=iso-strict",
+            f"-n{limit}",
+            "--decorate=short",
+            "--pretty=format:%H%x1f%h%x1f%P%x1f%ad%x1f%an%x1f%s%x1f%b%x1f%D",
+        ],
+    )
+    commits: list[dict[str, Any]] = []
+    for line in result.splitlines():
+        if not line.strip():
+            continue
+        sha, short_sha, parents_raw, authored_at, author_name, subject, body, decorations = (
+            line.split("\x1f") + ["", "", "", "", "", "", "", ""]
+        )[:8]
+        commits.append(
+            {
+                "sha": sha.strip(),
+                "short_sha": short_sha.strip(),
+                "parents": [item for item in parents_raw.strip().split() if item],
+                "authored_at": authored_at.strip(),
+                "author_name": author_name.strip(),
+                "subject": subject.strip(),
+                "body": body.strip(),
+                "decorations": decorations.strip(),
+            }
+        )
+    return commits
+
+
+def _normalize_branch_refs(raw: Any) -> list[str]:
+    text = str(raw or "").strip()
+    if not text:
+        return []
+    refs: list[str] = []
+    for part in text.split(","):
+        cleaned = part.strip()
+        if not cleaned:
+            continue
+        if cleaned.startswith("HEAD -> "):
+            cleaned = cleaned[len("HEAD -> ") :].strip()
+        if cleaned.startswith("tag: "):
+            continue
+        if cleaned.startswith("origin/"):
+            continue
+        if cleaned == "HEAD":
+            continue
+        refs.append(cleaned)
+    return refs
+
+
+def _body_preview(body: str, *, max_lines: int = 3, max_chars: int = 220) -> str | None:
+    if not body:
+        return None
+    lines = [line.strip() for line in body.splitlines() if line.strip()]
+    if not lines:
+        return None
+    preview = " ".join(lines[:max_lines]).strip()
+    if len(preview) > max_chars:
+        preview = preview[: max_chars - 1].rstrip() + "…"
+    return preview or None
+
+
 def _normalize_patch_lines(patch: str) -> list[str]:
     lines = [line.rstrip("\n") for line in patch.splitlines()]
     if not lines:

package/src/deepscientist/gitops/service.py

@@ -100,7 +100,10 @@ def checkpoint_repo(repo: Path, message: str, allow_empty: bool = False) -> dict
             "branch": current_branch(repo),
             "head": head_commit(repo),
         }
-    result = run_command(["git", "commit", "-m", message], cwd=repo, check=False)
+    command = ["git", "commit", "-m", message]
+    if allow_empty:
+        command.insert(2, "--allow-empty")
+    result = run_command(command, cwd=repo, check=False)
     return {
         "committed": result.returncode == 0,
         "branch": current_branch(repo),

package/src/deepscientist/mcp/server.py

@@ -526,6 +526,45 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             allow_empty=allow_empty,
         )
 
+    @server.tool(
+        name="git",
+        description=(
+            "Run git-oriented workspace operations for Copilot mode and general quest maintenance. "
+            "Use action=status|commit|branch|checkout|log|show|diff|graph."
+        ),
+    )
+    def git(
+        action: str,
+        message: str | None = None,
+        ref: str | None = None,
+        base: str | None = None,
+        head: str | None = None,
+        sha: str | None = None,
+        path: str | None = None,
+        branch: str | None = None,
+        create_from: str | None = None,
+        limit: int = 30,
+        allow_empty: bool = False,
+        checkout_new_branch: bool = False,
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.git_action(
+            context.require_quest_root(),
+            action=action,
+            workspace_root=context.worktree_root,
+            message=message,
+            ref=ref,
+            base=base,
+            head=head,
+            sha=sha,
+            path=path,
+            branch=branch,
+            create_from=create_from,
+            limit=limit,
+            allow_empty=allow_empty,
+            checkout_new_branch=checkout_new_branch,
+        )
+
     @server.tool(name="prepare_branch", description="Prepare an idea or run branch and optional worktree.")
     def prepare_branch(
         run_id: str | None = None,