synapse-cli-agent 0.1.13__py3-none-any.whl

synapse/runtime/subagents.py

@@ -0,0 +1,207 @@
+"""Default subagent specs for create_deep_agent(subagents=...).
+
+Note: deepagents FilesystemPermission is incompatible with backends that expose
+command execution (LocalShellBackend / SandboxBackendProtocol). Isolation for
+our product uses tool-exclusion middleware + system prompts instead of
+permissions.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from synapse.runtime.middleware import build_tool_error_recovery_middleware
+from synapse.runtime.tool_output_middleware import build_tool_output_transform_middleware
+from synapse.tool_output.pipeline import ToolOutputTransformPipeline
+from synapse.tool_output.repository import ToolOutputRepository
+from synapse.tool_output.transformers import load_transformer_plugins
+from synapse.tools import build_tool_result_reader_tool
+
+
+def _intent_middleware() -> list[Any]:
+    """Inject ``intent`` field into every tool arg schema (main-agent parity)."""
+    from synapse.runtime.middleware import build_intent_schema_middleware
+
+    return list(build_intent_schema_middleware())
+
+
+_TODO_TOOL_NAMES = {"write_todos", "todo_write", "todos"}
+
+
+def _tool_exclusion_middleware(excluded: set[str], *, allow_execute: bool = False) -> list[Any]:
+    """Hide restricted tools from subagents with one middleware instance."""
+    from synapse.runtime.middleware import build_tool_exclusion_middleware
+
+    blocked = set(excluded) | _TODO_TOOL_NAMES
+    if not allow_execute:
+        blocked.add("execute")
+    return [build_tool_exclusion_middleware(blocked)]
+
+
+_READONLY_TOOL_NAMES = {"write_file", "edit_file"}
+
+
+_PARALLEL_HINT = (
+    "- Run independent tool calls in parallel when they do not depend on each other.\n"
+    "- Every tool call must include a short English ``intent`` describing its purpose.\n"
+    "  Example: ``inspect pytest config`` / ``locate login failure``.\n"
+    "- Do not use generic intent values such as ``run tool`` or ``read_file``.\n"
+)
+
+
+def build_default_subagents(
+    *,
+    enabled: bool = True,
+    tester_model: str | None = None,
+    reviewer_model: str | None = None,
+    researcher_model: str | None = None,
+    isolate_tools: bool = True,
+    tool_output_db_path: Path | str | None = None,
+    tool_output_transform_threshold_bytes: int = 512,
+    tool_output_disabled_types: list[str] | None = None,
+    tool_output_transform_plugins: list[str] | None = None,
+    enable_native_tool_output_compression: bool = True,
+) -> list[dict[str, Any]] | None:
+    """Return declarative SubAgent specs, or None when disabled.
+
+    deepagents exposes these via the built-in `task` tool. The main agent
+    routes by reading each subagent's description.
+
+    When ``isolate_tools`` is True (LocalShell-safe):
+    - researcher: exclude write_file/edit_file/execute
+    - reviewer: exclude write_file/edit_file
+    - tester: uses built-in ``execute`` and project ``AGENTS.md`` commands
+    """
+    if not enabled:
+        return None
+
+    tester: dict[str, Any] = {
+        "name": "tester",
+        "description": (
+            "Run focused tests, diagnose failures, and propose minimal fixes. "
+            "Use for pytest failures, regressions, and verification after edits."
+        ),
+        "system_prompt": (
+            "You are a testing specialist for a Python coding agent.\n"
+            "- Prefer the narrowest useful pytest invocation first.\n"
+            "- Follow the project's AGENTS.md for test steps and conventions.\n"
+            "- Report failing tests, root cause, and exact commands run.\n"
+            "- Do not expand scope beyond verifying the requested behavior.\n"
+            "- Reply in Chinese when the parent conversation is Chinese.\n"
+            "- Do not use emoji in any output.\n" + _PARALLEL_HINT
+        ),
+    }
+    if tester_model:
+        tester["model"] = tester_model
+    if isolate_tools:
+        # Keep the tester on built-in tools; project commands belong in AGENTS.md.
+        tester["tools"] = []
+
+    tester["middleware"] = _tool_exclusion_middleware(set(), allow_execute=True)
+
+    reviewer: dict[str, Any] = {
+        "name": "reviewer",
+        "description": (
+            "Review code changes for correctness, regressions, security, and "
+            "style. Use after substantive edits or before summarizing a fix."
+        ),
+        "system_prompt": (
+            "You are a code reviewer for a local coding agent.\n"
+            "- Inspect diffs and related tests.\n"
+            "- Prioritize bugs, edge cases, and unsafe shell/file operations.\n"
+            "- Be concise: findings first, then residual risks.\n"
+            "- Do not rewrite large modules unless asked.\n"
+            "- Prefer read-only inspection; do not modify files unless required.\n"
+            "- Reply in Chinese when the parent conversation is Chinese.\n"
+            "- Do not use emoji in any output.\n" + _PARALLEL_HINT
+        ),
+    }
+    if reviewer_model:
+        reviewer["model"] = reviewer_model
+    # Reviewer may run read-only shell (git diff, pytest -q) but not write.
+    reviewer["middleware"] = _tool_exclusion_middleware(
+        _READONLY_TOOL_NAMES if isolate_tools else set(), allow_execute=True
+    )
+
+    researcher: dict[str, Any] = {
+        "name": "researcher",
+        "description": (
+            "Explore the codebase to answer questions: locate symbols, map "
+            "call chains, and summarize relevant files without making edits."
+        ),
+        "system_prompt": (
+            "You are a codebase researcher.\n"
+            "- Prefer read_file/glob over broad shell scans.\n"
+            "- Do not modify files.\n"
+            "- Do not run destructive shell commands.\n"
+            "- Return concrete file paths and short evidence snippets.\n"
+            "- Reply in Chinese when the parent conversation is Chinese.\n"
+            "- Do not use emoji in any output.\n" + _PARALLEL_HINT
+        ),
+    }
+    if researcher_model:
+        researcher["model"] = researcher_model
+    # Researcher is read-only and cannot run shell commands when isolated.
+    researcher["middleware"] = _tool_exclusion_middleware(
+        _READONLY_TOOL_NAMES if isolate_tools else set(),
+        allow_execute=not isolate_tools,
+    )
+
+    # Subagents use the exact same reversible transformation policy as the
+    # parent, scoped by their checkpoint namespace.
+    result_middleware: list[Any] = []
+    result_reader: Any | None = None
+    if tool_output_db_path is not None:
+        try:
+            output_pipeline = ToolOutputTransformPipeline(
+                transformers=load_transformer_plugins(tool_output_transform_plugins or []),
+                disabled_types=set(tool_output_disabled_types or []),
+                use_native=enable_native_tool_output_compression,
+            )
+        except Exception:  # noqa: BLE001
+            output_pipeline = ToolOutputTransformPipeline(
+                disabled_types=set(tool_output_disabled_types or []),
+                use_native=enable_native_tool_output_compression,
+            )
+        result_middleware = [
+            build_tool_output_transform_middleware(
+                ToolOutputRepository(tool_output_db_path),
+                threshold_bytes=tool_output_transform_threshold_bytes,
+                pipeline=output_pipeline,
+            ),
+            build_tool_error_recovery_middleware(),
+        ]
+        result_reader = build_tool_result_reader_tool(tool_output_db_path)
+    for spec in (researcher, tester, reviewer):
+        existing = list(spec.get("middleware") or [])
+        spec["middleware"] = result_middleware + _intent_middleware() + existing
+        if result_reader is not None:
+            spec["tools"] = [*list(spec.get("tools") or []), result_reader]
+
+    return [researcher, tester, reviewer]
+
+
+def format_subagents_lines(specs: list[dict[str, Any]] | None) -> list[str]:
+    if not specs:
+        return ["subagents: disabled"]
+    lines = [f"subagents: {len(specs)}"]
+    for spec in specs:
+        name = spec.get("name") or "?"
+        model = spec.get("model") or "(inherit)"
+        tools = spec.get("tools") or []
+        tool_names = [getattr(t, "name", getattr(t, "__name__", str(t))) for t in tools]
+        mw = spec.get("middleware") or []
+        isolation = "tool-exclude" if mw else ("tools+" if tools else "default")
+        if spec.get("permissions"):
+            isolation = "permissions(unsupported-with-shell)"
+        lines.append(f"  - {name}  model={model}  isolate={isolation}")
+        if tool_names:
+            lines.append(f"    tools+: {', '.join(str(n) for n in tool_names)}")
+        desc = str(spec.get("description") or "")
+        if desc:
+            one = " ".join(desc.split())
+            if len(one) > 90:
+                one = one[:89] + "…"
+            lines.append(f"    {one}")
+    return lines

synapse/runtime/tool_ignore.py

@@ -0,0 +1,221 @@
+"""Gitignore-based path filters for filesystem tools.
+
+Used by ``CodingLocalShellBackend`` so ``glob`` / ``grep`` skip paths that
+developers already marked ignored (``.venv``, build caches, agent state, ...).
+
+Practical gitwildmatch subset (not a full git clone):
+- root ``.gitignore`` only
+- ``*``, ``?``, ``**``, trailing ``/`` directory rules, ``!`` negation
+- extra deny patterns OR-ed via config
+
+Not a security sandbox: ``execute`` can still touch ignored paths.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+
+def _strip_comment(line: str) -> str:
+    out: list[str] = []
+    escaped = False
+    for ch in line:
+        if escaped:
+            out.append(ch)
+            escaped = False
+            continue
+        if ch == "\\":
+            escaped = True
+            out.append(ch)
+            continue
+        if ch == "#":
+            break
+        out.append(ch)
+    return "".join(out).rstrip().replace("\\ ", " ").replace("\\#", "#")
+
+
+def _gitignore_pattern_to_regex(pattern: str) -> re.Pattern[str]:
+    """Compile one gitignore pattern to regex over relative POSIX paths."""
+    pat = pattern
+    dir_only = pat.endswith("/")
+    if dir_only:
+        pat = pat[:-1]
+
+    anchored = pat.startswith("/")
+    if anchored:
+        pat = pat[1:]
+    elif "/" in pat:
+        anchored = True
+
+    parts: list[str] = ["^"]
+    if not anchored:
+        parts.append("(?:.*/)?")
+
+    i = 0
+    n = len(pat)
+    while i < n:
+        c = pat[i]
+        if c == "*":
+            if i + 1 < n and pat[i + 1] == "*":
+                i += 2
+                if i < n and pat[i] == "/":
+                    i += 1
+                    parts.append("(?:.*/)?")
+                else:
+                    parts.append(".*")
+            else:
+                parts.append("[^/]*")
+                i += 1
+        elif c == "?":
+            parts.append("[^/]")
+            i += 1
+        elif c == "[":
+            j = i + 1
+            if j < n and pat[j] in {"!", "]"}:
+                j += 1
+            while j < n and pat[j] != "]":
+                j += 1
+            if j >= n:
+                parts.append(re.escape(c))
+                i += 1
+            else:
+                class_body = pat[i + 1 : j]
+                if class_body.startswith("!"):
+                    class_body = "^" + class_body[1:]
+                parts.append("[" + class_body + "]")
+                i = j + 1
+        else:
+            parts.append(re.escape(c))
+            i += 1
+
+    # Directory-only and plain-name rules both exclude trees under the name.
+    parts.append("(?:/.*)?")
+    parts.append("$")
+    return re.compile("".join(parts))
+
+
+@dataclass(frozen=True)
+class _Rule:
+    regex: re.Pattern[str]
+    negate: bool
+    raw: str
+
+
+_BUILTIN_DENY_PATTERNS = (".git/",)
+_BUILTIN_DENY_RULES = tuple(
+    _Rule(regex=_gitignore_pattern_to_regex(pattern), negate=False, raw=pattern)
+    for pattern in _BUILTIN_DENY_PATTERNS
+)
+
+
+class ToolIgnoreMatcher:
+    """Match workspace-relative paths against built-in, gitignore, and deny rules."""
+
+    def __init__(self, rules: list[_Rule]) -> None:
+        self._rules = list(rules)
+
+    @property
+    def rule_count(self) -> int:
+        """Number of configured gitignore or extra-deny rules."""
+        return len(self._rules)
+
+    @property
+    def has_rules(self) -> bool:
+        """Whether built-in or configured filters can exclude a path."""
+        return bool(_BUILTIN_DENY_RULES or self._rules)
+
+    @classmethod
+    def from_workspace(
+        cls,
+        root: Path | str,
+        *,
+        extra_deny: list[str] | None = None,
+    ) -> ToolIgnoreMatcher:
+        root_path = Path(root).expanduser().resolve()
+        rules: list[_Rule] = []
+        gi = root_path / ".gitignore"
+        if gi.is_file():
+            try:
+                text = gi.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                text = ""
+            rules.extend(cls._parse_lines(text.splitlines()))
+        for raw in extra_deny or []:
+            rules.extend(cls._parse_lines([str(raw)]))
+        return cls(rules)
+
+    @classmethod
+    def from_patterns(cls, patterns: list[str]) -> ToolIgnoreMatcher:
+        rules: list[_Rule] = []
+        for raw in patterns:
+            rules.extend(cls._parse_lines([raw]))
+        return cls(rules)
+
+    @staticmethod
+    def _parse_lines(lines: list[str]) -> list[_Rule]:
+        out: list[_Rule] = []
+        for line in lines:
+            raw = line.strip()
+            if not raw:
+                continue
+            body = _strip_comment(raw)
+            if not body:
+                continue
+            negate = body.startswith("!")
+            if negate:
+                body = body[1:].strip()
+            if not body:
+                continue
+            try:
+                regex = _gitignore_pattern_to_regex(body)
+            except re.error:
+                continue
+            out.append(_Rule(regex=regex, negate=negate, raw=raw))
+        return out
+
+    @staticmethod
+    def normalize(path: str | Path) -> str:
+        text = str(path).replace("\\", "/").strip()
+        if not text or text in {".", "./"}:
+            return ""
+        while text.startswith("./"):
+            text = text[2:]
+        if text.startswith("/"):
+            text = text[1:]
+        if len(text) >= 2 and text[1] == ":":
+            text = text[2:].lstrip("/")
+        text = PurePosixPath(text).as_posix()
+        return "" if text == "." else text.rstrip("/")
+
+    def is_ignored(self, path: str | Path, *, is_dir: bool = False) -> bool:
+        del is_dir  # tree match is encoded in regex via (?:/.*)?
+        rel = self.normalize(path)
+        if not rel:
+            return False
+        if any(rule.regex.match(rel) for rule in _BUILTIN_DENY_RULES):
+            return True
+        if not self._rules:
+            return False
+        ignored = False
+        matched = False
+        for rule in self._rules:
+            if rule.regex.match(rel):
+                matched = True
+                ignored = not rule.negate
+        return ignored if matched else False
+
+
+def relative_to_root(path: str | Path, root: Path) -> str:
+    """Best-effort workspace-relative POSIX path for ignore checks."""
+    text = str(path).replace("\\", "/")
+    try:
+        p = Path(path)
+        if p.is_absolute():
+            return p.resolve().relative_to(root.resolve()).as_posix()
+    except Exception:  # noqa: BLE001
+        pass
+    if text.startswith("/"):
+        return text[1:]
+    return text

synapse/runtime/tool_output_eval.py

@@ -0,0 +1,118 @@
+"""Deterministic offline evaluation for tool-output transformers."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from synapse.tool_output.models import TransformContext
+from synapse.tool_output.pipeline import ToolOutputTransformPipeline
+
+
+@dataclass(frozen=True)
+class ToolOutputEvalCase:
+    case_id: str
+    content: str
+    tool_name: str = "execute"
+    query: str = ""
+    required: tuple[str, ...] = ()
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> ToolOutputEvalCase:
+        return cls(
+            case_id=str(value["id"]),
+            content=str(value["content"]),
+            tool_name=str(value.get("tool_name") or "execute"),
+            query=str(value.get("query") or ""),
+            required=tuple(str(item) for item in value.get("required", [])),
+        )
+
+
+@dataclass(frozen=True)
+class ToolOutputEvalResult:
+    case_id: str
+    content_type: str
+    transformer: str
+    original_bytes: int
+    visible_bytes: int
+    savings_ratio: float
+    required_total: int
+    required_retained: int
+
+    @property
+    def passed(self) -> bool:
+        return (
+            self.required_retained == self.required_total
+            and self.visible_bytes < self.original_bytes
+        )
+
+
+def load_cases(path: Path | str) -> list[ToolOutputEvalCase]:
+    value = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(value, list):
+        raise ValueError("tool-output eval fixture must be a JSON array")
+    return [ToolOutputEvalCase.from_dict(item) for item in value if isinstance(item, dict)]
+
+
+def evaluate_cases(
+    cases: list[ToolOutputEvalCase], *, pipeline: ToolOutputTransformPipeline | None = None
+) -> list[ToolOutputEvalResult]:
+    active = pipeline or ToolOutputTransformPipeline()
+    results: list[ToolOutputEvalResult] = []
+    for case in cases:
+        transformed = active.transform(
+            case.content,
+            TransformContext(tool_name=case.tool_name, status="success", query=case.query),
+        )
+        original_bytes = len(case.content.encode("utf-8"))
+        visible_bytes = len(transformed.content.encode("utf-8"))
+        retained = sum(item in transformed.content for item in case.required)
+        results.append(
+            ToolOutputEvalResult(
+                case_id=case.case_id,
+                content_type=transformed.content_type.value,
+                transformer=transformed.transformer,
+                original_bytes=original_bytes,
+                visible_bytes=visible_bytes,
+                savings_ratio=round(1 - visible_bytes / original_bytes, 4)
+                if original_bytes
+                else 0.0,
+                required_total=len(case.required),
+                required_retained=retained,
+            )
+        )
+    return results
+
+
+def summarize_results(results: list[ToolOutputEvalResult]) -> dict[str, Any]:
+    original = sum(item.original_bytes for item in results)
+    visible = sum(item.visible_bytes for item in results)
+    required_total = sum(item.required_total for item in results)
+    required_retained = sum(item.required_retained for item in results)
+    return {
+        "cases": len(results),
+        "passed": sum(item.passed for item in results),
+        "original_bytes": original,
+        "visible_bytes": visible,
+        "savings_ratio": round(1 - visible / original, 4) if original else 0.0,
+        "required_retention": (
+            round(required_retained / required_total, 4) if required_total else 1.0
+        ),
+        "results": [
+            {
+                "id": item.case_id,
+                "type": item.content_type,
+                "transformer": item.transformer,
+                "savings_ratio": item.savings_ratio,
+                "required_retention": (
+                    round(item.required_retained / item.required_total, 4)
+                    if item.required_total
+                    else 1.0
+                ),
+                "passed": item.passed,
+            }
+            for item in results
+        ],
+    }