mosscode 0.1.0__py3-none-any.whl

mosscode/tools/base.py

@@ -0,0 +1,384 @@
+"""Protocol-independent tool contract and a single validation/execution boundary."""
+
+import asyncio
+import json
+from abc import ABC, abstractmethod
+from contextvars import ContextVar
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from ..messages import ToolCall, ToolDefinition, ToolResult
+from ..permissions import Decision, PermissionPolicy
+from ..security import SecurityError, project_path, resolve_path
+
+# The call a tool is executing, for tools that need its id (the agent tool's row in the UI).
+CURRENT_CALL: ContextVar[ToolCall | None] = ContextVar("mosscode_current_call", default=None)
+
+
+class Params(BaseModel):
+    model_config = ConfigDict(strict=True, extra="forbid")
+
+
+class ToolFailure(Exception):
+    def __init__(self, code: str, message: str, **details: Any):
+        super().__init__(message)
+        self.code = code
+        self.details = details
+
+
+def bounded_output(output, details):
+    encoded = output.encode("utf-8")
+    if len(encoded) > 65536:
+        return (encoded[:65536].decode("utf-8", errors="ignore") + "\n（结果已截断）", {**details, "truncated": True})
+    return output, details
+
+
+HOOK_NOTE_LIMIT = 8000  # Hook text added to one tool result.
+
+
+def with_hook_notes(result: ToolResult, notes, modified_by: str | None) -> ToolResult:
+    """Hook notes and the reformatting notice go after the result, into history and the transcript."""
+    if not notes and not modified_by:
+        return result
+    blocks, room = [], HOOK_NOTE_LIMIT
+    for hook_id, note in notes:
+        if room <= 0:
+            break
+        text = note if len(note) <= room else note[:room] + "\n（Hook 内容超出 8000 个字符，已截断）"
+        room -= len(note)
+        blocks.append(f'<hook-notification hook="{hook_id}">\n{text}\n</hook-notification>')
+    details = result.details
+    if modified_by:
+        blocks.append(f"文件已被 Hook {modified_by} 修改（如格式化）；再次编辑前请重新读取。")
+        details = {**details, "hook_modified": modified_by}  # The tool row shows it; the output may be cut there.
+    return replace(result, output=result.output + "\n\n" + "\n\n".join(blocks), details=details)
+
+
+def _stamp(path: Path | None):
+    try:
+        status = path.stat() if path is not None else None
+    except OSError:
+        return None
+    return (status.st_mtime_ns, status.st_size) if status is not None else None
+
+
+def reject_json_constant(value):
+    raise ValueError("非有限数字不是 JSON 参数。")
+
+
+class ExecutionCancelled(asyncio.CancelledError):
+    def __init__(self, result: ToolResult):
+        super().__init__()
+        self.result = result
+
+
+class Tool(ABC):
+    name: str
+    description: str
+    params_model: type[Params]
+    prompt_summary = ""
+    prompt_guidelines: tuple[str, ...] = ()
+    timeout = 30.0
+    read_only = False
+    plan_only = False  # Offered only in plan mode (exit_plan_mode).
+    plan_commands = False  # Offered in plan mode; the policy admits only read-only commands.
+    plan_allowed = False  # Offered and allowed in plan mode although not read-only (memory).
+
+    def validate_arguments(self, raw):
+        return self.params_model.model_validate(raw)
+
+    def __init__(self, root: Path):
+        self.root = root.resolve()
+
+    def path(self, value: str) -> Path:
+        try:
+            return project_path(self.root, value)
+        except SecurityError as exc:
+            raise ToolFailure(exc.code, str(exc)) from None
+
+    def read_path(self, value: str) -> Path:
+        """Read tools may leave the project; the permission policy asks first."""
+        try:
+            return resolve_path(self.root, value)
+        except SecurityError as exc:
+            raise ToolFailure(exc.code, str(exc)) from None
+
+    def display(self, path: Path) -> str:
+        return path.relative_to(self.root).as_posix() if path.is_relative_to(self.root) else str(path)
+
+    def definition(self) -> ToolDefinition:
+        guidelines = tuple(dict.fromkeys(rule.strip() for rule in self.prompt_guidelines if rule.strip()))
+        description = "\n".join((self.description, *(f"- {rule}" for rule in guidelines)))
+        return ToolDefinition(
+            self.name, description, self.params_model.model_json_schema(), self.prompt_summary, guidelines
+        )
+
+    @abstractmethod
+    async def execute(self, params: Params) -> tuple[str, dict[str, Any]]: ...
+
+
+async def file_io(function, *args):
+    # A cancelled Python thread cannot roll back filesystem changes. Settle it
+    # before returning so the runtime can retain the actual outcome in history.
+    worker = asyncio.create_task(asyncio.to_thread(function, *args))
+    try:
+        return await asyncio.shield(worker)
+    except asyncio.CancelledError:
+        return await asyncio.shield(worker)
+
+
+class ToolRegistry:
+    def __init__(self, tools=(), *, permissions: PermissionPolicy | None = None):
+        self._tools: dict[str, Tool] = {}
+        for tool in tools:
+            self.register(tool)
+        first = next(iter(self._tools.values()), None)
+        self.permissions = permissions or PermissionPolicy(first.root if first else Path.cwd())
+        # Set by the application; without it oversized results are cut to a preview, not stored.
+        self.session = None
+        self.hooks = None  # The HookEngine, set by the application.
+        self.agent = "main"  # "fork" or "subagent" in a sub-agent's view.
+        self.agent_type = ""  # The definition name, "fork" or "skill:<name>".
+        self.forbidden: frozenset[str] = frozenset()  # Offered (fork cache) but refused when called.
+        self.nested = False  # Started by a hook's agent action; its tool events run no agent action.
+        self.worktree = ""  # The worktree a sub-agent works in, relative to the repository.
+        # withheld(tool) -> True keeps a tool for sub-agents and members but neither offers nor runs it here.
+        self.withheld = None
+        if any(tool.root != self.permissions.root for tool in self._tools.values()):
+            raise ValueError("工具与权限策略必须使用同一个项目根目录。")
+
+    def use_session(self, session) -> None:
+        """Store oversized results in this run's directory and let read_file open them without approval."""
+        self.session = session
+        self.permissions.session_dir = session.directory if session is not None else None
+
+    def forget_reads(self) -> None:
+        """After compaction the model no longer holds file contents: edits need a fresh read."""
+        for tool in self._tools.values():
+            state = getattr(tool, "state", None)
+            if state is not None and hasattr(state, "clear"):
+                state.clear()
+
+    def register(self, tool: Tool) -> None:
+        if hasattr(self, "permissions") and tool.root != self.permissions.root:
+            raise ValueError("工具与权限策略必须使用同一个项目根目录。")
+        if tool.name in self._tools:
+            raise ValueError(f"工具名称重复：{tool.name}")
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Tool | None:
+        return self._tools.get(name)
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(name for name, tool in self._tools.items() if not self._withheld(tool))
+
+    def _withheld(self, tool: Tool) -> bool:
+        return self.withheld is not None and self.withheld(tool)
+
+    def unregister(self, name: str) -> None:
+        self._tools.pop(name, None)
+
+    def for_agent(
+        self,
+        *,
+        agent: str,
+        agent_type: str,
+        permissions: PermissionPolicy,
+        state=None,
+        keep=None,
+        extra=(),
+        forbidden=(),
+    ) -> "ToolRegistry":
+        """A sub-agent's registry.
+
+        Tools holding a FileState are copied and share `state` (a new, empty one when None);
+        keep(name) filters the rest; extra tools are added; forbidden names stay offered but are refused.
+        """
+        from copy import copy
+
+        from .files import FileState
+
+        state = state if state is not None else FileState()
+        view = ToolRegistry(permissions=permissions)
+        view.session, view.hooks, view.agent, view.agent_type = self.session, self.hooks, agent, agent_type
+        view.forbidden = frozenset(forbidden)
+        for name, tool in self._tools.items():
+            if keep is not None and not keep(name):
+                continue
+            if getattr(tool, "state", None) is not None:
+                tool = copy(tool)
+                tool.state = state
+            view._tools[name] = tool
+        for tool in extra:  # Replace same-named ones.
+            if tool.root != permissions.root:
+                raise ValueError("工具与权限策略必须使用同一个项目根目录。")
+            view._tools[tool.name] = tool
+        return view
+
+    def file_state(self):
+        """The FileState the file tools share, if any."""
+        return next((tool.state for tool in self._tools.values() if getattr(tool, "state", None) is not None), None)
+
+    def definitions(self, *, read_only: bool = False, plan: bool = False) -> tuple[ToolDefinition, ...]:
+        # Plan mode offers read-only tools, read-only commands and the tool that submits the plan.
+        def offered(tool):
+            if plan:
+                return tool.read_only or tool.plan_only or tool.plan_commands or tool.plan_allowed
+            return not tool.plan_only and (not read_only or tool.read_only)
+
+        return tuple(tool.definition() for tool in self._tools.values() if offered(tool) and not self._withheld(tool))
+
+    def is_read_only(self, name: str) -> bool:
+        tool = self.get(name)
+        return tool is not None and tool.read_only
+
+    def _bound(self, call: ToolCall, output: str, details: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+        from ..tool_budget import EXEMPT, bound_result
+
+        if call.name in EXEMPT:
+            return bounded_output(output, details)
+        return bound_result(call.name, call.id, output, details, self.session)
+
+    async def _invoke(self, call: ToolCall, tool: Tool, params: Params) -> ToolResult:
+        CURRENT_CALL.set(call)  # Runs in its own task: the value never leaks to the caller.
+        try:
+            output, details = await tool.execute(params)
+            output, details = self._bound(call, output, details)
+            return ToolResult(call.id, call.name, output, details=details)
+        except ToolFailure as exc:
+            output, details = self._bound(call, str(exc), exc.details)
+            return ToolResult(call.id, call.name, output, True, exc.code, details)
+        except FileNotFoundError:
+            return ToolResult(call.id, call.name, "文件或目录不存在。", True, "not_found")
+        except IsADirectoryError:
+            return ToolResult(call.id, call.name, "目标是目录，不能作为文本文件操作。", True, "is_directory")
+        except UnicodeError:
+            return ToolResult(call.id, call.name, "文件不是可读取的 UTF-8 文本。", True, "encoding_error")
+        except PermissionError:
+            return ToolResult(call.id, call.name, "系统拒绝访问目标。", True, "permission_denied")
+        except OSError:
+            return ToolResult(call.id, call.name, "文件系统或进程操作失败。", True, "os_error")
+        except Exception:
+            return ToolResult(call.id, call.name, "工具内部错误。", True, "internal_error")
+
+    async def execute(self, call: ToolCall, *, read_only: bool = False) -> ToolResult:
+        tool = self.get(call.name)
+        if tool is None:
+            return ToolResult(call.id, call.name, "未知工具。", True, "unknown_tool")
+        if self._withheld(tool):
+            from ..coordinator import WITHHELD
+
+            return ToolResult(
+                call.id, call.name, WITHHELD.format(name=call.name), True, "coordinator_withheld", {"executed": False}
+            )
+        if call.name in self.forbidden:
+            return ToolResult(
+                call.id,
+                call.name,
+                f"你是子 Agent，不能使用 {call.name}；请在自己的范围内完成任务并在报告中说明。",
+                True,
+                "subagent_forbidden",
+                {"executed": False},
+            )
+        if read_only and not tool.read_only:
+            # Explicit caller restriction, separate from the approval-based plan mode.
+            return ToolResult(call.id, call.name, "本次调用限定只读工具；此调用未执行。", True, "plan_blocked")
+        try:
+            raw = json.loads(call.arguments, parse_constant=reject_json_constant)
+        except (ValueError, TypeError):
+            return ToolResult(call.id, call.name, "工具参数不是完整、合法的 JSON。", True, "invalid_json")
+        try:
+            params = tool.validate_arguments(raw)
+        except ToolFailure as exc:
+            return ToolResult(call.id, call.name, str(exc), True, exc.code, exc.details)
+        except ValidationError as exc:
+            issues = [
+                {"field": ".".join(map(str, e["loc"])), "message": e["msg"]}
+                for e in exc.errors(include_input=False, include_context=False, include_url=False)
+            ]
+            listed = "\n".join(f"- {issue['field'] or '(参数)'}：{issue['message']}" for issue in issues[:20])
+            return ToolResult(
+                call.id, call.name, "工具参数校验失败：\n" + listed, True, "invalid_arguments", {"issues": issues}
+            )
+        hooks, state = self.hooks, {}
+        gate = notify = None
+        if hooks is not None:
+
+            async def gate(operation):
+                state["operation"] = operation
+                if not hooks.wants("pre_tool_use"):
+                    return None
+                outcome = await hooks.fire(self._event("pre_tool_use", call.name, raw, operation, tool.root))
+                state["notes"] = list(outcome.notes)
+                if outcome.rejection is None:
+                    return None
+                state["hook"] = outcome.rejection[0]
+                return Decision("deny", "hook_rejected", outcome.rejection[1])
+
+            async def notify(request):
+                if hooks.wants("permission_request"):
+                    operation = request.operation if request.operation.tool == call.name else None
+                    await hooks.fire(self._event("permission_request", call.name, raw, operation, tool.root))
+
+        decision = await self.permissions.authorize(call.id, tool, params, gate=gate, notify=notify)
+        if decision.action != "allow":
+            details = {"executed": False, **({"hook": state["hook"]} if decision.code == "hook_rejected" else {})}
+            return ToolResult(call.id, call.name, decision.reason, True, decision.code, details)
+        result = await self._run(call, tool, params)
+        if hooks is None:
+            return result
+        return await self._after(call, tool, raw, state, result)
+
+    async def _after(self, call: ToolCall, tool: Tool, raw, state, result: ToolResult) -> ToolResult:
+        """post_tool_use; a cancelled hook keeps the tool result."""
+        hooks, notes, modified = self.hooks, list(state.get("notes", ())), None
+        if hooks.wants("post_tool_use"):
+            event = self._event("post_tool_use", call.name, raw, state.get("operation"), tool.root, result)
+            watched = event.file_path if call.name in {"write_file", "edit_file"} and not result.is_error else None
+            before = _stamp(watched)
+            try:
+                outcome = await hooks.fire(event)
+            except asyncio.CancelledError:
+                raise ExecutionCancelled(with_hook_notes(result, notes, None)) from None
+            notes.extend(outcome.notes)
+            if before is not None and outcome.ran and _stamp(watched) != before:
+                modified = outcome.ran[-1]  # FileState keeps the tool's own stamp: the next edit must reread.
+        return with_hook_notes(result, notes, modified)
+
+    def _event(self, name, tool_name, raw, operation, root, result=None):
+        from ..hooks import tool_event
+
+        event = tool_event(name, self.agent, tool_name, raw, operation, root, result, agent_type=self.agent_type)
+        if self.worktree:
+            event = replace(
+                event,
+                fields={**event.fields, "worktree": self.worktree},
+                payload={**event.payload, "worktree": self.worktree},
+            )
+        return replace(event, nested=True) if self.nested else event
+
+    async def _run(self, call: ToolCall, tool: Tool, params: Params) -> ToolResult:
+        task = asyncio.create_task(self._invoke(call, tool, params))
+        limit = getattr(params, "timeout", tool.timeout)
+        try:
+            return await asyncio.wait_for(asyncio.shield(task), timeout=limit)
+        except (TimeoutError, asyncio.CancelledError) as exc:
+            task.cancel()
+            try:
+                outcome = await task
+            except asyncio.CancelledError:
+                code = "timeout" if isinstance(exc, TimeoutError) else "cancelled"
+                outcome = ToolResult(
+                    call.id,
+                    call.name,
+                    "工具执行超时。" if code == "timeout" else "工具已取消，可能已有部分外部效果。",
+                    True,
+                    code,
+                )
+            if isinstance(exc, asyncio.CancelledError):
+                raise ExecutionCancelled(outcome) from None
+            # Local file operations may finish during cancellation cleanup.
+            return replace(outcome, details={**outcome.details, "deadline_exceeded": True})

mosscode/tools/diffing.py

@@ -0,0 +1,16 @@
+"""Unified diffs for people (approval and transcript); the model gets a summary."""
+
+import difflib
+
+DIFF_LIMIT = 200
+DIFF_INPUT_LIMIT = 20000  # Lines per side; larger files skip the quadratic matcher.
+
+
+def unified_diff(before: str, after: str, name: str, *, limit: int = DIFF_LIMIT) -> str:
+    old, new = before.splitlines(), after.splitlines()
+    if max(len(old), len(new)) > DIFF_INPUT_LIMIT:
+        return f"（文件超过 {DIFF_INPUT_LIMIT} 行，未生成 diff）"
+    lines = list(difflib.unified_diff(old, new, f"a/{name}", f"b/{name}", lineterm="", n=3))
+    if len(lines) > limit:
+        lines = [*lines[:limit], f"…（diff 共 {len(lines)} 行，仅显示前 {limit} 行）"]
+    return "\n".join(lines)

mosscode/tools/execution.py

@@ -0,0 +1,99 @@
+"""Parallelize adjacent reads, preserve ordering across side-effect barriers."""
+
+import asyncio
+from copy import deepcopy
+from time import monotonic
+
+from ..messages import Message, ResponseBoundary, ToolProgress, ToolResult
+from ..tool_budget import bound_message
+from .base import ExecutionCancelled, ToolRegistry
+
+PARALLEL_AGENTS = "agent"  # Adjacent agent calls run together like adjacent reads.
+
+
+def _group(call, registry: ToolRegistry) -> str | None:
+    if call.name == PARALLEL_AGENTS and registry.get(call.name) is not None:
+        return "agent"
+    return "read" if registry.is_read_only(call.name) else None
+
+
+def partition_calls(calls, registry: ToolRegistry, concurrency: int = 4):
+    batch, kind = [], None
+    for index, call in enumerate(calls):
+        group = _group(call, registry)
+        if batch and (group != kind or len(batch) == concurrency):
+            yield batch
+            batch = []
+        if group is None:
+            yield [index]
+            continue
+        batch.append(index)
+        kind = group
+    if batch:
+        yield batch
+
+
+async def execute_batch(message: Message, registry: ToolRegistry, history: list[Message], *, read_only: bool = False):
+    calls = message.tool_calls
+    results = [None] * len(calls)
+    jobs: dict[int, asyncio.Task] = {}
+    started = {}
+    approval_job = None
+    position = len(history)
+    history.append(Message("tool", ()))
+
+    def save():
+        history[position] = Message("tool", (), tool_results=tuple(deepcopy(r) for r in results if r is not None))
+
+    try:
+        yield ResponseBoundary(message)
+        for batch in partition_calls(calls, registry):
+            for index in batch:
+                yield ToolProgress(calls[index], "running")
+            for index in batch:
+                started[index] = monotonic()
+                jobs[index] = asyncio.create_task(registry.execute(calls[index], read_only=read_only))
+            while jobs:
+                if approval_job is None:
+                    approval_job = asyncio.create_task(registry.permissions.requests.get())
+                done, _ = await asyncio.wait([*jobs.values(), approval_job], return_when=asyncio.FIRST_COMPLETED)
+                if approval_job in done:
+                    request = approval_job.result()
+                    approval_job = None
+                    if request.id in registry.permissions.pending:
+                        yield request
+                for index in sorted(i for i, task in jobs.items() if task in done):
+                    result = await jobs[index]
+                    del jobs[index]
+                    results[index] = result
+                    save()
+                    yield ToolProgress(calls[index], "finished", result, monotonic() - started[index])
+    finally:
+        if approval_job is not None:
+            approval_job.cancel()
+            try:
+                await approval_job
+            except asyncio.CancelledError:
+                pass
+        for task in jobs.values():
+            if not task.done():
+                task.cancel()
+        # Await individually to preserve ExecutionCancelled.result.
+        for index, task in jobs.items():
+            try:
+                results[index] = await task
+            except ExecutionCancelled as exc:
+                results[index] = exc.result
+            except asyncio.CancelledError:
+                results[index] = ToolResult(calls[index].id, calls[index].name, "调用已取消。", True, "cancelled")
+            except Exception:
+                results[index] = ToolResult(
+                    calls[index].id, calls[index].name, "工具执行出现内部错误。", True, "internal_error"
+                )
+        for index, result in enumerate(results):
+            if result is None:
+                results[index] = ToolResult(
+                    calls[index].id, calls[index].name, "本轮已停止；此调用未执行。", True, "not_executed"
+                )
+        save()
+        history[position] = bound_message(history[position], registry.session)