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

synapse/runtime/execute_capture.py

@@ -0,0 +1,48 @@
+"""Per-tool-call capture channel for untruncated shell output.
+
+``FilesystemMiddleware`` only converts ``ExecuteResponse.output`` into a
+``ToolMessage``. The response contract cannot carry artifacts, so the backend
+records the full pre-truncation output in this context-local side channel while
+the tool-output transformation middleware invokes the execute tool.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+
+
+@dataclass
+class ExecuteOutputCapture:
+    """Full and model-visible backend output for one execute invocation."""
+
+    full_output: str | None = None
+    displayed_output: str | None = None
+    truncated: bool = False
+
+
+_active_capture: ContextVar[ExecuteOutputCapture | None] = ContextVar(
+    "synapse_execute_output_capture",
+    default=None,
+)
+
+
+def begin_execute_capture() -> tuple[ExecuteOutputCapture, Token[ExecuteOutputCapture | None]]:
+    """Install an empty capture object for the current tool-call context."""
+    capture = ExecuteOutputCapture()
+    return capture, _active_capture.set(capture)
+
+
+def end_execute_capture(token: Token[ExecuteOutputCapture | None]) -> None:
+    """Restore the enclosing tool-call capture context."""
+    _active_capture.reset(token)
+
+
+def capture_execute_output(*, full_output: str, displayed_output: str, truncated: bool) -> None:
+    """Record the backend response before its size limit discarded content."""
+    capture = _active_capture.get()
+    if capture is None:
+        return
+    capture.full_output = full_output
+    capture.displayed_output = displayed_output
+    capture.truncated = truncated

synapse/runtime/fs_permissions.py

@@ -0,0 +1,79 @@
+"""FilesystemPermission helpers for create_deep_agent(permissions=...).
+
+Important: deepagents currently rejects permissions when the backend supports
+command execution (LocalShellBackend / SandboxBackendProtocol). This project
+always uses LocalShellBackend, so ``build_filesystem_permissions`` returns
+None unless ``force=True`` (for non-shell backends / experiments).
+
+Product readonly mode should use harness tool exclusion instead
+(``apply_harness_exclusions`` / ``AGENT_READONLY``).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_filesystem_permissions(
+    *,
+    enabled: bool = False,
+    readonly: bool = False,
+    deny_paths: list[str] | None = None,
+    force: bool = False,
+    shell_backend: bool = True,
+) -> list[Any] | None:
+    """Build deepagents FilesystemPermission rules.
+
+    Paths must be POSIX-style and start with '/'. With LocalShellBackend +
+    virtual_mode, workspace roots are typically exposed under '/'.
+
+    Returns None when ``shell_backend`` is True (default), because permissions
+    + execute backends are unsupported by FilesystemMiddleware.
+    """
+    if shell_backend and not force:
+        # Avoid hard failure at agent build time on LocalShellBackend.
+        return None
+
+    if not enabled and not readonly and not deny_paths:
+        return None
+
+    from deepagents import FilesystemPermission
+
+    rules: list[Any] = []
+
+    if readonly:
+        # Deny writes everywhere; reads remain allowed by default.
+        rules.append(
+            FilesystemPermission(
+                operations=["write"],
+                paths=["/**"],
+                mode="deny",
+            )
+        )
+
+    for path in deny_paths or []:
+        p = path.strip().replace("\\", "/")
+        if not p:
+            continue
+        if not p.startswith("/"):
+            p = "/" + p
+        rules.append(
+            FilesystemPermission(
+                operations=["read", "write"],
+                paths=[p],
+                mode="deny",
+            )
+        )
+
+    # Sensible defaults when permissions feature is on.
+    if enabled and not deny_paths:
+        for p in ("/**/.env", "/**/.env.*", "/**/secrets/**"):
+            rules.append(
+                FilesystemPermission(
+                    operations=["read", "write"],
+                    paths=[p],
+                    mode="deny",
+                )
+            )
+
+    return rules or None

synapse/runtime/harness.py

@@ -0,0 +1,57 @@
+"""HarnessProfile registration helpers (excluded_tools etc.)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+_DEFAULT_EXCLUDES = frozenset({"ls", "grep"})
+_DEFAULT_READONLY_EXCLUDES = frozenset(
+    {
+        "execute",
+        "write_file",
+        "edit_file",
+    }
+)
+
+
+def apply_harness_exclusions(
+    model_spec: str,
+    *,
+    readonly: bool = False,
+    excluded_tools: Iterable[str] | None = None,
+) -> frozenset[str]:
+    """Register harness excluded_tools for the active model/provider.
+
+    ``ls`` and ``grep`` are excluded by default because ``execute`` can run the
+    project's native directory and search commands. Read-only mode additionally
+    excludes ``execute``, ``write_file``, and ``edit_file``.
+
+    deepagents only removes built-in tools via HarnessProfile.excluded_tools
+    (tools= is additive). Registration is additive/merge under the same key.
+    """
+    names = set(_DEFAULT_EXCLUDES)
+    names.update(excluded_tools or [])
+    if readonly:
+        names |= set(_DEFAULT_READONLY_EXCLUDES)
+    excluded = frozenset(n.strip() for n in names if n and n.strip())
+    if not excluded:
+        return frozenset()
+
+    from deepagents import (
+        GeneralPurposeSubagentProfile,
+        HarnessProfile,
+        register_harness_profile,
+    )
+
+    profile = HarnessProfile(
+        excluded_tools=excluded,
+        general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False),
+    )
+    # Model-level and provider-level keys so both string specs and prebuilt
+    # BaseChatModel resolution paths can match.
+    register_harness_profile(model_spec, profile)
+    if ":" in model_spec:
+        provider = model_spec.split(":", 1)[0]
+        if provider:
+            register_harness_profile(provider, profile)
+    return excluded

synapse/runtime/hitl.py

@@ -0,0 +1,197 @@
+"""Human-in-the-loop interrupt detection and resume helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class PendingAction:
+    """One tool call waiting for human decision."""
+
+    name: str
+    args: dict[str, Any] = field(default_factory=dict)
+    description: str = ""
+    allowed_decisions: list[str] = field(default_factory=lambda: ["approve", "reject"])
+
+
+@dataclass
+class PendingInterrupt:
+    """Graph is paused for HITL."""
+
+    actions: list[PendingAction] = field(default_factory=list)
+    raw: Any = None
+
+
+def _as_dict(obj: Any) -> dict[str, Any]:
+    if obj is None:
+        return {}
+    if isinstance(obj, dict):
+        return obj
+    if hasattr(obj, "model_dump"):
+        try:
+            data = obj.model_dump()
+            if isinstance(data, dict):
+                return data
+        except Exception:  # noqa: BLE001
+            pass
+    out: dict[str, Any] = {}
+    for key in (
+        "name",
+        "args",
+        "description",
+        "action_request",
+        "review_config",
+        "value",
+        "action",
+    ):
+        if hasattr(obj, key):
+            out[key] = getattr(obj, key)
+    return out
+
+
+def _parse_action_request(item: Any) -> PendingAction | None:
+    data = _as_dict(item)
+    # Nested shapes: {action_request: {name, args, description}, review_config: {...}}
+    ar = data.get("action_request") or data.get("action") or data
+    ar = _as_dict(ar) if not isinstance(ar, dict) else ar
+    name = str(ar.get("name") or data.get("name") or "").strip()
+    if not name:
+        return None
+    args = ar.get("args") if isinstance(ar.get("args"), dict) else {}
+    desc = str(ar.get("description") or data.get("description") or "")
+    rc = data.get("review_config") or {}
+    rc = _as_dict(rc) if not isinstance(rc, dict) else rc
+    allowed = list(rc.get("allowed_decisions") or ["approve", "reject"])
+    return PendingAction(name=name, args=args or {}, description=desc, allowed_decisions=allowed)
+
+
+def extract_pending_interrupt(agent: Any, config: dict[str, Any]) -> PendingInterrupt | None:
+    """Return pending HITL interrupt for the thread, if any."""
+    if agent is None:
+        return None
+    get_state = getattr(agent, "get_state", None)
+    if not callable(get_state):
+        return None
+    try:
+        state = get_state(config)
+    except Exception:  # noqa: BLE001
+        return None
+
+    actions: list[PendingAction] = []
+    raw_items: list[Any] = []
+
+    # Preferred: state.interrupts (LangGraph >= 0.2)
+    interrupts = getattr(state, "interrupts", None) or ()
+    for item in interrupts:
+        raw_items.append(item)
+        value = getattr(item, "value", item)
+        # HITLRequest: {action_requests: [...], review_configs: [...]}
+        vdict = _as_dict(value)
+        reqs = vdict.get("action_requests") or vdict.get("actionRequests")
+        if isinstance(reqs, list) and reqs:
+            reviews = vdict.get("review_configs") or vdict.get("reviewConfigs") or []
+            for i, req in enumerate(reqs):
+                packed = {"action_request": req}
+                if i < len(reviews):
+                    packed["review_config"] = reviews[i]
+                act = _parse_action_request(packed)
+                if act:
+                    actions.append(act)
+            continue
+        act = _parse_action_request(value)
+        if act:
+            actions.append(act)
+
+    # Fallback: tasks with interrupts
+    if not actions:
+        tasks = getattr(state, "tasks", None) or ()
+        for task in tasks:
+            tintr = getattr(task, "interrupts", None) or ()
+            for item in tintr:
+                raw_items.append(item)
+                value = getattr(item, "value", item)
+                vdict = _as_dict(value)
+                reqs = vdict.get("action_requests") or []
+                if isinstance(reqs, list) and reqs:
+                    for req in reqs:
+                        act = _parse_action_request({"action_request": req})
+                        if act:
+                            actions.append(act)
+                else:
+                    act = _parse_action_request(value)
+                    if act:
+                        actions.append(act)
+
+    if not actions and not raw_items:
+        # Graph may still be mid-node with next != ()
+        nxt = getattr(state, "next", None) or ()
+        if not nxt:
+            return None
+        # No parseable actions
+        return None
+
+    if not actions:
+        return PendingInterrupt(actions=[], raw=raw_items or interrupts)
+
+    return PendingInterrupt(actions=actions, raw=raw_items or interrupts)
+
+
+def format_interrupt_lines(pending: PendingInterrupt) -> list[str]:
+    """Human-readable pending approvals."""
+    if not pending.actions:
+        return [
+            "approval required (unparsed interrupt)",
+            "use /approve or /reject after inspecting agent state",
+        ]
+    lines = [f"approval required for {len(pending.actions)} tool call(s):"]
+    for i, act in enumerate(pending.actions, 1):
+        args_preview = str(act.args)
+        if len(args_preview) > 120:
+            args_preview = args_preview[:119] + "…"
+        lines.append(f"  {i}. {act.name}  args={args_preview}")
+        if act.description:
+            one = " ".join(act.description.split())
+            if len(one) > 140:
+                one = one[:139] + "…"
+            lines.append(f"     {one}")
+    lines.append("decide: /approve  |  /reject [reason]")
+    return lines
+
+
+def build_decisions(
+    pending: PendingInterrupt,
+    *,
+    action: str,
+    message: str | None = None,
+) -> list[dict[str, Any]]:
+    """Build resume decisions list matching pending action count."""
+    kind = (action or "approve").strip().casefold()
+    if kind not in {"approve", "reject"}:
+        kind = "approve"
+    decisions: list[dict[str, Any]] = []
+    n = max(1, len(pending.actions))
+    for _ in range(n):
+        if kind == "approve":
+            decisions.append({"type": "approve"})
+        else:
+            d: dict[str, Any] = {"type": "reject"}
+            if message:
+                d["message"] = message
+            else:
+                d["message"] = "Rejected by user via /reject"
+            decisions.append(d)
+    return decisions
+
+
+def build_resume_payload(decisions: list[dict[str, Any]]) -> Any:
+    """LangGraph Command(resume=...) payload for HITL middleware."""
+    from langgraph.types import Command
+
+    return Command(resume={"decisions": decisions})
+
+
+def has_pending_interrupt(agent: Any, config: dict[str, Any]) -> bool:
+    pending = extract_pending_interrupt(agent, config)
+    return pending is not None and bool(pending.actions or pending.raw)

synapse/runtime/interaction_ledger.py

@@ -0,0 +1,82 @@
+"""Thread-scoped turn and model-call correlation for compression diagnostics."""
+
+from __future__ import annotations
+
+import hashlib
+import threading
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class InteractionPosition:
+    turn_id: str
+    turn_index: int
+    model_call_index: int
+
+
+@dataclass
+class _ThreadPosition:
+    user_fingerprint: str = ""
+    turn_id: str = ""
+    turn_index: int = 0
+    model_call_index: int = 0
+
+
+_lock = threading.RLock()
+_positions: dict[str, _ThreadPosition] = {}
+
+
+def user_fingerprint(content: Any) -> str:
+    return hashlib.sha256(str(content or "").encode("utf-8")).hexdigest()[:16]
+
+
+def begin_model_call(
+    thread_id: str,
+    current_user_content: Any,
+    *,
+    turn_index_hint: int = 0,
+    model_call_index_hint: int = 0,
+) -> InteractionPosition:
+    """Advance a thread position using deterministic persisted-position hints."""
+    fingerprint = user_fingerprint(current_user_content)
+    with _lock:
+        state = _positions.setdefault(thread_id, _ThreadPosition())
+        hinted_turn = max(0, int(turn_index_hint or 0))
+        new_turn = (
+            not state.turn_id
+            or state.user_fingerprint != fingerprint
+            or (hinted_turn and state.turn_index != hinted_turn)
+        )
+        if new_turn:
+            state.turn_index = hinted_turn or state.turn_index + 1
+            state.model_call_index = max(0, int(model_call_index_hint or 0))
+            state.user_fingerprint = fingerprint
+            seed = f"{thread_id}:{state.turn_index}:{fingerprint}"
+            state.turn_id = hashlib.sha256(seed.encode("utf-8")).hexdigest()[:16]
+        else:
+            state.model_call_index = max(
+                state.model_call_index, max(0, int(model_call_index_hint or 0))
+            )
+        state.model_call_index += 1
+        return InteractionPosition(
+            turn_id=state.turn_id,
+            turn_index=state.turn_index,
+            model_call_index=state.model_call_index,
+        )
+
+
+def current_position(thread_id: str) -> InteractionPosition:
+    with _lock:
+        state = _positions.get(thread_id) or _ThreadPosition()
+        return InteractionPosition(
+            turn_id=state.turn_id,
+            turn_index=state.turn_index,
+            model_call_index=state.model_call_index,
+        )
+
+
+def clear_interaction_positions() -> None:
+    """Reset process-local positions for tests and clean agent restarts."""
+    with _lock:
+        _positions.clear()