@researai/deepscientist 1.5.14 → 1.5.16

package/src/deepscientist/mcp/server.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Any
 
 from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
 
 from ..artifact import ArtifactService
 from ..artifact.metrics import MetricContractValidationError
@@ -54,6 +55,16 @@ ARTIFACT_STATE_CHANGE_WATCHDOG_NOTES = {
 }
 
 
+def _read_only_tool_annotations(*, title: str | None = None) -> ToolAnnotations:
+    return ToolAnnotations(
+        title=title,
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+
+
 def _metric_validation_error_payload(exc: MetricContractValidationError) -> dict[str, Any]:
     return exc.as_payload()
 
@@ -62,7 +73,7 @@ def _progress_watchdog_note(tool_call_count: int) -> str:
     return (
         "By the way, you have gone "
         f"{tool_call_count} tool calls without notifying the user via artifact.interact(...). "
-        "Please report your latest progress now."
+        "Inspect whether the user-visible state actually changed; only send a progress update if there is a real new checkpoint, blocker, or route change."
     )
 
 
@@ -71,7 +82,7 @@ def _visibility_watchdog_note(seconds_since_last_update: int) -> str:
     return (
         "By the way, it has been "
         f"{minutes} minutes since the last user-visible artifact.interact(...). "
-        "Send one concise progress update now before continuing with background work."
+        "Inspect the current run or task state now. Only send a new user-visible update if the frontier materially changed or the user explicitly needs a fresh checkpoint."
     )
 
 
@@ -114,11 +125,16 @@ def _attach_interaction_watchdog(
     state_change_note: str | None = None,
 ) -> dict[str, Any]:
     enriched = dict(payload)
-    enriched["interaction_watchdog"] = dict(watchdog or {})
+    interaction_watchdog = dict(watchdog or {})
     notes = _collect_interaction_watchdog_notes(
         watchdog,
         state_change_note=state_change_note,
     )
+    interaction_watchdog["user_update_due"] = bool(
+        interaction_watchdog.get("user_update_due")
+        or any(str(item.get("kind") or "") == "state_change" for item in notes)
+    )
+    enriched["interaction_watchdog"] = interaction_watchdog
     if not notes:
         return enriched
     enriched["watchdog_notes"] = notes
@@ -377,6 +393,7 @@ def build_memory_server(context: McpContext) -> FastMCP:
             "Read a memory card by id or path. "
             "Use after list_recent or search surfaced a specific card worth reusing now."
         ),
+        annotations=_read_only_tool_annotations(title="Read memory card"),
     )
     def read(
         card_id: str | None = None,
@@ -394,6 +411,7 @@ def build_memory_server(context: McpContext) -> FastMCP:
             "Search memory cards by metadata or body text. "
             "Use before broad literature search, retries, route decisions, or repeated debugging."
         ),
+        annotations=_read_only_tool_annotations(title="Search memory cards"),
     )
     def search(
         query: str,
@@ -413,6 +431,7 @@ def build_memory_server(context: McpContext) -> FastMCP:
             "List the most recently updated memory cards. "
             "Use to recover quest context at turn start, after resume, or after a long pause."
         ),
+        annotations=_read_only_tool_annotations(title="List recent memory cards"),
     )
     def list_recent(
         scope: str = "quest",
@@ -507,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,
@@ -557,19 +615,26 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         name="submit_idea",
         description=(
             "Create or revise the active research idea. "
-            "Normal research flow should use mode=create together with lineage_intent=continue_line or branch_alternative, so each durable idea submission becomes a new branch/worktree and a new user-visible research node. "
+            "Normal research flow should use mode=create together with submission_mode='line' and lineage_intent=continue_line or branch_alternative, so each durable idea submission becomes a new branch/worktree and a new user-visible research node. "
+            "submission_mode='candidate' records a candidate idea brief without opening a new branch yet. "
             "mode=revise is maintenance-only for refining the current active idea.md in place. "
             "When foundation_ref is omitted, lineage_intent infers the parent and default foundation from the active research line."
         ),
     )
     def submit_idea(
         mode: str = "create",
+        submission_mode: str = "line",
         idea_id: str | None = None,
         lineage_intent: str | None = None,
         title: str = "",
         problem: str = "",
         hypothesis: str = "",
         mechanism: str = "",
+        method_brief: str = "",
+        selection_scores: dict[str, Any] | None = None,
+        mechanism_family: str = "",
+        change_layer: str = "",
+        source_lens: str = "",
         expected_gain: str = "",
         evidence_paths: list[str] | None = None,
         risks: list[str] | None = None,
@@ -578,17 +643,24 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         foundation_reason: str = "",
         next_target: str = "experiment",
         draft_markdown: str = "",
+        source_candidate_id: str | None = None,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         return service.submit_idea(
             context.require_quest_root(),
             mode=mode,
+            submission_mode=submission_mode,
             idea_id=idea_id,
             lineage_intent=lineage_intent,
             title=title,
             problem=problem,
             hypothesis=hypothesis,
             mechanism=mechanism,
+            method_brief=method_brief,
+            selection_scores=selection_scores,
+            mechanism_family=mechanism_family,
+            change_layer=change_layer,
+            source_lens=source_lens,
             expected_gain=expected_gain,
             evidence_paths=evidence_paths,
             risks=risks,
@@ -597,6 +669,7 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             foundation_reason=foundation_reason,
             next_target=next_target,
             draft_markdown=draft_markdown,
+            source_candidate_id=source_candidate_id,
         )
 
     @server.tool(
@@ -605,6 +678,7 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             "List research branches with branch number, active idea, foundation info, and corresponding main-experiment results. "
             "Use before creating the next idea when you need to compare possible foundations."
         ),
+        annotations=_read_only_tool_annotations(title="List research branches"),
     )
     def list_research_branches(comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
         return service.list_research_branches(context.require_quest_root())
@@ -615,16 +689,135 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             "Resolve the current canonical research ids and refs. "
             "Use this before supplementary work when you need the active idea, latest main run, active campaign, outline, or reply-thread ids without guessing."
         ),
+        annotations=_read_only_tool_annotations(title="Resolve runtime refs"),
     )
     def resolve_runtime_refs(comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
         return service.resolve_runtime_refs(context.require_quest_root())
 
+    @server.tool(
+        name="get_paper_contract_health",
+        description=(
+            "Inspect whether the active paper line is actually unblocked for writing or finalize work. "
+            "Use detail='summary' for a compact decision surface or detail='full' for exact blocking items."
+        ),
+        annotations=_read_only_tool_annotations(title="Get paper contract health"),
+    )
+    def get_paper_contract_health(
+        detail: str = "summary",
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_paper_contract_health(
+            context.require_quest_root(),
+            detail=detail,
+        )
+
+    @server.tool(
+        name="get_quest_state",
+        description=(
+            "Read the current quest runtime state without mutating anything. "
+            "Use detail='summary' for a compact operational view or detail='full' for recent artifacts, runs, and active interactions."
+        ),
+        annotations=_read_only_tool_annotations(title="Get quest state"),
+    )
+    def get_quest_state(
+        detail: str = "summary",
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_quest_state(
+            context.require_quest_root(),
+            detail=detail,
+        )
+
+    @server.tool(
+        name="get_global_status",
+        description=(
+            "Read a concise quest-global status summary for direct user questions such as overall progress, paper readiness, or the latest measured result. "
+            "Use detail='brief' for a compact answer surface or detail='full' for more structured context."
+        ),
+        annotations=_read_only_tool_annotations(title="Get global status"),
+    )
+    def get_global_status(
+        detail: str = "brief",
+        locale: str = "zh",
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_global_status(
+            context.require_quest_root(),
+            detail=detail,
+            locale=locale,
+        )
+
+    @server.tool(
+        name="get_method_scoreboard",
+        description=(
+            "Read or refresh the quest-level method scoreboard so overall experiment history and the current incumbent line are explicit."
+        ),
+    )
+    def get_method_scoreboard(comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
+        return service.refresh_method_scoreboard(context.require_quest_root())
+
+    @server.tool(
+        name="get_optimization_frontier",
+        description=(
+            "Read a compact optimization-frontier summary for algorithm-first quests. "
+            "It summarizes candidate briefs, promoted lines, recent implementation candidates, stagnant branches, fusion opportunities, and the recommended next mode."
+        ),
+        annotations=_read_only_tool_annotations(title="Get optimization frontier"),
+    )
+    def get_optimization_frontier(
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_optimization_frontier(
+            context.require_quest_root(),
+        )
+
+    @server.tool(
+        name="read_quest_documents",
+        description=(
+            "Read durable quest documents such as brief, plan, status, summary, and active user requirements. "
+            "Use mode='excerpt' for compact recovery or mode='full' when exact document wording matters."
+        ),
+        annotations=_read_only_tool_annotations(title="Read quest documents"),
+    )
+    def read_quest_documents(
+        names: list[str] | None = None,
+        mode: str = "excerpt",
+        max_lines: int = 12,
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.read_quest_documents(
+            context.require_quest_root(),
+            names=names,
+            mode=mode,
+            max_lines=max_lines,
+        )
+
+    @server.tool(
+        name="get_conversation_context",
+        description=(
+            "Read a recent window of quest conversation history. "
+            "Use this when earlier user/assistant continuity matters and the current prompt intentionally keeps only a compact turn launcher."
+        ),
+        annotations=_read_only_tool_annotations(title="Get conversation context"),
+    )
+    def get_conversation_context(
+        limit: int = 12,
+        include_attachments: bool = False,
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_conversation_context(
+            context.require_quest_root(),
+            limit=limit,
+            include_attachments=include_attachments,
+        )
+
     @server.tool(
         name="get_analysis_campaign",
         description=(
             "Get one analysis campaign manifest with todo items, slice status, and next pending slice. "
             "Pass campaign_id='active' or omit it to recover the active campaign."
         ),
+        annotations=_read_only_tool_annotations(title="Get analysis campaign"),
     )
     def get_analysis_campaign(
         campaign_id: str | None = "active",
@@ -762,6 +955,7 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             "List candidate/revised paper outlines and the selected outline reference. "
             "Use this before writing-facing analysis campaigns or when you need a valid outline_id."
         ),
+        annotations=_read_only_tool_annotations(title="List paper outlines"),
     )
     def list_paper_outlines(comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
         return service.list_paper_outlines(context.require_quest_root())
@@ -957,7 +1151,14 @@ def build_artifact_server(context: McpContext) -> FastMCP:
     def render_git_graph(comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
         return service.render_git_graph(context.require_quest_root())
 
-    @server.tool(name="interact", description="Send a structured user-facing update and optionally fetch new inbound messages.")
+    @server.tool(
+        name="interact",
+        description=(
+            "Send a structured user-facing interaction and optionally fetch new inbound messages. "
+            "Use kind='answer' for direct user questions, kind='progress' for long-running checkpoint updates, "
+            "kind='milestone' for material state changes, and kind='decision_request' only for true blocking decisions."
+        ),
+    )
     def interact(
         kind: str = "progress",
         message: str = "",
@@ -977,6 +1178,9 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         reply_schema: dict[str, Any] | None = None,
         reply_to_interaction_id: str | None = None,
         supersede_open_requests: bool = True,
+        dedupe_key: str | None = None,
+        suppress_if_unchanged: bool | None = None,
+        min_interval_seconds: int | None = None,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         result = service.interact(
@@ -999,6 +1203,9 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             reply_schema=reply_schema,
             reply_to_interaction_id=reply_to_interaction_id,
             supersede_open_requests=supersede_open_requests,
+            dedupe_key=dedupe_key,
+            suppress_if_unchanged=suppress_if_unchanged,
+            min_interval_seconds=min_interval_seconds,
         )
         result["interaction_watchdog"] = quest_service.artifact_interaction_watchdog_status(context.require_quest_root())
         return result

package/src/deepscientist/process_control.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import signal
+import subprocess
+import time
+from typing import Any
+
+
+def process_session_popen_kwargs(
+    *,
+    hide_window: bool = False,
+    new_process_group: bool = True,
+) -> dict[str, Any]:
+    if os.name == "nt":  # pragma: no cover - exercised on Windows
+        creationflags = 0
+        if new_process_group and hasattr(subprocess, "CREATE_NEW_PROCESS_GROUP"):
+            creationflags |= getattr(subprocess, "CREATE_NEW_PROCESS_GROUP")
+        if hide_window and hasattr(subprocess, "CREATE_NO_WINDOW"):
+            creationflags |= getattr(subprocess, "CREATE_NO_WINDOW")
+        payload: dict[str, Any] = {}
+        if creationflags:
+            payload["creationflags"] = creationflags
+        if hide_window and hasattr(subprocess, "STARTUPINFO") and hasattr(subprocess, "STARTF_USESHOWWINDOW"):
+            startupinfo = subprocess.STARTUPINFO()
+            startupinfo.dwFlags |= getattr(subprocess, "STARTF_USESHOWWINDOW")
+            startupinfo.wShowWindow = getattr(subprocess, "SW_HIDE", 0)
+            payload["startupinfo"] = startupinfo
+        return payload
+    if new_process_group:
+        return {
+            "start_new_session": True,
+        }
+    return {}
+
+
+def is_process_alive(pid: object) -> bool:
+    if not isinstance(pid, int) or pid <= 0:
+        return False
+    if os.name != "nt":
+        proc_stat_path = Path("/proc") / str(pid) / "stat"
+        if proc_stat_path.exists():
+            try:
+                parts = proc_stat_path.read_text(encoding="utf-8").split()
+            except OSError:
+                parts = []
+            if len(parts) >= 3 and parts[2] == "Z":
+                return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def terminate_process_ids(
+    *,
+    process_pid: int | None,
+    process_group_id: int | None,
+    force: bool = False,
+) -> None:
+    if os.name == "nt":  # pragma: no cover - exercised on Windows
+        if isinstance(process_pid, int) and process_pid > 0:
+            taskkill_args = ["taskkill", "/PID", str(process_pid), "/T"]
+            if force:
+                taskkill_args.append("/F")
+            subprocess.run(taskkill_args, check=False, capture_output=True, text=True)
+            if not force and is_process_alive(process_pid):
+                try:
+                    os.kill(process_pid, signal.SIGTERM)
+                except OSError:
+                    pass
+        return
+    if isinstance(process_group_id, int) and process_group_id > 0:
+        try:
+            os.killpg(process_group_id, signal.SIGKILL if force else signal.SIGTERM)
+        except ProcessLookupError:
+            return
+        return
+    if isinstance(process_pid, int) and process_pid > 0:
+        try:
+            os.kill(process_pid, signal.SIGKILL if force else signal.SIGTERM)
+        except ProcessLookupError:
+            return
+
+
+def terminate_subprocess(
+    process: subprocess.Popen[Any],
+    *,
+    process_group_id: int | None = None,
+    force: bool = False,
+    prefer_ctrl_break: bool = False,
+    grace_seconds: float = 5.0,
+) -> None:
+    if process.poll() is not None:
+        return
+
+    if os.name == "nt":  # pragma: no cover - exercised on Windows
+        if not force and prefer_ctrl_break and hasattr(signal, "CTRL_BREAK_EVENT"):
+            try:
+                process.send_signal(signal.CTRL_BREAK_EVENT)  # type: ignore[attr-defined]
+            except (AttributeError, OSError, ValueError):
+                try:
+                    process.terminate()
+                except OSError:
+                    return
+        elif not force:
+            try:
+                process.terminate()
+            except OSError:
+                return
+        else:
+            try:
+                process.kill()
+            except OSError:
+                return
+        if force:
+            return
+        deadline = time.monotonic() + max(grace_seconds, 0.1)
+        while time.monotonic() < deadline:
+            if process.poll() is not None:
+                return
+            time.sleep(0.05)
+        try:
+            process.kill()
+        except OSError:
+            return
+        return
+
+    if isinstance(process_group_id, int) and process_group_id > 0:
+        try:
+            os.killpg(process_group_id, signal.SIGKILL if force else signal.SIGTERM)
+        except ProcessLookupError:
+            return
+    else:
+        try:
+            process.kill() if force else process.terminate()
+        except OSError:
+            return
+    if force:
+        return
+    deadline = time.monotonic() + max(grace_seconds, 0.1)
+    while time.monotonic() < deadline:
+        if process.poll() is not None:
+            return
+        time.sleep(0.05)
+    if isinstance(process_group_id, int) and process_group_id > 0:
+        try:
+            os.killpg(process_group_id, signal.SIGKILL)
+        except ProcessLookupError:
+            return
+    elif process.poll() is None:
+        try:
+            process.kill()
+        except OSError:
+            return