shikiru-cli 0.2.0__py3-none-any.whl

shikiru/cli/report.py

@@ -0,0 +1,156 @@
+"""`shikiru report`: validates and atomically stores an agent turn's report."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import typer
+from pydantic import ValidationError
+
+from shikiru.agents.contracts import ROLE_ENV_VAR, RUN_DIR_ENV_VAR, role_dir
+from shikiru.domain.feedback import FeedbackContractError, FeedbackInput, check_feedback_report
+from shikiru.domain.reports import (
+    CURRENT_TURN_LINK_NAME,
+    FEEDBACK_FILENAME,
+    REPORT_FILENAME,
+    REPORT_JSON_INDENT,
+    REPORT_KIND_FILENAME,
+    ReportKind,
+    model_for,
+)
+from shikiru.errors import EXIT_NOT_INITIALISED, EXIT_USAGE_ERROR, ShikiruError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from pydantic import BaseModel
+
+    from shikiru.domain.reports import Report
+
+
+class ReportError(ShikiruError):
+    """A failure while handling `shikiru report`, with the process exit code to return.
+
+    `exit_code` is set per instance rather than per subclass. Invalid input and a missing current
+    turn use different exit codes through this same error type.
+    """
+
+    def __init__(self, exit_code: int, message: str) -> None:
+        """Record the process `exit_code` and the human-readable `message` for stderr."""
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.message = message
+
+
+def resolve_current_turn_dir(environ: Mapping[str, str]) -> Path:
+    """Resolve `$SHIKIRU_RUN_DIR/$SHIKIRU_ROLE/current_turn` to its target directory."""
+    run_dir = environ.get(RUN_DIR_ENV_VAR)
+    role = environ.get(ROLE_ENV_VAR)
+    if not run_dir or not role:
+        message = f"{RUN_DIR_ENV_VAR} and {ROLE_ENV_VAR} must both be set"
+        raise ReportError(EXIT_NOT_INITIALISED, message)
+    link = role_dir(Path(run_dir), role) / CURRENT_TURN_LINK_NAME
+    if not link.is_symlink() or not link.exists():
+        message = f"no current turn: {link} is missing or does not point at a live turn dir"
+        raise ReportError(EXIT_NOT_INITIALISED, message)
+    return link.resolve()
+
+
+def _report_kind(turn_dir: Path) -> ReportKind:
+    kind_path = turn_dir / REPORT_KIND_FILENAME
+    if not kind_path.is_file():
+        message = f"{kind_path} is missing"
+        raise ReportError(EXIT_USAGE_ERROR, message)
+    raw_kind = kind_path.read_text().strip()
+    try:
+        return ReportKind(raw_kind)
+    except ValueError:
+        message = f"{kind_path}: unknown report kind {raw_kind!r}"
+        raise ReportError(EXIT_USAGE_ERROR, message) from None
+
+
+def _load_report_data(file_path: Path) -> object:
+    try:
+        raw_text = file_path.read_text()
+    except OSError as error:
+        message = f"cannot read {file_path}: {error}"
+        raise ReportError(EXIT_USAGE_ERROR, message) from error
+    try:
+        return json.loads(raw_text)
+    except json.JSONDecodeError as error:
+        message = f"{file_path}: invalid JSON: {error}"
+        raise ReportError(EXIT_USAGE_ERROR, message) from error
+
+
+def _validation_error_messages(error: ValidationError) -> list[str]:
+    messages: list[str] = []
+    for violation in error.errors():
+        field_path = ".".join(str(part) for part in violation["loc"]) or "<root>"
+        messages.append(f"{field_path}: {violation['msg']}")
+    return messages
+
+
+def validate_report(turn_dir: Path, file_path: Path) -> BaseModel:
+    """Validate `file_path`'s JSON against the model named in `turn_dir`'s `report.kind`."""
+    kind = _report_kind(turn_dir)
+    data = _load_report_data(file_path)
+    model = model_for(kind)
+    try:
+        report = model.model_validate(data)
+    except ValidationError as error:
+        message = "\n".join(_validation_error_messages(error))
+        raise ReportError(EXIT_USAGE_ERROR, message) from error
+    _check_feedback_contract(turn_dir, report)
+    return report
+
+
+def _check_feedback_contract(turn_dir: Path, report: Report) -> None:
+    feedback_path = turn_dir / FEEDBACK_FILENAME
+    if not feedback_path.is_file():
+        return
+    try:
+        feedback = FeedbackInput.model_validate_json(feedback_path.read_text())
+        check_feedback_report(feedback, report)
+    except (ValidationError, OSError) as error:
+        message = f"cannot read {feedback_path}: {error}"
+        raise ReportError(EXIT_USAGE_ERROR, message) from error
+    except FeedbackContractError as error:
+        raise ReportError(EXIT_USAGE_ERROR, str(error)) from error
+
+
+def write_report(turn_dir: Path, report: BaseModel) -> Path:
+    """Write `report` to `turn_dir/report.json`, replacing it atomically."""
+    report_path = turn_dir / REPORT_FILENAME
+    descriptor, temp_name = tempfile.mkstemp(dir=turn_dir, prefix=f".{REPORT_FILENAME}.")
+    try:
+        with os.fdopen(descriptor, "w") as temp_file:
+            temp_file.write(report.model_dump_json(indent=REPORT_JSON_INDENT))
+        Path(temp_name).replace(report_path)
+    except BaseException:
+        Path(temp_name).unlink(missing_ok=True)
+        raise
+    return report_path
+
+
+def submit_report(file_path: Path, environ: Mapping[str, str]) -> Path:
+    """Resolve the current turn, validate `file_path` against its report kind, and store it."""
+    turn_dir = resolve_current_turn_dir(environ)
+    report = validate_report(turn_dir, file_path)
+    return write_report(turn_dir, report)
+
+
+_FILE_OPTION = typer.Option(..., "--file", exists=True, dir_okay=False, help="Report JSON.")
+
+
+def report_command(file: Path = _FILE_OPTION) -> None:
+    """Validate and store the current turn's report."""
+    try:
+        report_path = submit_report(file, os.environ)
+    except ReportError as error:
+        typer.echo(error.message, err=True)
+        raise typer.Exit(code=error.exit_code) from None
+    typer.echo(f"report accepted: {report_path}")

shikiru/cli/session_prompt.py

@@ -0,0 +1,63 @@
+"""Plain numbered session selection for the attach command."""
+
+from __future__ import annotations
+
+import signal
+from typing import TYPE_CHECKING
+
+from rich.text import Text
+
+from shikiru.cli.render import session_options_renderable
+from shikiru.errors import UsageError
+from shikiru.ui.console import human_console
+from shikiru.ui.section import BOLD_STEEL
+from shikiru.ui.tokens import SECONDARY_TEXT_COLOR
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from shikiru.operator.sessions import SessionRow
+
+
+SESSION_CANCELLED = "session selection was cancelled"
+SESSION_PROMPT_PREFIX = "Select a session number (or "
+SESSION_PROMPT_SUFFIX = " to cancel): "
+SESSION_CANCEL_CHOICES = frozenset({"q", "quit"})
+
+
+def prompt_for_session(rows: Sequence[SessionRow], host: str | None) -> SessionRow:
+    """Show full session identities and return the validated numbered selection."""
+    console = human_console()
+    console.print(session_options_renderable(tuple(rows), host=host, console=console))
+    while True:
+        prompt = Text.assemble(
+            (SESSION_PROMPT_PREFIX, SECONDARY_TEXT_COLOR),
+            ("q", BOLD_STEEL),
+            (SESSION_PROMPT_SUFFIX, SECONDARY_TEXT_COLOR),
+        )
+        console.print(prompt, end="")
+        previous_handler = signal.signal(signal.SIGINT, _interrupt_input)
+        try:
+            answer = input().strip()
+        except (EOFError, KeyboardInterrupt) as error:
+            raise UsageError(SESSION_CANCELLED) from error
+        finally:
+            signal.signal(signal.SIGINT, previous_handler)
+        if answer.lower() in SESSION_CANCEL_CHOICES:
+            raise UsageError(SESSION_CANCELLED)
+        if answer.isdecimal():
+            try:
+                selected = int(answer)
+            except ValueError:
+                pass
+            else:
+                if 1 <= selected <= len(rows):
+                    return rows[selected - 1]
+        retry = Text(f"Enter a number from 1 to {len(rows)}, or ", style=SECONDARY_TEXT_COLOR)
+        retry.append("q", style=BOLD_STEEL)
+        retry.append(" to cancel.", style=SECONDARY_TEXT_COLOR)
+        console.print(retry)
+
+
+def _interrupt_input(_signum: int, _frame: object) -> None:
+    raise KeyboardInterrupt

shikiru/cli/view.py

@@ -0,0 +1,131 @@
+"""`shikiru view`: a role pane's read-only live tail of its `view.jsonl`."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from rich.console import Console
+
+from shikiru.cli.context import project_root, state_from
+from shikiru.clock import SystemClock, to_local
+from shikiru.domain.tasks import Role
+from shikiru.paths import run_dir
+from shikiru.ui.quota_status import quota_status_text
+from shikiru.ui.status_strip import StatusStrip
+from shikiru.ui.stream import StreamLine
+from shikiru.ui.tokens import AMBER
+from shikiru.view_log import quota_status_path, read_quota_status, view_log_path
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from shikiru.clock import Clock
+
+_LINE_END = b"\n"
+_VIEW_POLL_SECONDS = 0.5
+_VIEW_READ_BYTES = 65_536
+
+
+class ViewTail:
+    """Follows one `view.jsonl`, printing each complete row through a `StreamLine`.
+
+    While `status_path` exists, its quota wait shows as a status strip above the output.
+    """
+
+    def __init__(
+        self,
+        path: Path,
+        stream: StreamLine,
+        console: Console,
+        clock: Clock,
+        *,
+        status_path: Path,
+        strip: StatusStrip,
+    ) -> None:
+        """Tail `path` from its start, rendering with `stream` onto `console`."""
+        self._path = path
+        self._stream = stream
+        self._console = console
+        self._clock = clock
+        self._status_path = status_path
+        self._strip = strip
+        self._offset = 0
+        self._pending_bytes = b""
+        self._size = (console.size.width, console.size.height)
+
+    async def follow(self) -> None:
+        """Print rows as they are appended, polling through the clock until cancelled."""
+        while True:
+            size = self._console.size
+            resized = (size.width, size.height) != self._size and self._strip.active
+            if resized:
+                self._reset_for_replay()
+                self.sync_status()
+            while self.drain():
+                await self._clock.sleep(0)
+            if not resized and self.sync_status():
+                self._reset_for_replay()
+                self.sync_status()
+                while self.drain():
+                    await self._clock.sleep(0)
+            size = self._console.size
+            self._size = (size.width, size.height)
+            await self._clock.sleep(_VIEW_POLL_SECONDS)
+
+    def sync_status(self) -> bool:
+        """Show the published quota wait and report whether output needs replaying."""
+        status = read_quota_status(self._status_path)
+        if status is None:
+            return self._strip.sync(None)
+        action, at = status
+        now = to_local(self._clock.now())
+        return self._strip.sync(
+            quota_status_text(action, to_local(at) if at is not None else None, now)
+        )
+
+    def _reset_for_replay(self) -> None:
+        self._strip.reset_for_replay()
+        self._stream.reset()
+        self._offset = 0
+        self._pending_bytes = b""
+
+    def drain(self) -> bool:
+        """Print complete rows from one bounded chunk; return whether more may remain."""
+        if not self._path.is_file():
+            return False
+        with self._path.open("rb") as log:
+            log.seek(self._offset)
+            chunk = log.read(_VIEW_READ_BYTES)
+        if not chunk:
+            return False
+        self._offset += len(chunk)
+        combined = self._pending_bytes + chunk
+        complete = combined[: combined.rfind(_LINE_END) + 1]
+        self._pending_bytes = combined[len(complete) :]
+        for raw in complete.splitlines():
+            for line in self._stream.render(json.loads(raw)):
+                self._console.print(line)
+        return len(chunk) == _VIEW_READ_BYTES
+
+
+def view_command(
+    context: typer.Context,
+    task_id: Annotated[str, typer.Argument()],
+    role: Annotated[Role, typer.Argument()],
+) -> None:
+    """Render `role`'s live view of `task_id`."""
+    root = project_root(state_from(context), require_config=False)
+    console = Console()
+    tail = ViewTail(
+        view_log_path(run_dir(root, task_id), role.value),
+        StreamLine(role),
+        console,
+        SystemClock(),
+        status_path=quota_status_path(run_dir(root, task_id), role.value),
+        strip=StatusStrip(console, sys.stdin, AMBER),
+    )
+    asyncio.run(tail.follow())

shikiru/clock.py

@@ -0,0 +1,41 @@
+"""Injectable time: every timer in Shikiru goes through a `Clock`."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime
+from typing import Protocol
+
+
+class Clock(Protocol):
+    """A source of the current time and of delay, injected wherever either is needed."""
+
+    def now(self) -> datetime:
+        """Return the current UTC-aware time."""
+        ...
+
+    async def sleep(self, seconds: float) -> None:
+        """Suspend the caller for `seconds`."""
+        ...
+
+
+class SystemClock:
+    """A `Clock` backed by the real wall clock and event loop."""
+
+    def now(self) -> datetime:
+        """Return the current UTC-aware time."""
+        return datetime.now(UTC)
+
+    async def sleep(self, seconds: float) -> None:
+        """Suspend the caller for `seconds`."""
+        await asyncio.sleep(seconds)
+
+
+def to_local(value: datetime) -> datetime:
+    """Return `value` as the viewer's local time, using the offset in force at that instant."""
+    return value.astimezone()
+
+
+def from_local(value: datetime) -> datetime:
+    """Return the aware instant the naive wall-clock `value` names in the viewer's zone."""
+    return value.astimezone()

shikiru/config/__init__.py

@@ -0,0 +1,8 @@
+"""Configuration: merge, validate and expose `Settings`."""
+
+from __future__ import annotations
+
+from shikiru.config.loader import load_settings
+from shikiru.config.settings import Settings
+
+__all__ = ["Settings", "load_settings"]

shikiru/config/defaults.toml

@@ -0,0 +1,131 @@
+[project]
+trackers = []
+
+[sessions]
+ssh_timeout_seconds = 30
+
+[orchestration]
+max_parallel = 2
+max_iterations = 5
+integration = "merge"
+pr_feedback = "changes_requested"
+push_interval_seconds = 14400
+remote_recheck_seconds = 60
+poll_seconds = 2
+shutdown_seconds = 15
+dispatch_budget_seconds = 10
+engine_start_seconds = 5
+
+[orchestration.resources]
+max_cpu_pct = 85
+min_free_ram_gb = 4
+sample_seconds = 2
+cpu_window_seconds = 30
+
+[orchestration.timeouts]
+stall = 1200
+tool = 7200
+max_quota_wait = 28800
+integration_wait = 1800
+pr_wait = 604800
+helper = 300
+cache_copy = 600
+git_command = 120
+
+[orchestration.faults]
+backoff_initial_seconds = 2
+backoff_max_seconds = 60
+unexpected_fault_limit = 10
+stop_notify_seconds = 30
+repeat_notify_seconds = 300
+
+[orchestration.retries]
+unavailable_initial_seconds = 30
+unavailable_multiplier = 4
+unavailable_max_seconds = 300
+unavailable_max_retries = 3
+
+[orchestration.quota_refresh]
+interval_seconds = 300
+timeout_seconds = 30
+
+[orchestration.network]
+fetch_timeout_seconds = 30
+poll_attempts = 8
+pr_poll_seconds = 300
+pr_close_attempts = 5
+
+[escalation]
+tried_lines = 8
+
+[roles.implementer]
+escalate_after = 2
+
+[dashboard]
+widgets = ["header", "escalations", "strips", "queue", "dialogue", "usage", "resources", "docker", "disk", "faults"]
+animations = true
+docker_refresh_seconds = 5
+docker_timeout_seconds = 5
+docker_scope = "project"
+disk_refresh_seconds = 60
+disk_size_refresh_seconds = 300
+disk_warn_free_pct = 10
+disk_alert_free_pct = 5
+repo_status_cache_seconds = 10
+task_work_cache_seconds = 2
+timeline_page_size = 20
+timeline_scan_rows = 256
+timeline_refresh_seconds = 1
+recent_task_limit = 30
+recent_task_window = 3
+last_words_chars = 4000
+now_max_lines = 6
+now_compact_lines = 2
+results_commits = 3
+action_confirmation_seconds = 5
+
+[dashboard.motion]
+refresh_hz = 4
+stamp_flash_milliseconds = 400
+escalation_pulse_hz = 1
+task_event_limit = 50
+merge_event_limit = 20
+
+[dashboard.layout]
+split = "v"
+panes = [
+  { pane = "leader", size = 40 },
+  { pane = "implementer", size = 40 },
+  { pane = "shell", size = 20 },
+]
+
+[dashboard.titles]
+window = "{task_id} {title:.24}"
+leader = "{role_label} · {agent}:{model}/{effort}{pending_rung} · iter {iteration} · ctx {context} · {cost} {flags_text}"
+implementer = "{role_label} · {agent}:{model}/{effort}{pending_rung} · iter {iteration} · ctx {context} · {cost} {flags_text}"
+system = "Shikiru · {project} · {active}/{max_parallel} active · {queued} queued"
+shell = "Project folder · {cwd}"
+context_warn_pct = 40
+context_alert_pct = 60
+
+[dashboard.gauges]
+quota_warn_pct = 50
+quota_alert_pct = 90
+
+[notify]
+command = ""
+timeout_seconds = 30
+
+[logging]
+engine_log_max_bytes = 10485760
+engine_log_backups = 3
+
+[doctor]
+probe_timeout = 180
+probe_stream_tail_lines = 20
+
+[retention]
+interval_seconds = 3600
+finished_task_days = 30
+event_days = 90
+command_days = 30