shikiru-cli 0.2.0__py3-none-any.whl

shikiru/engine/turns.py

@@ -0,0 +1,457 @@
+"""Builds one prompt directory and runs its resumable headless turns."""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import TYPE_CHECKING, TypedDict
+
+from shikiru.agents.contracts import (
+    PROJECT_ENV_VAR,
+    ROLE_ENV_VAR,
+    RUN_DIR_ENV_VAR,
+    SLOT_ENV_VAR,
+    TASK_ENV_VAR,
+    FailureKind,
+    TurnFailed,
+    role_dir,
+)
+from shikiru.agents.contracts import (
+    TurnSpec as AgentTurnSpec,
+)
+from shikiru.domain.events import EventKind
+from shikiru.domain.feedback import FeedbackContractError, FeedbackInput, check_feedback_report
+from shikiru.domain.recovery import Completed, Failed, ProtocolError, Stalled, TurnResult
+from shikiru.domain.reports import (
+    CURRENT_TURN_LINK_NAME,
+    FACTS_FILENAME,
+    FEEDBACK_FILENAME,
+    HELPER_REPORT_FILENAME,
+    PROMPT_FILENAME,
+    REPORT_FILENAME,
+    REPORT_JSON_INDENT,
+    REPORT_KIND_FILENAME,
+    REPORT_SCHEMA_FILENAME,
+    schema_for,
+)
+from shikiru.errors import InvariantError, ShikiruError
+from shikiru.helper.helper import FailureClassification
+from shikiru.helper.models import Unrecoverable
+from shikiru.paths import run_dir, task_root, turns_dir
+from shikiru.private import make_private_dir, write_private_text
+from shikiru.prompts.renderer import OPERATOR_MESSAGES_KEY
+from shikiru.view_log import TURN_DIR_ITERATION_MARKER, TURN_DIR_SEPARATOR
+from shikiru.workspace.reports import InvalidTurnReportError, load_turn_report
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+    from pathlib import Path
+
+    from shikiru.config.settings import Settings
+    from shikiru.domain.reports import Report, ReportKind
+    from shikiru.domain.tasks import Role, Step, Task
+    from shikiru.engine.agents import AgentPool
+    from shikiru.engine.monitor import TurnMonitor
+    from shikiru.engine.sessions import SessionManager, SessionSelection
+    from shikiru.helper.helper import Helper
+    from shikiru.prompts.renderer import PromptName, PromptRenderer
+    from shikiru.store.events import EventLog
+    from shikiru.store.runs import RunStore
+    from shikiru.store.tasks import TaskStore
+    from shikiru.workspace.messages import OperatorMessages
+
+NUDGE_LIMIT = 2
+CLASSIFY_CONFIDENCE = 0.8
+_TURN_NUMBER_WIDTH = 2
+TURN_PROMPT = "Read {prompt_path} and follow it exactly."
+_NUDGE_MESSAGE = (
+    "Your turn ended without a valid report. Submit it with `shikiru report` as described "
+    "at the end of {prompt_path}."
+)
+_LOGGER = logging.getLogger(__name__)
+
+
+class TurnHeld(Exception):
+    """A task hold was set before the turn's agent process could start."""
+
+
+class _HelperCall(TypedDict):
+    cwd: Path
+    timeout: timedelta
+
+
+@dataclass(frozen=True)
+class TurnRequest:
+    """Prompt details for one workflow step."""
+
+    step: Step
+    iteration: int
+    kind: ReportKind
+    template: PromptName
+    context: Mapping[str, object]
+    facts: str
+    feedback: FeedbackInput | None = None
+
+
+def read_turn_report(turn_dir: Path) -> Report | None:
+    """Read `turn_dir`'s submitted report or Helper rebuild; invalid files raise explicitly."""
+    loaded = load_turn_report(turn_dir)
+    return loaded.report if loaded is not None else None
+
+
+def turn_environment(
+    task: Task, role: Role, run_dir_path: Path, project_name: str
+) -> dict[str, str]:
+    """Return the environment used by every agent process for `task`'s `role`."""
+    if task.slot is None:
+        message = f"{task.id} has no assigned slot; a turn needs a dispatched task"
+        raise InvariantError(message)
+    return session_environment(task, role, run_dir_path, project_name)
+
+
+def session_environment(
+    task: Task, role: Role, run_dir_path: Path, project_name: str
+) -> dict[str, str]:
+    """Return the environment of `task`'s `role` process, with the slot only when it has one."""
+    environment = {
+        RUN_DIR_ENV_VAR: str(run_dir_path),
+        ROLE_ENV_VAR: role.value,
+        PROJECT_ENV_VAR: project_name,
+        TASK_ENV_VAR: task.id,
+    }
+    if task.slot is not None:
+        environment[SLOT_ENV_VAR] = str(task.slot)
+    return environment
+
+
+class TurnRunner:
+    """Create turn files, run a process per attempt, and resolve reports and failures."""
+
+    def __init__(
+        self,
+        *,
+        agents: AgentPool,
+        sessions: SessionManager,
+        monitor: TurnMonitor,
+        helper: Helper,
+        renderer: PromptRenderer,
+        messages: OperatorMessages,
+        events: EventLog,
+        runs: RunStore,
+        tasks: TaskStore,
+        project_root: Path,
+        settings: Settings,
+    ) -> None:
+        self._agents = agents
+        self._sessions = sessions
+        self._monitor = monitor
+        self._helper = helper
+        self._renderer = renderer
+        self._messages = messages
+        self._events = events
+        self._runs = runs
+        self._tasks = tasks
+        self._project_root = project_root
+        self._settings = settings
+
+    async def run(
+        self,
+        task: Task,
+        role: Role,
+        selection: SessionSelection,
+        request: TurnRequest,
+        *,
+        on_start: Callable[[Path], None] | None = None,
+        on_nudge: Callable[[], None],
+    ) -> tuple[TurnResult, Path, SessionSelection]:
+        """Run one workflow turn and any resumed nudge turns to a normalized result.
+
+        Operator messages delivered into the turn return to the queue unless it completes.
+        Raises `TurnHeld`, before any agent process starts, when the task is held.
+        """
+        turn_dir = self._prepare_turn_dir(
+            run_dir(self._project_root, task.id), task.id, role, request
+        )
+        if on_start is not None:
+            on_start(turn_dir)
+        completed = False
+        try:
+            result, selection = await self._attempts(
+                task, role, selection, request, turn_dir, on_nudge=on_nudge
+            )
+            completed = isinstance(result, Completed)
+        finally:
+            if not completed:
+                self._messages.requeue(task.id, role, turn_dir)
+        return result, turn_dir, selection
+
+    async def _attempts(
+        self,
+        task: Task,
+        role: Role,
+        selection: SessionSelection,
+        request: TurnRequest,
+        turn_dir: Path,
+        *,
+        on_nudge: Callable[[], None],
+    ) -> tuple[TurnResult, SessionSelection]:
+        task_run_dir = run_dir(self._project_root, task.id)
+        task_root_dir = task_root(self._project_root, task.id)
+        prompt_path = turn_dir / PROMPT_FILENAME
+        prompt = TURN_PROMPT.format(prompt_path=prompt_path)
+        nudges = 0
+        last_message = ""
+        while True:
+            if self._tasks.require(task.id).held:
+                raise TurnHeld
+            if nudges:
+                on_nudge()
+            agent = self._agents.get(selection.rung.agent)
+            turn_spec = AgentTurnSpec(
+                rung=selection.rung,
+                role=role.value,
+                prompt=prompt,
+                cwd=task_root_dir,
+                run_dir=task_run_dir,
+                turn_dir=turn_dir,
+                add_dirs=(),
+                env=turn_environment(task, role, task_run_dir, self._settings.project.name),
+                session_id=selection.session_id,
+                usage=selection.run.usage,
+                on_process=self._monitor.process_recorder(task_run_dir, role),
+            )
+            turn = await agent.start_turn(turn_spec)
+            terminal = await self._monitor.run(
+                turn,
+                agent=agent,
+                task=task,
+                role=role,
+                rung=selection.rung,
+                run_id=selection.run.id,
+                turn_dir=turn_dir,
+                run_dir=task_run_dir,
+            )
+            if isinstance(terminal, TurnFailed):
+                return await self._classify_unknown(terminal, task, selection), selection
+            if isinstance(terminal, Stalled | ProtocolError):
+                return terminal, selection
+            last_message = terminal.last_message
+            try:
+                report = read_turn_report(turn_dir)
+                _require_feedback_contract(request, report)
+            except InvalidTurnReportError, FeedbackContractError:
+                _LOGGER.exception("invalid report in completed turn %s", turn_dir)
+                report = None
+            if report is not None:
+                return Completed(report=report), selection
+            if nudges >= NUDGE_LIMIT:
+                rebuilt = await self._rebuild(task, selection, turn_dir, request, last_message)
+                return rebuilt, selection
+            nudges += 1
+            prompt = _NUDGE_MESSAGE.format(prompt_path=prompt_path)
+            selection = self._sessions.session_for(task, role)
+
+    def completed_turn(
+        self, task_id: str, role: Role, request: TurnRequest
+    ) -> tuple[Completed, Path] | None:
+        """Return the report of `request`'s latest turn when it holds a valid one.
+
+        A restarted engine re-runs the step whose turn it lost. When that turn is the task's
+        latest, still `role`'s current turn, and already submitted a valid report, the report is
+        consumed as is instead of starting another turn.
+        """
+        turns_root = turns_dir(self._project_root, task_id)
+        if not turns_root.is_dir():
+            return None
+        turn_dir = turns_root / _turn_dir_name(_turn_count(turns_root), request)
+        link = role_dir(run_dir(self._project_root, task_id), role.value) / CURRENT_TURN_LINK_NAME
+        if not link.is_symlink() or link.readlink() != turn_dir:
+            return None
+        if not _turn_matches_request(turn_dir, request):
+            return None
+        try:
+            report = read_turn_report(turn_dir)
+            if report is not None:
+                _require_feedback_contract(request, report)
+        except InvalidTurnReportError, FeedbackContractError:
+            _LOGGER.exception("invalid report in interrupted turn %s", turn_dir)
+            return None
+        if report is None:
+            return None
+        return Completed(report=report), turn_dir
+
+    def _prepare_turn_dir(
+        self, task_run_dir: Path, task_id: str, role: Role, request: TurnRequest
+    ) -> Path:
+        turns_root = turns_dir(self._project_root, task_id)
+        make_private_dir(turns_root)
+        turn_dir = turns_root / _turn_dir_name(_turn_count(turns_root) + 1, request)
+        make_private_dir(turn_dir)
+        self._requeue_unreported(task_run_dir, task_id, role)
+        (turn_dir / REPORT_FILENAME).unlink(missing_ok=True)
+        (turn_dir / HELPER_REPORT_FILENAME).unlink(missing_ok=True)
+        self._point_current_turn(task_run_dir, role, turn_dir)
+        delivered = self._messages.deliver(task_id, role, turn_dir)
+        context = {**request.context, OPERATOR_MESSAGES_KEY: [str(path) for path in delivered]}
+        write_private_text(
+            turn_dir / PROMPT_FILENAME, self._renderer.render(request.template, context)
+        )
+        write_private_text(
+            turn_dir / REPORT_SCHEMA_FILENAME,
+            json.dumps(schema_for(request.kind), indent=REPORT_JSON_INDENT),
+        )
+        write_private_text(turn_dir / REPORT_KIND_FILENAME, request.kind.value)
+        if request.facts:
+            write_private_text(turn_dir / FACTS_FILENAME, request.facts)
+        if request.feedback is not None:
+            write_private_text(
+                turn_dir / FEEDBACK_FILENAME,
+                request.feedback.model_dump_json(indent=REPORT_JSON_INDENT),
+            )
+        return turn_dir
+
+    def _requeue_unreported(self, task_run_dir: Path, task_id: str, role: Role) -> None:
+        link = role_dir(task_run_dir, role.value) / CURRENT_TURN_LINK_NAME
+        if not link.is_symlink():
+            return
+        previous = link.readlink()
+        reported = any(
+            (previous / name).exists() for name in (REPORT_FILENAME, HELPER_REPORT_FILENAME)
+        )
+        if not reported:
+            self._messages.requeue(task_id, role, previous)
+
+    @staticmethod
+    def _point_current_turn(task_run_dir: Path, role: Role, turn_dir: Path) -> None:
+        link = role_dir(task_run_dir, role.value) / CURRENT_TURN_LINK_NAME
+        make_private_dir(link.parent)
+        if link.is_symlink() or link.exists():
+            link.unlink()
+        link.symlink_to(turn_dir)
+
+    def _helper_call(self, task: Task) -> _HelperCall:
+        return _HelperCall(
+            cwd=task_root(self._project_root, task.id),
+            timeout=timedelta(seconds=self._settings.orchestration.timeouts.helper),
+        )
+
+    async def _classify_unknown(
+        self, failure: TurnFailed, task: Task, selection: SessionSelection
+    ) -> Failed:
+        if failure.kind is not FailureKind.UNKNOWN:
+            return Failed(failure.kind, failure.resets_at, failure.message)
+        try:
+            classification = await self._helper.classify_failure(
+                failure.message, **self._helper_call(task)
+            )
+        except (ShikiruError, TimeoutError, OSError) as error:
+            _LOGGER.exception("failure classification failed for %s", task.id)
+            self._events.append(
+                EventKind.HELPER_ACTION,
+                task_id=task.id,
+                message=f"{task.id} failure classification failed",
+                data={"role": selection.run.role.value, "error": str(error)},
+            )
+            return Failed(FailureKind.OTHER, None, failure.message, unclassified=True)
+        if isinstance(classification, FailureClassification):
+            accepted = (
+                classification.confidence >= CLASSIFY_CONFIDENCE
+                and classification.kind is not FailureKind.UNKNOWN
+            )
+            self._events.append(
+                EventKind.HELPER_ACTION,
+                task_id=task.id,
+                message=f"{task.id} failure classified as {classification.kind.value}",
+                data={
+                    "role": selection.run.role.value,
+                    "kind": classification.kind.value,
+                    "confidence": classification.confidence,
+                    "accepted": accepted,
+                },
+            )
+            if accepted:
+                return Failed(classification.kind, classification.resets_at, failure.message)
+        else:
+            self._events.append(
+                EventKind.HELPER_ACTION,
+                task_id=task.id,
+                message=f"{task.id} failure could not be classified",
+                data={"role": selection.run.role.value, "reason": classification.unrecoverable},
+            )
+        return Failed(FailureKind.OTHER, None, failure.message, unclassified=True)
+
+    async def _rebuild(
+        self,
+        task: Task,
+        selection: SessionSelection,
+        turn_dir: Path,
+        request: TurnRequest,
+        last_message: str,
+    ) -> TurnResult:
+        try:
+            report = await self._helper.rebuild_report(
+                request.kind, last_message, request.facts, **self._helper_call(task)
+            )
+        except (ShikiruError, TimeoutError, OSError) as error:
+            _LOGGER.exception("report rebuild failed for %s", task.id)
+            self._events.append(
+                EventKind.HELPER_ACTION,
+                task_id=task.id,
+                message=f"{task.id} report rebuild failed",
+                data={"role": selection.run.role.value, "error": str(error)},
+            )
+            return ProtocolError()
+        if isinstance(report, Unrecoverable):
+            self._events.append(
+                EventKind.HELPER_ACTION,
+                task_id=task.id,
+                message=f"{task.id} report could not be rebuilt",
+                data={"role": selection.run.role.value, "reason": report.unrecoverable},
+            )
+            return ProtocolError()
+        if request.feedback is not None:
+            try:
+                check_feedback_report(request.feedback, report)
+            except FeedbackContractError as error:
+                _LOGGER.warning(
+                    "rebuilt report for %s breaks the feedback contract: %s", task.id, error
+                )
+                return ProtocolError()
+        write_private_text(
+            turn_dir / HELPER_REPORT_FILENAME, report.model_dump_json(indent=REPORT_JSON_INDENT)
+        )
+        return Completed(report=report, rebuilt=True)
+
+
+def _turn_matches_request(turn_dir: Path, request: TurnRequest) -> bool:
+    kind_path = turn_dir / REPORT_KIND_FILENAME
+    if not kind_path.is_file() or kind_path.read_text().strip() != request.kind.value:
+        return False
+    feedback_path = turn_dir / FEEDBACK_FILENAME
+    if request.feedback is None:
+        return not feedback_path.exists()
+    if not feedback_path.is_file():
+        return False
+    try:
+        recorded = FeedbackInput.model_validate_json(feedback_path.read_text())
+    except ValueError:
+        return False
+    return recorded == request.feedback
+
+
+def _require_feedback_contract(request: TurnRequest, report: Report | None) -> None:
+    if request.feedback is not None and report is not None:
+        check_feedback_report(request.feedback, report)
+
+
+def _turn_count(turns_root: Path) -> int:
+    return sum(1 for entry in turns_root.iterdir() if entry.is_dir())
+
+
+def _turn_dir_name(number: int, request: TurnRequest) -> str:
+    return (
+        f"{number:0{_TURN_NUMBER_WIDTH}d}{TURN_DIR_SEPARATOR}{request.step.value}"
+        f"{TURN_DIR_ITERATION_MARKER}{request.iteration}"
+    )

shikiru/errors.py

@@ -0,0 +1,144 @@
+"""The Shikiru error hierarchy and its exit codes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+EXIT_GENERIC_ERROR = 1
+EXIT_USAGE_ERROR = 2
+EXIT_NOT_INITIALISED = 3
+EXIT_COMMAND_REJECTED = 4
+
+
+class ShikiruError(Exception):
+    """Base class for all errors the CLI maps to a process exit code."""
+
+    exit_code: int = EXIT_GENERIC_ERROR
+
+
+class InvariantError(ShikiruError):
+    """An invariant the engine relies on does not hold: a logic bug, not an environmental fault."""
+
+
+class UsageError(ShikiruError):
+    """The operator invoked a command incorrectly."""
+
+    exit_code = EXIT_USAGE_ERROR
+
+
+class NotInitialisedError(ShikiruError):
+    """No `.shikiru/` project was found where one was required."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        project_root: Path | None = None,
+        missing_path: Path | None = None,
+    ) -> None:
+        """Record the missing project location when the CLI can identify it."""
+        super().__init__(message)
+        self.project_root = project_root
+        self.missing_path = missing_path
+
+    exit_code = EXIT_NOT_INITIALISED
+
+
+class CommandRejectedError(ShikiruError):
+    """The engine rejected an operator command."""
+
+    exit_code = EXIT_COMMAND_REJECTED
+
+
+class StaleTaskBranchError(ShikiruError):
+    """A task branch left by an earlier state already exists and is not at the task's base."""
+
+
+class ConfigError(ShikiruError):
+    """Project or default configuration is missing or invalid."""
+
+
+class ProjectNotRepositoryRootError(ConfigError):
+    """The selected project directory is outside or below a Git repository root."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        project_root: Path,
+        repository_root: Path | None,
+    ) -> None:
+        """Record both the selected directory and an enclosing repository, when available."""
+        super().__init__(message)
+        self.project_root = project_root
+        self.repository_root = repository_root
+
+
+class RepositoryHasNoCommitsError(ConfigError):
+    """The selected Git repository does not have a commit at HEAD."""
+
+    def __init__(self, message: str, *, project_root: Path) -> None:
+        """Record the repository whose first commit is required."""
+        super().__init__(message)
+        self.project_root = project_root
+
+
+class HeadlessOutputError(ShikiruError):
+    """An agent's headless response did not contain valid structured output."""
+
+
+class DatabaseError(ShikiruError):
+    """The state database could not be opened, migrated or queried."""
+
+
+class CommandFailed(ShikiruError):
+    """A subprocess run through `process.SubprocessRunner` exited non-zero."""
+
+    def __init__(self, argv: Sequence[str], returncode: int, stderr: str) -> None:
+        """Record the failed command's `argv`, exit code and captured stderr."""
+        argv_tuple = tuple(argv)
+        super().__init__(f"command {argv_tuple} exited {returncode}: {stderr}")
+        self.argv = argv_tuple
+        self.returncode = returncode
+        self.stderr = stderr
+
+
+class CommandTimeoutError(ShikiruError):
+    """A subprocess run through `process.SubprocessRunner` was killed after its timeout elapsed."""
+
+    def __init__(self, argv: Sequence[str], timeout: float) -> None:
+        """Record the timed-out command's `argv` and its `timeout` in seconds."""
+        argv_tuple = tuple(argv)
+        super().__init__(f"command {argv_tuple} timed out after {timeout}s")
+        self.argv = argv_tuple
+        self.timeout = timeout
+
+
+PROCESS_FAILURES = (CommandFailed, CommandTimeoutError)
+"""A subprocess call that exited non-zero or timed out."""
+
+
+class DetachedProcessError(ShikiruError):
+    """A detached process could not be launched."""
+
+    def __init__(self, argv: Sequence[str], error: OSError) -> None:
+        """Record the detached command and operating-system error."""
+        argv_tuple = tuple(argv)
+        super().__init__(f"could not launch detached command {argv_tuple}: {error}")
+        self.argv = argv_tuple
+        self.error = error
+
+
+class ProcessReplacementError(ShikiruError):
+    """A process could not replace the current process."""
+
+    def __init__(self, argv: Sequence[str], error: OSError) -> None:
+        """Record the replacement command and operating-system error."""
+        argv_tuple = tuple(argv)
+        super().__init__(f"could not replace process with {argv_tuple}: {error}")
+        self.argv = argv_tuple
+        self.error = error

shikiru/helper/__init__.py

@@ -0,0 +1,3 @@
+"""The Helper (Joshu): ordered headless calls that rebuild reports and classify failures."""
+
+from __future__ import annotations