shikiru-cli 0.2.0__py3-none-any.whl

shikiru/agents/sdk/__init__.py

@@ -0,0 +1,17 @@
+"""Reusable process and stream tools for agent plugins."""
+
+from shikiru.agents.sdk.turn import (
+    StreamingTurn,
+    TurnParser,
+    TurnProcess,
+    TurnProcessResult,
+    TurnProcessSequence,
+)
+
+__all__ = [
+    "StreamingTurn",
+    "TurnParser",
+    "TurnProcess",
+    "TurnProcessResult",
+    "TurnProcessSequence",
+]

shikiru/agents/sdk/reset_time.py

@@ -0,0 +1,137 @@
+"""`ResetTimeParser`: turns an agent's reset-time strings into aware `datetime`s."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from shikiru.clock import Clock
+
+_EPOCH_SECONDS_PATTERN = re.compile(r"^\d+(\.\d+)?$")
+_CLOCK_TIME_PATTERN = re.compile(
+    r"resets\s+(?P<hour>\d{1,2})(?::(?P<minute>\d{2}))?\s*(?P<meridiem>am|pm)\s*\((?P<zone>[^)]+)\)",
+    re.IGNORECASE,
+)
+_RELATIVE_DURATION_COMPONENT = r"(?P<amount>\d+)\s*(?P<unit>second|minute|hour|day)s?"
+_RELATIVE_DURATION_PATTERN = re.compile(
+    rf"in\s+(?P<components>(?:{_RELATIVE_DURATION_COMPONENT}\s*)+)", re.IGNORECASE
+)
+_RELATIVE_DURATION_COMPONENT_PATTERN = re.compile(_RELATIVE_DURATION_COMPONENT, re.IGNORECASE)
+_DATE_TEXT_PATTERN = re.compile(
+    r"(?P<month>[A-Za-z]{3})[a-z]*\.?\s+(?P<day>\d{1,2})(?:st|nd|rd|th)?,?\s+(?P<year>\d{4})"
+    r"(?:\s+at)?\s+(?P<hour>\d{1,2}):(?P<minute>\d{2})\s*(?P<meridiem>am|pm)"
+    r"(?:\s*\((?P<zone>[^)]+)\)|\s+(?P<utc>UTC|GMT)\b)?",
+    re.IGNORECASE,
+)
+_MONTHS = ("jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec")
+_PM = "pm"
+_SECONDS_PER_UNIT = {"second": 1, "minute": 60, "hour": 3600, "day": 86400}
+_HOURS_PER_MERIDIEM = 12
+
+
+class ResetTimeParser:
+    """Parses a `resets ...`, ISO, epoch-seconds or relative-duration string into a `datetime`."""
+
+    def __init__(
+        self, clock: Clock, *, resolve_local: Callable[[datetime], datetime] | None = None
+    ) -> None:
+        """Anchor relative and clock-time parsing on `clock.now()`, never the wall clock.
+
+        `resolve_local` turns a naive wall-clock time into the aware instant it names in the
+        zone the agent printed it in. Without it a date text that names no zone stays unknown.
+        """
+        self._clock = clock
+        self._resolve_local = resolve_local
+
+    def parse(self, text: str) -> datetime | None:
+        """Return the aware `datetime` `text` names, or `None` if no known format matches."""
+        stripped = text.strip()
+        return (
+            self._parse_epoch(stripped)
+            or self._parse_iso(stripped)
+            or self._parse_relative(stripped)
+            or self._parse_clock_time(stripped)
+            or self._parse_date_text(stripped)
+        )
+
+    def _parse_epoch(self, text: str) -> datetime | None:
+        if not _EPOCH_SECONDS_PATTERN.match(text):
+            return None
+        return datetime.fromtimestamp(float(text), tz=UTC)
+
+    def _parse_iso(self, text: str) -> datetime | None:
+        try:
+            parsed = datetime.fromisoformat(text)
+        except ValueError:
+            return None
+        return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=UTC)
+
+    def _parse_relative(self, text: str) -> datetime | None:
+        match = _RELATIVE_DURATION_PATTERN.search(text)
+        if match is None:
+            return None
+        seconds = sum(
+            int(component.group("amount")) * _SECONDS_PER_UNIT[component.group("unit").lower()]
+            for component in _RELATIVE_DURATION_COMPONENT_PATTERN.finditer(
+                match.group("components")
+            )
+        )
+        return self._clock.now() + timedelta(seconds=seconds)
+
+    def _parse_clock_time(self, text: str) -> datetime | None:
+        match = _CLOCK_TIME_PATTERN.search(text)
+        if match is None:
+            return None
+        try:
+            zone = ZoneInfo(match.group("zone"))
+        except ZoneInfoNotFoundError, ValueError:
+            return None
+        hour = int(match.group("hour")) % _HOURS_PER_MERIDIEM
+        if match.group("meridiem").lower() == _PM:
+            hour += _HOURS_PER_MERIDIEM
+        minute = int(match.group("minute") or 0)
+        now_in_zone = self._clock.now().astimezone(zone)
+        candidate = now_in_zone.replace(hour=hour, minute=minute, second=0, microsecond=0)
+        if candidate <= now_in_zone:
+            candidate += timedelta(days=1)
+        return candidate
+
+    def _parse_date_text(self, text: str) -> datetime | None:
+        match = _DATE_TEXT_PATTERN.search(text)
+        if match is None:
+            return None
+        month = match.group("month").lower()
+        if month not in _MONTHS:
+            return None
+        hour = int(match.group("hour"))
+        if not 1 <= hour <= _HOURS_PER_MERIDIEM:
+            return None
+        hour = hour % _HOURS_PER_MERIDIEM
+        if match.group("meridiem").lower() == _PM:
+            hour += _HOURS_PER_MERIDIEM
+        try:
+            naive = datetime(  # noqa: DTZ001
+                int(match.group("year")),
+                _MONTHS.index(month) + 1,
+                int(match.group("day")),
+                hour,
+                int(match.group("minute")),
+            )
+        except ValueError:
+            return None
+        return self._attach_zone(naive, match.group("zone"), match.group("utc"))
+
+    def _attach_zone(self, naive: datetime, zone: str | None, utc: str | None) -> datetime | None:
+        if utc is not None:
+            return naive.replace(tzinfo=UTC)
+        if zone is not None:
+            try:
+                return naive.replace(tzinfo=ZoneInfo(zone.strip()))
+            except ZoneInfoNotFoundError, ValueError:
+                return None
+        return self._resolve_local(naive) if self._resolve_local is not None else None

shikiru/agents/sdk/turn.py

@@ -0,0 +1,335 @@
+"""Process-per-turn plugin building blocks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol
+
+from shikiru.agents.contracts import (
+    AgentSignal,
+    FailureKind,
+    SessionStarted,
+    TurnEnded,
+    TurnFailed,
+    TurnSpec,
+)
+from shikiru.private import append_private_bytes, make_private_dir
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Callable, Mapping
+    from pathlib import Path
+
+    from shikiru.process import SpawnedProcess, SubprocessRunner
+
+STREAM_FILENAME_SUFFIX = ".stream.jsonl"
+STDERR_FILENAME_SUFFIX = ".stderr.log"
+_LINE_ENDINGS = "\r\n"
+EMPTY_OUTPUT = "(empty)"
+
+
+def stream_log_path(turn_dir: Path, role: str) -> Path:
+    """Return where a turn keeps `role`'s raw stdout stream."""
+    return turn_dir / f"{role}{STREAM_FILENAME_SUFFIX}"
+
+
+def stderr_log_path(turn_dir: Path, role: str) -> Path:
+    """Return where a turn keeps `role`'s captured stderr."""
+    return turn_dir / f"{role}{STDERR_FILENAME_SUFFIX}"
+
+
+def _append_raw(path: Path, content: bytes) -> None:
+    make_private_dir(path.parent)
+    append_private_bytes(path, content)
+
+
+class TurnParser(Protocol):
+    """Maps one agent's stdout lines and process exit into normalized signals."""
+
+    def feed(self, line: str) -> list[AgentSignal]:
+        """Map one newline-free stdout line to zero or more signals."""
+        ...
+
+    def finish(
+        self, exit_code: int, stderr: str, *, interrupted: bool = False
+    ) -> list[AgentSignal]:
+        """Map process exit and captured stderr, marking an intentional stop as interrupted."""
+        ...
+
+
+@dataclass(frozen=True)
+class TurnProcess:
+    """One process in a plugin's compact, prompt or retry sequence."""
+
+    argv: tuple[str, ...]
+    cwd: Path
+    env: Mapping[str, str]
+    parser: TurnParser
+
+
+@dataclass(frozen=True)
+class TurnProcessResult:
+    """The parsed outcome of one process in a turn sequence."""
+
+    signals: tuple[AgentSignal, ...]
+    exit_code: int
+    stderr: str
+
+
+class TurnProcessSequence(Protocol):
+    """Builds the next process in one turn, using the previous process outcome."""
+
+    def start(self, spec: TurnSpec) -> TurnProcess:
+        """Build the first process, including pre-turn compaction when needed."""
+        ...
+
+    def advance(self, spec: TurnSpec, previous: TurnProcessResult) -> TurnProcess | None:
+        """Build a compact or retry process, or finish the turn with `None`."""
+        ...
+
+
+class StreamingTurn:
+    """Runs a plugin's process sequence and validates the turn's start and final signal."""
+
+    def __init__(
+        self,
+        spec: TurnSpec,
+        runner: SubprocessRunner,
+        sequence: TurnProcessSequence,
+        first_process: TurnProcess,
+        process: SpawnedProcess,
+    ) -> None:
+        self._spec = spec
+        self._runner = runner
+        self._sequence = sequence
+        self._current_process_spec = first_process
+        self._process = process
+        self._signal_reader_started = False
+        self._stopped = False
+        self._interrupted = False
+        self._session_id: str | None = None
+        self._session_started = False
+        self._process_session_started = False
+        self._signal_count = 0
+
+    @classmethod
+    async def start(
+        cls, spec: TurnSpec, runner: SubprocessRunner, sequence: TurnProcessSequence
+    ) -> StreamingTurn:
+        """Create the first child process and return a live `Turn`."""
+        first_process = sequence.start(spec)
+        process = await runner.spawn(
+            first_process.argv,
+            cwd=first_process.cwd,
+            env=first_process.env,
+            on_started=spec.on_process,
+        )
+        return cls(spec, runner, sequence, first_process, process)
+
+    @property
+    def pid(self) -> int:
+        """Return the operating system id for the process running now."""
+        return self._process.pid
+
+    async def signals(self) -> AsyncIterator[AgentSignal]:
+        """Yield normalized signals once, preserving each process's raw output in the turn dir."""
+        if self._signal_reader_started:
+            message = "signals() can only be consumed once"
+            raise RuntimeError(message)
+        self._signal_reader_started = True
+        process = self._process
+        try:
+            while True:
+                self._process_session_started = False
+                execution = _ProcessExecution(
+                    parser=self._current_process_spec.parser,
+                    stream_path=self._stream_path,
+                    stderr_path=self._stderr_path,
+                    normalize=self._normalize,
+                    process=process,
+                    interrupted=lambda: self._interrupted,
+                )
+                async for signal in execution.signals():
+                    yield signal
+                outcome = execution.outcome
+                protocol_failure = self._protocol_failure(execution, outcome, process)
+                if protocol_failure is not None:
+                    yield protocol_failure
+                    return
+                if not self._session_started or self._stopped:
+                    terminal = self._stopped_or_start_failure(execution, outcome, process)
+                    if terminal is not None:
+                        yield terminal
+                    return
+                next_process = self._sequence.advance(self._spec, outcome)
+                if next_process is None:
+                    terminal = execution.terminal or self._unknown_failure(
+                        "agent process ended without a turn result",
+                        outcome.exit_code,
+                        process.stderr_tail,
+                    )
+                    yield terminal
+                    return
+                process = await self._runner.spawn(
+                    next_process.argv,
+                    cwd=next_process.cwd,
+                    env=next_process.env,
+                    on_started=self._spec.on_process,
+                )
+                self._current_process_spec = next_process
+                self._process = process
+        finally:
+            if process.returncode is None:
+                await process.stop()
+
+    async def stop(self) -> None:
+        """Stop the process running now, allowing a later turn to resume its session."""
+        self._stopped = True
+        self._interrupted = self._interrupted or self._process.returncode is None
+        await self._process.stop()
+
+    @classmethod
+    def _unknown_failure(cls, reason: str, exit_code: int, stderr_tail: str) -> TurnFailed:
+        return TurnFailed(
+            kind=FailureKind.UNKNOWN,
+            message=cls._unknown_message(reason, exit_code, stderr_tail),
+            resets_at=None,
+        )
+
+    def _protocol_failure(
+        self, execution: _ProcessExecution, outcome: TurnProcessResult, process: SpawnedProcess
+    ) -> TurnFailed | None:
+        if execution.protocol_problem is None:
+            return None
+        return self._unknown_failure(
+            execution.protocol_problem, outcome.exit_code, process.stderr_tail
+        )
+
+    def _stopped_or_start_failure(
+        self, execution: _ProcessExecution, outcome: TurnProcessResult, process: SpawnedProcess
+    ) -> TurnEnded | TurnFailed | None:
+        if not self._session_started:
+            if self._interrupted and not outcome.signals:
+                return None
+            if isinstance(execution.terminal, TurnFailed):
+                return execution.terminal
+            return self._unknown_failure(
+                "agent stream omitted SessionStarted", outcome.exit_code, process.stderr_tail
+            )
+        if execution.terminal is not None:
+            return execution.terminal
+        if self._interrupted:
+            return None
+        return self._unknown_failure(
+            "agent process ended without a turn result", outcome.exit_code, process.stderr_tail
+        )
+
+    def _normalize(self, signal: AgentSignal) -> tuple[AgentSignal | None, str | None]:
+        if not isinstance(signal, SessionStarted):
+            return self._normalize_other(signal)
+        if self._process_session_started:
+            return None, "process emitted more than one SessionStarted"
+        self._process_session_started = True
+        return self._normalize_session_start(signal)
+
+    def _normalize_session_start(
+        self, signal: SessionStarted
+    ) -> tuple[AgentSignal | None, str | None]:
+        if self._session_started:
+            if signal.session_id != self._session_id:
+                return None, "turn emitted more than one session id"
+            return None, None
+        if self._signal_count:
+            return None, "agent stream emitted a signal before SessionStarted"
+        if not signal.session_id.strip():
+            return None, "agent stream emitted an empty session id"
+        if self._spec.session_id is not None and signal.session_id != self._spec.session_id:
+            return None, "resumed turn emitted a different session id"
+        self._session_id = signal.session_id
+        self._session_started = True
+        self._signal_count += 1
+        return signal, None
+
+    def _normalize_other(self, signal: AgentSignal) -> tuple[AgentSignal | None, str | None]:
+        if not self._session_started:
+            self._signal_count += 1
+            return None, "turn emitted a signal before SessionStarted"
+        self._signal_count += 1
+        return signal, None
+
+    @staticmethod
+    def _unknown_message(reason: str, exit_code: int, stderr_tail: str) -> str:
+        tail = stderr_tail or EMPTY_OUTPUT
+        return f"{reason}; process exited with status {exit_code}; stderr tail: {tail}"
+
+    @property
+    def _stream_path(self) -> Path:
+        return stream_log_path(self._spec.turn_dir, self._spec.role)
+
+    @property
+    def _stderr_path(self) -> Path:
+        return stderr_log_path(self._spec.turn_dir, self._spec.role)
+
+
+class _ProcessExecution:
+    def __init__(
+        self,
+        *,
+        parser: TurnParser,
+        stream_path: Path,
+        stderr_path: Path,
+        normalize: Callable[[AgentSignal], tuple[AgentSignal | None, str | None]],
+        process: SpawnedProcess,
+        interrupted: Callable[[], bool],
+    ) -> None:
+        self._parser = parser
+        self._stream_path = stream_path
+        self._stderr_path = stderr_path
+        self._normalize = normalize
+        self._process = process
+        self._interrupted = interrupted
+        self._signals: list[AgentSignal] = []
+        self.terminal: TurnEnded | TurnFailed | None = None
+        self.protocol_problem: str | None = None
+        self._outcome: TurnProcessResult | None = None
+
+    @property
+    def outcome(self) -> TurnProcessResult:
+        if self._outcome is None:
+            message = "process signals must be consumed before reading the outcome"
+            raise RuntimeError(message)
+        return self._outcome
+
+    async def signals(self) -> AsyncIterator[AgentSignal]:
+        async for raw_line in self._process.stdout_lines():
+            _append_raw(self._stream_path, raw_line)
+            line = raw_line.decode(errors="replace").rstrip(_LINE_ENDINGS)
+            async for signal in self._parsed(self._parser.feed(line)):
+                yield signal
+        exit_code = await self._process.wait()
+        _append_raw(self._stderr_path, self._process.stderr_bytes)
+        async for signal in self._parsed(
+            self._parser.finish(
+                exit_code,
+                self._process.stderr,
+                interrupted=self._interrupted(),
+            )
+        ):
+            yield signal
+        self._outcome = TurnProcessResult(tuple(self._signals), exit_code, self._process.stderr)
+
+    async def _parsed(self, signals: list[AgentSignal]) -> AsyncIterator[AgentSignal]:
+        for signal in signals:
+            if self.terminal is not None:
+                self.protocol_problem = self.protocol_problem or (
+                    "process emitted a signal after its terminal signal"
+                )
+                self._signals.append(signal)
+                continue
+            if isinstance(signal, (TurnEnded, TurnFailed)):
+                self.terminal = signal
+            else:
+                normalized, problem = self._normalize(signal)
+                self.protocol_problem = self.protocol_problem or problem
+                if normalized is not None and self.protocol_problem is None:
+                    yield normalized
+            self._signals.append(signal)

shikiru/agents/settings.py

@@ -0,0 +1,151 @@
+"""The optional agent capability that exposes operator-editable plugin options."""
+
+from __future__ import annotations
+
+import math
+import shlex
+from dataclasses import dataclass
+from enum import StrEnum, auto
+from typing import TYPE_CHECKING, Protocol, cast
+
+from shikiru.errors import ConfigError
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from shikiru.agents.contracts import Agent
+
+
+class SettingKind(StrEnum):
+    """How an agent option is edited and written to the project config."""
+
+    NUMBER = auto()
+    CHOICE = auto()
+    ARGS = auto()
+
+
+class AgentSettingError(ConfigError):
+    """A rejected agent setting; `key` names the plugin option and `input_id` its editor."""
+
+    def __init__(self, key: str, message: str, input_id: str = "") -> None:
+        """Explain why the text entered for option `key` cannot be written."""
+        super().__init__(message)
+        self.key = key
+        self.input_id = input_id
+
+
+class AgentOptionsError(ConfigError):
+    """A plugin's rejection of its options; `key` names the offending option when known."""
+
+    def __init__(self, message: str, key: str | None = None) -> None:
+        """Explain why a plugin refuses its options, naming option `key` when one is at fault."""
+        super().__init__(message)
+        self.key = key
+
+
+@dataclass(frozen=True, slots=True)
+class AgentSetting:
+    """One option a plugin offers the Operator, with its default, guidance and accepted values."""
+
+    key: str
+    label: str
+    help: str
+    kind: SettingKind
+    default: float | str | tuple[str, ...] | None
+    unit: str = ""
+    choices: tuple[str, ...] = ()
+    minimum: float | None = None
+    maximum: float | None = None
+
+    @property
+    def optional(self) -> bool:
+        """Whether the Operator may leave the option unset, so it is not written."""
+        return self.kind is SettingKind.CHOICE and self.default is None
+
+    def display(self) -> str:
+        """Return the default as the text the Operator edits."""
+        if self.default is None:
+            return ""
+        if isinstance(self.default, tuple):
+            return shlex.join(self.default)
+        if isinstance(self.default, str):
+            return self.default
+        return f"{self.default:g}"
+
+    def parse(self, raw: str) -> float | str | list[str] | None:
+        """Return the value to write for `raw`, `None` for an unset option, or raise."""
+        if self.kind is SettingKind.NUMBER:
+            return self._number(raw)
+        if self.kind is SettingKind.CHOICE:
+            return self._choice(raw)
+        return self._args(raw)
+
+    def _number(self, raw: str) -> float:
+        try:
+            value = float(raw)
+        except ValueError:
+            value = math.nan
+        below = self.minimum is not None and value < self.minimum
+        above = self.maximum is not None and value > self.maximum
+        if not math.isfinite(value) or below or above:
+            raise AgentSettingError(self.key, f"{self.label} must be {self._number_rule()}.")
+        return value
+
+    def _number_rule(self) -> str:
+        if self.minimum is not None and self.maximum is not None:
+            return f"a number from {self.minimum:g} to {self.maximum:g}"
+        if self.minimum is not None:
+            return f"a number of at least {self.minimum:g}"
+        if self.maximum is not None:
+            return f"a number of at most {self.maximum:g}"
+        return "a number"
+
+    def _choice(self, raw: str) -> str | None:
+        text = raw.strip()
+        if not text and self.optional:
+            return None
+        if text not in self.choices:
+            options = ", ".join(self.choices)
+            message = f"{self.label} must be one of: {options}."
+            raise AgentSettingError(self.key, message)
+        return text
+
+    def _args(self, raw: str) -> list[str]:
+        try:
+            return shlex.split(raw)
+        except ValueError as error:
+            message = f"{self.label} has invalid quoting: {error}."
+            raise AgentSettingError(self.key, message) from error
+
+
+@dataclass(frozen=True, slots=True)
+class AgentSettings:
+    """What an agent offers for editing, or why it cannot."""
+
+    agent: str
+    settings: tuple[AgentSetting, ...] = ()
+    supported: bool = True
+    error: str | None = None
+
+
+class SettingsProvider(Protocol):
+    """Optional agent capability listing the options worth writing to the project config."""
+
+    def settings(self) -> Sequence[AgentSetting]: ...
+
+
+def settings_for(agent: Agent) -> tuple[AgentSetting, ...] | None:
+    """Return an agent's validated settings, or `None` when it lacks the capability."""
+    provider: object = getattr(agent, "settings", None)
+    if provider is None:
+        return None
+    if not callable(provider):
+        message = f"agent {agent.name!r} returned an invalid settings capability"
+        raise ConfigError(message)
+    value = cast("Sequence[object]", provider())
+    offered = tuple(item for item in value if isinstance(item, AgentSetting))
+    keys = {item.key for item in offered}
+    if len(offered) != len(value) or len(keys) != len(offered) or not all(keys):
+        message = f"agent {agent.name!r} returned invalid or duplicate settings"
+        raise ConfigError(message)
+    return offered

shikiru/agents/testing/__init__.py

@@ -0,0 +1,26 @@
+"""The agent plugin contract test kit, imported only by tests."""
+
+from __future__ import annotations
+
+from shikiru.agents.testing.contract_suite import (
+    AgentContractSuite,
+    CompactionCase,
+    CompactionScenario,
+    InvocationCase,
+    RecordedStream,
+    ReplayedProcess,
+    assert_agent_obligations,
+)
+from shikiru.agents.testing.resume import RESUME_NONCE_PROMPT, RESUME_RECALL_PROMPT
+
+__all__ = [
+    "RESUME_NONCE_PROMPT",
+    "RESUME_RECALL_PROMPT",
+    "AgentContractSuite",
+    "CompactionCase",
+    "CompactionScenario",
+    "InvocationCase",
+    "RecordedStream",
+    "ReplayedProcess",
+    "assert_agent_obligations",
+]