bareagent-cli 0.1.0__py3-none-any.whl

bareagent/planning/tasks.py

@@ -0,0 +1,348 @@
+from __future__ import annotations
+
+import copy
+import json
+import threading
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from bareagent.core.fileutil import atomic_write_json, generate_random_id, utc_timestamp_iso
+from bareagent.core.schema import tool_schema as _schema
+
+TASK_STATUSES = {"pending", "in_progress", "done", "failed"}
+
+
+@dataclass(slots=True)
+class Task:
+    id: str
+    title: str
+    description: str
+    status: str
+    depends_on: list[str]
+    created_at: str
+    updated_at: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+TASK_TOOL_SCHEMAS: list[dict[str, Any]] = [
+    _schema(
+        "task_create",
+        "Create a persisted task with optional dependency task IDs.",
+        {
+            "title": {
+                "type": "string",
+                "description": "Short task title.",
+            },
+            "description": {
+                "type": "string",
+                "description": "Optional task description.",
+                "default": "",
+            },
+            "depends_on": {
+                "type": "array",
+                "description": "Optional dependency task IDs.",
+                "items": {"type": "string"},
+                "default": [],
+            },
+        },
+        ["title"],
+    ),
+    _schema(
+        "task_update",
+        "Update a persisted task status and/or title.",
+        {
+            "task_id": {
+                "type": "string",
+                "description": "Task ID to update.",
+            },
+            "status": {
+                "type": "string",
+                "enum": sorted(TASK_STATUSES),
+                "description": "Optional new task status.",
+            },
+            "title": {
+                "type": "string",
+                "description": "Optional new task title.",
+            },
+        },
+        ["task_id"],
+    ),
+    _schema(
+        "task_get",
+        "Get a single persisted task by ID.",
+        {
+            "task_id": {
+                "type": "string",
+                "description": "Task ID to look up.",
+            }
+        },
+        ["task_id"],
+    ),
+    _schema(
+        "task_list",
+        "List persisted tasks, optionally filtered by status.",
+        {
+            "status": {
+                "type": "string",
+                "enum": sorted(TASK_STATUSES),
+                "description": "Optional task status filter.",
+            }
+        },
+        [],
+    ),
+]
+
+
+class TaskManager:
+    """Persist tasks on disk and enforce dependency validation."""
+
+    def __init__(self, task_file: str | Path = ".tasks.json") -> None:
+        self.task_file = Path(task_file)
+        self.tasks: dict[str, Task] = {}
+        self._lock = threading.RLock()
+        self._load()
+
+    def create(
+        self,
+        title: str,
+        description: str = "",
+        depends_on: list[str] | None = None,
+    ) -> Task:
+        with self._lock:
+            normalized_title = title.strip()
+            if not normalized_title:
+                raise ValueError("title must not be empty")
+
+            normalized_depends_on = self._normalize_depends_on(depends_on)
+            self._ensure_dependencies_exist(normalized_depends_on)
+            now = self._timestamp()
+            task = Task(
+                id=self._generate_task_id(),
+                title=normalized_title,
+                description=description.strip(),
+                status="pending",
+                depends_on=normalized_depends_on,
+                created_at=now,
+                updated_at=now,
+            )
+            self.tasks[task.id] = task
+            try:
+                self._ensure_acyclic()
+            except Exception:
+                del self.tasks[task.id]
+                raise
+            self._save()
+            return self._copy_task(task)
+
+    def update(
+        self,
+        task_id: str,
+        status: str | None = None,
+        title: str | None = None,
+        expected_status: str | None = None,
+    ) -> Task:
+        with self._lock:
+            task = self._get_unsafe(task_id)
+            if expected_status is not None:
+                normalized_expected_status = expected_status.strip()
+                self._validate_status(normalized_expected_status)
+                if task.status != normalized_expected_status:
+                    raise ValueError(
+                        f"Task {task.id} status is {task.status}, "
+                        f"expected {normalized_expected_status}"
+                    )
+
+            changed = False
+
+            if status is not None:
+                normalized_status = status.strip()
+                self._validate_status(normalized_status)
+                if task.status != normalized_status:
+                    task.status = normalized_status
+                    changed = True
+
+            if title is not None:
+                normalized_title = title.strip()
+                if not normalized_title:
+                    raise ValueError("title must not be empty")
+                if task.title != normalized_title:
+                    task.title = normalized_title
+                    changed = True
+
+            if changed:
+                task.updated_at = self._timestamp()
+                self._save()
+
+            return self._copy_task(task)
+
+    def get(self, task_id: str) -> Task:
+        with self._lock:
+            return self._copy_task(self._get_unsafe(task_id))
+
+    def _get_unsafe(self, task_id: str) -> Task:
+        """Return the internal task reference. Caller must hold self._lock."""
+        normalized_id = task_id.strip()
+        task = self.tasks.get(normalized_id)
+        if task is None:
+            raise ValueError(f"Unknown task id: {task_id}")
+        return task
+
+    def list(self, status: str | None = None) -> list[Task]:
+        with self._lock:
+            if status is None:
+                return [self._copy_task(t) for t in self.tasks.values()]
+
+            normalized_status = status.strip()
+            self._validate_status(normalized_status)
+            return [
+                self._copy_task(t)
+                for t in self.tasks.values()
+                if t.status == normalized_status
+            ]
+
+    def get_ready_tasks(self) -> list[Task]:
+        with self._lock:
+            ready_tasks: list[Task] = []
+            for task in self.tasks.values():
+                if task.status != "pending":
+                    continue
+                if all(
+                    self.tasks.get(dep_id) is not None
+                    and self.tasks[dep_id].status == "done"
+                    for dep_id in task.depends_on
+                ):
+                    ready_tasks.append(self._copy_task(task))
+            return ready_tasks
+
+    @staticmethod
+    def _copy_task(task: Task) -> Task:
+        """Return a shallow copy with an independent depends_on list."""
+        copied = copy.copy(task)
+        copied.depends_on = list(task.depends_on)
+        return copied
+
+    def _save(self) -> None:
+        payload = {
+            "tasks": {task_id: task.to_dict() for task_id, task in self.tasks.items()}
+        }
+        atomic_write_json(self.task_file, payload)
+
+    def _load(self) -> None:
+        try:
+            with self.task_file.open("r", encoding="utf-8") as file:
+                payload = json.load(file)
+        except FileNotFoundError:
+            self.tasks = {}
+            return
+
+        if not isinstance(payload, dict):
+            raise ValueError("Task file must contain a JSON object")
+
+        raw_tasks = payload.get("tasks", {})
+        if not isinstance(raw_tasks, dict):
+            raise ValueError("Task file 'tasks' field must be an object")
+
+        loaded_tasks: dict[str, Task] = {}
+        for task_id, raw_task in raw_tasks.items():
+            if not isinstance(raw_task, dict):
+                raise ValueError(f"Invalid task payload for {task_id}")
+            loaded_tasks[task_id] = Task(**raw_task)
+
+        self.tasks = loaded_tasks
+        self._validate_graph()
+
+    def _validate_graph(self) -> None:
+        for task in self.tasks.values():
+            self._validate_status(task.status)
+            self._ensure_dependencies_exist(task.depends_on)
+        self._ensure_acyclic()
+
+    def _normalize_depends_on(self, depends_on: list[str] | None) -> list[str]:
+        if depends_on is None:
+            return []
+
+        normalized: list[str] = []
+        seen: set[str] = set()
+        for dependency_id in depends_on:
+            normalized_id = str(dependency_id).strip()
+            if not normalized_id:
+                raise ValueError("depends_on entries must not be empty")
+            if normalized_id in seen:
+                continue
+            seen.add(normalized_id)
+            normalized.append(normalized_id)
+        return normalized
+
+    def _ensure_dependencies_exist(self, depends_on: list[str]) -> None:
+        for dependency_id in depends_on:
+            if dependency_id not in self.tasks:
+                raise ValueError(f"Unknown dependency task id: {dependency_id}")
+
+    def _ensure_acyclic(self) -> None:
+        visiting: set[str] = set()
+        visited: set[str] = set()
+
+        def _dfs(task_id: str) -> None:
+            if task_id in visiting:
+                raise ValueError(f"Cyclic task dependency detected at: {task_id}")
+            if task_id in visited:
+                return
+
+            visiting.add(task_id)
+            for dependency_id in self.tasks[task_id].depends_on:
+                _dfs(dependency_id)
+            visiting.remove(task_id)
+            visited.add(task_id)
+
+        for task_id in self.tasks:
+            _dfs(task_id)
+
+    def _generate_task_id(self) -> str:
+        while True:
+            task_id = generate_random_id(8)
+            if task_id not in self.tasks:
+                return task_id
+
+    def _timestamp(self) -> str:
+        return utc_timestamp_iso()
+
+    def _validate_status(self, status: str) -> None:
+        if status not in TASK_STATUSES:
+            valid = ", ".join(sorted(TASK_STATUSES))
+            raise ValueError(f"Invalid task status: {status}. Expected one of: {valid}")
+
+
+def make_task_handlers(task_manager: TaskManager) -> dict[str, Any]:
+    def _task_create(
+        title: str,
+        description: str = "",
+        depends_on: list[str] | None = None,
+    ) -> dict[str, Any]:
+        return task_manager.create(
+            title=title,
+            description=description,
+            depends_on=depends_on,
+        ).to_dict()
+
+    def _task_update(
+        task_id: str,
+        status: str | None = None,
+        title: str | None = None,
+    ) -> dict[str, Any]:
+        if status is None and title is None:
+            raise ValueError("status or title is required")
+        return task_manager.update(
+            task_id=task_id, status=status, title=title
+        ).to_dict()
+
+    return {
+        "task_create": _task_create,
+        "task_update": _task_update,
+        "task_get": lambda task_id: task_manager.get(task_id).to_dict(),
+        "task_list": lambda status=None: [
+            task.to_dict() for task in task_manager.list(status=status)
+        ],
+    }

bareagent/planning/todo.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from bareagent.core.schema import tool_schema as _schema
+
+VALID_TODO_STATUSES = {"pending", "in_progress", "done"}
+
+
+TODO_TOOL_SCHEMAS: list[dict[str, Any]] = [
+    _schema(
+        "todo_write",
+        "Create or update an in-memory TODO item for the current task.",
+        {
+            "action": {
+                "type": "string",
+                "enum": ["add", "update"],
+                "description": "Whether to add a new TODO or update an existing one.",
+            },
+            "task": {
+                "type": "string",
+                "description": "The task text when action=add.",
+            },
+            "priority": {
+                "type": "string",
+                "description": "Task priority when action=add.",
+                "default": "normal",
+            },
+            "task_id": {
+                "type": "string",
+                "description": "The TODO id when action=update.",
+            },
+            "status": {
+                "type": "string",
+                "enum": sorted(VALID_TODO_STATUSES),
+                "description": "New status when action=update.",
+            },
+        },
+        ["action"],
+    ),
+    _schema(
+        "todo_read",
+        "List all in-memory TODO items and their current status.",
+        {},
+        [],
+    ),
+]
+
+
+class TodoManager:
+    """Manage short-lived in-memory TODO items for the active session."""
+
+    def __init__(self) -> None:
+        self.tasks: dict[str, dict[str, str]] = {}
+        self._next_id = 1
+        self._lock = threading.Lock()
+
+    def reset(self) -> None:
+        """Clear all tasks and reset the ID counter."""
+        with self._lock:
+            self.tasks.clear()
+            self._next_id = 1
+
+    def add(self, task: str, priority: str = "normal") -> str:
+        with self._lock:
+            task_text = task.strip()
+            if not task_text:
+                raise ValueError("task must not be empty")
+
+            task_id = f"t{self._next_id}"
+            self._next_id += 1
+            self.tasks[task_id] = {
+                "task": task_text,
+                "status": "pending",
+                "priority": priority.strip() or "normal",
+            }
+            return (
+                f"Added TODO {task_id} [{self.tasks[task_id]['priority']}]: {task_text}"
+            )
+
+    def update(self, task_id: str, status: str) -> str:
+        with self._lock:
+            normalized_id = task_id.strip()
+            if normalized_id not in self.tasks:
+                raise ValueError(f"Unknown TODO id: {task_id}")
+
+            normalized_status = status.strip()
+            if normalized_status not in VALID_TODO_STATUSES:
+                valid = ", ".join(sorted(VALID_TODO_STATUSES))
+                raise ValueError(
+                    f"Invalid TODO status: {status}. Expected one of: {valid}"
+                )
+
+            self.tasks[normalized_id]["status"] = normalized_status
+            return f"Updated TODO {normalized_id} -> {normalized_status}"
+
+    def list(self) -> str:
+        with self._lock:
+            if not self.tasks:
+                return "No TODO items."
+
+            lines = ["TODO items:"]
+            for task_id, item in self.tasks.items():
+                lines.append(
+                    f"- {task_id} [{item['status']}] ({item['priority']}) {item['task']}"
+                )
+            return "\n".join(lines)
+
+    def get_nag_reminder(self) -> str | None:
+        with self._lock:
+            pending_lines = [
+                f"- {task_id} [{item['status']}] ({item['priority']}) {item['task']}"
+                for task_id, item in self.tasks.items()
+                if item["status"] != "done"
+            ]
+            if not pending_lines:
+                return None
+
+            return "\n".join(
+                [
+                    "You still have unfinished TODO items. Keep them in sync with your progress.",
+                    *pending_lines,
+                ]
+            )
+
+
+def make_todo_handlers(todo_manager: TodoManager) -> dict[str, Any]:
+    def _todo_write(
+        action: str,
+        task: str | None = None,
+        priority: str = "normal",
+        task_id: str | None = None,
+        status: str | None = None,
+    ) -> str:
+        if action == "add":
+            if task is None:
+                raise ValueError("task is required when action=add")
+            return todo_manager.add(task=task, priority=priority)
+
+        if action == "update":
+            if task_id is None:
+                raise ValueError("task_id is required when action=update")
+            if status is None:
+                raise ValueError("status is required when action=update")
+            return todo_manager.update(task_id=task_id, status=status)
+
+        raise ValueError(f"Unknown todo_write action: {action}")
+
+    return {
+        "todo_write": _todo_write,
+        "todo_read": todo_manager.list,
+    }

bareagent/planning/worktree.py

@@ -0,0 +1,122 @@
+"""Git worktree lifecycle helpers for sub-agent isolation.
+
+A thin, dependency-free wrapper around the ``git worktree`` CLI so that a
+sub-agent can run with all of its file operations rooted in an isolated
+working tree + temp branch, leaving the parent workspace untouched. This
+module knows nothing about the agent loop or LLM providers and is unit
+testable against a real temporary repository.
+
+The git subprocess style mirrors ``src/core/context.py::_run_git_command``
+(cwd + capture + text + utf-8 + errors="replace" + timeout). These calls
+run as infrastructure (same tier as ``tasks.py`` / ``context.py``) and are
+deliberately *not* routed through ``PermissionGuard`` — the sub-agent's own
+bash/write tools are still gated by its ``child_permission``.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from bareagent.core.fileutil import generate_random_id
+
+_GIT_TIMEOUT = 30
+
+
+class WorktreeError(Exception):
+    """Raised when creating a git worktree fails."""
+
+
+@dataclass(slots=True)
+class WorktreeHandle:
+    """Identifies an isolated worktree created for a sub-agent."""
+
+    path: str
+    branch: str
+    base_workspace: str
+
+
+def _run_git(workspace: str | Path, *args: str) -> subprocess.CompletedProcess[str]:
+    """Run a git command, returning the completed process (no ``check``).
+
+    Callers inspect ``returncode`` and decide whether to raise or swallow —
+    creation raises, cleanup is best-effort.
+    """
+    return subprocess.run(
+        ["git", "-C", str(workspace), *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=_GIT_TIMEOUT,
+    )
+
+
+def is_git_repo(workspace: str | Path) -> bool:
+    """Return ``True`` when *workspace* sits inside a git work tree."""
+    try:
+        completed = _run_git(workspace, "rev-parse", "--is-inside-work-tree")
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return completed.returncode == 0 and completed.stdout.strip() == "true"
+
+
+def create_worktree(workspace: str | Path) -> WorktreeHandle:
+    """Create an isolated worktree + temp branch for *workspace*.
+
+    The worktree is placed under the system temp directory (outside the repo,
+    so the sub-agent's glob/grep cannot scan it and it never enters the git
+    index). ``mkdtemp`` pre-creates an empty directory; ``git worktree add``
+    accepts an existing empty directory as its target.
+    """
+    worktree_id = generate_random_id(8)
+    branch = f"bareagent/wt-{worktree_id}"
+    path = tempfile.mkdtemp(prefix="bareagent-wt-")
+
+    try:
+        completed = _run_git(workspace, "worktree", "add", path, "-b", branch)
+    except (OSError, subprocess.SubprocessError) as exc:
+        raise WorktreeError(f"git worktree add failed: {exc}") from exc
+
+    if completed.returncode != 0:
+        detail = completed.stderr.strip() or completed.stdout.strip() or "unknown error"
+        raise WorktreeError(f"git worktree add failed: {detail}")
+
+    return WorktreeHandle(path=path, branch=branch, base_workspace=str(workspace))
+
+
+def worktree_status(path: str | Path) -> tuple[bool, str]:
+    """Return ``(dirty, summary)`` for the worktree at *path*.
+
+    Dirty is defined as a non-empty ``git status --porcelain`` — a sub-agent's
+    output is uncommitted changes (auto-commit is out of scope), so there is no
+    commits-ahead comparison.
+    """
+    try:
+        completed = _run_git(path, "status", "--porcelain")
+    except (OSError, subprocess.SubprocessError):
+        return False, "status unavailable"
+
+    lines = [line for line in completed.stdout.splitlines() if line.strip()]
+    dirty = bool(lines)
+    summary = f"{len(lines)} file(s) changed" if dirty else "no changes"
+    return dirty, summary
+
+
+def remove_worktree(handle: WorktreeHandle) -> None:
+    """Remove the worktree and delete its branch (best-effort, idempotent).
+
+    Both steps swallow failures: cleanup must never raise into the sub-agent's
+    result path. A leftover worktree is visible via ``git worktree list``.
+    """
+    base = handle.base_workspace
+    for args in (
+        ("worktree", "remove", "--force", handle.path),
+        ("branch", "-D", handle.branch),
+    ):
+        try:
+            _run_git(base, *args)
+        except (OSError, subprocess.SubprocessError):
+            pass

bareagent/provider/__init__.py

@@ -0,0 +1 @@
+"""Provider integrations for BareAgent."""