mindcode 0.2.0__py3-none-any.whl

mindcode/runtime.py

@@ -0,0 +1,541 @@
+from __future__ import annotations
+
+import difflib
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from mindagent.context import ContextConfig, ContextManager
+from mindagent.core import (
+    ActionRisk,
+    ActionDispatcher,
+    ActionType,
+    AgentOrchestrator,
+    AgentRuntime,
+    RunConfig,
+    SessionPolicy,
+    SubAgentExecutor,
+)
+from mindagent.providers import ProviderReasoner, ProviderRouter
+from mindagent.providers.openai import OpenAIProvider, OpenAIProviderParam
+from mindagent.tools import (
+    ExecCommandTool,
+    FileEditTool,
+    FileReadTool,
+    FileWriteTool,
+    ToolExecutor,
+    ToolRegistry,
+    WorkspacePathResolver,
+    workspace_paths,
+)
+from mindagent.tools.base import BaseTool, ToolContext
+
+from .config import ProviderConfig
+from .mcp import MCPClient, adapt_mcp_tools
+from .policy import ApprovalMode, make_policy
+from .skills import Skill, SkillRegistry
+from .subagents import MasterWorkerSystem
+
+
+SYSTEM_PROMPT = (
+    "You are mindcode, an autonomous senior engineer working inside "
+    "the user's workspace.\n"
+    "\n"
+    "# General\n"
+    "- You run inside a fixed workspace root (injected below). Only "
+    "read/edit files and run commands within it. Do NOT search or operate "
+    "outside it (e.g. no `find`/`ls` on the home directory or parent "
+    "paths).\n"
+    "- If a dedicated tool exists for an action, prefer it over shell "
+    "commands (`file_read` over `cat`). Prefer `file_read` for file "
+    "contents and `exec_command` with `rg`/`grep` for searches; `rg` is "
+    "much faster than `grep`. An empty search result is not an error.\n"
+    "- The `exec_command` tool does not invoke a shell: pass `command` as "
+    "an argv array, never a string, and do not include standalone shell "
+    "operators such as |, &&, ;, >, or <. Split pipelines into separate "
+    "tool calls, or explicitly invoke ['sh', '-c', '...'] when a shell is "
+    "required.\n"
+    "- Mirror the user's language (e.g. reply in Chinese when the user "
+    "writes Chinese). Keep answers concise.\n"
+    "\n"
+    "# Autonomy and Persistence\n"
+    "- Bias to action: once the user gives a direction, proactively gather "
+    "context, implement, verify, and refine without waiting for prompts at "
+    "each step. Make reasonable assumptions instead of asking clarifying "
+    "questions; only stop to ask when truly blocked, and then ask a "
+    "targeted question plus state what you have ruled out.\n"
+    "- Persist end-to-end within the turn whenever feasible: do not stop "
+    "at analysis or partial fixes; carry changes through implementation, "
+    "verification, and a clear closing summary unless the user explicitly "
+    "pauses or redirects.\n"
+    "- Deliver working code, not just a plan. Never end a turn with only "
+    "a plan unless the user asked for one.\n"
+    "- Avoid excessive looping: if you re-read or re-edit the same files "
+    "without clear progress, stop and end the turn with a concise summary "
+    "and the explicit blocker.\n"
+    "- Keep reasoning summaries empty or under 12 words; never narrate "
+    "progress or greet the user there — act silently and report only in "
+    "the final answer.\n"
+    "\n"
+    "# Exploration and Reading\n"
+    "- Think first: before any tool call, decide ALL files/resources you "
+    "will need.\n"
+    "- Batch independent reads: issue independent `file_read`/search calls "
+    "together in one block instead of one-by-one. Only go sequential when "
+    "the next step truly depends on the previous result.\n"
+    "- Edits and commands stay serial: never batch "
+    "`file_write`/`file_edit`/`exec_command` calls that touch the same "
+    "files or depend on each other; verify each consequential change "
+    "before moving on.\n"
+    "\n"
+    "# Code Implementation\n"
+    "- Optimize for correctness, clarity, and reliability over speed: fix "
+    "the root cause, not the symptom; avoid risky shortcuts and "
+    "speculative changes.\n"
+    "- Conform to codebase conventions: follow existing patterns, helpers, "
+    "naming, and formatting; if you must diverge, state why.\n"
+    "- Inspect before editing: read enough surrounding context first, then "
+    "make precise, batched edits instead of many tiny patches. Always "
+    "cite file paths you touched.\n"
+    "- Run relevant checks after changes (tests, build, type-check per "
+    "repo conventions) and fix failures before finishing.\n"
+    "- You may be in a dirty worktree: NEVER revert, discard, or amend "
+    "changes you did not make unless explicitly requested. If unrelated "
+    "changes appear in files you touched, work with them; if they are "
+    "elsewhere, ignore them.\n"
+    "\n"
+    "# Final Message\n"
+    "- Be concise and scannable: lead with the outcome, then the minimal "
+    "context (what changed, where, why).\n"
+    "- Reference file paths instead of dumping file contents. Suggest "
+    "logical next steps (tests, commit) briefly."
+)
+
+
+MASTER_SYSTEM_PROMPT = (
+    "You are mindcode's task coordinator. Delegate all workspace "
+    "inspection, editing, and command execution to the registered coder "
+    "agent with the agent_delegate tool. Give the coder a bounded task, "
+    "file scope, and verification goal. Bias to action: decompose and "
+    "delegate immediately instead of asking the user for details you can "
+    "reasonably assume. Review the returned evidence before reporting a "
+    "result. Do not claim work completed without worker evidence. Keep "
+    "reasoning summaries empty or under 12 words; never narrate progress "
+    "there."
+)
+
+
+PROJECT_CONTEXT_SKILL = (
+    "Built-in skill: project context discovery.\n"
+    "For project-specific development, debugging, deployment, model analysis, "
+    "benchmarking, or task execution, first discover project instructions "
+    "progressively instead of guessing. Locate AGENTS.md with exec_command "
+    "(rg --files -g AGENTS.md, or find . -name AGENTS.md). If present, "
+    "read it with file_read before planning. Then look for environment "
+    "and execution context only when relevant: REMOTES.md. "
+    "Use REMOTES.md for runtime environment, services, logs, remote "
+    "machines, deployment paths, and common operations. Keep discovery "
+    "simple and stable: do not look for additional convention files unless "
+    "the user explicitly names them. Read only the files needed for the "
+    "current task. Do not preload broad documentation or scan outside the "
+    "workspace."
+)
+
+
+def build_system_prompt(workspace: Path) -> str:
+    """注入实际 workspace 路径与边界约束，避免模型跑到 workspace 之外。"""
+    return (
+        SYSTEM_PROMPT
+        + "\n\n"
+        + PROJECT_CONTEXT_SKILL
+        + f"\n\nWorkspace root: {workspace}.\n"
+        "Only read/edit files and run commands within this workspace. "
+        "Do NOT search or operate outside it (e.g. no `find`/`ls` on the "
+        "home directory or parent paths). Prefer file_read for file "
+        "contents and exec_command with rg/grep for searches; an empty "
+        "search result is not an error."
+    )
+
+
+def build_master_system_prompt(workspace: Path) -> str:
+    return (
+        MASTER_SYSTEM_PROMPT
+        + f"\n\nWorkspace root: {workspace}."
+        + " Every agent_delegate call must set context.agent_id to 'coder' "
+        "and context.mode to 'await_result'."
+    )
+
+
+class DiffingFileTool(BaseTool):
+    """Wrap a file-mutating tool to capture before/after content for diffs.
+
+    Reuses the wrapped tool's ToolDefinition so ToolRegistry still routes
+    by name and the LLM sees the identical schema.
+    """
+
+    def __init__(self, inner: BaseTool, workspace_root: str | Path):
+        self._inner = inner
+        self._fallback_resolver = WorkspacePathResolver(workspace_root)
+        self.definition = self._inner.definition
+
+    def assess_risk(
+        self,
+        arguments: dict[str, Any],
+        context: Any | None = None,
+    ) -> ActionRisk:
+        return self._inner.assess_risk(arguments, context)
+
+    async def execute(
+        self,
+        arguments: dict[str, Any],
+        context: ToolContext,
+    ) -> dict[str, Any]:
+        resolver = workspace_paths(context, self._fallback_resolver)
+        rel_path = arguments.get("path", "")
+        before = self._safe_read(resolver, rel_path)
+
+        result = await self._inner.execute(arguments, context)
+
+        after = self._safe_read(resolver, rel_path)
+        result["mindcode_diff"] = _unified_diff(before, after, rel_path)
+        result["mindcode_before"] = before
+        return result
+
+    @staticmethod
+    def _safe_read(
+        resolver: WorkspacePathResolver,
+        rel_path: str,
+    ) -> str:
+        if not rel_path:
+            return ""
+        try:
+            path = resolver.resolve(rel_path, must_exist=False)
+        except Exception:
+            return ""
+        if not path.is_file():
+            return ""
+        try:
+            return path.read_text(encoding="utf-8")
+        except Exception:
+            return ""
+
+
+def _unified_diff(before: str, after: str, rel_path: str) -> str:
+    if before == after:
+        return ""
+    diff_lines = difflib.unified_diff(
+        before.splitlines(keepends=True),
+        after.splitlines(keepends=True),
+        fromfile=f"a/{rel_path}",
+        tofile=f"b/{rel_path}",
+    )
+    return "".join(diff_lines)
+
+
+_SHELL_CONTROL_TOKENS = frozenset(
+    {
+        "|",
+        "||",
+        "|&",
+        "&&",
+        ";",
+        ";;",
+        "&",
+        ">",
+        ">>",
+        ">|",
+        "<",
+        "<<",
+        "<<<",
+        "<&",
+        ">&",
+        "&>",
+        "&>>",
+        "2>",
+        "2>>",
+        "2>&1",
+    }
+)
+
+
+class GuardedExecCommandTool(BaseTool):
+    """Reject shell syntax before delegating to direct argv execution."""
+
+    def __init__(self, inner: ExecCommandTool):
+        self._inner = inner
+        # Keep the exact definition so providers continue to see the
+        # mindagent exec_command schema.
+        self.definition = inner.definition
+
+    def assess_risk(
+        self,
+        arguments: dict[str, Any],
+        context: Any | None = None,
+    ) -> ActionRisk:
+        return self._inner.assess_risk(arguments, context)
+
+    async def execute(
+        self,
+        arguments: dict[str, Any],
+        context: ToolContext,
+    ) -> dict[str, Any]:
+        command = arguments.get("command")
+        if isinstance(command, list):
+            for argument in command:
+                if (
+                    isinstance(argument, str)
+                    and argument in _SHELL_CONTROL_TOKENS
+                ):
+                    raise ValueError(
+                        "exec_command 不经过 shell，不能把 shell 控制符 "
+                        f"{argument!r} 作为独立参数传入；请拆分命令，"
+                        "或显式使用 ['sh', '-c', '...'] 等合适的 argv。"
+                    )
+        return await self._inner.execute(arguments, context)
+
+
+def build_runtime(
+    workspace: Path,
+    *,
+    provider_config: ProviderConfig,
+    approve_mode: ApprovalMode,
+    model: str | None = None,
+    stream: bool = True,
+    event_handler: Any | None = None,
+    max_steps: int = 50,
+    step_timeout_s: float | None = 300.0,
+    total_timeout_s: float | None = 1800.0,
+    extra_tools: Iterable[BaseTool] | None = None,
+    skills: Iterable[Skill] | None = None,
+    mcp_clients: Iterable[MCPClient] | None = None,
+    approval_callback: Any | None = None,
+) -> AgentRuntime:
+    skill_registry = SkillRegistry(skills)
+    mcp_tools: list[BaseTool] = []
+    for client in mcp_clients or ():
+        mcp_tools.extend(adapt_mcp_tools(client))
+
+    registry = ToolRegistry(
+        [
+            FileReadTool(workspace),
+            DiffingFileTool(FileWriteTool(workspace), workspace),
+            DiffingFileTool(FileEditTool(workspace), workspace),
+            GuardedExecCommandTool(ExecCommandTool(workspace)),
+            *skill_registry.tools(),
+            *mcp_tools,
+            *(extra_tools or ()),
+        ]
+    )
+
+    # ``step_timeout_s=None`` disables the Runtime's ReAct step deadline; it
+    # must not turn into an arbitrary 330s provider deadline.  Leave the
+    # provider timeout unset in that case so the Provider layer applies its
+    # own default request timeout.
+    provider_timeout_s = (
+        None
+        if step_timeout_s is None
+        else max(120.0, step_timeout_s + 30.0)
+    )
+    reasoner = _build_provider_reasoner(
+        provider_config,
+        model=model,
+        tools=registry.provider_schemas(),
+        action_risks=registry.action_risks(),
+        action_risk_resolver=registry.assess_risk,
+        stream=stream,
+        timeout_s=provider_timeout_s,
+        # 产品层单次模型请求期限，默认取 step_timeout_s；与传输层 timeout
+        # (OpenAIProviderParam.timeout) 正交，先到者为准。
+        request_timeout_s=step_timeout_s,
+    )
+
+    policy_engine = make_policy(
+        approve_mode,
+        approval_callback=approval_callback,
+    )
+
+    system_prompt = build_system_prompt(workspace)
+    skill_instructions = skill_registry.instructions()
+    if skill_instructions:
+        system_prompt += "\n\n" + skill_instructions
+
+    return AgentRuntime(
+        reasoner,
+        ToolExecutor(registry),
+        context_manager=ContextManager(
+            ContextConfig(system_prompt=system_prompt)
+        ),
+        policy_engine=policy_engine,
+        event_handler=event_handler,
+        config=RunConfig(
+            max_steps=max_steps,
+            step_timeout_s=step_timeout_s,
+            total_timeout_s=total_timeout_s,
+            # policy_timeout_s 已废弃：core 侧同步 policy 不再设 deadline，统一 None。
+            policy_timeout_s=None,
+            enable_heartbeat=False,
+        ),
+    )
+
+
+def build_master_worker_system(
+    workspace: Path,
+    *,
+    provider_config: ProviderConfig,
+    approve_mode: ApprovalMode,
+    model: str | None = None,
+    stream: bool = True,
+    event_handler: Any | None = None,
+    max_steps: int = 50,
+    step_timeout_s: float | None = 300.0,
+    total_timeout_s: float | None = 1800.0,
+    skills: Iterable[Skill] | None = None,
+    mcp_clients: Iterable[MCPClient] | None = None,
+    approval_callback: Any | None = None,
+) -> MasterWorkerSystem:
+    """Build a restricted master and one workspace-capable coder worker."""
+    orchestrator = AgentOrchestrator()
+
+    async def worker_event_handler(event: Any) -> None:
+        await orchestrator.handle_agent_event(event)
+        if event_handler is not None:
+            await event_handler(event)
+
+    provider_timeout_s = (
+        None
+        if step_timeout_s is None
+        else max(120.0, step_timeout_s + 30.0)
+    )
+    worker = build_runtime(
+        workspace,
+        provider_config=provider_config,
+        approve_mode=approve_mode,
+        model=model,
+        stream=stream,
+        event_handler=worker_event_handler,
+        max_steps=max_steps,
+        step_timeout_s=step_timeout_s,
+        total_timeout_s=total_timeout_s,
+        skills=skills,
+        mcp_clients=mcp_clients,
+        approval_callback=approval_callback,
+    )
+    coder_tool_names = frozenset(
+        schema.get("function", {}).get("name")
+        for schema in worker.reasoner.tools
+        if schema.get("function", {}).get("name") not in {
+            ProviderReasoner.ASK_USER_TOOL,
+            ProviderReasoner.COMPLETE_TOOL,
+        }
+    )
+    orchestrator.register_agent(
+        "coder",
+        worker,
+        session_policy=SessionPolicy(
+            allowed_action_types=frozenset({ActionType.TOOL}),
+            allowed_tools=coder_tool_names,
+            allow_write=True,
+            allow_dangerous=False,
+            max_parallel_actions=1,
+        ),
+    )
+
+    delegate_modes = frozenset({"await_result"})
+    dispatcher = ActionDispatcher()
+    dispatcher.register(
+        ActionType.AGENT,
+        SubAgentExecutor(
+            orchestrator.run_child,
+            allowed_modes=delegate_modes,
+        ),
+    )
+    master_reasoner = _build_provider_reasoner(
+        provider_config,
+        model=model,
+        tools=SubAgentExecutor.tool_schemas(modes=delegate_modes),
+        action_types=SubAgentExecutor.action_types(),
+        stream=stream,
+        timeout_s=provider_timeout_s,
+        # 同 worker：产品层期限默认取 step_timeout_s，与传输层 timeout 正交。
+        request_timeout_s=step_timeout_s,
+    )
+    master = AgentRuntime(
+        master_reasoner,
+        dispatcher,
+        context_manager=ContextManager(
+            ContextConfig(system_prompt=build_master_system_prompt(workspace))
+        ),
+        policy_engine=make_policy(
+            approve_mode,
+            approval_callback=approval_callback,
+        ),
+        event_handler=event_handler,
+        config=RunConfig(
+            max_steps=max_steps,
+            step_timeout_s=step_timeout_s,
+            total_timeout_s=total_timeout_s,
+            # policy_timeout_s 已废弃：core 侧同步 policy 不再设 deadline，统一 None。
+            policy_timeout_s=None,
+            enable_heartbeat=False,
+        ),
+    )
+    orchestrator.register_agent(
+        "master",
+        master,
+        session_policy=SessionPolicy(
+            allowed_action_types=frozenset({ActionType.AGENT}),
+            allow_write=False,
+            allow_dangerous=False,
+            max_parallel_actions=1,
+        ),
+    )
+    return MasterWorkerSystem(orchestrator)
+
+
+def _build_provider_reasoner(
+    provider_config: ProviderConfig,
+    *,
+    model: str | None,
+    tools: list[dict[str, Any]],
+    action_types: dict[str, ActionType] | None = None,
+    action_risks: dict[str, ActionRisk] | None = None,
+    action_risk_resolver: Any | None = None,
+    stream: bool,
+    timeout_s: float | None = None,
+    request_timeout_s: float | None = None,
+) -> ProviderReasoner:
+    model_name = provider_config.resolve_model(model)
+    if provider_config.protocol != "openai":
+        raise ValueError(
+            f"provider {provider_config.name} 使用 protocol="
+            f"{provider_config.protocol!r}；当前 runtime 只支持 openai "
+            "compatible endpoint"
+        )
+    if not provider_config.base_url:
+        raise ValueError(
+            f"provider {provider_config.name} 缺少 base_url；"
+            f"编辑 ~/.cache/mindcode/config.toml"
+        )
+
+    # Pass a placeholder when api_key is empty so AsyncOpenAI can construct.
+    # The real error surfaces on the first chat() call; until then the user
+    # can fix it from the REPL via /api-key without restarting.
+    api_key = provider_config.api_key or "pending-api-key"
+    param = OpenAIProviderParam(
+        model=model_name,
+        api_key=api_key,
+        base_url=provider_config.base_url,
+        timeout=timeout_s if timeout_s is not None else 120.0,
+    )
+    provider = OpenAIProvider(param)
+    router = ProviderRouter([provider])
+
+    return ProviderReasoner(
+        router,
+        tools=tools,
+        action_types=action_types,
+        action_risks=action_risks,
+        action_risk_resolver=action_risk_resolver,
+        stream=stream,
+        request_timeout_s=request_timeout_s,
+    )

mindcode/skills.py

@@ -0,0 +1,154 @@
+"""MindCode-owned skill registration and loading.
+
+Skills are intentionally small: an instruction block can be injected into the
+runtime system prompt and may optionally contribute ordinary MindAgent tools.
+The registry does not execute skills or depend on a plugin framework.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from mindagent.tools.base import BaseTool
+
+
+@dataclass(frozen=True)
+class Skill:
+    """A named instruction block with optional tools."""
+
+    name: str
+    instructions: str
+    tools: tuple[BaseTool, ...] = field(default_factory=tuple)
+
+    def __post_init__(self) -> None:
+        name = self.name.strip()
+        if not name:
+            raise ValueError("skill name 不能为空")
+        if not self.instructions.strip():
+            raise ValueError(f"skill {name!r} instructions 不能为空")
+        object.__setattr__(self, "name", name)
+        object.__setattr__(self, "instructions", self.instructions.strip())
+        object.__setattr__(self, "tools", tuple(self.tools))
+
+
+class SkillRegistry:
+    """Deterministic in-memory skill registry owned by MindCode."""
+
+    def __init__(self, skills: Iterable[Skill] | None = None):
+        self._skills: dict[str, Skill] = {}
+        for skill in skills or ():
+            self.register(skill)
+
+    def register(self, skill: Skill) -> None:
+        if not isinstance(skill, Skill):
+            raise TypeError("只能注册 Skill 实例")
+        if skill.name in self._skills:
+            raise ValueError(f"Skill 已注册: {skill.name}")
+        self._skills[skill.name] = skill
+
+    def get(self, name: str) -> Skill:
+        try:
+            return self._skills[name]
+        except KeyError as exc:
+            raise KeyError(f"Skill 不存在: {name}") from exc
+
+    def __iter__(self) -> Iterator[Skill]:
+        return iter(self._skills.values())
+
+    def __len__(self) -> int:
+        return len(self._skills)
+
+    def instructions(self) -> str:
+        """Render registered instructions for a system prompt."""
+        return "\n\n".join(
+            f"Skill: {skill.name}\n{skill.instructions}"
+            for skill in self
+        )
+
+    def tools(self) -> list[BaseTool]:
+        """Return skill-provided tools in registration order."""
+        return [tool for skill in self for tool in skill.tools]
+
+
+class SkillLoader:
+    """Load plain Markdown skill files without external dependencies.
+
+    A file named ``SKILL.md`` uses its parent directory name by default; other
+    Markdown files use their stem. An optional minimal front matter header is
+    supported for a custom name::
+
+        ---
+        name: repository-guidance
+        ---
+        ...instructions...
+    """
+
+    def load_file(self, path: str | Path, *, name: str | None = None) -> Skill:
+        source = Path(path)
+        text = source.read_text(encoding="utf-8")
+        front_name, body = _parse_front_matter(text)
+        skill_name = name or front_name or _default_name(source)
+        return Skill(skill_name, body)
+
+    def load_directory(
+        self,
+        path: str | Path,
+        *,
+        pattern: str = "SKILL.md",
+    ) -> list[Skill]:
+        root = Path(path)
+        if not root.is_dir():
+            raise ValueError(f"skill 目录不存在: {root}")
+        return [
+            self.load_file(source)
+            for source in sorted(root.rglob(pattern))
+            if source.is_file()
+        ]
+
+    def load_into(
+        self,
+        registry: SkillRegistry,
+        paths: Iterable[str | Path],
+    ) -> list[Skill]:
+        loaded: list[Skill] = []
+        for path in paths:
+            source = Path(path)
+            items = (
+                self.load_directory(source)
+                if source.is_dir()
+                else [self.load_file(source)]
+            )
+            for skill in items:
+                registry.register(skill)
+                loaded.append(skill)
+        return loaded
+
+
+def _default_name(path: Path) -> str:
+    if path.name.lower() == "skill.md":
+        return path.parent.name
+    return path.stem
+
+
+def _parse_front_matter(text: str) -> tuple[str | None, str]:
+    if not text.startswith("---\n"):
+        return None, text
+    marker = "\n---\n"
+    end = text.find(marker, 4)
+    if end < 0:
+        return None, text
+    header = text[4:end]
+    name: str | None = None
+    for line in header.splitlines():
+        key, separator, value = line.partition(":")
+        if separator and key.strip().lower() == "name":
+            value = value.strip()
+            if value:
+                name = value.strip("\"'")
+                break
+    return name, text[end + len(marker) :]
+
+
+__all__ = ["Skill", "SkillLoader", "SkillRegistry"]