devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/session/disagreement.py

@@ -0,0 +1,188 @@
+"""HITL disagreement resolution for multi-agent sessions."""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as _dt
+import json
+import re
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from devtorch_core import GCCRepository
+from devtorch_core.hitl import HITLChannel, HITLOrchestrator
+
+
+@dataclasses.dataclass
+class DisagreementRecord:
+    """
+    Durable record of a disagreement between agents on a concept.
+
+    Positions are free-form agent stances (e.g. a disclosure level or a design
+    choice) plus a confidence score.  The resolver can auto-consolidate, ask
+    a human, or escalate.
+    """
+
+    disagreement_id: str
+    session_id: str
+    concept: str
+    positions: List[Dict[str, Any]]  # [{agent_id, position, confidence}, ...]
+    state: str  # "open" | "consolidated" | "escalated"
+    resolution: str
+    created_at: str
+    updated_at: str
+
+    def to_dict(self) -> dict:
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DisagreementRecord":
+        known = {f.name for f in dataclasses.fields(cls)}
+        return cls(**{k: v for k, v in d.items() if k in known})
+
+
+class DisagreementResolver:
+    """
+    Records and resolves disagreements from multi-agent sessions.
+
+    Persisted layout: `.GCC/sessions/disagreements/<disagreement_id>.json`
+    """
+
+    def __init__(self, gcc_dir: Path, channels: Optional[List[HITLChannel]] = None) -> None:
+        self._gcc_dir = Path(gcc_dir)
+        self._dir = self._gcc_dir / "sessions" / "disagreements"
+        self._channels = channels or []
+
+    def _ensure_dir(self) -> None:
+        self._dir.mkdir(parents=True, exist_ok=True)
+
+    def _persist(self, record: DisagreementRecord) -> Path:
+        self._ensure_dir()
+        path = self._dir / f"{record.disagreement_id}.json"
+        path.write_text(
+            json.dumps(record.to_dict(), indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+        return path
+
+    def _load(self, disagreement_id: str) -> Optional[DisagreementRecord]:
+        path = self._dir / f"{disagreement_id}.json"
+        if not path.exists():
+            return None
+        try:
+            return DisagreementRecord.from_dict(
+                json.loads(path.read_text(encoding="utf-8"))
+            )
+        except (json.JSONDecodeError, TypeError, ValueError):
+            return None
+
+    def record_disagreement(
+        self,
+        session_id: str,
+        concept: str,
+        positions: List[Dict[str, Any]],
+    ) -> DisagreementRecord:
+        """Record a new disagreement and persist it."""
+        now = _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+        record = DisagreementRecord(
+            disagreement_id=str(uuid.uuid4()),
+            session_id=session_id,
+            concept=concept,
+            positions=positions,
+            state="open",
+            resolution="",
+            created_at=now,
+            updated_at=now,
+        )
+        self._persist(record)
+        return record
+
+    def list_disagreements(self, session_id: Optional[str] = None) -> List[DisagreementRecord]:
+        """Return all disagreements, optionally filtered by session_id."""
+        results: List[DisagreementRecord] = []
+        if not self._dir.exists():
+            return results
+        for f in sorted(self._dir.glob("*.json")):
+            try:
+                d = json.loads(f.read_text(encoding="utf-8"))
+                if session_id is not None and d.get("session_id") != session_id:
+                    continue
+                results.append(DisagreementRecord.from_dict(d))
+            except (json.JSONDecodeError, TypeError, ValueError):
+                continue
+        return results
+
+    def resolve(
+        self,
+        disagreement_id: str,
+        human_decision: Optional[str] = None,
+        channels: Optional[List[HITLChannel]] = None,
+    ) -> DisagreementRecord:
+        """
+        Resolve a disagreement.
+
+        - If *human_decision* is provided, record it as the consolidated resolution.
+        - Otherwise, if the disagreement needs human input, run the existing
+          HITLOrchestrator flow.  If the orchestrator returns a resolved/auto
+          resolved consolidation record, use its decision; otherwise escalate.
+        - If no human input is required, auto-consolidate by selecting the
+          highest-confidence position.
+        """
+        record = self._load(disagreement_id)
+        if record is None:
+            raise ValueError(f"Disagreement {disagreement_id!r} not found")
+
+        now = _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+
+        if human_decision is not None:
+            record.resolution = human_decision
+            record.state = "consolidated"
+        elif self.needs_human_input(record):
+            hitl_channels = channels if channels is not None else self._channels
+            # gcc_dir is the .GCC directory; GCCRepository expects the project root.
+            repo = GCCRepository(self._gcc_dir.parent)
+            orchestrator = HITLOrchestrator(repo, channels=hitl_channels, poll_attempts=1)
+            consolidation = orchestrator.run(record.concept)
+            if consolidation is not None and consolidation.state in ("resolved", "auto_resolved"):
+                record.resolution = consolidation.decision or ""
+                record.state = "consolidated"
+            else:
+                record.state = "escalated"
+        else:
+            best = max(
+                record.positions,
+                key=lambda p: float(p.get("confidence", 0.0)),
+            )
+            record.resolution = str(best.get("position", ""))
+            record.state = "consolidated"
+
+        record.updated_at = now
+        self._persist(record)
+        return record
+
+    def needs_human_input(self, disagreement: DisagreementRecord) -> bool:
+        """
+        Return True when the disagreement should be escalated to a human.
+
+        Triggers:
+        - confidence gap between the highest and lowest position > 0.3
+        - positions contain both PUBLIC and PRIVATE disclosure stances
+        """
+        positions = disagreement.positions
+        if not positions:
+            return False
+
+        confidences = [float(p.get("confidence", 0.0)) for p in positions]
+        if max(confidences) - min(confidences) > 0.3:
+            return True
+
+        public_seen = any(
+            re.search(r"\bPUBLIC\b", str(p.get("position", "")))
+            for p in positions
+        )
+        private_seen = any(
+            re.search(r"\bPRIVATE\b", str(p.get("position", "")))
+            for p in positions
+        )
+        return public_seen and private_seen

devtorch_core/session/models.py

@@ -0,0 +1,114 @@
+"""
+Sprint 28 — Session orchestration and sub-task planning models.
+
+Lightweight dataclasses for multi-agent sessions, subtasks, and agent role
+assignments.  All objects are plain dicts round-trippable via to_dict/from_dict
+so they can be stored as JSON under `.GCC/sessions/`.
+"""
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+from typing import Any, Dict, List
+
+
+# Session lifecycle statuses as string constants.
+class SessionStatus:
+    PENDING = "pending"
+    PLANNING = "planning"
+    ACTIVE = "active"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+# Module-level aliases for convenience.
+PENDING = SessionStatus.PENDING
+PLANNING = SessionStatus.PLANNING
+ACTIVE = SessionStatus.ACTIVE
+PAUSED = SessionStatus.PAUSED
+COMPLETED = SessionStatus.COMPLETED
+FAILED = SessionStatus.FAILED
+
+
+@dataclasses.dataclass
+class AgentAssignment:
+    agent_id: str
+    role: str
+    capabilities: List[str] = dataclasses.field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "AgentAssignment":
+        return cls(**data)
+
+
+@dataclasses.dataclass
+class Subtask:
+    subtask_id: str
+    session_id: str
+    description: str
+    dependencies: List[str] = dataclasses.field(default_factory=list)
+    status: str = PENDING
+    assigned_role: str = ""
+    concept: str = ""
+    assumptions: Dict[str, Any] = dataclasses.field(default_factory=dict)
+    created_at: str = dataclasses.field(default_factory=lambda: _now_iso())
+
+    def to_dict(self) -> dict:
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Subtask":
+        return cls(**data)
+
+
+@dataclasses.dataclass
+class Session:
+    session_id: str
+    name: str
+    problem: str
+    status: str = PENDING
+    agent_roles: List[AgentAssignment] = dataclasses.field(default_factory=list)
+    subtasks: List[Subtask] = dataclasses.field(default_factory=list)
+    assumptions: Dict[str, Any] = dataclasses.field(default_factory=dict)
+    created_at: str = dataclasses.field(default_factory=lambda: _now_iso())
+    updated_at: str = dataclasses.field(default_factory=lambda: _now_iso())
+
+    def to_dict(self) -> dict:
+        return {
+            "session_id": self.session_id,
+            "name": self.name,
+            "problem": self.problem,
+            "status": self.status,
+            "agent_roles": [a.to_dict() for a in self.agent_roles],
+            "subtasks": [s.to_dict() for s in self.subtasks],
+            "assumptions": dict(self.assumptions),
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Session":
+        return cls(
+            session_id=data["session_id"],
+            name=data["name"],
+            problem=data["problem"],
+            status=data["status"],
+            agent_roles=[AgentAssignment.from_dict(a) for a in data.get("agent_roles", [])],
+            subtasks=[Subtask.from_dict(s) for s in data.get("subtasks", [])],
+            assumptions=data.get("assumptions", {}),
+            created_at=data["created_at"],
+            updated_at=data["updated_at"],
+        )
+
+
+def _now_iso() -> str:
+    return dt.datetime.now(tz=dt.timezone.utc).isoformat()
+
+
+def is_terminal_status(status: str) -> bool:
+    """Return True if a session status is terminal."""
+    return status in (SessionStatus.COMPLETED, SessionStatus.FAILED)

devtorch_core/session/orchestrator.py

@@ -0,0 +1,182 @@
+"""
+Sprint 28 — Session orchestrator.
+
+Manages the lifecycle of a multi-agent session: creation, persistence under
+`.GCC/sessions/<id>.json`, updates, and closure.  When `DEVTORCH_SESSION_CLOUD_URL`
+is set, session metadata is also POSTed to that endpoint.  If the endpoint is
+unreachable, the orchestrator falls back to local storage and logs a
+`SESSION_CLOUD_FALLBACK` event to `.GCC/events.log.jsonl`.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, List, Optional
+
+from devtorch_core.gcc import GCCRepository
+from devtorch_core.storage import LocalFileBackend, StorageBackend
+
+from .models import AgentAssignment, Session, SessionStatus
+
+
+SESSION_DIR_NAME = "sessions"
+SESSION_COUNTER_FILE = ".counter"
+SESSION_CLOUD_URL_ENV = "DEVTORCH_SESSION_CLOUD_URL"
+SESSION_CLOUD_FALLBACK_EVENT = "SESSION_CLOUD_FALLBACK"
+
+
+class SessionOrchestrator:
+    """Create, persist, and update multi-agent sessions."""
+
+    def __init__(
+        self,
+        gcc_dir: str | Path,
+        backend: Optional[StorageBackend] = None,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        gcc_dir: Path to the `.GCC` directory for this project.
+        backend: Optional StorageBackend.  Defaults to LocalFileBackend.
+        """
+        self.gcc_dir = Path(gcc_dir)
+        self._repo = GCCRepository.at(self.gcc_dir.parent)
+        self._backend = backend if backend is not None else LocalFileBackend(self.gcc_dir)
+        self._sessions_key = SESSION_DIR_NAME
+
+    def _session_key(self, session_id: str) -> str:
+        return f"{self._sessions_key}/{session_id}.json"
+
+    def _counter_key(self) -> str:
+        return f"{self._sessions_key}/{SESSION_COUNTER_FILE}"
+
+    def _ensure_gcc(self) -> None:
+        """Initialize the `.GCC` repository if it has not been created yet."""
+        if not self._repo.is_initialized():
+            self._repo.init()
+
+    def _next_session_id(self, name: str, problem: str) -> str:
+        """Deterministic session ID based on content + counter (no wall-clock)."""
+        counter = 0
+        counter_key = self._counter_key()
+        if self._backend.exists(counter_key):
+            raw = self._backend.read_bytes(counter_key).decode("utf-8").strip()
+            try:
+                counter = int(raw)
+            except ValueError:
+                counter = 0
+        counter += 1
+        self._backend.write_bytes(counter_key, str(counter).encode("utf-8"))
+        content = f"session:{name}:{problem}:{counter}"
+        hash_part = hashlib.sha256(content.encode("utf-8")).hexdigest()[:16]
+        return f"s{counter:08x}-{hash_part}"
+
+    def _write_session(self, session: Session) -> None:
+        session.updated_at = _now_iso()
+        self._backend.write_bytes(
+            self._session_key(session.session_id),
+            json.dumps(session.to_dict(), indent=2, sort_keys=True).encode("utf-8"),
+        )
+
+    def _read_session(self, session_id: str) -> Session:
+        key = self._session_key(session_id)
+        if not self._backend.exists(key):
+            raise FileNotFoundError(f"Session not found: {session_id}")
+        data = json.loads(self._backend.read_bytes(key).decode("utf-8"))
+        return Session.from_dict(data)
+
+    def _log_cloud_fallback(self, session: Session, error: str) -> None:
+        """Log a SESSION_CLOUD_FALLBACK event to `.GCC/events.log.jsonl`."""
+        self._ensure_gcc()
+        self._repo._append_event(
+            event_type=SESSION_CLOUD_FALLBACK_EVENT,
+            payload={
+                "session_id": session.session_id,
+                "name": session.name,
+                "error": error,
+                "cloud_url": os.environ.get(SESSION_CLOUD_URL_ENV, ""),
+            },
+        )
+
+    def _post_to_cloud(self, session: Session) -> None:
+        """POST session metadata to the configured cloud URL if any."""
+        cloud_url = os.environ.get(SESSION_CLOUD_URL_ENV, "").strip()
+        if not cloud_url:
+            return
+        try:
+            data = json.dumps(session.to_dict(), sort_keys=True).encode("utf-8")
+            req = urllib.request.Request(
+                cloud_url,
+                data=data,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=5) as resp:
+                resp.read()
+        except Exception as exc:  # noqa: BLE001
+            self._log_cloud_fallback(session, str(exc))
+
+    def start_session(
+        self,
+        name: str,
+        problem: str,
+        agent_assignments: Optional[List[AgentAssignment]] = None,
+    ) -> Session:
+        """Create a new session and persist it locally (and to the cloud if configured)."""
+        self._ensure_gcc()
+        session_id = self._next_session_id(name, problem)
+        session = Session(
+            session_id=session_id,
+            name=name,
+            problem=problem,
+            status=SessionStatus.PLANNING,
+            agent_roles=agent_assignments or [],
+        )
+        self._write_session(session)
+        self._post_to_cloud(session)
+        return session
+
+    def list_sessions(self) -> List[Session]:
+        """Return all stored sessions as `Session` objects."""
+        keys = self._backend.list_keys(self._sessions_key)
+        sessions: List[Session] = []
+        for key in keys:
+            if key.endswith(".json") and not key.endswith(f"/{SESSION_COUNTER_FILE}"):
+                try:
+                    data = json.loads(self._backend.read_bytes(key).decode("utf-8"))
+                    sessions.append(Session.from_dict(data))
+                except (json.JSONDecodeError, OSError):
+                    continue
+        return sessions
+
+    def get_session(self, session_id: str) -> Session:
+        """Load a session by ID."""
+        return self._read_session(session_id)
+
+    def update_session(self, session_id: str, **kwargs: Any) -> Session:
+        """Update a session's fields and persist the change."""
+        session = self._read_session(session_id)
+        for key, value in kwargs.items():
+            if hasattr(session, key):
+                setattr(session, key, value)
+        self._write_session(session)
+        self._post_to_cloud(session)
+        return session
+
+    def close_session(self, session_id: str) -> Session:
+        """Mark a session as completed."""
+        return self.update_session(session_id, status=SessionStatus.COMPLETED)
+
+    def save_session(self, session: Session) -> None:
+        """Persist a fully constructed Session object (used by tests and simulators)."""
+        self._write_session(session)
+
+
+def _now_iso() -> str:
+    from datetime import datetime, timezone
+
+    return datetime.now(tz=timezone.utc).isoformat()

devtorch_core/session/planner.py

@@ -0,0 +1,169 @@
+"""
+Sprint 28 — Sub-task planner.
+
+Decomposes a session problem into a list of `Subtask` objects with dependency
+tracking.  The default strategy is deterministic rule-based: it parses numbered
+or bulleted lists and falls back to sentence splitting.  Dependency links can be
+expressed with `[after:N]` tags where N is a 1-based subtask index.
+
+For tests, the decomposition strategy can be injected via the `strategy`
+callable constructor argument.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Callable, List, Optional
+
+from .models import Session, SessionStatus, Subtask
+
+
+_AFTER_TAG_RE = re.compile(r"\[after:(\d+)\]")
+
+
+def _default_strategy(problem: str) -> List[dict]:
+    """
+    Deterministic rule-based decomposition.
+
+    1. Treat lines that begin with a number, bullet, or dash as separate items.
+    2. If no such lines are found, split on sentence boundaries.
+    3. If the problem is empty, return a single item that captures the original
+       problem text.
+    """
+    items = []
+    for line in problem.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        match = re.match(r"^(?:\d+[\.\)]\s*|[-\*]\s*)(.*)$", line)
+        if match:
+            items.append(match.group(1).strip())
+
+    if not items:
+        sentences = [s.strip() for s in problem.split(".") if s.strip()]
+        if not sentences:
+            return [{"description": problem, "dependencies": []}]
+        items = sentences
+
+    return [{"description": item, "dependencies": []} for item in items]
+
+
+def _extract_after_tags(description: str) -> tuple[str, List[str]]:
+    """Return (clean_description, list_of_1_based_dependency_indices)."""
+    deps: List[str] = []
+
+    def _collect(match: re.Match) -> str:
+        deps.append(match.group(1))
+        return ""
+
+    clean = _AFTER_TAG_RE.sub(_collect, description).strip()
+    return clean, deps
+
+
+class SubtaskPlanner:
+    """Decompose problems into subtasks and track their execution order."""
+
+    def __init__(self, strategy: Optional[Callable[[str], List[dict]]] = None) -> None:
+        self._strategy = strategy if strategy is not None else _default_strategy
+        self._counter = 0
+
+    def _next_subtask_id(self, session_id: str, description: str) -> str:
+        """Deterministic subtask ID based on content + counter (no wall-clock)."""
+        self._counter += 1
+        content = f"subtask:{session_id}:{description}:{self._counter}"
+        hash_part = hashlib.sha256(content.encode("utf-8")).hexdigest()[:12]
+        return f"t{self._counter:08x}-{hash_part}"
+
+    def plan(
+        self,
+        session_id: str,
+        problem: str,
+        orchestrator: "SessionOrchestrator",  # type: ignore[name-defined]
+    ) -> List[Subtask]:
+        """Decompose `problem` and store the resulting subtasks in the session."""
+        # Import locally to avoid circular dependency at module load time.
+        from .orchestrator import SessionOrchestrator
+
+        if not isinstance(orchestrator, SessionOrchestrator):
+            raise TypeError("orchestrator must be a SessionOrchestrator")
+
+        items = self._strategy(problem)
+
+        # Parse descriptions and dependency indices before IDs are generated.
+        parsed: List[tuple[str, List[str]]] = []
+        for item in items:
+            desc = item.get("description", "")
+            explicit_deps = item.get("dependencies", [])
+            clean_desc, after_indices = _extract_after_tags(desc)
+            parsed.append((clean_desc, after_indices + explicit_deps))
+
+        # Generate subtasks with deterministic IDs based on the cleaned content.
+        subtasks: List[Subtask] = []
+        for clean_desc, _ in parsed:
+            subtask_id = self._next_subtask_id(session_id, clean_desc)
+            subtasks.append(
+                Subtask(
+                    subtask_id=subtask_id,
+                    session_id=session_id,
+                    description=clean_desc,
+                )
+            )
+
+        # Resolve [after:N] indices to actual subtask IDs.
+        for i, (_, dep_indices) in enumerate(parsed):
+            resolved: List[str] = []
+            for idx in dep_indices:
+                try:
+                    n = int(idx) - 1
+                except ValueError:
+                    continue
+                if 0 <= n < len(subtasks):
+                    resolved.append(subtasks[n].subtask_id)
+            subtasks[i].dependencies = resolved
+
+        orchestrator.update_session(
+            session_id,
+            subtasks=subtasks,
+            status=SessionStatus.ACTIVE,
+        )
+        return subtasks
+
+    def next_subtask(
+        self,
+        session_id: str,
+        orchestrator: "SessionOrchestrator",  # type: ignore[name-defined]
+    ) -> Optional[Subtask]:
+        """Return the next pending subtask whose dependencies are all completed."""
+        from .orchestrator import SessionOrchestrator
+
+        if not isinstance(orchestrator, SessionOrchestrator):
+            raise TypeError("orchestrator must be a SessionOrchestrator")
+
+        session = orchestrator.get_session(session_id)
+        completed = {s.subtask_id for s in session.subtasks if s.status == SessionStatus.COMPLETED}
+        for subtask in session.subtasks:
+            if subtask.status == SessionStatus.PENDING:
+                if all(dep in completed for dep in subtask.dependencies):
+                    return subtask
+        return None
+
+    def mark_subtask(
+        self,
+        session_id: str,
+        subtask_id: str,
+        status: str,
+        orchestrator: "SessionOrchestrator",  # type: ignore[name-defined]
+    ) -> Optional[Subtask]:
+        """Update the status of a subtask and persist the session."""
+        from .orchestrator import SessionOrchestrator
+
+        if not isinstance(orchestrator, SessionOrchestrator):
+            raise TypeError("orchestrator must be a SessionOrchestrator")
+
+        session = orchestrator.get_session(session_id)
+        for subtask in session.subtasks:
+            if subtask.subtask_id == subtask_id:
+                subtask.status = status
+                orchestrator.update_session(session_id, subtasks=session.subtasks)
+                return subtask
+        return None