lemming-cli 0.1.0__py3-none-any.whl

lemming/tasks/__init__.py

@@ -0,0 +1,75 @@
+"""Task management package: lifecycle, operations, progress, and queries."""
+
+from .. import models, persistence
+from .lifecycle import (
+    STALE_THRESHOLD as STALE_THRESHOLD,
+)
+from .lifecycle import (
+    cancel_task as cancel_task,
+)
+from .lifecycle import (
+    claim_task as claim_task,
+)
+from .lifecycle import (
+    finish_task_attempt as finish_task_attempt,
+)
+from .lifecycle import (
+    generate_task_id as generate_task_id,
+)
+from .lifecycle import (
+    is_loop_running as is_loop_running,
+)
+from .lifecycle import (
+    is_pid_alive as is_pid_alive,
+)
+from .lifecycle import (
+    mark_task_in_progress as mark_task_in_progress,
+)
+from .lifecycle import (
+    reset_task as reset_task,
+)
+from .lifecycle import (
+    reset_task_logs as reset_task_logs,
+)
+from .lifecycle import (
+    update_heartbeat as update_heartbeat,
+)
+from .lifecycle import (
+    update_run_time as update_run_time,
+)
+from .operations import (
+    add_task as add_task,
+)
+from .operations import (
+    delete_tasks as delete_tasks,
+)
+from .operations import (
+    update_context as update_context,
+)
+from .operations import (
+    update_task as update_task,
+)
+from .progress import add_progress as add_progress
+from .queries import (
+    get_pending_task as get_pending_task,
+)
+from .queries import (
+    get_project_data as get_project_data,
+)
+
+# Re-export persistence functions for backward compatibility
+save_tasks = persistence.save_tasks
+load_tasks = persistence.load_tasks
+lock_tasks = persistence.lock_tasks
+acquire_loop_lock = persistence.acquire_loop_lock
+release_loop_lock = persistence.release_loop_lock
+get_loop_pid = persistence.get_loop_pid
+LOOP_LOCK_FILENAME = persistence.LOOP_LOCK_FILENAME
+
+# Re-export models for compatibility
+TaskNotFoundError = models.TaskNotFoundError
+Task = models.Task
+TaskStatus = models.TaskStatus
+ProjectData = models.ProjectData
+RoadmapConfig = models.RoadmapConfig
+Roadmap = models.Roadmap

lemming/tasks/lifecycle.py

@@ -0,0 +1,331 @@
+"""Task lifecycle management: claiming, heartbeats, cancellation, resets."""
+
+import os
+import pathlib
+import secrets
+import signal
+import time
+
+from .. import models, paths, persistence
+
+# Re-export constants for internal/external use
+STALE_THRESHOLD = persistence.STALE_THRESHOLD
+
+
+def generate_task_id() -> str:
+    """Generates a random short hex string for a unique task ID.
+
+    Returns:
+        A random 8-character hex string.
+    """
+    return secrets.token_hex(4)
+
+
+def is_pid_alive(pid: int) -> bool:
+    """Check if a process is still running.
+
+    Args:
+        pid: The process ID to check.
+
+    Returns:
+        True if the process is alive, False otherwise.
+    """
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+
+    # Check for zombie state on Linux
+    try:
+        status_path = pathlib.Path(f"/proc/{pid}/status")
+        if status_path.exists():
+            for line in status_path.read_text().splitlines():
+                if line.startswith("State:"):
+                    state = line.split()[1]
+                    if state == "Z":
+                        return False
+    except OSError:
+        pass
+
+    return True
+
+
+def is_loop_running(tasks_file: pathlib.Path) -> bool:
+    """Check if an orchestrator loop is actively running."""
+    pid = persistence.get_loop_pid(tasks_file)
+    return pid is not None and is_pid_alive(pid)
+
+
+def update_run_time(task: models.Task, end_time: float | None = None) -> None:
+    """Accumulates the execution run time for a given task.
+
+    Args:
+        task: The Task to update.
+        end_time: Optional end timestamp (defaults to current time).
+    """
+    if task.last_started_at is not None:
+        end = end_time or time.time()
+        duration = end - task.last_started_at
+        task.run_time += duration
+        task.last_started_at = None
+
+
+def is_task_active(task: models.Task, now: float) -> bool:
+    """Returns True if the task is actively being executed.
+
+    A task is active if:
+    1. It is marked IN_PROGRESS or has a requested_status (finalizing).
+    2. AND it has a PID that is alive.
+    3. AND its heartbeat is recent (not stale).
+    """
+    if (
+        task.status != models.TaskStatus.IN_PROGRESS
+        and not task.requested_status
+    ):
+        return False
+
+    if not task.pid or not is_pid_alive(task.pid):
+        return False
+
+    last_heartbeat = task.last_heartbeat or 0
+    if now - last_heartbeat > STALE_THRESHOLD:
+        return False
+
+    return True
+
+
+def _mark_task_in_progress(
+    data: models.Roadmap, task_id: str, pid: int | None = None
+) -> bool:
+    """Internal helper to mark a task as in_progress without locking or saving.
+
+    Args:
+        data: The Roadmap to update.
+        task_id: The ID of the task to mark.
+        pid: Optional process ID associated with the task.
+
+    Returns:
+        True if the task was successfully marked, False otherwise.
+    """
+    now = time.time()
+    for task in data.tasks:
+        if task.id == task_id:
+            # A task can be marked in progress if it's pending, or if it's
+            # nominally in progress/finalizing but has crashed or timed out
+            # (stale).
+            if task.status == models.TaskStatus.PENDING or (
+                (
+                    task.status == models.TaskStatus.IN_PROGRESS
+                    or task.requested_status
+                )
+                and not is_task_active(task, now)
+            ):
+                task.status = models.TaskStatus.IN_PROGRESS
+                task.last_heartbeat = now
+                if task.started_at is None:
+                    task.started_at = now
+                task.last_started_at = now
+                if pid is not None:
+                    task.pid = pid
+                return True
+            return False
+    return False
+
+
+def mark_task_in_progress(
+    tasks_file: pathlib.Path, task_id: str, pid: int | None = None
+) -> bool:
+    """Try to mark a task as in_progress. Returns True if successful.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        task_id: The ID of the task to mark.
+        pid: Optional process ID associated with the task.
+
+    Returns:
+        True if the task was successfully marked, False otherwise.
+    """
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+        if _mark_task_in_progress(data, task_id, pid=pid):
+            persistence.save_tasks(tasks_file, data)
+            return True
+    return False
+
+
+def claim_task(
+    tasks_file: pathlib.Path, task_id: str, pid: int
+) -> models.Task | None:
+    """Claims a task for execution: marks in_progress and increments attempts.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        task_id: The ID of the task to claim.
+        pid: The process ID of the agent executing the task.
+
+    Returns:
+        The claimed Task, or None if the task could not be claimed.
+    """
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+        if not _mark_task_in_progress(data, task_id, pid=pid):
+            return None
+
+        task = next(t for t in data.tasks if t.id == task_id)
+        if not task.requested_status:
+            task.attempts += 1
+        persistence.save_tasks(tasks_file, data)
+        return task
+
+
+def finish_task_attempt(
+    tasks_file: pathlib.Path, task_id: str
+) -> models.Task | None:
+    """Handles post-execution cleanup for a task attempt.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        task_id: The ID of the task that finished.
+
+    Returns:
+        The updated Task, or None if not found.
+    """
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+        task = next((t for t in data.tasks if t.id == task_id), None)
+        if not task:
+            return None
+
+        if task.status == models.TaskStatus.IN_PROGRESS:
+            # If it failed or simply finished without requesting completion,
+            # we keep it as pending so it can be retried.
+            if not task.requested_status:
+                update_run_time(task)
+                task.status = models.TaskStatus.PENDING
+                task.last_heartbeat = None
+            else:
+                task.last_heartbeat = time.time()
+
+            task.pid = None
+            persistence.save_tasks(tasks_file, data)
+
+        return task
+
+
+def update_heartbeat(
+    tasks_file: pathlib.Path, task_id: str, pid: int | None = None
+) -> bool:
+    """Updates the heartbeat timestamp for a task.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        task_id: The ID of the task to update.
+        pid: Optional new PID to store (e.g. the runner subprocess PID).
+
+    Returns:
+        True if the task is still in_progress, False if it was cancelled or
+        otherwise changed (caller should stop work).
+    """
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+        for task in data.tasks:
+            if task.id == task_id:
+                if task.status != models.TaskStatus.IN_PROGRESS:
+                    return False
+                task.last_heartbeat = time.time()
+                if pid is not None:
+                    task.pid = pid
+                break
+        persistence.save_tasks(tasks_file, data)
+    return True
+
+
+def reset_task_logs(tasks_file: pathlib.Path, task_id: str) -> None:
+    """Deletes the runner log for a given task.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        task_id: The ID of the task whose logs should be cleared.
+    """
+    log_file = paths.get_log_file(tasks_file, task_id)
+    if log_file.exists():
+        log_file.unlink()
+
+
+def cancel_task(tasks_file: pathlib.Path, task_id: str) -> bool:
+    """Kill the task process AND the orchestrator loop, then mark cancelled.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        task_id: The ID of the task to cancel.
+
+    Returns:
+        True if the task was found and cancellation was attempted, False
+        otherwise.
+    """
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+
+        for task in data.tasks:
+            if task.id == task_id:
+                # First kill the task itself
+                if task.pid:
+                    try:
+                        # Try to kill the whole process group if possible
+                        os.killpg(os.getpgid(task.pid), signal.SIGTERM)
+                    except OSError:
+                        try:
+                            os.kill(task.pid, signal.SIGTERM)
+                        except OSError:
+                            pass
+
+                # Also kill the orchestrator loop if it's running
+                loop_pid = persistence.get_loop_pid(tasks_file)
+                if loop_pid:
+                    try:
+                        os.kill(loop_pid, signal.SIGTERM)
+                    except OSError:
+                        pass
+
+                update_run_time(task)
+                task.status = models.TaskStatus.CANCELLED
+                task.pid = None
+                task.last_heartbeat = None
+                task.requested_status = None
+
+                persistence.save_tasks(tasks_file, data)
+                return True
+    return False
+
+
+def reset_task(tasks_file: pathlib.Path, task_id: str) -> models.Task:
+    """Resets a task's attempts and progress.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        task_id: ID of the task to reset.
+
+    Returns:
+        The reset Task.
+    """
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+        target = next((t for t in data.tasks if t.id.startswith(task_id)), None)
+        if not target:
+            raise models.TaskNotFoundError(f"Task {task_id} not found")
+
+        target.status = models.TaskStatus.PENDING
+        target.attempts = 0
+        target.progress = []
+        target.run_time = 0.0
+        target.completed_at = None
+        target.started_at = None
+        target.last_started_at = None
+        target.pid = None
+        target.last_heartbeat = None
+        target.requested_status = None
+
+        persistence.save_tasks(tasks_file, data)
+
+        reset_task_logs(tasks_file, target.id)
+    return target

lemming/tasks/lifecycle_test.py

@@ -0,0 +1,312 @@
+import os
+import signal
+import time
+from unittest.mock import patch
+
+from lemming import paths
+
+from .. import models, persistence
+from . import lifecycle
+
+
+def test_generate_task_id():
+    id1 = lifecycle.generate_task_id()
+    id2 = lifecycle.generate_task_id()
+    assert len(id1) == 8
+    assert id1 != id2
+
+
+def test_is_pid_alive():
+    assert lifecycle.is_pid_alive(os.getpid()) is True
+    assert lifecycle.is_pid_alive(999999) is False
+
+
+def test_is_loop_running_stale_pid(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    persistence.acquire_loop_lock(tasks_file)
+    assert lifecycle.is_loop_running(tasks_file) is True
+
+    # Manually overwrite with stale PID
+    lock_path = (
+        paths.get_project_dir(tasks_file) / persistence.LOOP_LOCK_FILENAME
+    )
+    lock_path.write_text("999999")
+    assert lifecycle.is_loop_running(tasks_file) is False
+
+
+def test_update_run_time():
+    task = models.Task(
+        id="1", description="test", last_started_at=time.time() - 5
+    )
+    lifecycle.update_run_time(task)
+    assert task.run_time >= 5.0
+
+
+def test_mark_task_in_progress(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    data = models.Roadmap(
+        tasks=[
+            models.Task(
+                id="1", description="Task 1", status=models.TaskStatus.PENDING
+            )
+        ]
+    )
+    persistence.save_tasks(tasks_file, data)
+
+    success = lifecycle.mark_task_in_progress(tasks_file, "1", pid=123)
+    assert success is True
+
+    updated_data = persistence.load_tasks(tasks_file)
+    assert updated_data.tasks[0].status == models.TaskStatus.IN_PROGRESS
+    assert updated_data.tasks[0].pid == 123
+
+
+def test_claim_task(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    data = models.Roadmap(
+        tasks=[
+            models.Task(
+                id="1", description="Task 1", status=models.TaskStatus.PENDING
+            )
+        ]
+    )
+    persistence.save_tasks(tasks_file, data)
+
+    claimed = lifecycle.claim_task(tasks_file, "1", pid=123)
+    assert claimed is not None
+    assert claimed.status == models.TaskStatus.IN_PROGRESS
+    assert claimed.pid == 123
+    assert claimed.attempts == 1
+
+
+def test_claim_already_in_progress(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    data = models.Roadmap(
+        tasks=[
+            models.Task(
+                id="1",
+                description="Task 1",
+                status=models.TaskStatus.IN_PROGRESS,
+                pid=os.getpid(),
+                last_heartbeat=time.time(),
+            )
+        ]
+    )
+    persistence.save_tasks(tasks_file, data)
+
+    # Second claim should fail
+    claimed_again = lifecycle.claim_task(tasks_file, "1", pid=456)
+    assert claimed_again is None
+
+    # But if it's stale, it should succeed
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+        data.tasks[0].last_heartbeat = time.time() - (
+            persistence.STALE_THRESHOLD + 1
+        )
+        persistence.save_tasks(tasks_file, data)
+
+    claimed_stale = lifecycle.claim_task(tasks_file, "1", pid=789)
+    assert claimed_stale is not None
+    assert claimed_stale.pid == 789
+    assert (
+        claimed_stale.attempts == 1
+    )  # 0 + 1 because we manually created it with 0
+
+
+def test_finish_task_attempt(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    data = models.Roadmap(
+        tasks=[
+            models.Task(
+                id="1",
+                description="Task 1",
+                status=models.TaskStatus.IN_PROGRESS,
+                last_started_at=time.time(),
+            )
+        ]
+    )
+    persistence.save_tasks(tasks_file, data)
+
+    finished = lifecycle.finish_task_attempt(tasks_file, "1")
+    assert finished.status == models.TaskStatus.PENDING
+    assert finished.pid is None
+
+
+def test_update_heartbeat(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    data = models.Roadmap(
+        tasks=[
+            models.Task(
+                id="1",
+                description="Task 1",
+                status=models.TaskStatus.IN_PROGRESS,
+            )
+        ]
+    )
+    persistence.save_tasks(tasks_file, data)
+
+    success = lifecycle.update_heartbeat(tasks_file, "1", pid=123)
+    assert success is True
+
+    updated_data = persistence.load_tasks(tasks_file)
+    assert updated_data.tasks[0].last_heartbeat is not None
+    assert updated_data.tasks[0].pid == 123
+
+
+def test_cancel_task(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    data = models.Roadmap(
+        tasks=[
+            models.Task(
+                id="1",
+                description="Task 1",
+                status=models.TaskStatus.IN_PROGRESS,
+                pid=os.getpid(),
+            )
+        ],
+    )
+    persistence.save_tasks(tasks_file, data)
+
+    with patch("lemming.tasks.lifecycle.os.killpg"):
+        success = lifecycle.cancel_task(tasks_file, "1")
+        assert success is True
+
+    updated_data = persistence.load_tasks(tasks_file)
+    assert updated_data.tasks[0].status == models.TaskStatus.CANCELLED
+    assert updated_data.tasks[0].pid is None
+
+
+def test_cancel_task_kills_loop_pid(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    data = models.Roadmap(
+        tasks=[
+            models.Task(
+                id="1",
+                description="Task 1",
+                status=models.TaskStatus.IN_PROGRESS,
+                pid=123,
+            )
+        ],
+    )
+    persistence.save_tasks(tasks_file, data)
+
+    # Mock get_loop_pid to return a dummy PID
+    with (
+        patch("lemming.persistence.get_loop_pid", return_value=456),
+        patch("lemming.tasks.lifecycle.os.getpgid", return_value=123),
+        patch("lemming.tasks.lifecycle.os.kill") as mock_kill,
+        patch("lemming.tasks.lifecycle.os.killpg") as mock_killpg,
+    ):
+        success = lifecycle.cancel_task(tasks_file, "1")
+        assert success is True
+
+        # Verify task PID was killed
+        mock_killpg.assert_called_once_with(123, signal.SIGTERM)
+        # Verify loop PID was killed
+        mock_kill.assert_any_call(456, signal.SIGTERM)
+
+        # Verify task is marked as cancelled
+        updated_data = persistence.load_tasks(tasks_file)
+        assert updated_data.tasks[0].status == models.TaskStatus.CANCELLED
+
+
+def test_reset_task(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    task_id = "12345678"
+    data = models.Roadmap(
+        tasks=[
+            models.Task(
+                id=task_id,
+                description="Task 1",
+                status=models.TaskStatus.COMPLETED,
+                progress=["done"],
+            )
+        ],
+    )
+    persistence.save_tasks(tasks_file, data)
+
+    # Create log file
+    log_file = paths.get_log_file(tasks_file, task_id)
+    log_file.parent.mkdir(parents=True, exist_ok=True)
+    log_file.write_text("log content")
+
+    reset_task = lifecycle.reset_task(tasks_file, task_id)
+    assert reset_task.status == models.TaskStatus.PENDING
+    assert reset_task.progress == []
+    assert not log_file.exists()
+
+
+@patch("lemming.tasks.lifecycle.is_pid_alive")
+def test_is_task_active(mock_is_pid_alive):
+    now = time.time()
+
+    # 1. Pending task is never active
+    task_pending = models.Task(
+        id="1", description="test", status=models.TaskStatus.PENDING
+    )
+    assert not lifecycle.is_task_active(task_pending, now)
+
+    # 2. IN_PROGRESS but no PID -> not active
+    task_no_pid = models.Task(
+        id="2",
+        description="test",
+        status=models.TaskStatus.IN_PROGRESS,
+        last_heartbeat=now,
+    )
+    assert not lifecycle.is_task_active(task_no_pid, now)
+
+    # 3. IN_PROGRESS, has PID, PID dead -> not active
+    mock_is_pid_alive.return_value = False
+    task_dead_pid = models.Task(
+        id="3",
+        description="test",
+        status=models.TaskStatus.IN_PROGRESS,
+        pid=123,
+        last_heartbeat=now,
+    )
+    assert not lifecycle.is_task_active(task_dead_pid, now)
+
+    # 4. IN_PROGRESS, has PID, PID alive, stale heartbeat -> not active
+    mock_is_pid_alive.return_value = True
+    stale_time = now - lifecycle.STALE_THRESHOLD - 10
+    task_stale = models.Task(
+        id="4",
+        description="test",
+        status=models.TaskStatus.IN_PROGRESS,
+        pid=123,
+        last_heartbeat=stale_time,
+    )
+    assert not lifecycle.is_task_active(task_stale, now)
+
+    # 5. IN_PROGRESS, has PID, PID alive, fresh heartbeat -> active!
+    task_active = models.Task(
+        id="5",
+        description="test",
+        status=models.TaskStatus.IN_PROGRESS,
+        pid=123,
+        last_heartbeat=now,
+    )
+    assert lifecycle.is_task_active(task_active, now)
+
+    # 6. Finalizing (requested_status), no PID -> not active (ready for hooks)
+    task_finalizing = models.Task(
+        id="6",
+        description="test",
+        status=models.TaskStatus.IN_PROGRESS,
+        requested_status=models.TaskStatus.COMPLETED,
+        last_heartbeat=now,
+    )
+    assert not lifecycle.is_task_active(task_finalizing, now)
+
+    # 7. Finalizing (requested_status), PID alive, fresh heartbeat -> active!
+    # (hooks running)
+    task_hooks_running = models.Task(
+        id="7",
+        description="test",
+        status=models.TaskStatus.IN_PROGRESS,
+        requested_status=models.TaskStatus.COMPLETED,
+        pid=123,
+        last_heartbeat=now,
+    )
+    assert lifecycle.is_task_active(task_hooks_running, now)