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

synapse/runtime/backends.py

@@ -0,0 +1,458 @@
+"""Backend factory for the coding agent.
+
+No remote sandbox. Local host filesystem + shell only.
+
+``LocalShellBackend.execute`` uses ``text=True`` without an explicit encoding, which
+on Chinese Windows often decodes with GBK and crashes on UTF-8 tool output
+(``UnicodeDecodeError: 'gbk' codec can't decode ...``).
+
+This module subclasses ``LocalShellBackend`` and reimplements ``execute`` with:
+- configurable output encoding (default UTF-8 + replace)
+- default shell ``pwsh`` (PowerShell 7+), with cmd/bash/system overrides
+- UTF-8-friendly env defaults for child Python processes
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from deepagents.backends import LocalShellBackend
+from deepagents.backends.protocol import ExecuteResponse
+
+from synapse.runtime.execute_capture import capture_execute_output
+from synapse.runtime.tool_ignore import ToolIgnoreMatcher, relative_to_root
+from synapse.settings import Settings
+
+# Default shell for this project: pwsh on Windows, bash elsewhere.
+DEFAULT_SHELL_EXECUTABLE = "pwsh" if sys.platform == "win32" else "bash"
+
+
+def _basename(path_or_name: str) -> str:
+    return Path(path_or_name).name.lower()
+
+
+def resolve_shell_invocation(
+    command: str,
+    shell_executable: str | None,
+) -> tuple[str | list[str], bool, str | None]:
+    """Map configured shell name/path to subprocess ``(args, shell, executable)``.
+
+    Notes
+    -----
+    On Windows, ``shell=True`` + ``executable=pwsh`` is unreliable because Python
+    still builds a ``cmd /c ...`` command line. Known shells are therefore invoked
+    as argument lists with ``shell=False``.
+    """
+    raw = (shell_executable or DEFAULT_SHELL_EXECUTABLE).strip()
+    key = raw.lower()
+    base = _basename(raw)
+
+    # System / cmd: classic shell=True (Windows COMSPEC / Unix /bin/sh)
+    if key in {"", "system", "default", "cmd", "cmd.exe"} or base in {"cmd", "cmd.exe"}:
+        if base in {"cmd", "cmd.exe"} and key not in {"system", "default", ""}:
+            exe = raw if Path(raw).is_file() else shutil.which(raw) or shutil.which("cmd")
+            return command, True, exe
+        return command, True, None
+
+    # PowerShell 7+ / Windows PowerShell
+    if base in {"pwsh", "pwsh.exe", "powershell", "powershell.exe"}:
+        exe = raw if Path(raw).is_file() else shutil.which(raw)
+        if exe is None and base.startswith("pwsh"):
+            # Prefer pwsh; fall back to Windows PowerShell if Core is missing.
+            exe = shutil.which("pwsh") or shutil.which("powershell")
+        if exe is None:
+            if sys.platform != "win32":
+                # Non-Windows: pwsh not available, fall back to bash.
+                exe = shutil.which("bash") or shutil.which("sh") or "bash"
+                return [exe, "-lc", command], False, None
+            exe = raw
+        return [exe, "-NoProfile", "-NonInteractive", "-Command", command], False, None
+
+    # bash / sh
+    if base in {"bash", "bash.exe", "sh", "sh.exe"}:
+        exe = raw if Path(raw).is_file() else shutil.which(raw) or raw
+        return [exe, "-lc", command], False, None
+
+    # Unknown absolute/custom binary: treat as shell program with shell=True.
+    return command, True, raw
+
+
+def _kill_process_tree(proc: subprocess.Popen[Any] | None) -> None:
+    """Kill a process and all its children (best-effort on Windows).
+
+    On Windows, ``proc.kill()`` only terminates the direct process; child
+    processes survive and hold pipe handles open, which causes
+    ``communicate()`` to hang.  Use ``taskkill /T`` to terminate the whole
+    process tree, then drain pipes with a short timeout.
+    """
+    if proc is None:
+        return
+    try:
+        pid = proc.pid
+    except Exception:  # noqa: BLE001
+        return
+    if pid is None:
+        return
+    if os.name == "nt":
+        try:
+            subprocess.run(
+                ["taskkill", "/T", "/F", "/PID", str(pid)],
+                capture_output=True,
+                timeout=10,
+                check=False,
+            )
+        except Exception:  # noqa: BLE001
+            pass
+    else:
+        try:
+            proc.kill()
+        except Exception:  # noqa: BLE001
+            pass
+    # Drain pipes with a short timeout so we don't hang forever if child
+    # processes still hold them open.
+    try:
+        proc.communicate(timeout=3)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _timeout_msg(effective_timeout: int, per_call_timeout: int | None) -> str:
+    if per_call_timeout is not None:
+        return (
+            f"Error: Command timed out after {effective_timeout} seconds "
+            "(custom timeout). The command may be stuck or require more time."
+        )
+    return (
+        f"Error: Command timed out after {effective_timeout} seconds. "
+        "For long-running commands, re-run using the timeout parameter."
+    )
+
+
+class CodingLocalShellBackend(LocalShellBackend):
+    """Local shell backend with explicit encoding and configurable shell."""
+
+    def __init__(
+        self,
+        *args: Any,
+        shell_executable: str | None = DEFAULT_SHELL_EXECUTABLE,
+        shell_encoding: str = "utf-8",
+        shell_encoding_errors: str = "replace",
+        deny_paths: list[str] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._shell_executable = (shell_executable or DEFAULT_SHELL_EXECUTABLE).strip()
+        self._shell_encoding = shell_encoding or "utf-8"
+        self._shell_encoding_errors = shell_encoding_errors or "replace"
+
+        # Prefer UTF-8 for Python children; does not fix every native CLI, but helps.
+        self._env.setdefault("PYTHONUTF8", "1")
+        self._env.setdefault("PYTHONIOENCODING", "utf-8")
+
+        if deny_paths:
+            matcher = ToolIgnoreMatcher.from_patterns(deny_paths)
+            self._tool_ignore_dedicated = True
+        else:
+            try:
+                root = Path(self.cwd).resolve()
+                matcher = ToolIgnoreMatcher.from_workspace(root)
+            except Exception:  # noqa: BLE001
+                matcher = ToolIgnoreMatcher([])
+            self._tool_ignore_dedicated = False
+        self._tool_ignore: ToolIgnoreMatcher = matcher
+
+    def _ripgrep_search(
+        self,
+        pattern: str,
+        base_full: Path,
+        include_glob: str | None,
+    ) -> dict[str, list[tuple[int, str]]] | None:
+        """UTF-8-safe ripgrep search (avoids Windows GBK decode crashes).
+
+        Upstream ``FilesystemBackend._ripgrep_search`` uses ``text=True`` without
+        ``encoding``, which on Chinese Windows can raise / leave ``stdout=None``
+        and then crash on ``stdout.splitlines()``.
+        """
+        import json
+
+        import deepagents.backends.filesystem as fs
+
+        rg_path = fs._resolve_ripgrep_path()
+        if rg_path is None:
+            return None
+
+        cmd = [rg_path, "--json", "-F"]
+        if include_glob:
+            cmd.extend(["--glob", include_glob])
+
+        rg_cwd: str | None = None
+        if base_full.is_dir():
+            cmd.extend(["--", pattern, "."])
+            rg_cwd = str(base_full)
+        else:
+            cmd.extend(["--", pattern, str(base_full)])
+
+        try:
+            proc = subprocess.run(  # noqa: S603
+                cmd,
+                capture_output=True,
+                text=True,
+                encoding=self._shell_encoding,
+                errors=self._shell_encoding_errors,
+                timeout=fs.DEFAULT_GREP_TIMEOUT,
+                check=False,
+                cwd=rg_cwd,
+            )
+        except subprocess.TimeoutExpired:
+            fs.logger.warning(
+                "ripgrep timed out after %ds; using Python grep fallback",
+                fs.DEFAULT_GREP_TIMEOUT,
+            )
+            return None
+        except (FileNotFoundError, PermissionError, NotADirectoryError, OSError) as e:
+            fs.logger.warning(
+                "ripgrep subprocess failed (%s: %s); using Python grep fallback",
+                type(e).__name__,
+                e,
+            )
+            try:
+                fs._resolve_ripgrep_path.cache_clear()
+            except Exception:  # noqa: BLE001
+                pass
+            return None
+        except UnicodeDecodeError as e:
+            # Should be unreachable with errors=replace; keep fallback safety.
+            fs.logger.warning(
+                "ripgrep decode failed (%s); using Python grep fallback", e
+            )
+            return None
+
+        if proc.returncode not in (0, 1):
+            stderr = (proc.stderr or "").strip()[:500]
+            fs.logger.warning(
+                "ripgrep exited %d (stderr=%r); using Python grep fallback",
+                proc.returncode,
+                stderr,
+            )
+            return None
+
+        stdout = proc.stdout or ""
+        results: dict[str, list[tuple[int, str]]] = {}
+        try:
+            base_resolved = base_full.resolve()
+        except OSError:
+            base_resolved = base_full
+
+        for line in stdout.splitlines():
+            try:
+                data = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            data_type = data.get("type")
+            if data_type == "error":
+                continue
+            if data_type != "match":
+                continue
+            pdata = data.get("data", {}) or {}
+            ftext = (pdata.get("path") or {}).get("text")
+            if not ftext:
+                continue
+            raw = Path(ftext)
+            p = raw if raw.is_absolute() else (base_full / raw)
+            try:
+                p.resolve().relative_to(base_resolved)
+            except (ValueError, OSError):
+                continue
+            if self.virtual_mode:
+                try:
+                    virt = self._to_virtual_path(p)
+                except (ValueError, OSError, RuntimeError):
+                    continue
+            else:
+                virt = str(p)
+            ln = pdata.get("line_number")
+            lt = (pdata.get("lines") or {}).get("text", "").rstrip("\n")
+            if ln is None:
+                continue
+            results.setdefault(virt, []).append((int(ln), lt))
+
+        return results
+
+    # --- filesystem tool overrides: respect gitignore / deny paths ---
+
+    def grep(
+        self,
+        pattern: str,
+        path: str | None = None,
+        glob: str | None = None,
+    ) -> Any:
+        result = super().grep(pattern, path=path, glob=glob)
+        if not self._tool_ignore.has_rules or not getattr(result, "matches", None):
+            return result
+        root = Path(self.cwd).resolve()
+        kept = [
+            m
+            for m in result.matches
+            if not self._tool_ignore.is_ignored(
+                relative_to_root(m["path"], root)
+            )
+        ]
+        result.matches = kept
+        return result
+
+    def glob(self, pattern: str, path: str | None = None) -> Any:
+        result = super().glob(pattern, path=path)
+        if not self._tool_ignore.has_rules or not getattr(result, "matches", None):
+            return result
+        root = Path(self.cwd).resolve()
+        kept = [
+            f
+            for f in result.matches
+            if not self._tool_ignore.is_ignored(
+                relative_to_root(f["path"], root)
+            )
+        ]
+        result.matches = kept
+        return result
+
+    def execute(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+    ) -> ExecuteResponse:
+        """Run a host shell command with safe text decoding.
+
+        Same contract as ``LocalShellBackend.execute``, but never relies on the
+        process locale (e.g. GBK) for stdout/stderr decoding.
+        """
+        if not command or not isinstance(command, str):
+            return ExecuteResponse(
+                output="Error: Command must be a non-empty string.",
+                exit_code=1,
+                truncated=False,
+            )
+
+        effective_timeout = timeout if timeout is not None else self._default_timeout
+        if effective_timeout <= 0:
+            msg = f"timeout must be positive, got {effective_timeout}"
+            raise ValueError(msg)
+
+        args, use_shell, executable = resolve_shell_invocation(
+            command, self._shell_executable
+        )
+
+        run_kwargs: dict[str, Any] = {
+            "args": args,
+            "shell": use_shell,
+            "stdout": subprocess.PIPE,
+            "stderr": subprocess.PIPE,
+            "stdin": subprocess.DEVNULL,
+            "text": True,
+            "encoding": self._shell_encoding,
+            "errors": self._shell_encoding_errors,
+            "env": self._env,
+            "cwd": str(self.cwd),
+        }
+        if executable:
+            run_kwargs["executable"] = executable
+
+        proc = None
+        try:
+            # Use Popen directly instead of subprocess.run because run()
+            # calls communicate() a second time after TimeoutExpired, which hangs
+            # on Windows when the shell spawns child processes that survive the
+            # kill and hold pipe handles open.
+            proc = subprocess.Popen(**run_kwargs)  # noqa: S602
+            stdout, stderr = proc.communicate(timeout=effective_timeout)
+            returncode = proc.returncode
+
+        except subprocess.TimeoutExpired:
+            _kill_process_tree(proc)
+            msg = _timeout_msg(effective_timeout, timeout)
+            return ExecuteResponse(
+                output=msg,
+                exit_code=124,
+                truncated=False,
+            )
+        except Exception as e:  # noqa: BLE001
+            if proc is not None:
+                try:
+                    proc.kill()
+                except Exception:  # noqa: BLE001
+                    pass
+            return ExecuteResponse(
+                output=f"Error executing command ({type(e).__name__}): {e}",
+                exit_code=1,
+                truncated=False,
+            )
+
+        output_parts: list[str] = []
+        if stdout:
+            output_parts.append(stdout)
+        if stderr:
+            stderr_lines = stderr.strip().split("\n")
+            output_parts.extend(f"[stderr] {line}" for line in stderr_lines)
+
+        full_output = "\n".join(output_parts) if output_parts else "<no output>"
+
+        truncated = False
+        output = full_output
+        if len(output) > self._max_output_bytes:
+            output = output[: self._max_output_bytes]
+            output += f"\n\n... Output truncated at {self._max_output_bytes} bytes."
+            truncated = True
+
+        if returncode != 0:
+            full_output = f"{full_output.rstrip()}\n\nExit code: {returncode}"
+            output = f"{output.rstrip()}\n\nExit code: {returncode}"
+
+        capture_execute_output(
+            full_output=full_output,
+            displayed_output=output,
+            truncated=truncated,
+        )
+        return ExecuteResponse(
+            output=output,
+            exit_code=returncode,
+            truncated=truncated,
+        )
+
+
+def build_backend(settings: Settings) -> CodingLocalShellBackend:
+    """Create a coding shell backend rooted at the workspace.
+
+    Notes
+    -----
+    - No sandbox isolation (by design for this project).
+    - ``inherit_env=True`` so host tools (python/uv/git/node) remain available.
+    - ``virtual_mode=True`` improves path semantics for file tools (shell is still unrestricted).
+    - Default shell is ``pwsh``; override with ``SHELL_EXECUTABLE`` (cmd/bash/path).
+    - Shell output is decoded with ``shell_encoding`` (default UTF-8) to avoid GBK crashes.
+    """
+    root = Path(settings.workspace).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+
+    executable = settings.shell_executable
+    if executable is not None:
+        executable = executable.strip() or None
+    if not executable:
+        executable = DEFAULT_SHELL_EXECUTABLE
+
+    return CodingLocalShellBackend(
+        root_dir=root,
+        virtual_mode=settings.virtual_mode,
+        timeout=settings.shell_timeout,
+        max_output_bytes=settings.max_output_bytes,
+        inherit_env=settings.inherit_env,
+        env=None,
+        shell_executable=executable,
+        shell_encoding=settings.shell_encoding,
+        shell_encoding_errors=settings.shell_encoding_errors,
+        deny_paths=settings.deny_fs_paths or None,
+    )

synapse/runtime/context_compact.py

@@ -0,0 +1,249 @@
+"""Context compaction helpers (deepagents SummarizationToolMiddleware).
+
+create_deep_agent already installs automatic SummarizationMiddleware.
+This module adds the manual ``compact_conversation`` tool layer and product
+helpers for /compact + observability.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_compact_tool_middleware(model: Any, backend: Any) -> Any:
+    """Return SummarizationToolMiddleware (manual compact_conversation tool)."""
+    from deepagents.middleware.summarization import create_summarization_tool_middleware
+
+    return create_summarization_tool_middleware(model, backend)
+
+
+def extract_summarization_event(state: Any) -> dict[str, Any] | None:
+    """Best-effort pull of ``_summarization_event`` from graph state/update."""
+    if state is None:
+        return None
+    if isinstance(state, dict):
+        event = state.get("_summarization_event")
+        if isinstance(event, dict):
+            return event
+        values = state.get("values")
+        if isinstance(values, dict):
+            event = values.get("_summarization_event")
+            if isinstance(event, dict):
+                return event
+        return None
+    values = getattr(state, "values", None)
+    if isinstance(values, dict):
+        event = values.get("_summarization_event")
+        if isinstance(event, dict):
+            return event
+    return None
+
+
+def format_summarization_event(event: dict[str, Any] | None) -> str | None:
+    """One-line UI notice for a compaction event."""
+    if not event:
+        return None
+    # Event shape varies; keep display defensive.
+    cutoff = event.get("cutoff") or event.get("cutoff_index")
+    path = event.get("file_path") or event.get("path") or event.get("history_path")
+    summary = event.get("summary")
+    bits: list[str] = ["context compacted"]
+    if cutoff is not None:
+        bits.append(f"cutoff={cutoff}")
+    if path:
+        bits.append(f"offload={path}")
+    if isinstance(summary, str) and summary.strip():
+        one = " ".join(summary.strip().split())
+        if len(one) > 80:
+            one = one[:79] + "…"
+        bits.append(f"summary={one}")
+    return " | ".join(bits)
+
+
+def force_compact_via_agent(
+    agent: Any,
+    *,
+    thread_id: str,
+    config: dict[str, Any] | None = None,
+) -> tuple[bool, list[str]]:
+    """Ask the agent to call ``compact_conversation`` now.
+
+    Returns (ok, status_lines). The tool may refuse when under its eligibility
+    gate (~50% of auto-summarization trigger).
+    """
+    if agent is None or not thread_id:
+        return False, ["compact failed: missing agent/thread_id"]
+
+    run_config = dict(config or {})
+    cfg = dict(run_config.get("configurable") or {})
+    cfg["thread_id"] = thread_id
+    run_config["configurable"] = cfg
+
+    prompt = (
+        "System instruction for this turn only: call the `compact_conversation` "
+        "tool immediately to compact the conversation context. Do not call other "
+        "tools. After the tool returns, reply with one short status line only "
+        "(success, refused/not eligible, or error)."
+    )
+    payload = {"messages": [{"role": "user", "content": prompt}]}
+    try:
+        ainvoke = getattr(agent, "ainvoke", None)
+        runtime = getattr(agent, "_coding_async_runtime", None)
+        if callable(ainvoke) and runtime is not None:
+            result = runtime.run(ainvoke(payload, run_config))
+        else:
+            result = agent.invoke(payload, run_config)
+    except Exception as exc:  # noqa: BLE001
+        return False, [f"compact failed: {exc}"]
+
+    lines: list[str] = []
+    event = extract_summarization_event(result)
+    note = format_summarization_event(event)
+    if note:
+        lines.append(note)
+
+    # Pull last AI / tool text for user feedback.
+    messages = []
+    if isinstance(result, dict):
+        messages = list(result.get("messages") or [])
+    text_bits: list[str] = []
+    for msg in reversed(messages[-8:]):
+        role = getattr(msg, "type", None) or getattr(msg, "role", None) or ""
+        name = getattr(msg, "name", None) or ""
+        content = getattr(msg, "content", None)
+        if content is None:
+            continue
+        body = content if isinstance(content, str) else str(content)
+        body = body.strip()
+        if not body:
+            continue
+        if str(role).lower() in {"tool", "toolmessage"} or name == "compact_conversation":
+            text_bits.append(body[:300])
+            break
+        if str(role).lower() in {"ai", "assistant"}:
+            text_bits.append(body[:300])
+            break
+    if text_bits:
+        lines.append(text_bits[0])
+    if not lines:
+        lines.append("compact requested (no status detail)")
+    ok = any(
+        "compact" in (ln or "").casefold()
+        or "summar" in (ln or "").casefold()
+        or "nothing to compact" in (ln or "").casefold()
+        or "not eligible" in (ln or "").casefold()
+        or "success" in (ln or "").casefold()
+        for ln in lines
+    )
+    return True if lines else ok, lines
+
+
+def context_status_lines(agent: Any, thread_id: str) -> list[str]:
+    """Report message count + last summarization event for current thread."""
+    lines: list[str] = [f"thread_id={thread_id}"]
+    if agent is None:
+        return lines + ["agent: none"]
+    get_state = getattr(agent, "get_state", None)
+    if not callable(get_state):
+        return lines + ["state: unavailable"]
+    try:
+        state = get_state({"configurable": {"thread_id": thread_id}})
+    except Exception as exc:  # noqa: BLE001
+        return lines + [f"state error: {exc}"]
+    values = getattr(state, "values", None) or {}
+    messages = values.get("messages") if isinstance(values, dict) else None
+    n = len(messages or [])
+    lines.append(f"messages={n}")
+    event = extract_summarization_event(state)
+    note = format_summarization_event(event)
+    if note:
+        lines.append(note)
+    else:
+        lines.append("summarization: none yet (auto middleware still active)")
+    return lines
+
+
+# --- UI filters: hide SESSION INTENT / SUMMARY compaction text from timeline ---
+
+_SUMMARY_MARKERS = (
+    "## SESSION INTENT",
+    "SESSION INTENT",
+    "## SUMMARY",
+)
+_WRAPPER_PREFIXES = (
+    "Here is a summary of the conversation to date:",
+    "You are in the middle of a conversation that has been summarized",
+)
+
+
+def is_lc_summarization_message(msg: Any) -> bool:
+    """True when message was tagged as summarization middleware output."""
+    ak = getattr(msg, "additional_kwargs", None)
+    if isinstance(ak, dict) and ak.get("lc_source") == "summarization":
+        return True
+    if isinstance(msg, dict):
+        ak2 = msg.get("additional_kwargs") or {}
+        if isinstance(ak2, dict) and ak2.get("lc_source") == "summarization":
+            return True
+        md = msg.get("response_metadata") or msg.get("metadata") or {}
+        if isinstance(md, dict) and md.get("lc_source") == "summarization":
+            return True
+    md2 = getattr(msg, "response_metadata", None)
+    if isinstance(md2, dict) and md2.get("lc_source") == "summarization":
+        return True
+    return False
+
+
+def is_stream_meta_summarization(meta: Any) -> bool:
+    """True when LangGraph messages-stream meta marks a summarization invoke."""
+    if not isinstance(meta, dict):
+        return False
+    for key in ("lc_source", "source"):
+        if meta.get(key) == "summarization":
+            return True
+    nested = meta.get("metadata") or meta.get("ls_metadata") or {}
+    if isinstance(nested, dict) and nested.get("lc_source") == "summarization":
+        return True
+    tags = meta.get("tags") or (
+        nested.get("tags") if isinstance(nested, dict) else None
+    )
+    if isinstance(tags, (list, tuple, set)):
+        if "summarization" in tags or "lc:summarization" in tags:
+            return True
+    return False
+
+
+def is_context_compact_text(text: str | None) -> bool:
+    """Heuristic: body looks like a context-compaction summary, not a user reply."""
+    body = (text or "").strip()
+    if not body:
+        return False
+    head = body[:800]
+    for p in _WRAPPER_PREFIXES:
+        if body.startswith(p) or p in head:
+            if any(
+                m in body
+                for m in ("SESSION INTENT", "SUMMARY", "ARTIFACTS", "NEXT STEPS")
+            ):
+                return True
+            if body.startswith(p):
+                return True
+
+    # DEFAULT_SUMMARY_PROMPT sections (with or without markdown ##).
+    has_intent = (
+        "## SESSION INTENT" in body
+        or body.lstrip("# ").startswith("SESSION INTENT")
+        or "\nSESSION INTENT\n" in f"\n{body}\n"
+    )
+    has_summary = (
+        "## SUMMARY" in body
+        or "\n## SUMMARY" in body
+        or "\nSUMMARY\n" in f"\n{body}\n"
+        or "\n# SUMMARY\n" in f"\n{body}\n"
+    )
+    if has_intent and has_summary:
+        return True
+    if has_intent and ("ARTIFACTS" in body or "NEXT STEPS" in body):
+        return True
+    return False
+