llmcode-cli 1.0.0__py3-none-any.whl

llm_code/swarm/types.py

@@ -0,0 +1,31 @@
+"""Frozen dataclasses for swarm member state and messages."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class SwarmStatus(Enum):
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPED = "stopped"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True)
+class SwarmMember:
+    id: str
+    role: str
+    task: str
+    backend: str          # "tmux" | "subprocess"
+    pid: int | None
+    status: SwarmStatus
+    model: str = ""
+
+
+@dataclass(frozen=True)
+class SwarmMessage:
+    from_id: str
+    to_id: str            # member id, or "*" for broadcast
+    text: str
+    timestamp: str        # ISO-8601

llm_code/task/__init__.py

@@ -0,0 +1,16 @@
+"""Structured task lifecycle management."""
+from __future__ import annotations
+
+from llm_code.task.types import (
+    CheckResult,
+    TaskState,
+    TaskStatus,
+    VerifyResult,
+)
+
+__all__ = [
+    "CheckResult",
+    "TaskState",
+    "TaskStatus",
+    "VerifyResult",
+]

llm_code/task/diagnostics.py

@@ -0,0 +1,93 @@
+"""Diagnostics engine: analyze verification failures and recommend actions."""
+from __future__ import annotations
+
+import dataclasses
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from llm_code.task.types import TaskState, VerifyResult
+
+
+@dataclasses.dataclass(frozen=True)
+class DiagnosticReport:
+    task_id: str
+    failed_checks: tuple[str, ...]
+    recommendation: str  # "continue" | "replan" | "escalate"
+    summary: str
+    report_path: str
+
+
+class DiagnosticsEngine:
+    """Analyze verify failures and recommend next action."""
+
+    def __init__(self, diagnostics_dir: Path) -> None:
+        self._dir = diagnostics_dir
+        self._dir.mkdir(parents=True, exist_ok=True)
+
+    def analyze(self, task: TaskState, verify_result: VerifyResult) -> DiagnosticReport:
+        """Analyze a VerifyResult and return a DiagnosticReport with recommendation."""
+        if verify_result.all_passed:
+            return DiagnosticReport(
+                task_id=task.id,
+                failed_checks=(),
+                recommendation="continue",
+                summary="All checks passed.",
+                report_path="",
+            )
+
+        failed = tuple(c.check_name for c in verify_result.checks if not c.passed)
+        total_checks = len(verify_result.checks)
+        failed_count = len(failed)
+
+        # Determine recommendation based on failure severity and history
+        prior_failures = sum(
+            1 for vr in task.verify_results if not vr.all_passed
+        )
+
+        if prior_failures >= 2:
+            # Multiple prior failures -> escalate
+            recommendation = "escalate"
+            summary = (
+                f"Task has failed verification {prior_failures + 1} times. "
+                f"Current failures: {', '.join(failed)}. Recommend escalation."
+            )
+        elif failed_count == total_checks:
+            # All checks failed -> escalate
+            recommendation = "escalate"
+            summary = (
+                f"All {total_checks} checks failed ({', '.join(failed)}). "
+                "Recommend escalation."
+            )
+        else:
+            # Partial failure -> replan
+            recommendation = "replan"
+            summary = (
+                f"{failed_count}/{total_checks} checks failed ({', '.join(failed)}). "
+                "Recommend replanning the failing areas."
+            )
+
+        # Save report to disk
+        report_data = {
+            "task_id": task.id,
+            "task_title": task.title,
+            "failed_checks": list(failed),
+            "recommendation": recommendation,
+            "summary": summary,
+            "check_details": [
+                {"name": c.check_name, "passed": c.passed, "output": c.output}
+                for c in verify_result.checks
+            ],
+            "prior_failure_count": prior_failures,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        report_path = self._dir / f"{task.id}-{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S')}.json"
+        report_path.write_text(json.dumps(report_data, indent=2), encoding="utf-8")
+
+        return DiagnosticReport(
+            task_id=task.id,
+            failed_checks=failed,
+            recommendation=recommendation,
+            summary=summary,
+            report_path=str(report_path),
+        )

llm_code/task/manager.py

@@ -0,0 +1,162 @@
+"""Task lifecycle manager with state machine transitions and disk persistence."""
+from __future__ import annotations
+
+import dataclasses
+import json
+import uuid
+from pathlib import Path
+
+from llm_code.task.types import TaskState, TaskStatus, VerifyResult, _now_iso
+
+
+# Valid transitions: from_status -> set of allowed to_statuses
+_TRANSITIONS: dict[TaskStatus, frozenset[TaskStatus]] = {
+    TaskStatus.PLAN: frozenset({TaskStatus.DO, TaskStatus.BLOCKED}),
+    TaskStatus.DO: frozenset({TaskStatus.VERIFY, TaskStatus.BLOCKED}),
+    TaskStatus.VERIFY: frozenset({TaskStatus.CLOSE, TaskStatus.DO, TaskStatus.BLOCKED}),
+    TaskStatus.CLOSE: frozenset({TaskStatus.DONE, TaskStatus.BLOCKED}),
+    TaskStatus.DONE: frozenset(),  # terminal
+    TaskStatus.BLOCKED: frozenset({TaskStatus.PLAN, TaskStatus.DO, TaskStatus.VERIFY}),
+}
+
+
+class TaskLifecycleManager:
+    """Manages task creation, state transitions, and persistence."""
+
+    def __init__(self, task_dir: Path) -> None:
+        self._task_dir = task_dir
+        self._task_dir.mkdir(parents=True, exist_ok=True)
+
+    def create_task(
+        self,
+        title: str,
+        plan: str = "",
+        goals: tuple[str, ...] = (),
+        session_id: str = "",
+    ) -> TaskState:
+        """Create a new task in PLAN status and persist to disk."""
+        task_id = f"task-{uuid.uuid4().hex[:8]}"
+        now = _now_iso()
+        task = TaskState(
+            id=task_id,
+            title=title,
+            status=TaskStatus.PLAN,
+            plan=plan,
+            goals=goals,
+            created_at=now,
+            updated_at=now,
+            session_id=session_id,
+        )
+        self._save(task)
+        return task
+
+    def transition(self, task_id: str, to_status: TaskStatus) -> TaskState:
+        """Transition a task to a new status, validating the state machine."""
+        task = self._load(task_id)
+        if task is None:
+            raise KeyError(f"Task not found: {task_id}")
+
+        allowed = _TRANSITIONS.get(task.status, frozenset())
+        if to_status not in allowed:
+            raise ValueError(
+                f"Invalid transition: {task.status.value} -> {to_status.value}. "
+                f"Allowed: {', '.join(s.value for s in allowed)}"
+            )
+
+        updated = dataclasses.replace(task, status=to_status, updated_at=_now_iso())
+        self._save(updated)
+        return updated
+
+    def get_task(self, task_id: str) -> TaskState | None:
+        """Get a task by ID, or None if not found."""
+        return self._load(task_id)
+
+    def list_tasks(
+        self,
+        status: TaskStatus | None = None,
+        exclude_done: bool = False,
+    ) -> tuple[TaskState, ...]:
+        """List all tasks, optionally filtered by status."""
+        tasks: list[TaskState] = []
+        for path in sorted(self._task_dir.glob("task-*.json")):
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                task = TaskState.from_dict(data)
+                if status is not None and task.status != status:
+                    continue
+                if exclude_done and task.status == TaskStatus.DONE:
+                    continue
+                tasks.append(task)
+            except (json.JSONDecodeError, KeyError, ValueError):
+                continue
+        return tuple(tasks)
+
+    def update_task(self, task_id: str, **kwargs) -> TaskState:
+        """Update arbitrary fields on a task (immutable replace)."""
+        task = self._load(task_id)
+        if task is None:
+            raise KeyError(f"Task not found: {task_id}")
+        # Convert list values to tuples for frozen dataclass compatibility
+        clean_kwargs: dict = {}
+        for k, v in kwargs.items():
+            if isinstance(v, list):
+                clean_kwargs[k] = tuple(v)
+            else:
+                clean_kwargs[k] = v
+        clean_kwargs["updated_at"] = _now_iso()
+        updated = dataclasses.replace(task, **clean_kwargs)
+        self._save(updated)
+        return updated
+
+    def append_verify_result(self, task_id: str, result: VerifyResult) -> TaskState:
+        """Append a VerifyResult to a task's verify_results tuple."""
+        task = self._load(task_id)
+        if task is None:
+            raise KeyError(f"Task not found: {task_id}")
+        updated = dataclasses.replace(
+            task,
+            verify_results=task.verify_results + (result,),
+            updated_at=_now_iso(),
+        )
+        self._save(updated)
+        return updated
+
+    def _save(self, task: TaskState) -> None:
+        path = self._task_dir / f"{task.id}.json"
+        path.write_text(json.dumps(task.to_dict(), indent=2), encoding="utf-8")
+
+    def _load(self, task_id: str) -> TaskState | None:
+        path = self._task_dir / f"{task_id}.json"
+        if not path.exists():
+            return None
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            return TaskState.from_dict(data)
+        except (json.JSONDecodeError, KeyError, ValueError):
+            return None
+
+
+def build_incomplete_tasks_prompt(manager: TaskLifecycleManager) -> str:
+    """Build a system prompt section listing incomplete tasks from prior sessions."""
+    tasks = manager.list_tasks(exclude_done=True)
+    if not tasks:
+        return ""
+
+    lines = [
+        "## Incomplete Tasks (from prior sessions)",
+        "",
+        "The following tasks are still in progress. Resume or address them:",
+        "",
+    ]
+    for task in tasks:
+        lines.append(f"- **{task.id}** [{task.status.value}]: {task.title}")
+        if task.plan:
+            plan_preview = task.plan[:200].replace("\n", " ")
+            lines.append(f"  Plan: {plan_preview}")
+        if task.goals:
+            lines.append(f"  Goals: {', '.join(task.goals)}")
+        if task.files_modified:
+            lines.append(f"  Files: {', '.join(task.files_modified)}")
+        lines.append("")
+
+    return "\n".join(lines)

llm_code/task/types.py

@@ -0,0 +1,112 @@
+"""Frozen dataclasses for the task lifecycle."""
+from __future__ import annotations
+
+import dataclasses
+from datetime import datetime, timezone
+from enum import Enum
+
+
+class TaskStatus(Enum):
+    PLAN = "plan"
+    DO = "do"
+    VERIFY = "verify"
+    CLOSE = "close"
+    DONE = "done"
+    BLOCKED = "blocked"
+
+
+@dataclasses.dataclass(frozen=True)
+class CheckResult:
+    check_name: str
+    passed: bool
+    output: str = ""
+
+
+@dataclasses.dataclass(frozen=True)
+class VerifyResult:
+    task_id: str
+    all_passed: bool
+    checks: tuple[CheckResult, ...] = ()
+    llm_judgment: str = ""
+    recommended_action: str = "continue"  # "continue" | "replan" | "escalate"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclasses.dataclass(frozen=True)
+class TaskState:
+    id: str
+    title: str
+    status: TaskStatus = TaskStatus.PLAN
+    plan: str = ""
+    goals: tuple[str, ...] = ()
+    files_modified: tuple[str, ...] = ()
+    verify_results: tuple[VerifyResult, ...] = ()
+    diagnostic_path: str = ""
+    created_at: str = dataclasses.field(default_factory=_now_iso)
+    updated_at: str = dataclasses.field(default_factory=_now_iso)
+    session_id: str = ""
+
+    def to_dict(self) -> dict:
+        """Serialize to a JSON-compatible dict."""
+        return {
+            "id": self.id,
+            "title": self.title,
+            "status": self.status.value,
+            "plan": self.plan,
+            "goals": list(self.goals),
+            "files_modified": list(self.files_modified),
+            "verify_results": [
+                {
+                    "task_id": vr.task_id,
+                    "all_passed": vr.all_passed,
+                    "checks": [
+                        {"check_name": c.check_name, "passed": c.passed, "output": c.output}
+                        for c in vr.checks
+                    ],
+                    "llm_judgment": vr.llm_judgment,
+                    "recommended_action": vr.recommended_action,
+                }
+                for vr in self.verify_results
+            ],
+            "diagnostic_path": self.diagnostic_path,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "session_id": self.session_id,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> TaskState:
+        """Deserialize from a dict."""
+        verify_results = tuple(
+            VerifyResult(
+                task_id=vr["task_id"],
+                all_passed=vr["all_passed"],
+                checks=tuple(
+                    CheckResult(
+                        check_name=c["check_name"],
+                        passed=c["passed"],
+                        output=c.get("output", ""),
+                    )
+                    for c in vr.get("checks", [])
+                ),
+                llm_judgment=vr.get("llm_judgment", ""),
+                recommended_action=vr.get("recommended_action", "continue"),
+            )
+            for vr in data.get("verify_results", [])
+        )
+        return cls(
+            id=data["id"],
+            title=data["title"],
+            status=TaskStatus(data["status"]),
+            plan=data.get("plan", ""),
+            goals=tuple(data.get("goals", [])),
+            files_modified=tuple(data.get("files_modified", [])),
+            verify_results=verify_results,
+            diagnostic_path=data.get("diagnostic_path", ""),
+            created_at=data.get("created_at", _now_iso()),
+            updated_at=data.get("updated_at", _now_iso()),
+            session_id=data.get("session_id", ""),
+        )

llm_code/task/verifier.py

@@ -0,0 +1,104 @@
+"""Verifier: run automatic checks (pytest, ruff, file_exists) for a task."""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from llm_code.task.types import CheckResult, TaskState, VerifyResult
+
+
+class Verifier:
+    """Runs automated verification checks against a task's output."""
+
+    def __init__(self, cwd: Path, timeout: int = 120) -> None:
+        self._cwd = cwd
+        self._timeout = timeout
+
+    def verify(self, task: TaskState) -> VerifyResult:
+        """Run all applicable checks for a task and return a VerifyResult."""
+        checks: list[CheckResult] = []
+
+        # Always run pytest and ruff
+        checks.append(self.run_check_pytest())
+        checks.append(self.run_check_ruff())
+
+        # Check that modified files exist
+        if task.files_modified:
+            checks.append(self.run_check_files_exist(task.files_modified))
+
+        all_passed = all(c.passed for c in checks)
+
+        return VerifyResult(
+            task_id=task.id,
+            all_passed=all_passed,
+            checks=tuple(checks),
+            llm_judgment="",  # filled by LLM in a separate step
+            recommended_action="continue" if all_passed else "replan",
+        )
+
+    def run_check_pytest(self) -> CheckResult:
+        """Run pytest and return a CheckResult."""
+        try:
+            result = subprocess.run(
+                ["python", "-m", "pytest", "--tb=short", "-q"],
+                cwd=str(self._cwd),
+                capture_output=True,
+                text=True,
+                timeout=self._timeout,
+            )
+            return CheckResult(
+                check_name="pytest",
+                passed=result.returncode == 0,
+                output=(result.stdout + result.stderr).strip()[:2000],
+            )
+        except subprocess.TimeoutExpired:
+            return CheckResult(
+                check_name="pytest",
+                passed=False,
+                output=f"Timeout after {self._timeout}s",
+            )
+        except FileNotFoundError:
+            return CheckResult(
+                check_name="pytest",
+                passed=False,
+                output="pytest not found in PATH",
+            )
+
+    def run_check_ruff(self) -> CheckResult:
+        """Run ruff check and return a CheckResult."""
+        try:
+            result = subprocess.run(
+                ["ruff", "check", "."],
+                cwd=str(self._cwd),
+                capture_output=True,
+                text=True,
+                timeout=self._timeout,
+            )
+            return CheckResult(
+                check_name="ruff",
+                passed=result.returncode == 0,
+                output=(result.stdout + result.stderr).strip()[:2000],
+            )
+        except subprocess.TimeoutExpired:
+            return CheckResult(
+                check_name="ruff",
+                passed=False,
+                output=f"Timeout after {self._timeout}s",
+            )
+        except FileNotFoundError:
+            return CheckResult(
+                check_name="ruff",
+                passed=False,
+                output="ruff not found in PATH",
+            )
+
+    def run_check_files_exist(self, files: tuple[str, ...]) -> CheckResult:
+        """Check that all modified files exist on disk."""
+        missing = [f for f in files if not (self._cwd / f).exists()]
+        if missing:
+            return CheckResult(
+                check_name="file_exists",
+                passed=False,
+                output=f"Missing files: {', '.join(missing)}",
+            )
+        return CheckResult(check_name="file_exists", passed=True, output="All files present")

llm_code/tools/agent.py

@@ -0,0 +1,145 @@
+"""AgentTool — spawns a sub-agent runtime to handle a delegated sub-task."""
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import inspect
+from typing import Callable
+
+from pydantic import BaseModel
+
+from llm_code.api.types import StreamTextDelta
+from llm_code.tools.agent_roles import BUILT_IN_ROLES, AgentRole
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+
+
+class AgentInput(BaseModel):
+    task: str
+    model: str = ""
+    role: str = ""
+
+
+class AgentTool(Tool):
+    """Spawn a sub-agent to handle a sub-task, up to max_depth levels deep."""
+
+    def __init__(
+        self,
+        runtime_factory: Callable,
+        max_depth: int = 3,
+        current_depth: int = 0,
+    ) -> None:
+        self._runtime_factory = runtime_factory
+        self._max_depth = max_depth
+        self._current_depth = current_depth
+
+    # ------------------------------------------------------------------
+    # Tool interface
+    # ------------------------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        return "agent"
+
+    @property
+    def description(self) -> str:
+        return "Spawn a sub-agent to handle a sub-task"
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "task": {
+                    "type": "string",
+                    "description": "Task for the sub-agent",
+                },
+                "model": {
+                    "type": "string",
+                    "description": "Optional model override",
+                },
+                "role": {
+                    "type": "string",
+                    "enum": ["explore", "plan", "verify"],
+                    "description": "Built-in agent role with restricted tools",
+                },
+            },
+            "required": ["task"],
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.FULL_ACCESS
+
+    def is_concurrency_safe(self, args: dict) -> bool:
+        # Each sub-agent has its own session
+        return True
+
+    # ------------------------------------------------------------------
+    # Execution
+    # ------------------------------------------------------------------
+
+    def execute(self, args: dict) -> ToolResult:
+        if self._current_depth >= self._max_depth:
+            return ToolResult(
+                output=f"Max agent depth reached ({self._max_depth})",
+                is_error=True,
+            )
+
+        task: str = args.get("task", "")
+        model: str | None = args.get("model") or None
+        role_name: str = args.get("role", "")
+
+        # Resolve role
+        role: AgentRole | None = None
+        if role_name:
+            role = BUILT_IN_ROLES.get(role_name)
+            if role is None:
+                return ToolResult(
+                    output=f"Unknown role: '{role_name}'. Valid roles: {list(BUILT_IN_ROLES)}",
+                    is_error=True,
+                )
+
+        # Sync wrapper: works whether or not an event loop is running
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop and loop.is_running():
+            with concurrent.futures.ThreadPoolExecutor() as pool:
+                result = pool.submit(
+                    asyncio.run, self._execute_async(task, model, role)
+                ).result()
+        else:
+            result = asyncio.run(self._execute_async(task, model, role))
+
+        return result
+
+    def _call_factory(self, model: str | None, role: AgentRole | None):
+        """Call runtime_factory, passing role= only if the factory accepts it."""
+        try:
+            sig = inspect.signature(self._runtime_factory)
+            params = sig.parameters
+            accepts_role = (
+                "role" in params
+                or any(
+                    p.kind == inspect.Parameter.VAR_KEYWORD
+                    for p in params.values()
+                )
+            )
+        except (ValueError, TypeError):
+            accepts_role = False
+
+        if accepts_role:
+            return self._runtime_factory(model, role=role)
+        return self._runtime_factory(model)
+
+    async def _execute_async(
+        self, task: str, model: str | None, role: AgentRole | None
+    ) -> ToolResult:
+        runtime = self._call_factory(model, role)
+        collected: list[str] = []
+        async for event in runtime.run_turn(task):
+            if isinstance(event, StreamTextDelta):
+                collected.append(event.text)
+        return ToolResult(output="".join(collected) or "(no output)")