devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/consolidation/synthesizer.py

@@ -0,0 +1,87 @@
+"""
+LLM-powered consolidation synthesizer.
+
+Uses the same pattern as theta_synthesis.py: builds a prompt from
+ReasoningEntries + DivergenceSignals, sends to claude-haiku, returns
+a ConsolidationDraft. Gated by DEVTORCH_DISABLE env var.
+Never raises — errors return a skip result.
+"""
+from __future__ import annotations
+
+import dataclasses
+import os
+from typing import List
+
+
+@dataclasses.dataclass
+class ConsolidationDraft:
+    decision: str
+    decision_trace: str
+    model: str
+    tokens_used: int
+    skipped: bool = False
+    skip_reason: str = ""
+
+
+def synthesise_consolidation(
+    concept: str,
+    reasoning_entries: list,
+    divergence_signals: list,
+    model: str = "claude-haiku-4-5-20251001",
+) -> ConsolidationDraft:
+    """Run LLM synthesis over reasoning entries + divergence signals."""
+    if os.environ.get("DEVTORCH_DISABLE"):
+        return ConsolidationDraft(decision="", decision_trace="", model=model, tokens_used=0,
+                                  skipped=True, skip_reason="DEVTORCH_DISABLE set")
+    try:
+        import anthropic
+    except ImportError:
+        return ConsolidationDraft(decision="", decision_trace="", model=model, tokens_used=0,
+                                  skipped=True, skip_reason="anthropic SDK not installed")
+
+    prompt = _build_prompt(concept, reasoning_entries, divergence_signals)
+    try:
+        client = anthropic.Anthropic()
+        response = client.messages.create(
+            model=model,
+            max_tokens=512,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        text = response.content[0].text if response.content else ""
+        tokens = response.usage.input_tokens + response.usage.output_tokens
+        decision, trace = _parse_response(text)
+        return ConsolidationDraft(decision=decision, decision_trace=trace,
+                                  model=model, tokens_used=tokens)
+    except Exception as exc:
+        return ConsolidationDraft(decision="", decision_trace="", model=model, tokens_used=0,
+                                  skipped=True, skip_reason=str(exc))
+
+
+def _build_prompt(concept: str, reasoning_entries: list, divergence_signals: list) -> str:
+    entry_lines = "\n".join(
+        f"  [{i+1}] agent={e.agent_id} conf={e.confidence:.2f}: {e.reasoning_text[:200]}"
+        for i, e in enumerate(reasoning_entries[:10])
+    )
+    signal_lines = "\n".join(
+        f"  [{s.signal_type}/{s.severity}] {s.description}"
+        for s in divergence_signals[:5]
+    )
+    return (
+        f"You are a governance analyst. Agents have diverged on concept: '{concept}'.\n\n"
+        f"Agent reasoning:\n{entry_lines or '  (none)'}\n\n"
+        f"Divergence signals:\n{signal_lines or '  (none)'}\n\n"
+        "Write two sections:\n"
+        "DECISION: A 1-2 sentence consolidated position that resolves the divergence.\n"
+        "TRACE: A 1-2 sentence explanation of WHY this consolidation was reached.\n\n"
+        "Format exactly:\nDECISION: <text>\nTRACE: <text>"
+    )
+
+
+def _parse_response(text: str) -> tuple[str, str]:
+    decision, trace = "", ""
+    for line in text.splitlines():
+        if line.startswith("DECISION:"):
+            decision = line[len("DECISION:"):].strip()
+        elif line.startswith("TRACE:"):
+            trace = line[len("TRACE:"):].strip()
+    return decision or text[:200], trace or "LLM synthesis"

devtorch_core/consolidation/workflow.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import dataclasses
+import datetime as _dt
+import json
+import uuid
+from pathlib import Path
+from typing import List, Optional
+
+from devtorch_core.divergence.detector import DivergenceSignal
+
+_CONSOLIDATIONS_DIR = "consolidations"
+
+_SEVERITY_ORDER = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
+
+
+@dataclasses.dataclass
+class ConsolidationRecord:
+    """
+    Durable record of a consolidation event.
+
+    decision_trace is DevTorch's own reasoning — WHY it chose to block,
+    escalate to human, or auto-resolve.
+    """
+    record_id: str
+    concept: str
+    signals: List[dict]          # serialised DivergenceSignal dicts
+    state: str                   # drafting | pending_human | auto_resolved | resolved | blocked
+    decision: str                # consolidated position text
+    decision_trace: str          # DevTorch's reasoning for its action
+    agents_involved: List[str]
+    human_comments: List[dict]
+    created_at: str
+    resolved_at: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ConsolidationRecord":
+        known = {f.name for f in dataclasses.fields(cls)}
+        return cls(**{k: v for k, v in d.items() if k in known})
+
+
+class ConsolidationWorkflow:
+    """
+    State machine for agent reasoning consolidation.
+
+    Transitions:
+      drafting → pending_human  (HIGH or MEDIUM severity divergence)
+      drafting → auto_resolved  (LOW severity only)
+      drafting → blocked        (signal type E: consensus contradiction)
+      pending_human → resolved  (human provides decision via add_human_comment)
+    """
+
+    def __init__(self, repo) -> None:
+        self._repo = repo
+        self._gcc_dir = repo.gcc_dir
+        self._dir = self._gcc_dir / _CONSOLIDATIONS_DIR
+        self._dir.mkdir(exist_ok=True)
+
+    def start(
+        self,
+        concept: str,
+        signals: List[DivergenceSignal],
+    ) -> ConsolidationRecord:
+        """Create a ConsolidationRecord and determine initial state from signals."""
+        record_id = str(uuid.uuid4())
+        now = _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+
+        all_agents = list({aid for s in signals for aid in s.agent_ids})
+        max_severity = self._max_severity(signals)
+
+        # E-type signals always block
+        e_signals = [s for s in signals if s.signal_type == "E"]
+        if e_signals:
+            state = "blocked"
+            decision = ""
+            trace = (
+                f"Blocked: {len(e_signals)} consensus contradiction(s) detected on '{concept}'. "
+                "Human review required before proceeding."
+            )
+        elif max_severity == "LOW":
+            state = "auto_resolved"
+            decision = self._auto_decision(concept, signals)
+            trace = (
+                f"Auto-resolved: all signals LOW severity on '{concept}'. "
+                f"Signals: {', '.join(s.signal_type for s in signals)}. "
+                "No human intervention required."
+            )
+        else:
+            state = "pending_human"
+            decision = ""
+            trace = (
+                f"Escalated to human: {max_severity} severity signal(s) detected on '{concept}'. "
+                f"Signal types: {', '.join(s.signal_type + '(' + s.severity + ')' for s in signals)}. "
+                "Awaiting human comment or resolution."
+            )
+
+        record = ConsolidationRecord(
+            record_id=record_id,
+            concept=concept,
+            signals=[dataclasses.asdict(s) for s in signals],
+            state=state,
+            decision=decision,
+            decision_trace=trace,
+            agents_involved=all_agents,
+            human_comments=[],
+            created_at=now,
+            resolved_at=now if state == "auto_resolved" else None,
+        )
+        self._save(record)
+        return record
+
+    def add_human_comment(
+        self,
+        record_id: str,
+        author: str,
+        comment: str,
+        decision: Optional[str] = None,
+    ) -> ConsolidationRecord:
+        """Add a human comment and optionally resolve the record."""
+        record = self.get(record_id)
+        if record is None:
+            raise ValueError(f"ConsolidationRecord {record_id!r} not found")
+
+        now = _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+        record.human_comments.append({"author": author, "comment": comment, "timestamp": now})
+
+        if decision is not None:
+            record.decision = decision
+            record.state = "resolved"
+            record.resolved_at = now
+            record.decision_trace += f"\nResolved by {author} at {now[:19]}: {decision}"
+
+        self._save(record)
+        return record
+
+    def get(self, record_id: str) -> Optional[ConsolidationRecord]:
+        path = self._dir / f"{record_id}.json"
+        if not path.exists():
+            return None
+        try:
+            return ConsolidationRecord.from_dict(json.loads(path.read_text(encoding="utf-8")))
+        except (json.JSONDecodeError, TypeError):
+            return None
+
+    def list_for_concept(self, concept: str) -> List[ConsolidationRecord]:
+        results = []
+        for f in self._dir.glob("*.json"):
+            try:
+                d = json.loads(f.read_text(encoding="utf-8"))
+                if d.get("concept") == concept:
+                    results.append(ConsolidationRecord.from_dict(d))
+            except (json.JSONDecodeError, TypeError):
+                continue
+        return sorted(results, key=lambda r: r.created_at, reverse=True)
+
+    def _save(self, record: ConsolidationRecord) -> None:
+        path = self._dir / f"{record.record_id}.json"
+        path.write_text(json.dumps(record.to_dict(), indent=2) + "\n", encoding="utf-8")
+
+    @staticmethod
+    def _max_severity(signals: List[DivergenceSignal]) -> str:
+        if not signals:
+            return "LOW"
+        return min(signals, key=lambda s: _SEVERITY_ORDER.get(s.severity, 99)).severity
+
+    @staticmethod
+    def _auto_decision(concept: str, signals: List[DivergenceSignal]) -> str:
+        return (
+            f"No high-severity divergence detected on '{concept}'. "
+            "Agents may proceed with existing sensitivity signals. "
+            f"Low-severity signals noted: {', '.join(s.description[:80] for s in signals)}."
+        )

devtorch_core/daemon/__init__.py

@@ -0,0 +1,27 @@
+"""DevTorch background daemon (S26).
+
+Provides a long-running filesystem watcher that emits `fs_change` events to
+`.GCC/events.log.jsonl` without requiring IDE hooks.
+"""
+
+from devtorch_core.daemon.supervisor import (
+    PID_FILE_NAME,
+    LOG_FILE_NAME,
+    start_daemon,
+    stop_daemon,
+    daemon_status,
+    daemon_logs,
+    _run_daemon,
+)
+from devtorch_core.daemon.watcher import ProjectWatcher
+
+__all__ = [
+    "PID_FILE_NAME",
+    "LOG_FILE_NAME",
+    "start_daemon",
+    "stop_daemon",
+    "daemon_status",
+    "daemon_logs",
+    "_run_daemon",
+    "ProjectWatcher",
+]

devtorch_core/daemon/supervisor.py

@@ -0,0 +1,293 @@
+"""
+Background daemon supervisor for the DevTorch CLI (S26).
+
+The daemon runs a filesystem watcher in the background and optionally the
+unified DevTorch server.  It writes its PID to `.GCC/devtorch_daemon.pid` and
+logs to `.GCC/devtorch_daemon.log`.
+
+CLI commands:
+    devtorch daemon start    # idempotent
+    devtorch daemon stop
+    devtorch daemon status
+    devtorch daemon logs
+"""
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+
+PID_FILE_NAME = "devtorch_daemon.pid"
+LOG_FILE_NAME = "devtorch_daemon.log"
+
+
+def _gcc_dir(project_root: Path) -> Path:
+    """Resolve the .GCC directory for a project root, ensuring it exists."""
+    from devtorch_core import GCCRepository
+
+    repo = GCCRepository.at(project_root)
+    if not repo.is_initialized():
+        raise RuntimeError(f"No initialized .GCC/ found at {project_root}")
+    return repo.gcc_dir
+
+
+def _read_pid(gcc_dir: Path) -> Optional[int]:
+    """Read the daemon PID from the PID file, if present and valid."""
+    pid_path = gcc_dir / PID_FILE_NAME
+    if not pid_path.exists():
+        return None
+    try:
+        return int(pid_path.read_text(encoding="utf-8").strip())
+    except Exception:
+        return None
+
+
+def _is_alive(pid: int) -> bool:
+    """Check whether a process with the given PID is still running."""
+    try:
+        os.kill(pid, 0)
+        return True
+    except (OSError, ProcessLookupError):
+        return False
+
+
+def _wait_for_pid(
+    gcc_dir: Path,
+    timeout: float = 2.0,
+    interval: float = 0.1,
+) -> Optional[int]:
+    """Wait for a daemon PID file to appear and refer to a live process."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        pid = _read_pid(gcc_dir)
+        if pid is not None and _is_alive(pid):
+            return pid
+        time.sleep(interval)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# daemon process entry point
+# ---------------------------------------------------------------------------
+
+
+def _run_daemon(
+    project_root: Optional[str] = None,
+    run_server: bool = False,
+    host: str = "127.0.0.1",
+    port: int = 8765,
+    stop_event: Optional[threading.Event] = None,
+) -> None:
+    """Entry point for the daemon process.
+
+    This function is invoked by the subprocess spawned in `start_daemon`.
+    It writes the PID file, starts the project watcher, and optionally runs the
+    unified server.  The process keeps running until it receives SIGTERM/SIGINT.
+    """
+    if project_root is None:
+        project_root = os.environ.get("DEVTORCH_DAEMON_ROOT", str(Path.cwd()))
+    root = Path(project_root).resolve()
+
+    gcc_dir = _gcc_dir(root)
+    pid_path = gcc_dir / PID_FILE_NAME
+    pid_path.write_text(str(os.getpid()), encoding="utf-8")
+
+    if stop_event is None:
+        stop_event = threading.Event()
+
+    def _handle_signal(signum: int, frame: Any) -> None:
+        stop_event.set()
+
+    try:
+        signal.signal(signal.SIGTERM, _handle_signal)
+        signal.signal(signal.SIGINT, _handle_signal)
+    except Exception:
+        # May fail in some test environments; continue without signal handling.
+        pass
+
+    try:
+        from devtorch_core.daemon.watcher import ProjectWatcher
+
+        watcher = ProjectWatcher(root)
+        watcher.start()
+    except Exception as exc:
+        print(f"Failed to start watcher: {exc}", file=sys.stderr)
+        pid_path.unlink(missing_ok=True)
+        raise
+
+    server_thread: Optional[threading.Thread] = None
+    if run_server:
+        try:
+            from devtorch_core.serve import serve_all
+
+            def _serve() -> None:
+                try:
+                    serve_all(host=host, port=port, gcc_path=str(root))
+                except Exception as exc:
+                    print(f"Unified server exited: {exc}", file=sys.stderr)
+
+            server_thread = threading.Thread(target=_serve, daemon=True)
+            server_thread.start()
+        except Exception as exc:
+            print(f"Failed to start unified server: {exc}", file=sys.stderr)
+
+    print(f"DevTorch daemon started (PID {os.getpid()}) watching {root}")
+    sys.stdout.flush()
+
+    try:
+        while not stop_event.is_set():
+            stop_event.wait(1.0)
+    finally:
+        watcher.stop()
+        print(f"DevTorch daemon stopped (PID {os.getpid()})")
+        sys.stdout.flush()
+        pid_path.unlink(missing_ok=True)
+
+
+# ---------------------------------------------------------------------------
+# process spawning
+# ---------------------------------------------------------------------------
+
+
+def _build_daemon_command(project_root: Path, run_server: bool, host: str, port: int) -> list[str]:
+    """Build the command used to spawn the daemon subprocess."""
+    code = (
+        "from devtorch_core.daemon.supervisor import _run_daemon; "
+        f"_run_daemon(project_root={str(project_root)!r}, run_server={run_server!r}, "
+        f"host={host!r}, port={port!r})"
+    )
+    return [sys.executable, "-c", code]
+
+
+# ---------------------------------------------------------------------------
+# public control functions
+# ---------------------------------------------------------------------------
+
+
+def start_daemon(
+    project_root: Path,
+    run_server: bool = False,
+    host: str = "127.0.0.1",
+    port: int = 8765,
+    popen_factory: Optional[Callable[..., Any]] = None,
+) -> tuple[bool, str]:
+    """Start the daemon if it is not already running.
+
+    Returns (success, message).  If the daemon is already running, reports
+    the existing PID without starting a new process (idempotent).
+    """
+    try:
+        gcc_dir = _gcc_dir(project_root)
+    except RuntimeError as exc:
+        return False, str(exc)
+
+    pid = _read_pid(gcc_dir)
+    if pid is not None and _is_alive(pid):
+        return True, f"DevTorch daemon already running (PID {pid})"
+
+    log_path = gcc_dir / LOG_FILE_NAME
+    cmd = _build_daemon_command(project_root, run_server, host, port)
+
+    env = dict(os.environ)
+    env["DEVTORCH_DAEMON_ROOT"] = str(project_root)
+
+    if popen_factory is None:
+        popen_factory = subprocess.Popen
+
+    with open(log_path, "a", encoding="utf-8") as log_f:
+        process = popen_factory(
+            cmd,
+            stdout=log_f,
+            stderr=subprocess.STDOUT,
+            stdin=subprocess.DEVNULL,
+            start_new_session=True,
+            env=env,
+        )
+
+    new_pid = _wait_for_pid(gcc_dir)
+    if new_pid is not None:
+        return True, f"DevTorch daemon started (PID {new_pid})"
+    return False, (
+        f"Daemon subprocess launched (PID {process.pid}) but PID file "
+        f"was not written to {gcc_dir / PID_FILE_NAME}"
+    )
+
+
+def stop_daemon(project_root: Path) -> tuple[bool, str]:
+    """Stop the daemon and clean up its PID file.
+
+    Returns (success, message).  If no daemon is running, returns a message
+    explaining that and cleans up any stale PID file.
+    """
+    try:
+        gcc_dir = _gcc_dir(project_root)
+    except RuntimeError as exc:
+        return False, str(exc)
+
+    pid = _read_pid(gcc_dir)
+    pid_path = gcc_dir / PID_FILE_NAME
+
+    if pid is None:
+        return False, "DevTorch daemon is not running"
+
+    if not _is_alive(pid):
+        pid_path.unlink(missing_ok=True)
+        return False, f"Daemon PID {pid} is not alive; cleaned up stale PID file"
+
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except (OSError, ProcessLookupError):
+        pid_path.unlink(missing_ok=True)
+        return False, f"Failed to signal daemon PID {pid}; cleaned up PID file"
+
+    for _ in range(20):
+        if not _is_alive(pid):
+            break
+        time.sleep(0.1)
+
+    if _is_alive(pid):
+        try:
+            os.kill(pid, signal.SIGKILL)
+            time.sleep(0.1)
+        except (OSError, ProcessLookupError):
+            pass
+
+    pid_path.unlink(missing_ok=True)
+    return True, f"DevTorch daemon stopped (PID {pid})"
+
+
+def daemon_status(project_root: Path) -> dict[str, Any]:
+    """Return a status dict for the daemon."""
+    try:
+        gcc_dir = _gcc_dir(project_root)
+    except RuntimeError as exc:
+        return {"running": False, "pid": None, "log_path": None, "error": str(exc)}
+
+    pid = _read_pid(gcc_dir)
+    log_path = gcc_dir / LOG_FILE_NAME
+    if pid is None:
+        return {"running": False, "pid": None, "log_path": str(log_path)}
+    alive = _is_alive(pid)
+    if not alive:
+        return {"running": False, "pid": pid, "log_path": str(log_path)}
+    return {"running": True, "pid": pid, "log_path": str(log_path)}
+
+
+def daemon_logs(project_root: Path, lines: int = 50) -> list[str]:
+    """Return the last N lines of the daemon log file."""
+    try:
+        gcc_dir = _gcc_dir(project_root)
+    except RuntimeError:
+        return []
+
+    log_path = gcc_dir / LOG_FILE_NAME
+    if not log_path.exists():
+        return []
+    with log_path.open("r", encoding="utf-8") as f:
+        return f.read().splitlines()[-lines:]