shikiru-cli 0.2.0__py3-none-any.whl

shikiru/operator/timeline.py

@@ -0,0 +1,416 @@
+"""Bounded reads of recorded normalized signal files for task evidence pages."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, cast
+
+from shikiru.domain.tasks import Role
+from shikiru.domain.timeline import (
+    MISSING_SIGNAL_SUMMARY,
+    TIMELINE_ACTIVITY_CATEGORY,
+    TIMELINE_AGENT_CATEGORY,
+    TIMELINE_ALL_CATEGORY,
+    TIMELINE_DECISION_CATEGORY,
+    TIMELINE_ENGINE_CATEGORY,
+    TIMELINE_EVIDENCE_CATEGORY,
+    TIMELINE_MESSAGE_CATEGORY,
+    TIMELINE_SIGNAL_CATEGORY,
+    TIMELINE_SOURCE_AGENT,
+    TIMELINE_TOOL_CATEGORY,
+    TIMELINE_TRANSITION_CATEGORY,
+    TIMELINE_USAGE_CATEGORY,
+    ParsedSignal,
+    parse_signal_row,
+)
+from shikiru.domain.timeline_phrases import GLYPH_ATTENTION, Phrase, Tone
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from pathlib import Path
+
+CURSOR_VERSION = 1
+SIGNAL_LINE_BLOCK_BYTES = 65536
+CURSOR_POSITION_FIELDS = 2
+TIMELINE_CURSOR_ERROR = "task evidence cursor is invalid"
+TIMELINE_CURSOR_FILTER_ERROR = "task evidence cursor belongs to different filters"
+TIMELINE_MISSING_DETAIL = "No recorded normalized signal file is available for this role."
+TIMELINE_READ_ERROR_SUMMARY = "Could not read recorded signal evidence"
+TIMELINE_READ_ERROR_PREFIX = "unavailable:"
+
+
+@dataclass(frozen=True)
+class TimelineFilters:
+    """Filters applied consistently to engine events and normalized signal evidence."""
+
+    role: str | None
+    turn: str | None
+    category: str
+
+
+@dataclass(frozen=True)
+class TimelineCursor:
+    """Positions immediately after the newest rows already shown from each source."""
+
+    event_before: tuple[str, int] | None
+    signal_before: Mapping[str, int | None]
+
+
+@dataclass(frozen=True)
+class TimelineItem:
+    """One evidence row with stable identity and its source ordering key."""
+
+    identity: str
+    timestamp: datetime | None
+    source: str
+    category: str
+    summary: str
+    phrase: Phrase
+    detail: str
+    role: str | None
+    turn: str | None
+    event_id: int | None = None
+    signal_offset: int | None = None
+    signal_end_offset: int | None = None
+    incomplete: bool = False
+    timestamp_error: str | None = None
+    listed: bool = True
+
+
+@dataclass(frozen=True)
+class SignalBatch:
+    """A bounded signal page and a position that safely replays its first row."""
+
+    items: tuple[TimelineItem, ...]
+    replay_offset: int | None
+    scan_offset: int
+    has_more: bool = False
+
+
+def encode_cursor(cursor: TimelineCursor, filters: TimelineFilters) -> str:
+    """Serialize a source-position cursor with the filters that define its ordering."""
+    encoded = {
+        "version": CURSOR_VERSION,
+        "event_before": list(cursor.event_before) if cursor.event_before is not None else None,
+        "signal_before": dict(cursor.signal_before),
+        "filters": {"role": filters.role, "turn": filters.turn, "category": filters.category},
+    }
+    return json.dumps(encoded, separators=(",", ":"), sort_keys=True)
+
+
+def decode_cursor(
+    token: str,
+    *,
+    filters: TimelineFilters,
+    roles: Sequence[str],
+) -> TimelineCursor:
+    """Validate an opaque cursor before continuing a filtered evidence page."""
+    data = _cursor_mapping(token)
+    expected_filters = {"role": filters.role, "turn": filters.turn, "category": filters.category}
+    if data.get("filters") != expected_filters:
+        raise ValueError(TIMELINE_CURSOR_FILTER_ERROR)
+    signal_before = _signal_positions(data, filters, roles)
+    event_before = _event_position(data)
+    return TimelineCursor(event_before=event_before, signal_before=signal_before)
+
+
+def _cursor_mapping(token: str) -> dict[str, object]:
+    try:
+        raw_data: object = json.loads(token)
+    except json.JSONDecodeError as error:
+        raise ValueError(TIMELINE_CURSOR_ERROR) from error
+    if not isinstance(raw_data, dict):
+        raise TypeError(TIMELINE_CURSOR_ERROR)
+    untyped_data = cast("dict[object, object]", raw_data)
+    if not all(isinstance(key, str) for key in untyped_data):
+        raise ValueError(TIMELINE_CURSOR_ERROR)
+    data = cast("dict[str, object]", untyped_data)
+    if type(data.get("version")) is not int or data.get("version") != CURSOR_VERSION:
+        raise ValueError(TIMELINE_CURSOR_ERROR)
+    return data
+
+
+def _signal_positions(
+    data: Mapping[str, object], filters: TimelineFilters, roles: Sequence[str]
+) -> dict[str, int | None]:
+    raw_signal_before = data.get("signal_before")
+    valid_roles = {item.value for item in Role}
+    if not isinstance(raw_signal_before, dict):
+        raise TypeError(TIMELINE_CURSOR_ERROR)
+    untyped_positions = cast("dict[object, object]", raw_signal_before)
+    if not all(isinstance(role, str) for role in untyped_positions):
+        raise TypeError(TIMELINE_CURSOR_ERROR)
+    signal_before = cast("dict[str, object]", untyped_positions)
+    if not set(signal_before) <= valid_roles:
+        raise ValueError(TIMELINE_CURSOR_ERROR)
+    if not set(signal_before) <= set(roles):
+        raise ValueError(TIMELINE_CURSOR_ERROR)
+    if filters.role is not None and set(signal_before) != set(roles):
+        raise ValueError(TIMELINE_CURSOR_ERROR)
+    positions: dict[str, int | None] = {}
+    for role, offset in signal_before.items():
+        if offset is not None and (
+            not isinstance(offset, int) or isinstance(offset, bool) or offset < -1
+        ):
+            raise ValueError(TIMELINE_CURSOR_ERROR)
+        positions[role] = offset
+    return positions
+
+
+def _event_position(data: Mapping[str, object]) -> tuple[str, int] | None:
+    value = data.get("event_before")
+    if value is None:
+        return None
+    if not isinstance(value, list):
+        raise TypeError(TIMELINE_CURSOR_ERROR)
+    position = cast("list[object]", value)
+    if len(position) != CURSOR_POSITION_FIELDS:
+        raise ValueError(TIMELINE_CURSOR_ERROR)
+    timestamp_value, event_id = position
+    if not isinstance(timestamp_value, str):
+        raise TypeError(TIMELINE_CURSOR_ERROR)
+    if not isinstance(event_id, int) or isinstance(event_id, bool) or event_id < 1:
+        raise ValueError(TIMELINE_CURSOR_ERROR)
+    try:
+        timestamp = datetime.fromisoformat(timestamp_value)
+    except ValueError as error:
+        raise ValueError(TIMELINE_CURSOR_ERROR) from error
+    if timestamp.tzinfo is None:
+        raise ValueError(TIMELINE_CURSOR_ERROR)
+    return timestamp_value, event_id
+
+
+def initial_cursor(paths: Mapping[str, Path]) -> TimelineCursor:
+    """Capture each normalized source's current tail for a stable latest-page read."""
+    positions: dict[str, int | None] = {}
+    for role, path in paths.items():
+        try:
+            positions[role] = path.stat().st_size
+        except OSError:
+            positions[role] = None
+    return TimelineCursor(event_before=None, signal_before=positions)
+
+
+def read_signal_batch(
+    path: Path,
+    *,
+    role: str,
+    before_offset: int | None,
+    filters: TimelineFilters,
+    limit: int,
+    scan_limit: int,
+) -> SignalBatch:
+    """Read at most `limit` matching signal rows backwards without retaining the file."""
+    if before_offset == -1:
+        return SignalBatch(items=(), replay_offset=-1, scan_offset=-1)
+    try:
+        snapshot = _signal_snapshot(path, before_offset)
+        if snapshot is None:
+            return _missing_batch(role, filters)
+        return _scan_signal_file(
+            path,
+            role=role,
+            end_position=snapshot,
+            filters=filters,
+            limit=limit,
+            scan_limit=scan_limit,
+        )
+    except (OSError, ValueError) as error:
+        return _unavailable_batch(role, filters, error)
+
+
+def _signal_snapshot(path: Path, before_offset: int | None) -> int | None:
+    try:
+        file_size = path.stat().st_size
+    except FileNotFoundError:
+        return None
+    end_position = file_size if before_offset is None else before_offset
+    if end_position > file_size:
+        message = f"recorded signal file changed before its saved cursor: {path}"
+        raise ValueError(message)
+    return end_position
+
+
+def _missing_batch(role: str, filters: TimelineFilters) -> SignalBatch:
+    missing = _missing_signal(role)
+    if _matches_signal(missing, filters):
+        return SignalBatch(items=(missing,), replay_offset=None, scan_offset=0)
+    return SignalBatch(items=(), replay_offset=0, scan_offset=0)
+
+
+def _unavailable_batch(
+    role: str, filters: TimelineFilters, error: OSError | ValueError
+) -> SignalBatch:
+    unavailable = _unavailable_signal(role, error)
+    if _matches_signal(unavailable, filters):
+        return SignalBatch(items=(unavailable,), replay_offset=-1, scan_offset=-1)
+    return SignalBatch(items=(), replay_offset=-1, scan_offset=-1)
+
+
+def _scan_signal_file(
+    path: Path,
+    *,
+    role: str,
+    end_position: int,
+    filters: TimelineFilters,
+    limit: int,
+    scan_limit: int,
+) -> SignalBatch:
+    items: list[TimelineItem] = []
+    position = end_position
+    scanned = 0
+    while position > 0 and len(items) < limit and scanned < scan_limit:
+        parsed = _previous_signal(path, role, position)
+        if parsed is None:
+            position = 0
+            break
+        position = parsed.start_offset
+        scanned += 1
+        item = _timeline_item(parsed)
+        if _matches_signal(item, filters):
+            items.append(item)
+    replay_offset = items[0].signal_end_offset if items else position
+    scan_offset = position
+    return SignalBatch(
+        items=tuple(items),
+        replay_offset=replay_offset,
+        scan_offset=scan_offset,
+        has_more=position > 0,
+    )
+
+
+def signal_category_is_requested(category: str) -> bool:
+    """Whether an evidence category can contain normalized agent signal rows."""
+    return category in {
+        TIMELINE_ALL_CATEGORY,
+        TIMELINE_AGENT_CATEGORY,
+        TIMELINE_SIGNAL_CATEGORY,
+        TIMELINE_TOOL_CATEGORY,
+        TIMELINE_MESSAGE_CATEGORY,
+        TIMELINE_USAGE_CATEGORY,
+        TIMELINE_EVIDENCE_CATEGORY,
+        TIMELINE_TRANSITION_CATEGORY,
+    }
+
+
+def event_category_is_requested(category: str) -> bool:
+    """Whether an evidence category can contain engine event rows."""
+    return category in {
+        TIMELINE_ALL_CATEGORY,
+        TIMELINE_ACTIVITY_CATEGORY,
+        TIMELINE_ENGINE_CATEGORY,
+        TIMELINE_DECISION_CATEGORY,
+        TIMELINE_TRANSITION_CATEGORY,
+    }
+
+
+def _previous_signal(
+    path: Path,
+    role: str,
+    end_position: int,
+) -> ParsedSignal | None:
+    with path.open("rb") as handle:
+        handle.seek(end_position - 1)
+        last_byte = handle.read(1)
+        incomplete = last_byte != b"\n"
+        line_end = end_position - 1 if last_byte == b"\n" else end_position
+        if line_end <= 0:
+            return None
+        search_end = line_end
+        line_start = 0
+        while search_end > 0:
+            block_start = max(search_end - SIGNAL_LINE_BLOCK_BYTES, 0)
+            handle.seek(block_start)
+            block = handle.read(search_end - block_start)
+            delimiter = block.rfind(b"\n")
+            if delimiter >= 0:
+                line_start = block_start + delimiter + 1
+                break
+            search_end = block_start
+        handle.seek(line_start)
+        raw = handle.read(line_end - line_start)
+    return parse_signal_row(
+        raw,
+        role=role,
+        start_offset=line_start,
+        end_offset=end_position,
+        incomplete=incomplete,
+    )
+
+
+def _timeline_item(signal: ParsedSignal) -> TimelineItem:
+    timestamp_error = signal.timestamp_error
+    if signal.incomplete:
+        timestamp_error = "JSONL row has not ended with a newline"
+    return TimelineItem(
+        identity=f"signal:{signal.role}:{signal.start_offset}",
+        timestamp=signal.timestamp,
+        source=TIMELINE_SOURCE_AGENT,
+        category=signal.category,
+        summary=signal.summary,
+        phrase=signal.phrase,
+        detail=signal.detail,
+        role=signal.role,
+        turn=signal.turn,
+        signal_offset=signal.start_offset,
+        signal_end_offset=signal.end_offset,
+        incomplete=signal.incomplete,
+        timestamp_error=timestamp_error,
+        listed=signal.listed,
+    )
+
+
+def _missing_signal(role: str) -> TimelineItem:
+    return TimelineItem(
+        identity=f"missing:{role}",
+        timestamp=None,
+        source=TIMELINE_SOURCE_AGENT,
+        category=TIMELINE_EVIDENCE_CATEGORY,
+        summary=MISSING_SIGNAL_SUMMARY,
+        phrase=Phrase(MISSING_SIGNAL_SUMMARY),
+        detail=TIMELINE_MISSING_DETAIL,
+        role=role,
+        turn=None,
+        signal_offset=0,
+        signal_end_offset=None,
+        timestamp_error="recorded timestamp is missing",
+        listed=False,
+    )
+
+
+def _unavailable_signal(role: str, error: OSError | ValueError) -> TimelineItem:
+    return TimelineItem(
+        identity=f"{TIMELINE_READ_ERROR_PREFIX}{role}",
+        timestamp=None,
+        source=TIMELINE_SOURCE_AGENT,
+        category=TIMELINE_EVIDENCE_CATEGORY,
+        summary=TIMELINE_READ_ERROR_SUMMARY,
+        phrase=Phrase(TIMELINE_READ_ERROR_SUMMARY, GLYPH_ATTENTION, Tone.WARNING),
+        detail=str(error),
+        role=role,
+        turn=None,
+        signal_offset=None,
+        signal_end_offset=None,
+        timestamp_error="recorded timestamp is unavailable because the source could not be read",
+    )
+
+
+def _matches_signal(item: TimelineItem, filters: TimelineFilters) -> bool:
+    if filters.role is not None and filters.role != item.role:
+        return False
+    if item.identity.startswith(TIMELINE_READ_ERROR_PREFIX):
+        return filters.category in {
+            TIMELINE_ALL_CATEGORY,
+            TIMELINE_AGENT_CATEGORY,
+            TIMELINE_SIGNAL_CATEGORY,
+            TIMELINE_EVIDENCE_CATEGORY,
+        }
+    if filters.turn is not None and filters.turn != item.turn:
+        return False
+    if filters.category == TIMELINE_AGENT_CATEGORY:
+        return item.listed
+    if filters.category in {TIMELINE_ALL_CATEGORY, TIMELINE_SIGNAL_CATEGORY}:
+        return True
+    return filters.category == item.category

shikiru/operator/toml_text.py

@@ -0,0 +1,62 @@
+"""Render keys and values as TOML text that reads back unchanged."""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import TYPE_CHECKING, cast
+
+from shikiru.errors import ConfigError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+BARE_KEY = re.compile(r"[A-Za-z0-9_-]+")
+SHORT_ESCAPES: Mapping[str, str] = {
+    "\b": "\\b",
+    "\t": "\\t",
+    "\n": "\\n",
+    "\f": "\\f",
+    "\r": "\\r",
+    '"': '\\"',
+    "\\": "\\\\",
+}
+LAST_CONTROL_CODE = 0x1F
+DELETE_CODE = 0x7F
+VALUE_SEPARATOR = ", "
+
+
+def toml_string(text: str) -> str:
+    """Return `text` as a TOML basic string, keeping non-ASCII characters literal."""
+    parts: list[str] = []
+    for character in text:
+        code = ord(character)
+        if character in SHORT_ESCAPES:
+            parts.append(SHORT_ESCAPES[character])
+        elif code <= LAST_CONTROL_CODE or code == DELETE_CODE:
+            parts.append(f"\\u{code:04X}")
+        else:
+            parts.append(character)
+    return f'"{"".join(parts)}"'
+
+
+def toml_key(key: str) -> str:
+    """Return `key` bare when TOML allows it, otherwise as one quoted key."""
+    return key if BARE_KEY.fullmatch(key) else toml_string(key)
+
+
+def toml_value(value: object) -> str:
+    """Return a bool, int, finite float, string or list of those as TOML text."""
+    if isinstance(value, bool):
+        return str(value).lower()
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float) and math.isfinite(value):
+        return repr(value)
+    if isinstance(value, str):
+        return toml_string(value)
+    if isinstance(value, (list, tuple)):
+        items = cast("Sequence[object]", value)
+        return f"[{VALUE_SEPARATOR.join(toml_value(item) for item in items)}]"
+    message = f"cannot write {value!r} to the project config"
+    raise ConfigError(message)

shikiru/palette.py

@@ -0,0 +1,18 @@
+"""Shared semantic colors for terminal and dashboard surfaces."""
+
+BACKGROUND_COLOR = "#11151b"
+SURFACE_COLOR = "#171d25"
+RAISED_SURFACE_COLOR = "#171d25"
+SELECTED_SURFACE_COLOR = "#233340"
+DETAIL_SURFACE_COLOR = "#1c2530"
+NEUTRAL_BORDER_COLOR = "#3d4654"
+PRIMARY_TEXT_COLOR = "#dce2e9"
+SECONDARY_TEXT_COLOR = "#9aa5b5"
+STEEL_BLUE = "#83bddd"
+SAGE = "#90cba6"
+AMBER = "#dfb16c"
+DUSTY_ROSE = "#e3a0a0"
+SCROLLBAR_THUMB_COLOR = "#344b5d"
+SCROLLBAR_THUMB_HOVER_COLOR = "#415e72"
+SCROLLBAR_THUMB_ACTIVE_COLOR = STEEL_BLUE
+SCROLLBAR_TRACK_COLOR = "#000008"

shikiru/paths.py

@@ -0,0 +1,91 @@
+"""Project-local paths defined by the runtime layout."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+SHIKIRU_DIR_NAME = ".shikiru"
+PROJECT_CONFIG_RELATIVE_PATH = f"{SHIKIRU_DIR_NAME}/config.toml"
+PROMPT_OVERRIDES_RELATIVE_PATH = f"{SHIKIRU_DIR_NAME}/prompts"
+STATE_DB_FILENAME = "state.db"
+SCHEMA_BACKUPS_DIR_NAME = "backups"
+ENGINE_LOCK_FILENAME = "engine.lock"
+ENGINE_LOG_DIR = "logs"
+ENGINE_LOG_FILENAME = "engine.log"
+ENGINE_OUTPUT_FILENAME = "engine.out"
+WORKTREES_DIR_NAME = "worktrees"
+RUNS_DIR_NAME = "runs"
+TURNS_DIR_NAME = "turns"
+MESSAGES_DIR_NAME = "messages"
+PROBE_DIR_NAME = "probe"
+PROBE_REPO_DIR_NAME = "repo"
+PROBE_RUN_DIR_NAME = "run"
+EXCLUDE_LINE = f"/{SHIKIRU_DIR_NAME}/"
+
+
+def project_state_dir(project_root: Path) -> Path:
+    """Return the project's `.shikiru/` state directory."""
+    return project_root / SHIKIRU_DIR_NAME
+
+
+def project_config_path(project_root: Path) -> Path:
+    """Return the project's settings file path."""
+    return project_root / PROJECT_CONFIG_RELATIVE_PATH
+
+
+def state_db_path(project_root: Path) -> Path:
+    """Return the project's SQLite state database path."""
+    return project_state_dir(project_root) / STATE_DB_FILENAME
+
+
+def engine_lock_path(project_root: Path) -> Path:
+    """Return the project's engine liveness lock path."""
+    return project_state_dir(project_root) / ENGINE_LOCK_FILENAME
+
+
+def engine_log_path(project_root: Path) -> Path:
+    """Return the project's engine log path."""
+    return project_state_dir(project_root) / ENGINE_LOG_DIR / ENGINE_LOG_FILENAME
+
+
+def engine_output_path(project_root: Path) -> Path:
+    """Return the file holding the stdout and stderr of the engine process `start` spawned."""
+    return project_state_dir(project_root) / ENGINE_LOG_DIR / ENGINE_OUTPUT_FILENAME
+
+
+def runs_root(project_root: Path) -> Path:
+    """Return the `.shikiru/runs/` directory holding every task's run directory."""
+    return project_state_dir(project_root) / RUNS_DIR_NAME
+
+
+def run_dir(project_root: Path, task_id: str) -> Path:
+    """Return `task_id`'s `.shikiru/runs/` directory."""
+    return runs_root(project_root) / task_id
+
+
+def turns_dir(project_root: Path, task_id: str) -> Path:
+    """Return `task_id`'s turn artifacts directory."""
+    return run_dir(project_root, task_id) / TURNS_DIR_NAME
+
+
+def task_root(project_root: Path, task_id: str) -> Path:
+    """Return `task_id`'s `.shikiru/worktrees/` directory."""
+    return project_state_dir(project_root) / WORKTREES_DIR_NAME / task_id
+
+
+def queued_messages_dir(project_root: Path, task_id: str, role: str) -> Path:
+    """Return the directory holding `role`'s queued operator messages for `task_id`."""
+    return run_dir(project_root, task_id) / MESSAGES_DIR_NAME / role
+
+
+def probe_repo_path(project_root: Path) -> Path:
+    """Return the scratch repository `doctor --probe` runs its turns in."""
+    return project_state_dir(project_root) / PROBE_DIR_NAME / PROBE_REPO_DIR_NAME
+
+
+def probe_run_dir(project_root: Path) -> Path:
+    """Return the run directory `doctor --probe` keeps its turn artifacts in."""
+    return project_state_dir(project_root) / PROBE_DIR_NAME / PROBE_RUN_DIR_NAME

shikiru/plugins/agents/__init__.py

@@ -0,0 +1 @@
+"""Built-in agent plugins."""

shikiru/plugins/agents/claude/__init__.py

@@ -0,0 +1,5 @@
+"""Claude Code agent plugin."""
+
+from shikiru.plugins.agents.claude.agent import ClaudeAgent, create
+
+__all__ = ["ClaudeAgent", "create"]