shikiru-cli 0.2.0__py3-none-any.whl

shikiru/store/notification_cursor.py

@@ -0,0 +1,29 @@
+"""The durable notification cursor."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import sqlite3  # noqa: TID251
+
+
+class NotificationCursor:
+    """Stores the id up to which every urgent event has been delivered."""
+
+    def __init__(self, connection: sqlite3.Connection) -> None:
+        """Use `connection`, the engine's writer."""
+        self._connection = connection
+
+    def read(self) -> int | None:
+        """Return the stored event id, or `None` before the first engine start."""
+        row = self._connection.execute("SELECT event_id FROM notification_cursor").fetchone()
+        return None if row is None else int(row[0])
+
+    def write(self, event_id: int) -> None:
+        """Store `event_id` as the delivered-up-to id."""
+        self._connection.execute(
+            "INSERT INTO notification_cursor (id, event_id) VALUES (1, ?) "
+            "ON CONFLICT (id) DO UPDATE SET event_id = excluded.event_id",
+            (event_id,),
+        )

shikiru/store/pushes.py

@@ -0,0 +1,117 @@
+"""The durable record of locally integrated base branches awaiting a push."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shikiru.domain.pushes import PushTarget, pending_deadline
+from shikiru.store.database import (
+    format_timestamp,
+    parse_timestamp,
+    transaction,
+)
+
+if TYPE_CHECKING:
+    import sqlite3  # noqa: TID251
+    from datetime import datetime
+
+_COLUMNS = "base, registered, pushed, due_at, last_pushed_at"
+
+
+class PushTargets:
+    """Stores, per base branch, the integrations registered and the ones a push acknowledged."""
+
+    def __init__(self, connection: sqlite3.Connection) -> None:
+        """Use `connection`, the engine's writer."""
+        self._connection = connection
+
+    def register(self, base: str, *, now: datetime, interval: int) -> None:
+        """Record one more integration of `base` awaiting a push.
+
+        The first pending integration sets the deadline; later ones never move it.
+        """
+        with transaction(self._connection):
+            current = self.get(base)
+            if current is None:
+                due_at = pending_deadline(last_pushed_at=None, now=now, interval=interval)
+                self._connection.execute(
+                    f"INSERT INTO push_targets ({_COLUMNS}) VALUES (?, 1, 0, ?, NULL)",
+                    (base, format_timestamp(due_at)),
+                )
+                return
+            due_at = (
+                current.due_at
+                if current.pending and current.due_at is not None
+                else pending_deadline(
+                    last_pushed_at=current.last_pushed_at, now=now, interval=interval
+                )
+            )
+            self._connection.execute(
+                "UPDATE push_targets SET registered = registered + 1, due_at = ? WHERE base = ?",
+                (format_timestamp(due_at), base),
+            )
+
+    def get(self, base: str) -> PushTarget | None:
+        """Return `base`'s record, or `None` when no integration of it was ever registered."""
+        return fetch_push_target(self._connection, base)
+
+    def pending(self) -> list[PushTarget]:
+        """Return every base with integrations no push has acknowledged, oldest deadline first."""
+        rows = self._connection.execute(
+            f"SELECT {_COLUMNS} FROM push_targets WHERE registered > pushed ORDER BY due_at, base"
+        ).fetchall()
+        return [_target(row) for row in rows]
+
+    def acknowledge(self, base: str, *, registered: int, now: datetime, interval: int) -> None:
+        """Record a push at `now` that sent the integrations registered up to `registered`.
+
+        Integrations registered meanwhile stay pending, due an interval after this push.
+        """
+        with transaction(self._connection):
+            current = self.get(base)
+            if current is None:
+                return
+            due_at = (
+                format_timestamp(pending_deadline(last_pushed_at=now, now=now, interval=interval))
+                if current.registered > registered
+                else None
+            )
+            self._connection.execute(
+                "UPDATE push_targets SET pushed = ?, due_at = ?, last_pushed_at = ? WHERE base = ?",
+                (max(current.pushed, registered), due_at, format_timestamp(now), base),
+            )
+
+    def reconcile(self, base: str, *, registered: int, now: datetime, interval: int) -> None:
+        """Record externally observed publication and reset the next-work scheduling baseline."""
+        with transaction(self._connection):
+            current = self.get(base)
+            if current is None or current.pushed >= registered:
+                return
+            due_at = (
+                format_timestamp(pending_deadline(last_pushed_at=None, now=now, interval=interval))
+                if current.registered > registered
+                else None
+            )
+            self._connection.execute(
+                "UPDATE push_targets SET pushed = ?, due_at = ?, "
+                "last_pushed_at = NULL WHERE base = ?",
+                (registered, due_at, base),
+            )
+
+
+def fetch_push_target(connection: sqlite3.Connection, base: str) -> PushTarget | None:
+    """Return `base`'s record, or `None` when no integration of it was ever registered."""
+    row = connection.execute(
+        f"SELECT {_COLUMNS} FROM push_targets WHERE base = ?", (base,)
+    ).fetchone()
+    return None if row is None else _target(row)
+
+
+def _target(row: sqlite3.Row) -> PushTarget:
+    return PushTarget(
+        base=row["base"],
+        registered=row["registered"],
+        pushed=row["pushed"],
+        due_at=parse_timestamp(row["due_at"]),
+        last_pushed_at=parse_timestamp(row["last_pushed_at"]),
+    )

shikiru/store/quotas.py

@@ -0,0 +1,153 @@
+"""Quota snapshots and agent blocks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from shikiru.agents.contracts import QuotaWindow
+from shikiru.store.database import (
+    format_timestamp,
+    parse_required_timestamp,
+    parse_timestamp,
+    transaction,
+)
+
+if TYPE_CHECKING:
+    import sqlite3  # noqa: TID251
+    from datetime import datetime
+
+
+_SELECT_BLOCK = (
+    "SELECT agent_blocks.agent AS agent, agent_blocks.until AS until, "
+    "agent_blocks.reason AS reason, agent_block_times.blocked_at AS blocked_at "
+    "FROM agent_blocks JOIN agent_block_times ON agent_block_times.agent = agent_blocks.agent"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class AgentBlock:
+    """An agent blocked from dispatch until `until`."""
+
+    agent: str
+    until: datetime
+    reason: str
+    blocked_at: datetime
+
+
+def _row_to_quota_window(row: sqlite3.Row) -> QuotaWindow:
+    return QuotaWindow(
+        name=row["window"],
+        used_pct=row["used_pct"],
+        resets_at=parse_timestamp(row["resets_at"]),
+        observed_at=parse_required_timestamp(row["observed_at"]),
+    )
+
+
+def _row_to_agent_block(row: sqlite3.Row) -> AgentBlock:
+    return AgentBlock(
+        agent=row["agent"],
+        until=parse_required_timestamp(row["until"]),
+        reason=row["reason"],
+        blocked_at=parse_required_timestamp(row["blocked_at"]),
+    )
+
+
+def fetch_quotas(connection: sqlite3.Connection, agent: str) -> list[QuotaWindow]:
+    """Read every quota window recorded for `agent`."""
+    rows = connection.execute(
+        "SELECT agent, window, used_pct, resets_at, observed_at FROM quotas WHERE agent = ?",
+        (agent,),
+    ).fetchall()
+    return [_row_to_quota_window(row) for row in rows]
+
+
+def fetch_quota_agents(connection: sqlite3.Connection) -> list[str]:
+    """Read every agent with at least one recorded quota window."""
+    rows = connection.execute("SELECT DISTINCT agent FROM quotas ORDER BY agent").fetchall()
+    return [row[0] for row in rows]
+
+
+def fetch_active_agent_blocks(connection: sqlite3.Connection, now: datetime) -> list[AgentBlock]:
+    """Read every agent block still in effect at `now`."""
+    rows = connection.execute(
+        _SELECT_BLOCK + " WHERE agent_blocks.until > ?",
+        (format_timestamp(now),),
+    ).fetchall()
+    return [_row_to_agent_block(row) for row in rows]
+
+
+def fetch_agent_block(connection: sqlite3.Connection, agent: str) -> AgentBlock | None:
+    """Read an agent's block, including one whose deadline has passed."""
+    row = connection.execute(_SELECT_BLOCK + " WHERE agent_blocks.agent = ?", (agent,)).fetchone()
+    return _row_to_agent_block(row) if row is not None else None
+
+
+class QuotaStore:
+    """Persists quota snapshots and agent blocks."""
+
+    def __init__(self, connection: sqlite3.Connection) -> None:
+        """Use `connection` for every write below."""
+        self._connection = connection
+
+    def record(self, agent: str, window: QuotaWindow) -> None:
+        """Upsert `agent`'s quota window unless the stored sample was observed later."""
+        self._connection.execute(
+            """
+            INSERT INTO quotas (agent, window, used_pct, resets_at, observed_at)
+            VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT (agent, window) DO UPDATE SET
+              used_pct = excluded.used_pct,
+              resets_at = excluded.resets_at,
+              observed_at = excluded.observed_at
+            WHERE excluded.observed_at >= quotas.observed_at
+            """,
+            (
+                agent,
+                window.name,
+                window.used_pct,
+                format_timestamp(window.resets_at) if window.resets_at is not None else None,
+                format_timestamp(window.observed_at),
+            ),
+        )
+
+    def block(self, agent: str, until: datetime, reason: str, blocked_at: datetime) -> None:
+        """Block `agent` until the later of the current and requested deadlines.
+
+        `blocked_at` is when quota was last found exhausted; it only moves forward. The deadline
+        and the time land in one transaction, so a block is never half persisted.
+        """
+        with transaction(self._connection):
+            self._connection.execute(
+                "INSERT INTO agent_blocks (agent, until, reason) VALUES (?, ?, ?) "
+                "ON CONFLICT (agent) DO UPDATE SET "
+                "until = CASE WHEN agent_blocks.until >= excluded.until "
+                "THEN agent_blocks.until ELSE excluded.until END, "
+                "reason = CASE WHEN agent_blocks.until >= excluded.until "
+                "THEN agent_blocks.reason ELSE excluded.reason END",
+                (agent, format_timestamp(until), reason),
+            )
+            self._connection.execute(
+                "INSERT INTO agent_block_times (agent, blocked_at) VALUES (?, ?) "
+                "ON CONFLICT (agent) DO UPDATE SET blocked_at = excluded.blocked_at "
+                "WHERE excluded.blocked_at > agent_block_times.blocked_at",
+                (agent, format_timestamp(blocked_at)),
+            )
+
+    def clear_block(self, agent: str) -> None:
+        """Remove `agent`'s block, if any."""
+        with transaction(self._connection):
+            self._connection.execute("DELETE FROM agent_blocks WHERE agent = ?", (agent,))
+            self._connection.execute("DELETE FROM agent_block_times WHERE agent = ?", (agent,))
+
+    def active_blocks(self, now: datetime) -> list[AgentBlock]:
+        """Read every agent block still in effect at `now`."""
+        return fetch_active_agent_blocks(self._connection, now)
+
+    def block_for(self, agent: str) -> AgentBlock | None:
+        """Read `agent`'s current block, whether or not it is still active."""
+        return fetch_agent_block(self._connection, agent)
+
+    def windows_for(self, agent: str) -> list[QuotaWindow]:
+        """Read every quota window recorded for `agent`."""
+        return fetch_quotas(self._connection, agent)

shikiru/store/reader.py

@@ -0,0 +1,310 @@
+"""Read-only facade over the state DB for operator queries and the dashboard."""
+
+from __future__ import annotations
+
+import sqlite3  # noqa: TID251
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING
+
+from shikiru.errors import DatabaseError
+from shikiru.store.commands import (
+    CommandHistoryPage,
+    StoredCommand,
+    fetch_command,
+    fetch_command_history,
+    fetch_pending_command,
+)
+from shikiru.store.escalations import fetch_escalation, fetch_open_escalations
+from shikiru.store.events import (
+    MAX_TIMELINE_EVENT_LIMIT,
+    fetch_events_since,
+    fetch_latest_events,
+    fetch_timeline_events,
+)
+from shikiru.store.pushes import fetch_push_target
+from shikiru.store.quotas import (
+    AgentBlock,
+    fetch_active_agent_blocks,
+    fetch_agent_block,
+    fetch_quota_agents,
+    fetch_quotas,
+)
+from shikiru.store.runs import fetch_all_runs, fetch_runs_for_task, fetch_taken_over_roles_for_task
+from shikiru.store.tasks import (
+    fetch_task,
+    fetch_task_browser_page,
+    fetch_task_browser_pages,
+    fetch_task_relationships,
+    fetch_tasks,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from datetime import datetime
+
+    from shikiru.agents.contracts import QuotaWindow
+    from shikiru.clock import Clock
+    from shikiru.domain.commands import Command, CommandStatus
+    from shikiru.domain.escalation import Escalation
+    from shikiru.domain.events import Event, EventKind
+    from shikiru.domain.pushes import PushTarget
+    from shikiru.domain.runs import Run
+    from shikiru.domain.tasks import Role, Status, Task
+    from shikiru.store.database import Database
+    from shikiru.store.tasks import TaskBrowserPage, TaskRelationships
+
+DASHBOARD_CHANGE_POLL_SECONDS = 0.5
+CASEFOLD_SQL_FUNCTION = "casefold"
+MAX_COMMAND_HISTORY_LIMIT = 50
+
+OnChange = Callable[[], Awaitable[None]]
+
+
+class StateReader:
+    """Read-only views over the state DB, shared by `OperatorQueries` and the dashboard."""
+
+    def __init__(self, database: Database, clock: Clock) -> None:
+        """Open `database`'s read-only connection, polled through `clock` by `watch`."""
+        self._connection = database.connect_readonly()
+        self._connection.create_function(
+            CASEFOLD_SQL_FUNCTION,
+            1,
+            str.casefold,
+            deterministic=True,
+        )
+        self._database_path = database.path
+        self._clock = clock
+
+    def get_task(self, task_id: str) -> Task | None:
+        """See `shikiru.store.tasks.fetch_task`."""
+        return fetch_task(self._connection, task_id)
+
+    def list_tasks(self, *, statuses: Sequence[Status] | None = None) -> list[Task]:
+        """See `shikiru.store.tasks.fetch_tasks`."""
+        try:
+            return fetch_tasks(self._connection, statuses=statuses)
+        except (sqlite3.Error, TypeError) as error:
+            message = f"could not query read-only database {self._database_path}: {error}"
+            raise DatabaseError(message) from error
+
+    def task_browser_page(
+        self,
+        *,
+        category: str,
+        search: str,
+        limit: int,
+        offset: int,
+        diagnosed_stall_task_ids: Sequence[str] = (),
+        quota_wait_task_ids: Sequence[str] = (),
+    ) -> TaskBrowserPage:
+        """Read one bounded task browser page and its matching and project counts."""
+        try:
+            return fetch_task_browser_page(
+                self._connection,
+                category=category,
+                search=search,
+                limit=limit,
+                offset=offset,
+                diagnosed_stall_task_ids=diagnosed_stall_task_ids,
+                quota_wait_task_ids=quota_wait_task_ids,
+            )
+        except sqlite3.Error as error:
+            message = f"could not query read-only database {self._database_path}: {error}"
+            raise DatabaseError(message) from error
+
+    def task_browser_pages(
+        self,
+        *,
+        category: str,
+        search: str,
+        limit: int,
+        page_count: int,
+        diagnosed_stall_task_ids: Sequence[str] = (),
+        quota_wait_task_ids: Sequence[str] = (),
+    ) -> tuple[TaskBrowserPage, ...]:
+        """Read a contiguous range of bounded task pages from one database snapshot."""
+        try:
+            return fetch_task_browser_pages(
+                self._connection,
+                category=category,
+                search=search,
+                limit=limit,
+                page_count=page_count,
+                diagnosed_stall_task_ids=diagnosed_stall_task_ids,
+                quota_wait_task_ids=quota_wait_task_ids,
+            )
+        except sqlite3.Error as error:
+            message = f"could not query read-only database {self._database_path}: {error}"
+            raise DatabaseError(message) from error
+
+    def task_relationships(self, task_id: str, *, offset: int = 0) -> TaskRelationships | None:
+        """Read a task's bounded family group and its distinct stored graph relationships."""
+        try:
+            return fetch_task_relationships(self._connection, task_id, offset=offset)
+        except sqlite3.Error as error:
+            message = f"could not query read-only database {self._database_path}: {error}"
+            raise DatabaseError(message) from error
+
+    def agent_block(self, agent: str) -> AgentBlock | None:
+        """Read the engine's recorded quota block for one required agent."""
+        try:
+            return fetch_agent_block(self._connection, agent)
+        except sqlite3.Error as error:
+            message = f"could not query read-only database {self._database_path}: {error}"
+            raise DatabaseError(message) from error
+
+    def active_agent_blocks(self, now: datetime) -> list[AgentBlock]:
+        """Read every quota block the engine recorded that is still in effect at `now`."""
+        try:
+            return fetch_active_agent_blocks(self._connection, now)
+        except sqlite3.Error as error:
+            message = f"could not query read-only database {self._database_path}: {error}"
+            raise DatabaseError(message) from error
+
+    def list_runs(self, task_id: str) -> list[Run]:
+        """See `shikiru.store.runs.fetch_runs_for_task`."""
+        return fetch_runs_for_task(self._connection, task_id)
+
+    def list_taken_over_roles(self, task_id: str) -> tuple[Role, ...]:
+        """Return the bounded set of roles currently taken over for `task_id`."""
+        return fetch_taken_over_roles_for_task(self._connection, task_id)
+
+    def list_all_runs(self) -> list[Run]:
+        """See `shikiru.store.runs.fetch_all_runs`."""
+        return fetch_all_runs(self._connection)
+
+    def command_history(
+        self,
+        *,
+        limit: int,
+        offset: int = 0,
+        status: CommandStatus | None = None,
+    ) -> CommandHistoryPage:
+        """Read a bounded command-history page, preserving stored status and result."""
+        if not 0 < limit <= MAX_COMMAND_HISTORY_LIMIT:
+            message = f"command history limit must be between 1 and {MAX_COMMAND_HISTORY_LIMIT}"
+            raise ValueError(message)
+        if offset < 0:
+            message = "command history offset cannot be negative"
+            raise ValueError(message)
+        try:
+            return fetch_command_history(
+                self._connection,
+                limit=limit,
+                offset=offset,
+                status=status,
+            )
+        except sqlite3.Error as error:
+            message = f"could not query read-only database {self._database_path}: {error}"
+            raise DatabaseError(message) from error
+
+    def command_status(self, command_id: int) -> StoredCommand | None:
+        """Read one durable command status by id without changing its lifecycle."""
+        try:
+            return fetch_command(self._connection, command_id)
+        except sqlite3.Error as error:
+            message = f"could not query read-only database {self._database_path}: {error}"
+            raise DatabaseError(message) from error
+
+    def pending_command(self, command: Command) -> StoredCommand | None:
+        """Find one identical pending command through the read-only connection."""
+        try:
+            return fetch_pending_command(self._connection, command)
+        except sqlite3.Error as error:
+            message = f"could not query read-only database {self._database_path}: {error}"
+            raise DatabaseError(message) from error
+
+    def push_target(self, base: str) -> PushTarget | None:
+        """See `shikiru.store.pushes.fetch_push_target`."""
+        return fetch_push_target(self._connection, base)
+
+    def get_escalation(self, escalation_id: str) -> Escalation | None:
+        """See `shikiru.store.escalations.fetch_escalation`."""
+        return fetch_escalation(self._connection, escalation_id)
+
+    def list_open_escalations(self) -> list[Escalation]:
+        """See `shikiru.store.escalations.fetch_open_escalations`."""
+        return fetch_open_escalations(self._connection)
+
+    def list_quotas(self, agents: Sequence[str]) -> dict[str, list[QuotaWindow]]:
+        """Read quota windows for each requested agent."""
+        return {agent: fetch_quotas(self._connection, agent) for agent in agents}
+
+    def list_quota_agents(self) -> list[str]:
+        """Read every agent with persisted quota windows."""
+        return fetch_quota_agents(self._connection)
+
+    def events_since(
+        self,
+        since_id: int,
+        *,
+        kinds: Sequence[EventKind] | None = None,
+        task_id: str | None = None,
+    ) -> list[Event]:
+        """See `shikiru.store.events.fetch_events_since`."""
+        return fetch_events_since(self._connection, since_id, kinds=kinds, task_id=task_id)
+
+    def latest_events(
+        self,
+        limit: int,
+        *,
+        kinds: Sequence[EventKind] | None = None,
+        implementer_turns_only: bool = False,
+        task_id: str | None = None,
+    ) -> list[Event]:
+        """Read the latest matching events in chronological order."""
+        return fetch_latest_events(
+            self._connection,
+            limit,
+            kinds=kinds,
+            implementer_turns_only=implementer_turns_only,
+            task_id=task_id,
+        )
+
+    def task_timeline_events(
+        self,
+        task_id: str,
+        *,
+        limit: int,
+        before: tuple[str, int] | None = None,
+        kinds: Sequence[EventKind] | None = None,
+        role: str | None = None,
+        turn: str | None = None,
+    ) -> list[Event]:
+        """Read a bounded, newest-first task event page for the evidence timeline."""
+        if not 0 < limit <= MAX_TIMELINE_EVENT_LIMIT:
+            message = f"task timeline event limit must be between 1 and {MAX_TIMELINE_EVENT_LIMIT}"
+            raise ValueError(message)
+        try:
+            return fetch_timeline_events(
+                self._connection,
+                task_id,
+                limit=limit,
+                before=before,
+                kinds=kinds,
+                role=role,
+                turn=turn,
+            )
+        except sqlite3.Error as error:
+            message = f"could not query read-only database {self._database_path}: {error}"
+            raise DatabaseError(message) from error
+
+    def data_version(self) -> int:
+        """Return SQLite's `data_version` counter, bumped by every other connection's commit."""
+        row = self._connection.execute("PRAGMA data_version").fetchone()
+        return row[0]
+
+    def close(self) -> None:
+        """Release the read-only connection; the dashboard or operator calls this on shutdown."""
+        self._connection.close()
+
+    async def watch(self, on_change: OnChange) -> None:
+        """Call `on_change` once after every commit from another connection, until cancelled."""
+        last_version = self.data_version()
+        while True:
+            await self._clock.sleep(DASHBOARD_CHANGE_POLL_SECONDS)
+            current_version = self.data_version()
+            if current_version == last_version:
+                continue
+            last_version = current_version
+            await on_change()