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

synapse/runtime/pathing.py

@@ -0,0 +1,146 @@
+"""Workspace path helpers for virtual-mode file tools."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+# Common filesystem tool argument keys used by deepagents / our tools.
+_PATH_KEYS = (
+    "path",
+    "file_path",
+    "filename",
+    "file",
+    "target",
+    "target_file",
+    "source",
+    "src",
+    "dst",
+    "destination",
+    "directory",
+    "dir",
+    "glob",
+    "pattern_path",
+)
+
+
+_WIN_DRIVE = re.compile(r"^[A-Za-z]:[\\/]")
+_WIN_EXTENDED_PREFIX = re.compile(r"^(?:\\\\\?\\|//\?/)", re.IGNORECASE)
+
+
+def is_windows_absolute(path: str) -> bool:
+    s = _strip_windows_extended_prefix(str(path))
+    return bool(_WIN_DRIVE.match(s)) or s.startswith("\\\\")
+
+
+def _strip_windows_extended_prefix(path: str) -> str:
+    r"""Convert Windows ``\\?\`` paths to their normal drive / UNC form."""
+    s = str(path).strip()
+    if not _WIN_EXTENDED_PREFIX.match(s):
+        return s
+    remainder = _WIN_EXTENDED_PREFIX.sub("", s, count=1)
+    if remainder.upper().startswith("UNC\\"):
+        return "\\\\" + remainder[4:]
+    return remainder
+
+
+def is_virtual_path(path: str) -> bool:
+    """True for POSIX-style virtual paths like ``/src/a.py`` (not ``C:/...``)."""
+    s = str(path).strip()
+    if not s.startswith("/"):
+        return False
+    # Reject /C:/... style mistakes
+    if len(s) >= 3 and s[2] == ":" and s[1].isalpha():
+        return False
+    return True
+
+
+def to_virtual_path(path: str | os.PathLike[str] | None, workspace: Path) -> str | None:
+    """Map host paths under workspace to virtual paths starting with ``/``.
+
+    Examples (workspace = F:/project/repo):
+    - ``F:/project/repo/src/a.py`` -> ``/src/a.py``
+    - ``src/a.py`` -> ``/src/a.py``
+    - ``/src/a.py`` -> ``/src/a.py`` (unchanged)
+    - ``/`` -> ``/``
+    """
+    if path is None:
+        return None
+    s = _strip_windows_extended_prefix(str(path))
+    if not s:
+        return s
+
+    if is_virtual_path(s):
+        return s if s.startswith("/") else f"/{s}"
+
+    root = Path(workspace).resolve()
+
+    # Windows absolute / UNC / host absolute under workspace root
+    if is_windows_absolute(s) or os.path.isabs(s):
+        try:
+            cand = Path(s)
+            # resolve() may fail for non-existing; still ok for relative_to with abs paths
+            try:
+                cand_res = cand.resolve()
+            except OSError:
+                cand_res = cand
+            try:
+                rel = cand_res.relative_to(root)
+                rel_s = rel.as_posix()
+                return "/" if rel_s in {"", "."} else f"/{rel_s}"
+            except ValueError:
+                # Outside workspace: leave as-is
+                return s
+        except Exception:  # noqa: BLE001
+            return s
+
+    # Relative host path -> virtual
+    rel = s.replace("\\", "/").lstrip("./")
+    return "/" + rel if rel else "/"
+
+
+def rewrite_tool_args_paths(args: dict[str, Any], workspace: Path) -> dict[str, Any]:
+    """Return a shallow-copied args dict with path-like fields virtualized."""
+    out = dict(args)
+    for key in _PATH_KEYS:
+        if key not in out or out[key] is None:
+            continue
+        val = out[key]
+        if isinstance(val, str):
+            out[key] = to_virtual_path(val, workspace)
+        elif isinstance(val, list):
+            out[key] = [
+                to_virtual_path(v, workspace) if isinstance(v, str) else v for v in val
+            ]
+    return out
+
+
+def summarize_tool_result(content: Any, *, limit: int = 80) -> str:
+    """Compact tool-result status for CLI (no file body dump)."""
+    try:
+        if content is None:
+            text = ""
+        elif isinstance(content, str):
+            text = content
+        elif isinstance(content, (bytes, bytearray)):
+            text = bytes(content).decode("utf-8", errors="replace")
+        else:
+            text = str(content)
+    except Exception:  # noqa: BLE001
+        text = ""
+    stripped = text.strip() if isinstance(text, str) else ""
+    if not stripped:
+        return "ok"
+    lower = stripped.lower()
+    if lower.startswith("error") or "not supported" in lower or "traceback" in lower:
+        # Keep short error reason only
+        one = stripped.replace("\n", " ")
+        if len(one) > limit:
+            one = one[: limit - 3] + "..."
+        return one
+    # Success: size only, never dump body.
+    n = len(stripped)
+    lines = stripped.count("\n") + 1
+    return f"ok ({n} chars, {lines} lines)"

synapse/runtime/safety.py

@@ -0,0 +1,184 @@
+"""Command safety helpers and named safety profiles.
+
+Default product behavior: **no approval gate**, auto-pass (dev-autopass).
+Profiles make the product posture explicit:
+
+- dev-autopass: full tools, no HITL (default)
+- dev-approve: HITL on execute/write/edit
+- readonly: exclude write/execute tools via harness
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Literal
+
+SafetyProfileName = Literal["dev-autopass", "dev-approve", "readonly"]
+
+# Patterns considered dangerous on developer machines.
+DANGEROUS_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r)\b", re.I),
+    re.compile(r"\brm\s+-rf\s+/", re.I),
+    re.compile(r"\b(del|rmdir)\s+/s\b", re.I),
+    re.compile(r"\bformat\s+[a-z]:", re.I),
+    re.compile(r"\bmkfs\b", re.I),
+    re.compile(r"\bdd\s+if=", re.I),
+    re.compile(r":\s*\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;", re.I),  # fork bomb
+    re.compile(r"\bshutdown\b", re.I),
+    re.compile(r"\breboot\b", re.I),
+    re.compile(r"\bgit\s+push\s+.*--force\b", re.I),
+    re.compile(r"\bgit\s+reset\s+--hard\b", re.I),
+    re.compile(r"\bgit\s+clean\s+-fdx\b", re.I),
+    re.compile(r">\s*/dev/sd[a-z]", re.I),
+    re.compile(r"\bRemove-Item\b.*-Recurse\b.*-Force\b", re.I),
+]
+
+
+@dataclass(frozen=True)
+class SafetyVerdict:
+    allowed: bool
+    reason: str | None = None
+    matched_pattern: str | None = None
+
+
+@dataclass(frozen=True)
+class SafetyProfile:
+    """Named product posture for approval / readonly / blacklist."""
+
+    name: SafetyProfileName
+    require_approval: bool
+    readonly: bool
+    auto_approve: bool
+    enable_command_blacklist: bool
+    description: str
+
+
+SAFETY_PROFILES: dict[str, SafetyProfile] = {
+    "dev-autopass": SafetyProfile(
+        name="dev-autopass",
+        require_approval=False,
+        readonly=False,
+        auto_approve=True,
+        enable_command_blacklist=True,
+        description="Local dev default: full tools, no HITL, blacklist advisory.",
+    ),
+    "dev-approve": SafetyProfile(
+        name="dev-approve",
+        require_approval=True,
+        readonly=False,
+        auto_approve=False,
+        enable_command_blacklist=True,
+        description="Local dev with HITL on execute/write/edit.",
+    ),
+    "readonly": SafetyProfile(
+        name="readonly",
+        require_approval=False,
+        readonly=True,
+        auto_approve=True,
+        enable_command_blacklist=True,
+        description="Read-only: exclude write_file/edit_file/execute via harness.",
+    ),
+}
+
+
+def get_safety_profile(name: str | None) -> SafetyProfile:
+    key = (name or "dev-autopass").strip().casefold()
+    if key in SAFETY_PROFILES:
+        return SAFETY_PROFILES[key]
+    # aliases
+    if key in {"approve", "hitl", "dev_approve"}:
+        return SAFETY_PROFILES["dev-approve"]
+    if key in {"ro", "read-only", "read_only"}:
+        return SAFETY_PROFILES["readonly"]
+    if key in {"auto", "autopass", "dev_autopass", "off"}:
+        return SAFETY_PROFILES["dev-autopass"]
+    return SAFETY_PROFILES["dev-autopass"]
+
+
+def apply_safety_to_settings(settings: Any, profile: SafetyProfile | str) -> list[str]:
+    """Mutate settings fields from a named profile. Returns change notes."""
+    prof = get_safety_profile(profile if isinstance(profile, str) else profile.name)
+    notes: list[str] = []
+    mapping = {
+        "require_approval": prof.require_approval,
+        "auto_approve": prof.auto_approve,
+        "readonly": prof.readonly,
+        "enable_command_blacklist": prof.enable_command_blacklist,
+        "safety_profile": prof.name,
+    }
+    for key, val in mapping.items():
+        if not hasattr(settings, key):
+            continue
+        old = getattr(settings, key)
+        if old != val:
+            try:
+                setattr(settings, key, val)
+            except Exception:  # noqa: BLE001
+                # pydantic Settings may be frozen-ish; try model_copy pattern
+                pass
+            else:
+                notes.append(f"{key}: {old!r} -> {val!r}")
+    # pydantic BaseSettings often allows setattr on instance
+    if hasattr(settings, "model_copy") and not notes:
+        # try replace via object.__setattr__ for model fields
+        for key, val in mapping.items():
+            if hasattr(settings, key) and getattr(settings, key) != val:
+                object.__setattr__(settings, key, val)
+                notes.append(f"{key} -> {val!r}")
+    if not notes:
+        notes.append(f"profile already active: {prof.name}")
+    else:
+        notes.insert(0, f"safety profile: {prof.name}")
+        notes.append(prof.description)
+    return notes
+
+
+def check_command(command: str, *, enable_blacklist: bool = True) -> SafetyVerdict:
+    """Return whether a shell command is considered safe enough to run."""
+    if not enable_blacklist:
+        return SafetyVerdict(allowed=True)
+
+    text = command.strip()
+    if not text:
+        return SafetyVerdict(allowed=False, reason="empty command")
+
+    for pattern in DANGEROUS_PATTERNS:
+        if pattern.search(text):
+            return SafetyVerdict(
+                allowed=False,
+                reason="command matches dangerous pattern",
+                matched_pattern=pattern.pattern,
+            )
+    return SafetyVerdict(allowed=True)
+
+
+def build_interrupt_on(*, require_approval: bool) -> dict[str, bool] | None:
+    """Map product settings to deepagents `interrupt_on`.
+
+    Default: require_approval=False => no interrupt middleware.
+    """
+    if not require_approval:
+        return None
+    return {
+        "execute": True,
+        "write_file": True,
+        "edit_file": True,
+    }
+
+
+def format_safety_status(settings: Any) -> list[str]:
+    profile = getattr(settings, "safety_profile", None) or (
+        "dev-approve"
+        if getattr(settings, "require_approval", False)
+        else ("readonly" if getattr(settings, "readonly", False) else "dev-autopass")
+    )
+    return [
+        f"safety profile: {profile}",
+        f"  require_approval: {getattr(settings, 'require_approval', False)}",
+        f"  auto_approve: {getattr(settings, 'auto_approve', True)}",
+        f"  readonly: {getattr(settings, 'readonly', False)}",
+        f"  command_blacklist: {getattr(settings, 'enable_command_blacklist', True)}",
+        "profiles: dev-autopass | dev-approve | readonly",
+        "switch: /safety <profile>   (rebuilds agent)",
+    ]

synapse/runtime/steer.py

@@ -0,0 +1,240 @@
+"""Mid-run user guidance queue (type-B HITL / steer).
+
+While the agent loop is busy, the user can enqueue short instructions.
+They are drained at the next model step (after the current tool batch) and
+injected as HumanMessages so the LLM can change direction without Esc-cancel.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import deque
+from collections.abc import Callable
+from typing import Any
+
+STEER_PREFIX = "[Mid-run user guidance]"
+# UI-only label used for silent follow-up turns (should never paint in transcript).
+STEER_FOLLOWUP_PREFIX = "[steer follow-up]"
+
+SteerListener = Callable[[list[str]], None]
+
+
+def is_steer_message(msg: Any = None, *, text: str | None = None) -> bool:
+    """True if a LangChain message / plain text is mid-run guidance (model-only).
+
+    Used to keep steer chrome out of the transcript and status bar.
+    """
+    if text is None and msg is not None:
+        # Prefer kwargs flag set by middleware.
+        ak = getattr(msg, "additional_kwargs", None)
+        if isinstance(ak, dict) and ak.get("coding_steer"):
+            return True
+        if isinstance(msg, dict):
+            ak2 = msg.get("additional_kwargs") or {}
+            if isinstance(ak2, dict) and ak2.get("coding_steer"):
+                return True
+            content = msg.get("content")
+        else:
+            content = getattr(msg, "content", None)
+        if isinstance(content, str):
+            text = content
+        elif isinstance(content, list):
+            parts: list[str] = []
+            for block in content:
+                if isinstance(block, str):
+                    parts.append(block)
+                elif isinstance(block, dict) and block.get("text"):
+                    parts.append(str(block.get("text")))
+            text = "\n".join(parts)
+        else:
+            text = str(content or "")
+    body = (text or "").strip()
+    if not body:
+        return False
+    if body.startswith(STEER_PREFIX) or STEER_PREFIX in body[:80]:
+        return True
+    if body.startswith(STEER_FOLLOWUP_PREFIX):
+        return True
+    return False
+
+
+class SteerQueue:
+    """Thread-safe FIFO of mid-run guidance strings."""
+
+    def __init__(self) -> None:
+        self._items: deque[str] = deque()
+        self._lock = threading.Lock()
+        self._listeners: list[SteerListener] = []
+        self._pending_notifications: deque[
+            tuple[list[str], list[SteerListener]]
+        ] = deque()
+        self._notifying = False
+
+    def add_listener(self, callback: SteerListener) -> None:
+        """Register a callback invoked with a snapshot after each change."""
+        if callback is None:
+            return
+        with self._lock:
+            if callback not in self._listeners:
+                self._listeners.append(callback)
+
+    def remove_listener(self, callback: SteerListener) -> None:
+        with self._lock:
+            self._listeners = [cb for cb in self._listeners if cb is not callback]
+
+    def _snapshot(self) -> list[str]:
+        return list(self._items)
+
+    def _enqueue_notification_unlocked(self) -> bool:
+        self._pending_notifications.append(
+            (self._snapshot(), list(self._listeners))
+        )
+        if self._notifying:
+            return False
+        self._notifying = True
+        return True
+
+    def _dispatch_notifications(self) -> None:
+        # Preserve mutation order without invoking application code under _lock.
+        while True:
+            with self._lock:
+                if not self._pending_notifications:
+                    self._notifying = False
+                    return
+                snap, listeners = self._pending_notifications.popleft()
+            for callback in listeners:
+                try:
+                    callback(snap)
+                except Exception:  # noqa: BLE001
+                    pass
+
+    def push(self, text: str) -> int:
+        """Enqueue guidance. Returns pending count after push (0 if empty text)."""
+        body = (text or "").strip()
+        if not body:
+            return 0
+        with self._lock:
+            self._items.append(body)
+            n = len(self._items)
+            should_dispatch = self._enqueue_notification_unlocked()
+        if should_dispatch:
+            self._dispatch_notifications()
+        return n
+
+    def drain(self) -> list[str]:
+        """Pop all pending guidance (order preserved)."""
+        with self._lock:
+            items = list(self._items)
+            self._items.clear()
+            should_dispatch = bool(items) and self._enqueue_notification_unlocked()
+        if should_dispatch:
+            self._dispatch_notifications()
+        return items
+
+    def peek_count(self) -> int:
+        with self._lock:
+            return len(self._items)
+
+    def peek_items(self) -> list[str]:
+        """Return a copy of pending items (order preserved)."""
+        with self._lock:
+            return self._snapshot()
+
+    def remove_at(self, index: int) -> str | None:
+        """Remove one item by index. Returns removed text or None."""
+        with self._lock:
+            if index < 0 or index >= len(self._items):
+                return None
+            # deque has no pop(index); rebuild
+            items = list(self._items)
+            removed = items.pop(index)
+            self._items = deque(items)
+            should_dispatch = self._enqueue_notification_unlocked()
+        if should_dispatch:
+            self._dispatch_notifications()
+        return removed
+
+    def clear(self) -> list[str]:
+        """Drop all pending items. Returns the previous list."""
+        with self._lock:
+            if not self._items:
+                return []
+            items = list(self._items)
+            self._items.clear()
+            should_dispatch = self._enqueue_notification_unlocked()
+        if should_dispatch:
+            self._dispatch_notifications()
+        return items
+
+
+def format_steer_message(items: list[str]) -> str:
+    """Render queued guidance for the model."""
+    cleaned = [str(x).strip() for x in items if str(x).strip()]
+    if not cleaned:
+        return ""
+    header = (
+        f"{STEER_PREFIX}\n"
+        "The user is steering the current task. Incorporate the guidance below "
+        "into your next actions. Prefer adjusting the plan over restarting "
+        "unrelated work.\n"
+    )
+    if len(cleaned) == 1:
+        return f"{header}\n{cleaned[0]}"
+    body = "\n".join(f"{i}. {line}" for i, line in enumerate(cleaned, 1))
+    return f"{header}\nMultiple notes (in order):\n{body}"
+
+
+def format_steer_panel(items: list[str], *, max_preview: int = 72) -> str:
+    """Render a multi-line panel for TUI (human-facing)."""
+    cleaned = [str(x).strip() for x in items if str(x).strip()]
+    if not cleaned:
+        return ""
+    n = len(cleaned)
+    lines = [f"  ▸ steer queue · {n} pending · applies before next model step"]
+    for i, text in enumerate(cleaned, 1):
+        one = " ".join(text.split())
+        if len(one) > max_preview:
+            one = one[: max(0, max_preview - 1)] + "…"
+        lines.append(f"    {i}. {one}")
+    return "\n".join(lines)
+
+
+def build_steer_middleware(queue: SteerQueue):
+    """Inject drained queue messages before each model call (post-tool boundary)."""
+    from langchain.agents.middleware import AgentMiddleware, AgentState
+    from langchain_core.messages import HumanMessage
+
+    def _logic(state: Any, runtime: Any) -> dict[str, Any] | None:  # noqa: ARG001
+        items = queue.drain()
+        if not items:
+            return None
+        content = format_steer_message(items)
+        if not content:
+            return None
+        msg = HumanMessage(
+            content=content,
+            additional_kwargs={"coding_steer": True, "steer_count": len(items)},
+        )
+        return {"messages": [msg]}
+
+    def before_model(self, state: Any, runtime: Any) -> dict[str, Any] | None:  # noqa: ANN001
+        return _logic(state, runtime)
+
+    async def abefore_model(self, state: Any, runtime: Any) -> dict[str, Any] | None:  # noqa: ANN001
+        return _logic(state, runtime)
+
+    return type(
+        "inject_steer_queue",
+        (AgentMiddleware,),
+        {
+            "state_schema": AgentState,
+            "tools": [],
+            "before_model": before_model,
+            "abefore_model": abefore_model,
+        },
+    )()
+
+
+def get_agent_steer_queue(agent: Any) -> SteerQueue | None:
+    q = getattr(agent, "_coding_steer_queue", None)
+    return q if isinstance(q, SteerQueue) else None