shikiru-cli 0.2.0__py3-none-any.whl

shikiru/helper/helper.py

@@ -0,0 +1,182 @@
+"""Calls configured Helper headless agents in order and validates every answer."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from shikiru.agents.contracts import FailureKind, Rung
+from shikiru.domain.fencing import fence
+from shikiru.domain.reports import ReportKind, model_for, schema_for
+from shikiru.errors import (
+    CommandFailed,
+    CommandTimeoutError,
+    ConfigError,
+    HeadlessOutputError,
+)
+from shikiru.helper.models import Unrecoverable
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from datetime import timedelta
+    from pathlib import Path
+
+    from shikiru.agents.contracts import Agent, HeadlessAgent
+    from shikiru.clock import Clock
+    from shikiru.domain.reports import Report
+
+_REBUILD_PROMPT = (
+    "The agent's turn ended without a valid report. Reconstruct the report for this {kind} "
+    "turn from its last message and the facts below. If you cannot determine the report with "
+    'confidence, respond instead with \'{{"unrecoverable": "<reason>"}}.\n\n'
+    "## Last message\n\n{last_message}\n\n## Facts\n\n{facts}\n"
+)
+_CLASSIFY_PROMPT = (
+    "Classify this unrecognised agent failure into QUOTA, UNAVAILABLE, AUTH or OTHER. "
+    "Give confidence from 0 to 1 and a reset time only when known. If the text is ambiguous, "
+    "return UNKNOWN with low confidence.\n\n## Failure\n\n{failure}\n"
+)
+_EXPECTED_CALL_ERRORS = (
+    CommandFailed,
+    CommandTimeoutError,
+    HeadlessOutputError,
+    OSError,
+    TimeoutError,
+)
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class HelperEntry:
+    """One configured Helper rung and the agent selected for it."""
+
+    rung: Rung
+    agent: Agent
+
+
+@dataclass(frozen=True)
+class _HeadlessEntry:
+    rung: Rung
+    headless: HeadlessAgent
+
+
+class FailureClassification(BaseModel):
+    """The Helper's structured classification of an unrecognised agent failure."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    kind: FailureKind
+    confidence: float = Field(ge=0, le=1)
+    resets_at: datetime | None = None
+
+
+class Helper:
+    """Call configured headless helpers in order and validate their reports and classifications."""
+
+    def __init__(self, entries: Sequence[HelperEntry], clock: Clock) -> None:
+        if not entries:
+            message = "roles.helper.ladder must contain at least one rung"
+            raise ConfigError(message)
+        self._entries = tuple(self._headless_entry(entry) for entry in entries)
+        self._clock = clock
+
+    async def rebuild_report(
+        self,
+        kind: ReportKind,
+        last_message: str,
+        facts: str,
+        *,
+        cwd: Path,
+        timeout: timedelta,
+    ) -> Report | Unrecoverable:
+        """Reconstruct a missing report from the turn's final message and facts."""
+        schema = {"oneOf": [schema_for(kind), Unrecoverable.model_json_schema()]}
+        prompt = _REBUILD_PROMPT.format(
+            kind=kind.value,
+            last_message=fence(last_message, "text"),
+            facts=fence(facts, "text"),
+        )
+        return await self._ask(prompt, schema, model_for(kind), cwd, timeout)
+
+    async def classify_failure(
+        self,
+        failure: str,
+        *,
+        cwd: Path,
+        timeout: timedelta,
+    ) -> FailureClassification | Unrecoverable:
+        """Classify only the plugin's unrecognised failure text."""
+        schema = {
+            "oneOf": [
+                FailureClassification.model_json_schema(),
+                Unrecoverable.model_json_schema(),
+            ]
+        }
+        prompt = _CLASSIFY_PROMPT.format(failure=fence(failure, "text"))
+        return await self._ask(prompt, schema, FailureClassification, cwd, timeout)
+
+    def _headless_entry(self, entry: HelperEntry) -> _HeadlessEntry:
+        headless = entry.agent.headless()
+        if headless is None:
+            message = f"agent {entry.rung.agent!r} has no headless support required by roles.helper"
+            raise ConfigError(message)
+        return _HeadlessEntry(entry.rung, headless)
+
+    async def _ask[ResultT: BaseModel](
+        self,
+        prompt: str,
+        schema: Mapping[str, object],
+        model: type[ResultT],
+        cwd: Path,
+        timeout: timedelta,
+    ) -> ResultT | Unrecoverable:
+        started_at = self._clock.now()
+        failures: list[str] = []
+        for entry in self._entries:
+            label = f"{entry.rung.agent}:{entry.rung.model}/{entry.rung.effort}"
+            remaining = timeout - (self._clock.now() - started_at)
+            if remaining.total_seconds() <= 0:
+                failures.append(f"{label}: Helper timeout exhausted before call")
+                break
+            try:
+                raw = await entry.headless.ask(
+                    prompt,
+                    schema,
+                    entry.rung.model,
+                    entry.rung.effort,
+                    cwd,
+                    remaining,
+                )
+            except _EXPECTED_CALL_ERRORS as error:
+                failure = f"{label}: {type(error).__name__}: {error}"
+                failures.append(failure)
+                _LOGGER.warning("Helper rung failed: %s", failure, exc_info=True)
+                continue
+            result = self._validate(raw, model)
+            if not isinstance(result, Unrecoverable):
+                return result
+            failure = f"{label}: {result.unrecoverable}"
+            failures.append(failure)
+            _LOGGER.warning("Helper rung returned unusable output: %s", failure)
+        return Unrecoverable(unrecoverable=f"Helper ladder exhausted: {'; '.join(failures)}")
+
+    @staticmethod
+    def _validate[ResultT: BaseModel](
+        raw: Mapping[str, object], model: type[ResultT]
+    ) -> ResultT | Unrecoverable:
+        try:
+            return model.model_validate(raw)
+        except ValidationError as model_error:
+            try:
+                return Unrecoverable.model_validate(raw)
+            except ValidationError as unrecoverable_error:
+                reason = (
+                    f"invalid helper output for {model.__name__}: {raw!r}; "
+                    f"{model.__name__} errors: {model_error}; "
+                    f"unrecoverable errors: {unrecoverable_error}"
+                )
+                return Unrecoverable(unrecoverable=reason)

shikiru/helper/models.py

@@ -0,0 +1,11 @@
+"""Helper output model for the explicit inability to answer."""
+
+from __future__ import annotations
+
+from shikiru.domain.tasks import DomainModel
+
+
+class Unrecoverable(DomainModel):
+    """The Helper's explicit inability to answer, for either call."""
+
+    unrecoverable: str

shikiru/mcp/__init__.py

@@ -0,0 +1 @@
+"""FastMCP operator server."""

shikiru/mcp/server.py

@@ -0,0 +1,196 @@
+"""The stdio FastMCP adapter over the operator services."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import BaseModel, ConfigDict
+
+from shikiru.agents.contracts import parse_rung
+from shikiru.config.settings import ComplexityName
+from shikiru.domain.commands import (
+    AcceptResolution,
+    AnswerResolution,
+    CancelResolution,
+    Resolution,
+    ResolutionKind,
+    RetryResolution,
+)
+from shikiru.domain.events import Event, EventKind
+from shikiru.domain.tasks import Mode, Role, Status
+from shikiru.operator.commands import Ack
+from shikiru.operator.events import MAX_WAIT_SECONDS
+from shikiru.operator.queries import (
+    EscalationView,
+    PeekView,
+    StatusView,
+    TaskDetail,
+    TaskSummary,
+)
+
+if TYPE_CHECKING:
+    from shikiru.operator.services import OperatorServices
+
+SERVER_NAME = "shikiru"
+
+
+class ResolutionInput(BaseModel):
+    """Typed MCP input for an escalation resolution."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    kind: ResolutionKind
+    text: str | None = None
+    rung: str | None = None
+
+    def to_domain(self) -> Resolution:
+        """Convert this transport model to a typed domain resolution."""
+        if self.kind is ResolutionKind.ANSWER:
+            if self.text is None:
+                message = "answer resolution requires text"
+                raise ValueError(message)
+            return AnswerResolution(text=self.text)
+        if self.kind is ResolutionKind.RETRY:
+            return RetryResolution(rung=parse_rung(self.rung) if self.rung is not None else None)
+        if self.kind is ResolutionKind.ACCEPT:
+            return AcceptResolution()
+        return CancelResolution()
+
+
+def build_server(services: OperatorServices) -> FastMCP:
+    """Build a typed FastMCP server over injected operator services."""
+    server = FastMCP(SERVER_NAME)
+
+    _register_query_tools(server, services)
+    _register_command_tools(server, services)
+    _register_session_tools(server, services)
+    _register_event_tools(server, services)
+    return server
+
+
+def _register_query_tools(server: FastMCP, services: OperatorServices) -> None:
+    @server.tool()
+    def status(task_id: str | None = None) -> StatusView:
+        """Read engine, queue, usage and escalation status, optionally with one task's details."""
+        return services.queries.status(task_id)
+
+    @server.tool()
+    def list_tasks(statuses: list[Status] | None = None) -> list[TaskSummary]:
+        """List task summaries, optionally filtered by task status."""
+        return services.queries.list_tasks(statuses=statuses)
+
+    @server.tool()
+    def get_task(task_id: str) -> TaskDetail | None:
+        """Read one task's details, history, reports and sessions, or return null if absent."""
+        return services.queries.get_task(task_id)
+
+    @server.tool()
+    def list_escalations() -> list[EscalationView]:
+        """List all currently open escalations with their packets and structured decisions."""
+        return services.queries.list_escalations()
+
+    @server.tool()
+    def get_escalation(escalation_id: str) -> EscalationView | None:
+        """Read one open escalation with its packet and structured decisions, or null if absent."""
+        return services.queries.get_escalation(escalation_id)
+
+    @server.tool()
+    def peek_session(task_id: str, role: Role | None = None) -> PeekView | None:
+        """Read one task role's, or every role's, last message, usage and recent view lines."""
+        return services.queries.peek_session(task_id, role)
+
+
+def _register_command_tools(server: FastMCP, services: OperatorServices) -> None:
+    @server.tool()
+    async def submit_task(
+        *,
+        request: str,
+        title: str | None = None,
+        mode: Mode | None = None,
+        complexity: ComplexityName | None = None,
+        priority: int = 0,
+        depends_on: list[str] | None = None,
+        leader: str | None = None,
+        implementer: str | None = None,
+    ) -> Ack:
+        """Queue a task with optional title, mode, complexity, priority, dependencies and rungs."""
+        return await services.commands.submit_task(
+            request,
+            title=title,
+            mode=mode,
+            complexity=complexity,
+            priority=priority,
+            depends_on=depends_on or (),
+            leader=parse_rung(leader) if leader is not None else None,
+            implementer=parse_rung(implementer) if implementer is not None else None,
+        )
+
+    @server.tool()
+    async def prioritize_task(task_id: str, priority: int) -> Ack:
+        """Set a queued task's dispatch priority."""
+        return await services.commands.prioritize_task(task_id, priority)
+
+    @server.tool()
+    async def pause_task(task_id: str, *, now: bool = False) -> Ack:
+        """Pause a task, optionally requesting an immediate pause."""
+        return await services.commands.pause_task(task_id, now=now)
+
+    @server.tool()
+    async def resume_task(task_id: str) -> Ack:
+        """Resume a paused task."""
+        return await services.commands.resume_task(task_id)
+
+    @server.tool()
+    async def cancel_task(task_id: str) -> Ack:
+        """Cancel a task."""
+        return await services.commands.cancel_task(task_id)
+
+    @server.tool()
+    async def retry_task(task_id: str) -> Ack:
+        """Retry a failed or escalated task from its current step."""
+        return await services.commands.retry_task(task_id)
+
+    @server.tool()
+    async def set_rung(task_id: str, role: Role, rung: str) -> Ack:
+        """Set the task role's agent, model and optional effort rung."""
+        return await services.commands.set_rung(task_id, role, parse_rung(rung))
+
+    @server.tool()
+    async def resolve_escalation(escalation_id: str, resolution: ResolutionInput) -> Ack:
+        """Resolve an open escalation with an answer, retry, accept or cancel decision."""
+        return await services.commands.resolve_escalation(escalation_id, resolution.to_domain())
+
+
+def _register_session_tools(server: FastMCP, services: OperatorServices) -> None:
+    @server.tool()
+    async def send_message(task_id: str, role: Role, text: str) -> Ack:
+        """Queue a message the role reads at the start of its next turn."""
+        return await services.commands.send_message(task_id, role, text)
+
+    @server.tool()
+    async def take_over(task_id: str, role: Role) -> Ack:
+        """Stop the role's turn and run its session interactively in its pane."""
+        return await services.commands.take_over(task_id, role)
+
+    @server.tool()
+    async def hand_back(task_id: str, role: Role) -> Ack:
+        """Return a taken-over role's session to the engine and resume the task."""
+        return await services.commands.hand_back(task_id, role)
+
+
+def _register_event_tools(server: FastMCP, services: OperatorServices) -> None:
+    @server.tool()
+    async def wait_for_events(
+        since_id: int,
+        kinds: list[EventKind] | None = None,
+        task_id: str | None = None,
+        timeout_s: float = MAX_WAIT_SECONDS,
+    ) -> list[Event]:
+        """Wait up to 300 seconds for events after since_id with optional kind and task filters."""
+        return await services.events.wait(
+            since_id,
+            kinds=kinds,
+            task=task_id,
+            timeout=timeout_s,
+        )

shikiru/operator/__init__.py

@@ -0,0 +1,33 @@
+"""Operator services shared by the CLI, MCP server and dashboard palette."""
+
+from shikiru.operator.commands import Ack, AckStatus, OperatorCommands
+from shikiru.operator.doctor import Doctor, DoctorCheck, DoctorReport
+from shikiru.operator.events import EventFeed
+from shikiru.operator.queries import (
+    EscalationView,
+    OperatorQueries,
+    OperatorQueryError,
+    PeekView,
+    StatusView,
+    TaskDetail,
+    TaskSummary,
+)
+from shikiru.operator.services import OperatorServices
+
+__all__ = [
+    "Ack",
+    "AckStatus",
+    "Doctor",
+    "DoctorCheck",
+    "DoctorReport",
+    "EscalationView",
+    "EventFeed",
+    "OperatorCommands",
+    "OperatorQueries",
+    "OperatorQueryError",
+    "OperatorServices",
+    "PeekView",
+    "StatusView",
+    "TaskDetail",
+    "TaskSummary",
+]

shikiru/operator/attachment.py

@@ -0,0 +1,24 @@
+"""Shared admission policy for Shikiru-managed tmux client transitions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shikiru.errors import UsageError
+
+if TYPE_CHECKING:
+    from shikiru.tmux.client import Tmux
+
+_BUSY_SESSION_MESSAGE = (
+    "a terminal is already attached to Shikiru session {session!r}; detach it first, then retry"
+)
+
+
+async def admit_attachment(tmux: Tmux, session: str, current_pane: str | None) -> bool:
+    """Return true for a same-client no-op or refuse when another client owns the session."""
+    clients = await tmux.session_client_panes(session)
+    if not clients:
+        return False
+    if len(clients) == 1 and current_pane is not None and clients[0] == current_pane:
+        return True
+    raise UsageError(_BUSY_SESSION_MESSAGE.format(session=session))