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

synapse/content/prompts.py

@@ -0,0 +1,249 @@
+"""System prompts for the coding agent.
+
+Default body ships in English. Prefer loading an external markdown file:
+
+1. ``<workspace>/.synapse/system_prompt.md`` (project override)
+2. ``~/.synapse/system_prompt.md`` (user global)
+
+If the user file is missing, it is created from the built-in default on first use.
+The workspace footer is always appended in code.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from synapse.settings.config_paths import project_config_dir, user_config_dir
+
+SYSTEM_PROMPT_FILENAME = "system_prompt.md"
+
+# Built-in default (English). External config may override this body.
+DEFAULT_CODING_SYSTEM_PROMPT = """\
+You are a senior software engineering agent working in a local workspace.
+
+## Language and style
+
+* Think and reason in Chinese.
+* Reply to the user in Chinese.
+* Preserve code identifiers, paths, commands, logs, and API names as written.
+* Use no emoji or emoticons. Use plain text markers such as `-`, `[x]`, `OK`, and `FAIL`.
+* Keep responses concise and technical. Lead with the conclusion.
+
+## Goal
+
+Help implement features, fix bugs, refactor code, write tests, inspect repositories,
+and verify changes.
+
+## Effort calibration
+
+Match effort to the request.
+
+For greetings, connectivity checks, meaningless input, or casual conversation:
+
+* Reply briefly.
+* Do not call tools, scan files, create todos, or launch subagents.
+
+Do not inspect or modify the repository unless the user clearly requests
+implementation, debugging, review, testing, or repository-specific information.
+
+When intent is unclear but may represent a real task, ask for clarification
+in one or two short sentences. Do not substitute clarification with exploratory commands.
+
+For clear tasks, use the smallest targeted exploration necessary.
+Never scan the entire repository without a specific reason.
+
+## Virtual filesystem
+
+File tools such as `ls`, `glob`, `grep`, `read_file`, `edit_file`, and `write_file`
+operate on a virtual filesystem rooted at `/`.
+
+Valid paths:
+
+* `/`
+* `/README.md`
+* `/src/app.py`
+* `/tests`
+
+File-tool paths must:
+
+* Start with `/`.
+* Be relative to the workspace root.
+* Never use Windows drive paths, host absolute paths, or paths without a leading slash.
+
+The real host workspace path may only be used by shell or git commands.
+
+Use `ls /` only when a concrete file task exists and the target path is unknown.
+If a virtual-path error occurs, convert the path to `/...`;
+do not retry a host or Windows path.
+
+## Workspace rules
+
+* Stay within the workspace unless explicitly asked otherwise.
+* Read relevant files before editing when practical.
+* Never invent file contents or repository facts.
+* Prefer small, reversible changes over broad rewrites.
+* Never expose secrets, credentials, private keys, or `.env` contents.
+* Avoid destructive actions unless explicitly requested.
+
+## Workflow
+
+For a clear coding or debugging task:
+
+1. Understand the request and clarify only critical ambiguity.
+2. Locate the relevant files with targeted searches.
+3. Read only the necessary files or line ranges.
+4. Use `write_todos` only for genuinely multi-step, multi-file work likely to span multiple turns.
+5. Apply focused edits.
+6. Run the narrowest useful test, lint, typecheck, or build command.
+7. Diagnose failures and iterate until successful or clearly blocked.
+8. Finish with:
+
+   * What changed
+   * How it was verified
+   * Remaining risks, if any
+
+Prefer the repository's existing package and test commands.
+
+## Tool usage
+
+Every tool call must include a short English `intent` describing its purpose, for example:
+
+* `locate authentication handler`
+* `inspect pytest configuration`
+* `run narrow regression test`
+
+Do not use generic intent values such as `run tool` or `read_file`.
+
+Search only when required by a clear task.
+Keep searches targeted and avoid unnecessary full-file output.
+
+For `glob` and `grep` tools, automatically exclude common build artifacts and caches:
+* `target/`
+* `.venv/`
+* `.node_modules/`
+* `__pycache__/`
+* `.git/`
+* `*.pyc`
+
+For large files, read only relevant ranges. After editing, re-read changed regions when useful.
+
+`list_sessions` and `read_session` are forbidden unless the user explicitly
+asks to inspect or compare other sessions.
+
+Use direct repository tools by default. Use `task` subagents only for large work
+that genuinely benefits from isolation; never use them for small tasks,
+ordinary exploration, or conversation.
+
+## Parallel tool calls
+
+Run independent tool calls in parallel within the same turn.
+
+Parallelize when arguments are already known and results do not depend on each other, including:
+
+* Multiple file reads
+* `glob` and related file reads
+* `execute` and related reads
+* Edits to different files
+* Independent test or lint commands
+
+Serialize only when:
+
+* A later path, command, or patch depends on an earlier result.
+* The same file must be read before it can be edited.
+* Verification depends on edits being completed.
+
+Do not spread known independent reads or edits across multiple turns.
+Parallelism must remain relevant to the current task.
+
+## Output format
+
+Keep user-facing responses brief.
+
+Preferred structure:
+
+1. Conclusion in one or two sentences
+2. Short list of key changes or findings
+3. Verification and risks, when applicable
+
+Do not expose internal reasoning or paste long tool logs.
+For casual input, reply in one or two sentences.
+"""
+
+# Backward-compatible alias used by older imports/tests.
+CODING_SYSTEM_PROMPT = DEFAULT_CODING_SYSTEM_PROMPT
+
+
+def user_system_prompt_path() -> Path:
+    """``~/.synapse/system_prompt.md``."""
+    return user_config_dir() / SYSTEM_PROMPT_FILENAME
+
+
+def project_system_prompt_path(workspace: Path | str | None = None) -> Path:
+    """``<workspace>/.synapse/system_prompt.md``."""
+    return project_config_dir(workspace) / SYSTEM_PROMPT_FILENAME
+
+
+def ensure_user_system_prompt(*, force: bool = False) -> Path:
+    """Ensure the user global prompt file exists; seed from built-in default.
+
+    Returns the user prompt path. Does not overwrite an existing file unless
+    ``force=True``.
+    """
+    path = user_system_prompt_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if force or not path.is_file():
+        path.write_text(DEFAULT_CODING_SYSTEM_PROMPT.strip() + "\n", encoding="utf-8")
+    return path
+
+
+def resolve_system_prompt_path(workspace: Path | str | None = None) -> Path | None:
+    """Return the first existing external prompt file (project, then user)."""
+    candidates = [
+        project_system_prompt_path(workspace),
+        user_system_prompt_path(),
+    ]
+    for candidate in candidates:
+        try:
+            if candidate.is_file():
+                return candidate.resolve()
+        except OSError:
+            continue
+    return None
+
+
+def load_coding_system_prompt(
+    workspace: Path | str | None = None,
+    *,
+    ensure_user_file: bool = False,
+) -> str:
+    """Load prompt body from config file, else built-in default.
+
+    When ``ensure_user_file`` is True and neither project nor user file exists,
+    seed ``~/.synapse/system_prompt.md`` and load it.
+    """
+    path = resolve_system_prompt_path(workspace)
+    if path is None and ensure_user_file:
+        path = ensure_user_system_prompt()
+    if path is not None:
+        try:
+            text = path.read_text(encoding="utf-8").strip()
+            if text:
+                return text
+        except OSError:
+            pass
+    return DEFAULT_CODING_SYSTEM_PROMPT.strip()
+
+
+def build_system_prompt(workspace: Path, *, ensure_user_file: bool = False) -> str:
+    """Build a system prompt with workspace context."""
+    root = Path(workspace).resolve()
+    body = load_coding_system_prompt(root, ensure_user_file=ensure_user_file)
+    return (
+        f"{body}\n\n"
+        f"## Current workspace\n"
+        f"- Host root (shell/git only): `{root}`\n"
+        f"- File-tool virtual root: `/` maps to the host root above\n"
+        f"- Mapping example: `{root / 'README.md'}` -> `/README.md`\n"
+        f"- Shell commands run on the host, inside the workspace root.\n"
+        f"- Again: thinking and final replies must be Chinese; keep user-facing output concise.\n"
+    )

synapse/content/skills_catalog.py

@@ -0,0 +1,128 @@
+"""Discover local Agent Skills and memory files for /skills /memory."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+_FRONT_MATTER_RE = re.compile(r"\A---\s*\n(.*?)\n---\s*\n?", re.S)
+
+
+@dataclass
+class SkillInfo:
+    name: str
+    description: str = ""
+    path: str = ""
+    source: str = ""
+
+
+def _parse_frontmatter(text: str) -> dict[str, str]:
+    m = _FRONT_MATTER_RE.match(text or "")
+    if not m:
+        return {}
+    data: dict[str, str] = {}
+    for line in m.group(1).splitlines():
+        if ":" not in line:
+            continue
+        key, val = line.split(":", 1)
+        data[key.strip().casefold()] = val.strip().strip("\"'")
+    return data
+
+
+def discover_skills(skills_paths: list[str] | None) -> list[SkillInfo]:
+    """Scan skills directories for SKILL.md files."""
+    found: list[SkillInfo] = []
+    seen: set[str] = set()
+    for raw in skills_paths or []:
+        root = Path(raw).expanduser()
+        if not root.exists():
+            continue
+        if root.is_file() and root.name.upper() == "SKILL.MD":
+            candidates = [root]
+            source = str(root.parent)
+        else:
+            candidates = sorted(root.rglob("SKILL.md"))
+            source = str(root.resolve())
+        for skill_md in candidates:
+            try:
+                text = skill_md.read_text(encoding="utf-8")
+            except Exception:  # noqa: BLE001
+                continue
+            meta = _parse_frontmatter(text)
+            name = meta.get("name") or skill_md.parent.name
+            desc = meta.get("description") or ""
+            key = str(skill_md.resolve())
+            if key in seen:
+                continue
+            seen.add(key)
+            found.append(
+                SkillInfo(
+                    name=name,
+                    description=desc,
+                    path=str(skill_md.resolve()),
+                    source=source,
+                )
+            )
+    return found
+
+
+def format_skills_lines(skills: list[SkillInfo]) -> list[str]:
+    if not skills:
+        return ["skills: (none found)", "tip: put SKILL.md under skills/<name>/"]
+    lines = [f"skills: {len(skills)}"]
+    for s in skills:
+        desc = s.description
+        if len(desc) > 70:
+            desc = desc[:69] + "…"
+        lines.append(f"  - {s.name}: {desc or '(no description)'}")
+        lines.append(f"    {s.path}")
+    return lines
+
+
+def list_memory_files(memory_paths: list[str] | None) -> list[tuple[str, bool, int]]:
+    """Return (path, exists, size_bytes)."""
+    out: list[tuple[str, bool, int]] = []
+    for raw in memory_paths or []:
+        p = Path(raw).expanduser()
+        if p.exists() and p.is_file():
+            try:
+                size = p.stat().st_size
+            except Exception:  # noqa: BLE001
+                size = 0
+            out.append((str(p.resolve()), True, size))
+        else:
+            out.append((str(p), False, 0))
+    return out
+
+
+def format_memory_lines(entries: list[tuple[str, bool, int]]) -> list[str]:
+    if not entries:
+        return ["memory: (no paths configured)"]
+    lines = [f"memory files: {len(entries)}"]
+    for path, exists, size in entries:
+        if exists:
+            lines.append(f"  - {path}  ({size} bytes)")
+        else:
+            lines.append(f"  - {path}  (missing)")
+    lines.append("note: existing files are injected via create_deep_agent(memory=...)")
+    return lines
+
+
+def skills_paths_from_settings(settings: Any, project_root: Path | None = None) -> list[str]:
+    root = project_root or Path.cwd()
+    fn = getattr(settings, "resolved_skills_paths", None)
+    if callable(fn):
+        return list(fn(root) or [])
+    raw = getattr(settings, "skills_paths", None) or []
+    return [str((root / p).resolve()) if not Path(p).is_absolute() else p for p in raw]
+
+
+def memory_paths_from_settings(settings: Any, project_root: Path | None = None) -> list[str]:
+    root = project_root or Path.cwd()
+    fn = getattr(settings, "resolved_memory_paths", None)
+    if callable(fn):
+        return list(fn(root) or [])
+    raw = getattr(settings, "memory_paths", None) or []
+    return [str((root / p).resolve()) if not Path(p).is_absolute() else p for p in raw]

synapse/integrations/__init__.py

@@ -0,0 +1 @@
+"""External service and provider integrations."""

synapse/integrations/checkpoint_seed.py

@@ -0,0 +1,281 @@
+"""Fail-closed terminal checkpoint seeding for projected Codex text.
+
+This module is deliberately narrow. It writes an already validated visible-text
+snapshot into a fresh Synapse thread, then seals the graph at ``END`` so the
+thread has no pending tasks. It does not resume Codex runtime state, perform
+source discovery, create session metadata, or implement import idempotency.
+
+The implementation relies only on public LangGraph graph APIs, but its
+``model`` node behavior is compatibility-gated to the installed DeepAgents and
+LangGraph versions. Upgrade those dependencies only together with the contract
+tests in ``tests/test_checkpoint_seed.py``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Any
+
+from langchain_core.messages import AIMessage, HumanMessage
+from langgraph.graph import END
+
+from synapse.integrations.codex_history import PARSER_VERSION, PROJECTION_KIND
+
+if TYPE_CHECKING:
+    from langchain_core.messages import BaseMessage
+
+    from synapse.integrations.codex_history import CodexTextSnapshot
+
+SUPPORTED_LANGGRAPH_VERSION = "1.2.9"
+SUPPORTED_DEEPAGENTS_VERSION = "0.6.12"
+
+
+class CheckpointSeedError(RuntimeError):
+    """The requested checkpoint seed was rejected or could not be verified."""
+
+
+@dataclass(frozen=True)
+class CheckpointSeedResult:
+    """Verified terminal checkpoint location for a newly seeded thread."""
+
+    thread_id: str
+    config: dict[str, Any]
+    message_count: int
+
+
+class CheckpointSeeder:
+    """Seed a validated visible-text snapshot into a fresh, terminal thread.
+
+    The seed operation has one intentionally narrow compatibility contract:
+
+    - LangGraph 1.2.9 and DeepAgents 0.6.12 only.
+    - A root-namespace graph with a ``model`` node and a ``messages`` channel.
+    - An empty target thread only; a future import ledger owns idempotency.
+    - User/assistant text only, represented as deterministic message IDs.
+
+    Any failed write is compensated with ``delete_thread(thread_id)`` after the
+    target was proven empty before seeding. A cleanup failure is surfaced rather
+    than silently claiming a safe result.
+    """
+
+    def __init__(self, agent: Any) -> None:
+        self._agent = agent
+
+    def seed_snapshot(
+        self,
+        thread_id: str,
+        snapshot: CodexTextSnapshot,
+    ) -> CheckpointSeedResult:
+        """Write one safe Codex snapshot and verify that it is terminal."""
+        messages = _messages_from_snapshot(snapshot)
+        return self.seed_messages(thread_id, messages)
+
+    def verify_snapshot(
+        self,
+        thread_id: str,
+        snapshot: CodexTextSnapshot,
+    ) -> CheckpointSeedResult:
+        """Verify that a thread exactly contains a terminal snapshot seed."""
+        normalized_thread_id = _validate_thread_id(thread_id)
+        expected = _messages_from_snapshot(snapshot)
+        self._validate_compatibility()
+        saver = self._checkpointer()
+        config = {"configurable": {"thread_id": normalized_thread_id, "checkpoint_ns": ""}}
+        self._verify_terminal(config, expected, saver)
+        state = self._agent.get_state(config)
+        return CheckpointSeedResult(
+            thread_id=normalized_thread_id,
+            config=_copy_config(state.config),
+            message_count=len(expected),
+        )
+
+    def has_thread(self, thread_id: str) -> bool:
+        """Return whether the root checkpoint namespace has any saved state."""
+        normalized_thread_id = _validate_thread_id(thread_id)
+        config = {"configurable": {"thread_id": normalized_thread_id, "checkpoint_ns": ""}}
+        return self._checkpointer().get_tuple(config) is not None
+
+    def delete_thread(self, thread_id: str) -> None:
+        """Delete a thread only for a failed import compensation path."""
+        self._checkpointer().delete_thread(_validate_thread_id(thread_id))
+
+    def seed_messages(
+        self,
+        thread_id: str,
+        messages: Sequence[HumanMessage | AIMessage],
+    ) -> CheckpointSeedResult:
+        """Write explicit safe messages into a new terminal graph thread.
+
+        This lower-level entry point is retained for future non-Codex importers,
+        but it accepts only plain ``HumanMessage`` and ``AIMessage`` values with
+        stable unique IDs. It rejects tool calls and all metadata-bearing input.
+        """
+        normalized_thread_id = _validate_thread_id(thread_id)
+        expected = _validate_messages(messages)
+        self._validate_compatibility()
+        saver = self._checkpointer()
+        config = {"configurable": {"thread_id": normalized_thread_id, "checkpoint_ns": ""}}
+        if saver.get_tuple(config) is not None:
+            raise CheckpointSeedError("target thread already has a checkpoint")
+
+        attempted_write = False
+        try:
+            attempted_write = True
+            seeded_config = self._agent.update_state(
+                config,
+                {"messages": expected},
+                as_node="model",
+            )
+            terminal_config = self._agent.update_state(seeded_config, None, as_node=END)
+            self._verify_terminal(terminal_config, expected, saver)
+        except Exception as exc:
+            if attempted_write:
+                self._compensate(saver, normalized_thread_id, exc)
+            if isinstance(exc, CheckpointSeedError):
+                raise
+            raise CheckpointSeedError("checkpoint seed failed") from exc
+
+        return CheckpointSeedResult(
+            thread_id=normalized_thread_id,
+            config=_copy_config(terminal_config),
+            message_count=len(expected),
+        )
+
+    def _validate_compatibility(self) -> None:
+        installed = _framework_versions()
+        if installed != (SUPPORTED_LANGGRAPH_VERSION, SUPPORTED_DEEPAGENTS_VERSION):
+            raise CheckpointSeedError(
+                "checkpoint seeding is unsupported for installed framework versions"
+            )
+        nodes = getattr(self._agent, "nodes", None)
+        channels = getattr(self._agent, "channels", None)
+        if not isinstance(nodes, dict) or "model" not in nodes:
+            raise CheckpointSeedError("checkpoint seeding requires a graph model node")
+        if not isinstance(channels, dict) or "messages" not in channels:
+            raise CheckpointSeedError("checkpoint seeding requires a messages channel")
+        for name in ("update_state", "get_state"):
+            if not callable(getattr(self._agent, name, None)):
+                raise CheckpointSeedError(f"checkpoint seeding requires agent.{name}")
+
+    def _checkpointer(self) -> Any:
+        saver = getattr(self._agent, "_coding_checkpointer", None)
+        if saver is None:
+            saver = getattr(self._agent, "checkpointer", None)
+        if not callable(getattr(saver, "get_tuple", None)):
+            raise CheckpointSeedError("checkpoint seeding requires a readable checkpointer")
+        if not callable(getattr(saver, "delete_thread", None)):
+            raise CheckpointSeedError("checkpoint seeding requires checkpoint compensation")
+        return saver
+
+    def _verify_terminal(
+        self,
+        config: dict[str, Any],
+        expected: Sequence[HumanMessage | AIMessage],
+        saver: Any,
+    ) -> None:
+        state = self._agent.get_state(config)
+        if tuple(getattr(state, "next", ()) or ()):
+            raise CheckpointSeedError("seeded checkpoint still has pending graph tasks")
+        if tuple(getattr(state, "interrupts", ()) or ()):
+            raise CheckpointSeedError("seeded checkpoint has pending interrupts")
+        actual = list((getattr(state, "values", None) or {}).get("messages") or [])
+        if not _messages_match(actual, expected):
+            raise CheckpointSeedError("seeded checkpoint messages did not round-trip exactly")
+        checkpoint_tuple = saver.get_tuple(config)
+        if checkpoint_tuple is None:
+            raise CheckpointSeedError("seeded checkpoint could not be read back")
+        if getattr(checkpoint_tuple, "pending_writes", ()):
+            raise CheckpointSeedError("seeded checkpoint still has pending writes")
+
+    @staticmethod
+    def _compensate(saver: Any, thread_id: str, cause: Exception) -> None:
+        try:
+            saver.delete_thread(thread_id)
+        except Exception as cleanup_error:  # noqa: BLE001
+            raise CheckpointSeedError(
+                "checkpoint seed failed and cleanup was unsuccessful"
+            ) from cleanup_error
+
+
+def _framework_versions() -> tuple[str | None, str | None]:
+    try:
+        return version("langgraph"), version("deepagents")
+    except PackageNotFoundError:
+        return None, None
+
+
+def _validate_thread_id(thread_id: str) -> str:
+    if not isinstance(thread_id, str):
+        raise CheckpointSeedError("thread_id must be a string")
+    value = thread_id.strip()
+    if not value or len(value) > 120 or "\x00" in value:
+        raise CheckpointSeedError("thread_id is invalid")
+    return value
+
+
+def _messages_from_snapshot(snapshot: CodexTextSnapshot) -> list[HumanMessage | AIMessage]:
+    if not snapshot.importable:
+        raise CheckpointSeedError("snapshot is not safe to seed")
+    if (
+        snapshot.projection_kind != PROJECTION_KIND
+        or snapshot.parser_version != PARSER_VERSION
+    ):
+        raise CheckpointSeedError("snapshot projection contract is unsupported")
+
+    messages: list[HumanMessage | AIMessage] = []
+    for source in snapshot.messages:
+        if source.role == "user":
+            messages.append(HumanMessage(content=source.text, id=source.source_id))
+        elif source.role == "assistant":
+            messages.append(AIMessage(content=source.text, id=source.source_id))
+        else:
+            raise CheckpointSeedError("snapshot contains an unsupported message role")
+    return _validate_messages(messages)
+
+
+def _validate_messages(
+    messages: Sequence[HumanMessage | AIMessage],
+) -> list[HumanMessage | AIMessage]:
+    if not messages:
+        raise CheckpointSeedError("checkpoint seed requires at least one message")
+    normalized: list[HumanMessage | AIMessage] = []
+    ids: set[str] = set()
+    for message in messages:
+        if type(message) not in {HumanMessage, AIMessage}:
+            raise CheckpointSeedError("checkpoint seed accepts only user and assistant messages")
+        if not isinstance(message.id, str) or not message.id or message.id in ids:
+            raise CheckpointSeedError("checkpoint seed messages need unique stable IDs")
+        if not isinstance(message.content, str) or not message.content.strip():
+            raise CheckpointSeedError("checkpoint seed messages need nonempty text content")
+        if message.additional_kwargs or message.response_metadata:
+            raise CheckpointSeedError("checkpoint seed messages cannot carry metadata")
+        if isinstance(message, AIMessage) and (
+            message.tool_calls or message.invalid_tool_calls or message.usage_metadata
+        ):
+            raise CheckpointSeedError("checkpoint seed assistant messages cannot carry tool state")
+        ids.add(message.id)
+        normalized.append(message)
+    return normalized
+
+
+def _messages_match(actual: Sequence[BaseMessage], expected: Sequence[BaseMessage]) -> bool:
+    if len(actual) != len(expected):
+        return False
+    return all(
+        type(found) is type(wanted)
+        and found.id == wanted.id
+        and found.content == wanted.content
+        and not found.additional_kwargs
+        and not found.response_metadata
+        and (not isinstance(found, AIMessage) or not found.tool_calls)
+        for found, wanted in zip(actual, expected, strict=True)
+    )
+
+
+def _copy_config(config: dict[str, Any]) -> dict[str, Any]:
+    configurable = config.get("configurable")
+    if not isinstance(configurable, dict):
+        raise CheckpointSeedError("checkpoint seeding returned an invalid graph configuration")
+    return {"configurable": dict(configurable)}