syncmill 0.2.0__py3-none-any.whl

syncmill/gates.py

@@ -0,0 +1,179 @@
+"""Quality gates (#10) — validate an agent's work in its worktree before it's
+accepted.
+
+A gate runs *after* an agent finishes, against the diff it produced in its own
+worktree — never as a pre-run liveness probe (that would violate the "no
+``health_check`` on agents" invariant). It's reactive, like the rest of
+syncmill's fault handling: run, then judge the output.
+
+The gate is **plumbed through the strategy layer, never the agent layer** —
+agents stay pure ``execute(prompt, workdir, timeout)`` functions and know nothing
+about gates. The Supervisor builds the gate from config and injects it into the
+strategy, which decides what a gate verdict means for its topology: RouteStrategy
+falls back on failure, PipelineStrategy fails the chain, CompeteStrategy downranks
+failers when picking a winner.
+"""
+
+from __future__ import annotations
+
+import logging
+import shlex
+import subprocess
+from pathlib import Path
+from time import monotonic
+from typing import Protocol, runtime_checkable
+
+from syncmill.agents import _isolated_process_env, _sync_run
+from syncmill.config import GateConfig
+from syncmill.models import GateCheck, GateReport
+from syncmill.worktree import Worktree
+
+logger = logging.getLogger(__name__)
+
+# Per-check captured output is tailed to this many characters: a failing test run
+# can emit megabytes, but only the tail (where the failure is) needs to reach the
+# gate error / CLI without bloating a TaskResult.
+_OUTPUT_LIMIT = 4000
+
+
+def _gate_env(workdir: Path) -> dict[str, str]:
+    """The child environment for a gate check — the agents' isolation verbatim.
+
+    Reused rather than rebuilt so "isolated" can only ever mean one thing: git
+    routing and config injection stripped, syncmill's own run-identity IPC
+    stripped, ``PWD`` pinned to the worktree. A private cross-import (the
+    ``session.py`` → ``monitor.py`` precedent); ``agents`` imports nothing from
+    here, so the graph stays acyclic.
+    """
+    return _isolated_process_env(Path(workdir))
+
+
+@runtime_checkable
+class QualityGate(Protocol):
+    """Validates an agent's work in its worktree. Pure verdict: worktree in,
+    ``GateReport`` out — like agents, it knows nothing about the Supervisor."""
+
+    def evaluate(self, worktree: Worktree) -> GateReport: ...
+
+
+class CommandGate:
+    """Runs a fixed list of commands in the worktree; passes iff every one exits 0.
+
+    Each command is parsed with ``shlex.split`` and run **without a shell** —
+    matching how the rest of syncmill shells out (argv lists, no ``shell=True``).
+    Chain checks by configuring multiple commands, not with ``&&``/pipes. A
+    command that can't run (missing binary, bad syntax, timeout) counts as a
+    failed check rather than crashing the gate — an unverifiable result must not
+    be silently accepted, but it also must not abort the whole task.
+    """
+
+    def __init__(
+        self,
+        commands: list[str],
+        timeout_seconds: int,
+        *,
+        total_timeout_seconds: float | None = None,
+    ):
+        self._commands = list(commands)
+        self._timeout = timeout_seconds
+        self._total_timeout = total_timeout_seconds
+        self._deadline: float | None = None
+
+    def evaluate(self, worktree: Worktree) -> GateReport:
+        self._deadline = (
+            monotonic() + self._total_timeout
+            if self._total_timeout is not None
+            else None
+        )
+        try:
+            checks = [self._run_one(cmd, worktree.path) for cmd in self._commands]
+        finally:
+            self._deadline = None
+        report = GateReport.from_checks(checks)
+        logger.debug(
+            "Gate on %s (%s): %s", worktree.agent_id, worktree.path, report.summary()
+        )
+        return report
+
+    def _run_one(self, command: str, workdir: Path) -> GateCheck:
+        start = monotonic()
+
+        def failed(output: str) -> GateCheck:
+            # Every non-clean-exit path reports the same shape — a failed check
+            # with the elapsed time — so a launch/decode error is observable, not
+            # a zero-duration mystery, and never crashes the gate.
+            return GateCheck(
+                command, passed=False, exit_code=-1, output=output,
+                duration_seconds=round(monotonic() - start, 2),
+            )
+
+        try:
+            argv = shlex.split(command)
+        except ValueError as exc:
+            return failed(f"invalid command: {exc}")
+        if not argv:
+            return failed("empty command")
+        timeout = self._timeout
+        if self._deadline is not None:
+            remaining = self._deadline - monotonic()
+            if remaining <= 0:
+                return failed("workflow deadline exceeded before gate command")
+            timeout = min(timeout, remaining)
+        try:
+            # _sync_run: the owned-process-group runner — a timeout kills the
+            # command's WHOLE tree, not just the direct child (a test runner's
+            # spawned workers used to survive as orphans).
+            proc = _sync_run(
+                argv,
+                capture_output=True,
+                tail_chars=_OUTPUT_LIMIT,
+                # errors="replace": a gate command may emit invalid UTF-8 (test
+                # runners, binary diffs). Decoding must degrade to replacement
+                # chars, never raise UnicodeDecodeError and abort the task — the
+                # same policy the agent layer uses (agents.py).
+                text=True,
+                errors="replace",
+                cwd=str(workdir),
+                timeout=timeout,
+                # A gate check is usually a test/lint/build command that reads the
+                # repository, so an ambient GIT_DIR/GIT_WORK_TREE would have it
+                # validate a different tree than the worktree we are judging, and
+                # an ambient core.hooksPath would run someone else's script. Same
+                # isolation the agent subprocesses get — run-identity IPC
+                # included, since a gate command that invokes syncmill would
+                # otherwise adopt the parent's monitor identity and overwrite its
+                # envelope and result.json.
+                env=_gate_env(workdir),
+            )
+        except subprocess.TimeoutExpired:
+            return failed(f"timed out after {timeout:g}s")
+        except FileNotFoundError:
+            # FileNotFoundError covers both a missing binary and a missing cwd;
+            # check the workdir directly so the verdict names the real cause.
+            if not Path(workdir).exists():
+                return failed(f"working directory not found: {workdir}")
+            return failed(f"command not found: {argv[0]}")
+        except ValueError as exc:
+            # An invalid argument (e.g. an embedded NUL byte) makes subprocess.run
+            # raise ValueError, NOT OSError — it would otherwise escape every
+            # handler and crash the gate. A bad command is a failed check.
+            return failed(f"invalid command argument: {exc}")
+        except OSError as exc:
+            return failed(f"failed to launch: {exc}")
+        combined = (proc.stdout + proc.stderr).strip()
+        return GateCheck(
+            command,
+            passed=proc.returncode == 0,
+            exit_code=proc.returncode,
+            output=combined[-_OUTPUT_LIMIT:],
+            duration_seconds=round(monotonic() - start, 2),
+        )
+
+
+def build_gate(config: GateConfig, *, total_timeout_seconds: float | None = None) -> QualityGate | None:
+    """The gate described by ``config``, or ``None`` when no commands are
+    configured — the disabled default, where strategies skip gating entirely and
+    behavior is unchanged."""
+    if not config.commands:
+        return None
+    return CommandGate(config.commands, config.timeout_seconds, total_timeout_seconds=total_timeout_seconds)

syncmill/gateway.py

@@ -0,0 +1,234 @@
+"""Read-only MCP gateway over syncmill's ``shared`` memory + work-board (#15, Phase 2).
+
+A *one-way* (read-only) MCP surface that lets external/interactive MCP clients
+(Claude Code/Desktop, Cursor, …) READ syncmill's accumulated ``shared`` knowledge
+AND its work-board WITHOUT making syncmill's agents MCP-aware. The core invariant is
+untouched: agents never touch MCP and the Supervisor remains the sole *writer*; this
+gateway is a separate, non-agent, read-only *consumer*.
+
+Six read-only tools, no write/delete/index tool: ``shared_search`` / ``shared_read``
+/ ``shared_stats`` are locked to the ``shared`` namespace (never an agent's private
+``agent-runtime:*`` scope — see the isolation guard in ``SyncmillMemory.get_shared``);
+``board_list`` / ``board_get`` / ``board_stats`` (Phase 2) read the work-board when it
+is enabled, and report disabled-vs-unavailable when it is not.
+
+All memtomem access flows through ``SyncmillMemory`` and all board access through the
+``Board`` store (both advisory/best-effort here), so a broken or unavailable backend
+degrades gracefully — the server still starts and the tools report "currently
+unavailable" rather than crashing.
+"""
+
+from __future__ import annotations
+
+from mcp.server.mcpserver import MCPServer
+
+from syncmill.board import (
+    Board,
+    BoardError,
+    WorkState,
+    render_board,
+    render_board_stats,
+    render_item,
+)
+from syncmill.memory import SyncmillMemory
+
+SERVER_NAME = "syncmill-shared"
+INSTRUCTIONS = (
+    "Read-only gateway over syncmill's shared agent memory and work-board. Use "
+    "shared_search / shared_read / shared_stats for shared knowledge, and "
+    "board_list / board_get / board_stats to READ the work-board (items, an item's "
+    "detail + audit history, and team-health stats). The surface is read-only — it "
+    "cannot write memory or the board, and cannot read any agent's private scope."
+)
+
+DEFAULT_TOP_K = 10
+MAX_TOP_K = 50
+DEFAULT_BOARD_LIMIT = 50
+MAX_BOARD_LIMIT = 200
+#: The valid `state` filter values for board_list — derived from the work-item state
+#: machine so a client-supplied bad state is a clear ARGUMENT error, not a board outage.
+_VALID_BOARD_STATES = tuple(s.value for s in WorkState)
+
+_UNAVAILABLE = "shared memory is currently unavailable"
+#: The board_* tools always exist (a stable 6-tool surface), but report this when
+#: the server was started without the board enabled — distinct from a backend error.
+_BOARD_DISABLED = "the work-board is not enabled on this server"
+_BOARD_UNAVAILABLE = "the work-board is currently unavailable"
+
+
+def build_gateway(
+    memory: SyncmillMemory,
+    *,
+    board: Board | None = None,
+    board_error: str | None = None,
+) -> MCPServer:
+    """Construct the read-only MCP server (without running it).
+
+    Host/port are NOT construction-time concerns on the mcp 2.0 SDK: they are
+    ``mcp.run(transport="streamable-http", host=..., port=...)`` kwargs, and the
+    SDK computes its DNS-rebinding ``transport_security`` policy from the host
+    actually passed at run time (loopback hosts get automatic protection), so the
+    old stale-policy hazard of mutating settings after construction is structurally
+    gone. The CLI owns transport selection.
+
+    ``memory`` is injected (not built here) so tests can pass a fake-store-backed
+    ``SyncmillMemory`` with no monkeypatching, and so the CLI owns its lifetime.
+    The tools read memory's *per-call* return value (``None`` == backend failure)
+    to choose their message — they never consult the sticky ``memory.degraded``
+    flag, so a healthy-empty result is never mislabeled "unavailable".
+
+    ``board`` is the optional Phase-2 work-board (read-only). The board_* tools are
+    registered UNCONDITIONALLY — the surface is a stable six tools so the exact-set
+    regression guard never depends on whether the board is enabled. When ``board is
+    None`` they report ``_BOARD_DISABLED`` (genuinely off) UNLESS ``board_error`` is
+    set — i.e. the board WAS enabled but failed to open — in which case they report
+    ``_BOARD_UNAVAILABLE: <error>``, preserving the disabled-vs-broken distinction for
+    clients (mirrors the shared tools' healthy-empty-vs-unavailable split) while
+    keeping the shared-memory gateway alive. Like the shared tools they preserve
+    read-only + no-auth (no board-write tool exists). The board is sqlite-backed and
+    SYNCHRONOUS; its reads are quick, so calling them directly inside the async MCP
+    handlers is fine (no thread offload needed)."""
+    mcp = MCPServer(SERVER_NAME, instructions=INSTRUCTIONS)
+
+    def _board_or_message() -> Board | str:
+        """The board_* tools' shared guard: the usable ``Board`` (a narrowed
+        reference type checkers can see, unlike a bare None-check on the closed-over
+        ``Board | None``), else the right message — ``_BOARD_UNAVAILABLE`` for an
+        enabled-but-broken board (an error was reported), ``_BOARD_DISABLED`` for a
+        genuinely-off one."""
+        if board is not None:
+            return board
+        return f"{_BOARD_UNAVAILABLE}: {board_error}" if board_error else _BOARD_DISABLED
+
+    @mcp.tool()
+    async def shared_search(query: str, top_k: int = DEFAULT_TOP_K) -> str:
+        """Search syncmill's shared memory and return ranked excerpts.
+
+        Args:
+            query: Natural-language search query.
+            top_k: Maximum number of results to return (clamped to 1..50).
+        """
+        # Clamp untrusted input — an unauthenticated client must not be able to
+        # request an unbounded / oversized search.
+        top_k = max(1, min(int(top_k), MAX_TOP_K))
+        hits = await memory.search_shared(query, top_k=top_k)
+        if hits is None:
+            return _UNAVAILABLE
+        if not hits:
+            return "No matches in shared memory."
+        lines = [
+            f"{i}. [score {r.get('score', 0):.2f}] {r.get('source', 'unknown')} "
+            f"(id: {r.get('id', '?')})\n   {r.get('content', '')[:300]}"
+            for i, r in enumerate(hits, 1)
+        ]
+        return "\n".join(lines)
+
+    @mcp.tool()
+    async def shared_read(chunk_id: str) -> str:
+        """Read the full content of one shared-memory chunk by its id.
+
+        Args:
+            chunk_id: The chunk id (as shown in shared_search results).
+        """
+        read = await memory.get_shared(chunk_id)
+        if read.status == "unavailable":
+            # A backend failure on THIS call (or a refused scoped view) — never
+            # reported as data absence (#169).
+            return _UNAVAILABLE
+        chunk = read.chunk
+        if read.status != "found" or chunk is None:
+            # Covers missing, malformed, and non-shared ids alike — all "not
+            # found" from a read-only shared consumer's point of view (the
+            # privacy contract: a private chunk's existence is never disclosed).
+            return f"Chunk {chunk_id} not found in shared memory."
+        header = [
+            f"## Chunk {chunk.get('id', chunk_id)}",
+            f"- Source: {chunk.get('source', 'unknown')}",
+        ]
+        tags = ", ".join(chunk.get("tags") or [])
+        if tags:
+            header.append(f"- Tags: {tags}")
+        return "\n".join(header) + f"\n\n{chunk.get('content', '')}"
+
+    @mcp.tool()
+    async def shared_stats() -> str:
+        """Report how many chunks are in syncmill's shared memory."""
+        stats = await memory.shared_stats()
+        if stats is None:
+            return _UNAVAILABLE
+        return f"shared: {stats['chunk_count']} chunks"
+
+    @mcp.tool()
+    async def board_list(
+        state: str | None = None,
+        goal: str | None = None,
+        limit: int = DEFAULT_BOARD_LIMIT,
+    ) -> str:
+        """List work-board items (read-only), MOST-RECENT-first by creation order.
+
+        Args:
+            state: Optional state filter (planned/running/blocked/review/done).
+            goal: Optional goal filter.
+            limit: Maximum items to return (clamped to 1..200).
+        """
+        bd = _board_or_message()
+        if isinstance(bd, str):
+            return bd
+        # A bad `state` filter is a CLIENT argument error, not a backend outage —
+        # validate it up front and return a corrective message (with the valid set),
+        # so the LLM fixes the argument rather than concluding the board is down.
+        if state is not None and state not in _VALID_BOARD_STATES:
+            return (
+                f"Unknown state {state!r}. Valid states: "
+                f"{', '.join(_VALID_BOARD_STATES)}."
+            )
+        limit = max(1, min(int(limit), MAX_BOARD_LIMIT))
+        try:
+            # Sorted newest-first and bounded IN SQL: only `limit` rows are
+            # fetched and converted (#167 — the old reversed-FIFO slice
+            # materialized the whole board on the event loop to answer
+            # limit=1). Newest-first because an LLM reading "current board
+            # state" needs recent work; a truncated read keeps the newest, never
+            # the oldest, items.
+            items = bd.list_recent(state=state, goal=goal, limit=limit)
+        except BoardError as exc:
+            # A genuine backend/db error (the state was already validated above).
+            return f"{_BOARD_UNAVAILABLE}: {exc}"
+        if not items:
+            return "No board items match."
+        return render_board(items)
+
+    @mcp.tool()
+    async def board_get(item_id: str) -> str:
+        """Read one work-board item in full — state, evidence, handoff, audit history.
+
+        Args:
+            item_id: The item id (as shown in board_list).
+        """
+        bd = _board_or_message()
+        if isinstance(bd, str):
+            return bd
+        try:
+            # `get` validates the id (a malformed/guessed id is not-found, not a probe)
+            # and returns None for a missing item; only a real db error raises.
+            item = bd.get(item_id)
+            if item is None:
+                return f"Board item {item_id} not found."
+            return render_item(item, bd.transitions(item_id))
+        except BoardError as exc:
+            return f"{_BOARD_UNAVAILABLE}: {exc}"
+
+    @mcp.tool()
+    async def board_stats() -> str:
+        """Report work-board team-health stats — state breakdown, redispatched work,
+        stale-lease reclaims, false-done, and stalled (aged blocked / human-required /
+        dropped-handoff) items."""
+        bd = _board_or_message()
+        if isinstance(bd, str):
+            return bd
+        try:
+            return render_board_stats(bd.stats())
+        except BoardError as exc:
+            return f"{_BOARD_UNAVAILABLE}: {exc}"
+
+    return mcp

syncmill/git_env.py

@@ -0,0 +1,99 @@
+"""Safe child environments for Git operations bound to an explicit checkout."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+
+# Git documents these variables as repository, worktree, index, ref namespace,
+# shallow-boundary, or object-database routing controls. An ambient value can
+# make a command with an explicit cwd read or mutate a different repository.
+GIT_REPOSITORY_ROUTING_ENV = frozenset(
+    {
+        "GIT_DIR",
+        "GIT_WORK_TREE",
+        "GIT_COMMON_DIR",
+        "GIT_INDEX_FILE",
+        "GIT_OBJECT_DIRECTORY",
+        "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+        "GIT_NAMESPACE",
+        "GIT_SHALLOW_FILE",
+        "GIT_REPLACE_REF_BASE",
+        "GIT_CEILING_DIRECTORIES",
+        "GIT_DISCOVERY_ACROSS_FILESYSTEM",
+    }
+)
+
+
+# Git also accepts configuration through the environment, and configuration can
+# execute code: core.hooksPath points at scripts git runs itself, include.path
+# pulls in an arbitrary config file, and alias.<name> entries beginning with "!"
+# are shell commands. An ambient value therefore survives an explicit cwd the way
+# the routing variables above do — it does not redirect *which* repository is
+# read, it redirects what running a command in that repository *does*. syncmill
+# runs git inside worktrees an agent can write to, so these are stripped too.
+#
+# GIT_CONFIG_KEY_<n>/GIT_CONFIG_VALUE_<n> are numbered, hence the prefix match in
+# is_git_routing_var. Variables that merely *configure* an external helper the
+# user legitimately relies on (GIT_SSH_COMMAND, GIT_ASKPASS, GIT_EXEC_PATH) are
+# deliberately kept: stripping them breaks real authentication and custom git
+# installs, and unlike the above they are not a syncmill-introduced surface.
+GIT_CONFIG_INJECTION_ENV = frozenset(
+    {
+        "GIT_CONFIG",
+        "GIT_CONFIG_GLOBAL",
+        "GIT_CONFIG_SYSTEM",
+        "GIT_CONFIG_PARAMETERS",
+        "GIT_CONFIG_COUNT",
+    }
+)
+
+# Git also lets the environment redefine what a PATHSPEC means, which silently
+# changes the answer to a question rather than where it is asked. syncmill asks
+# git two security-relevant pathspec questions — is this state root ignored
+# (`check-ignore`), is this identity marker tracked (`ls-files`) — and both
+# read as a benign "no" when the pathspec stops meaning what the caller wrote:
+# GIT_LITERAL_PATHSPECS turns `:(icase)…` magic into a filename nothing
+# matches, and the glob/icase toggles reinterpret a plain path. Stripped for
+# the same reason as the routing variables above.
+GIT_PATHSPEC_SEMANTICS_ENV = frozenset(
+    {
+        "GIT_LITERAL_PATHSPECS",
+        "GIT_GLOB_PATHSPECS",
+        "GIT_NOGLOB_PATHSPECS",
+        "GIT_ICASE_PATHSPECS",
+    }
+)
+
+_NUMBERED_CONFIG_PREFIXES = ("GIT_CONFIG_KEY_", "GIT_CONFIG_VALUE_")
+
+
+def is_git_routing_var(key: str) -> bool:
+    """True if ``key`` routes a Git command's repository, injects its config, or
+    redefines pathspec semantics.
+
+    The single predicate behind every isolated child environment syncmill builds
+    (git calls here, agent and gate subprocesses in ``agents.py``/``gates.py``),
+    so the three can't drift on what "isolated" means.
+    """
+    return (
+        key in GIT_REPOSITORY_ROUTING_ENV
+        or key in GIT_CONFIG_INJECTION_ENV
+        or key in GIT_PATHSPEC_SEMANTICS_ENV
+        or key.startswith(_NUMBERED_CONFIG_PREFIXES)
+    )
+
+
+def isolated_git_env(
+    overrides: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """Copy the process environment without ambient Git routing or config injection."""
+    env = {
+        key: value
+        for key, value in os.environ.items()
+        if not is_git_routing_var(key)
+    }
+    if overrides:
+        env.update(overrides)
+    return env