monkeybot 2.1.1__py3-none-any.whl

monkeybot/core/persistence/sqlite.py

@@ -0,0 +1,218 @@
+"""SQLite connection helpers and schema DDL for monkeybot persistence."""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Final
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_DB_URL: Final[str] = "sqlite:///data/monkeybot.db"
+
+_LEGACY_SCHEMA_MESSAGE = """Legacy conversation_history schema detected (tool_name and/or
+tool_call_id columns present). The on-disk format changed in the
+typed-message-content release. Choose one:
+
+  Dev / demo agent:
+    rm -f demo_agent/workspace/data/monkeybot.db
+    rm -f demo_agent/workspace/data/monkeybot.db-shm
+    rm -f demo_agent/workspace/data/monkeybot.db-wal
+
+  Other deployments: there is no automated migration. The legacy format is
+  a JSON tail inside a TEXT column; transcribing it to typed blocks must
+  be done by the operator. See docs/migrations/typed-message-content.md."""
+
+SCHEMA_DDLS: Final[tuple[str, ...]] = (
+    """CREATE TABLE IF NOT EXISTS conversation_history (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    thread_id TEXT NOT NULL,
+    role TEXT NOT NULL,
+    content TEXT NOT NULL,
+    created_at INTEGER NOT NULL
+)""",
+    """CREATE TABLE IF NOT EXISTS subagent_runs (
+    run_id TEXT PRIMARY KEY,
+    parent_run_id TEXT,
+    script TEXT NOT NULL,
+    envelope_json TEXT NOT NULL,
+    status TEXT NOT NULL,
+    result_json TEXT,
+    error_json TEXT,
+    started_at INTEGER,
+    finished_at INTEGER,
+    scratch_dir TEXT,
+    worker_id TEXT,
+    claimed_at INTEGER
+)""",
+    """CREATE TABLE IF NOT EXISTS turn_usage (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    thread_id TEXT NOT NULL,
+    run_id TEXT,
+    model TEXT NOT NULL,
+    input_tokens INTEGER NOT NULL,
+    output_tokens INTEGER NOT NULL,
+    cached_tokens INTEGER NOT NULL,
+    cost_usd REAL NOT NULL,
+    duration_ms INTEGER NOT NULL,
+    created_at INTEGER NOT NULL,
+    context_json TEXT,
+    estimated_prompt_tokens INTEGER NOT NULL DEFAULT 0,
+    cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+    cache_creation_tokens INTEGER NOT NULL DEFAULT 0
+)""",
+    "CREATE INDEX IF NOT EXISTS idx_history_thread ON conversation_history(thread_id, created_at)",
+    """CREATE INDEX IF NOT EXISTS idx_history_thread_last
+    ON conversation_history(thread_id, created_at DESC, id DESC)""",
+    "CREATE INDEX IF NOT EXISTS idx_runs_parent ON subagent_runs(parent_run_id)",
+    """CREATE INDEX IF NOT EXISTS idx_runs_status ON subagent_runs(status)
+    WHERE status IN ('pending','running')""",
+    "CREATE INDEX IF NOT EXISTS idx_usage_thread ON turn_usage(thread_id, created_at)",
+    "CREATE INDEX IF NOT EXISTS idx_usage_cost ON turn_usage(created_at)",
+    """CREATE TABLE IF NOT EXISTS scheduled_loops (
+    loop_id TEXT PRIMARY KEY,
+    session_id TEXT NOT NULL,
+    status TEXT NOT NULL,
+    prompt TEXT NOT NULL,
+    interval_ms INTEGER NOT NULL,
+    max_ticks INTEGER,
+    max_runtime_ms INTEGER,
+    skip_if_busy INTEGER NOT NULL DEFAULT 1,
+    tick_index INTEGER NOT NULL DEFAULT 0,
+    next_tick_at_ms INTEGER NOT NULL,
+    started_at_ms INTEGER NOT NULL,
+    last_tick_at_ms INTEGER,
+    last_error TEXT,
+    stop_reason TEXT,
+    tick_in_flight INTEGER NOT NULL DEFAULT 0,
+    worker_id TEXT,
+    claimed_at_ms INTEGER
+)""",
+    """CREATE INDEX IF NOT EXISTS idx_scheduled_loops_due
+    ON scheduled_loops(status, tick_in_flight, next_tick_at_ms)
+    WHERE status = 'active'""",
+    """CREATE TABLE IF NOT EXISTS session_turn_locks (
+    session_id TEXT PRIMARY KEY,
+    request_id TEXT,
+    claimed_at_ms INTEGER
+)""",
+)
+
+
+def sqlite_path_from_db_url(db_url: str | None = None) -> str:
+    """Resolve sqlite database path suitable for aiosqlite.connect().
+
+    Accepts sqlite:////absolute/path, sqlite:///relative/path, sqlite:///:memory:.
+    If db_url is None, reads os.environ.get('DB_URL', DEFAULT_DB_URL).
+    Raises ValueError if scheme is not sqlite or path is empty.
+    """
+    if db_url is None:
+        db_url = os.environ.get("DB_URL", DEFAULT_DB_URL)
+    stripped = db_url.strip()
+    if not stripped:
+        raise ValueError("Database URL is empty")
+    prefix = "sqlite:///"
+    if not stripped.lower().startswith(prefix):
+        raise ValueError(f"Unsupported database URL: {db_url!r}")
+    remainder = stripped[len(prefix) :]
+    if not remainder:
+        raise ValueError("SQLite URL path is empty")
+    if remainder == ":memory:":
+        return ":memory:"
+    return remainder
+
+
+async def configure_connection(conn: aiosqlite.Connection) -> None:
+    """PRAGMA journal_mode=WAL; foreign_keys=ON; synchronous=NORMAL."""
+    await conn.execute("PRAGMA journal_mode=WAL")
+    await conn.execute("PRAGMA foreign_keys=ON")
+    await conn.execute("PRAGMA synchronous=NORMAL")
+
+
+async def _connection_db_path(conn: aiosqlite.Connection) -> str:
+    """Resolve main DB path for logging (``:memory:`` when no file path)."""
+    cursor = await conn.execute("PRAGMA database_list")
+    rows = await cursor.fetchall()
+    await cursor.close()
+    for row in rows:
+        if len(row) >= 3 and str(row[1]) == "main":
+            file_col = row[2]
+            return ":memory:" if not file_col else str(file_col)
+    return ":memory:"
+
+
+async def _log_legacy_schema_error(conn: aiosqlite.Connection) -> None:
+    path = await _connection_db_path(conn)
+    logger.error("Legacy conversation_history schema detected; db=%s", path)
+
+
+async def apply_schema(conn: aiosqlite.Connection) -> None:
+    """Create tables/indexes; refuse legacy conversation_history shapes."""
+    for ddl in SCHEMA_DDLS:
+        await conn.execute(ddl)
+    await conn.commit()
+    await _ensure_turn_usage_estimated_column(conn)
+    await _ensure_turn_usage_cache_columns(conn)
+    await _ensure_subagent_runs_claim_columns(conn)
+    cursor = await conn.execute("PRAGMA table_info(conversation_history)")
+    rows = await cursor.fetchall()
+    await cursor.close()
+    col_names = {str(r[1]) for r in rows}
+    if "tool_name" in col_names or "tool_call_id" in col_names:
+        await _log_legacy_schema_error(conn)
+        raise RuntimeError(_LEGACY_SCHEMA_MESSAGE)
+
+
+async def _ensure_turn_usage_estimated_column(conn: aiosqlite.Connection) -> None:
+    """Add ``estimated_prompt_tokens`` when upgrading an existing DB."""
+    cur = await conn.execute("PRAGMA table_info(turn_usage)")
+    rows = await cur.fetchall()
+    await cur.close()
+    names = {str(r[1]) for r in rows}
+    if "estimated_prompt_tokens" in names:
+        return
+    await conn.execute(
+        "ALTER TABLE turn_usage ADD COLUMN estimated_prompt_tokens INTEGER NOT NULL DEFAULT 0"
+    )
+    await conn.commit()
+
+
+async def _ensure_turn_usage_cache_columns(conn: aiosqlite.Connection) -> None:
+    """Add cache token columns when upgrading an existing DB."""
+    cur = await conn.execute("PRAGMA table_info(turn_usage)")
+    rows = await cur.fetchall()
+    await cur.close()
+    names = {str(r[1]) for r in rows}
+    for col in ("cache_read_tokens", "cache_creation_tokens"):
+        if col in names:
+            continue
+        await conn.execute(
+            f"ALTER TABLE turn_usage ADD COLUMN {col} INTEGER NOT NULL DEFAULT 0"
+        )
+    await conn.commit()
+
+
+async def _ensure_subagent_runs_claim_columns(conn: aiosqlite.Connection) -> None:
+    """Add worker claim columns when upgrading an existing DB."""
+    cur = await conn.execute("PRAGMA table_info(subagent_runs)")
+    rows = await cur.fetchall()
+    await cur.close()
+    names = {str(r[1]) for r in rows}
+    if "worker_id" not in names:
+        await conn.execute("ALTER TABLE subagent_runs ADD COLUMN worker_id TEXT")
+    if "claimed_at" not in names:
+        await conn.execute("ALTER TABLE subagent_runs ADD COLUMN claimed_at INTEGER")
+    await conn.commit()
+
+
+async def open_connection(db_url: str | None = None) -> aiosqlite.Connection:
+    """Open aiosqlite connection, configure WAL, return ready connection."""
+    path = sqlite_path_from_db_url(db_url)
+    if path != ":memory:":
+        Path(path).expanduser().resolve().parent.mkdir(parents=True, exist_ok=True)
+    conn = await aiosqlite.connect(path)
+    await configure_connection(conn)
+    return conn

monkeybot/core/persistence/sqlite_backend.py

@@ -0,0 +1,74 @@
+"""SQLite-backed StorageBackend implementation.
+
+Lazy-imported by :func:`monkeybot.core.persistence.backends.create_storage_backend`
+when a ``sqlite://`` URL is used — never loaded in Postgres-only deployments.
+"""
+
+from __future__ import annotations
+
+import aiosqlite
+
+from monkeybot.core.persistence.durable_runs import SQLiteRunStore
+from monkeybot.core.persistence.scheduled_loops import SQLiteScheduledLoopStore
+from monkeybot.core.persistence.session_turn_locks import SQLiteSessionTurnLockStore
+from monkeybot.core.persistence.history import SQLiteHistoryStore
+from monkeybot.core.persistence.sqlite import apply_schema, open_connection
+from monkeybot.core.persistence.usage import SQLiteUsageStore
+
+
+class SQLiteStorageBackend:
+    """SQLite-backed storage backend. One shared connection for the process lifetime."""
+
+    def __init__(self, db_url: str) -> None:
+        self._db_url = db_url
+        self._conn: aiosqlite.Connection | None = None
+        self._history_store: SQLiteHistoryStore | None = None
+        self._usage_store: SQLiteUsageStore | None = None
+        self._runs_store: SQLiteRunStore | None = None
+        self._scheduled_loops_store: SQLiteScheduledLoopStore | None = None
+        self._session_turn_lock_store: SQLiteSessionTurnLockStore | None = None
+
+    async def open(self, *, run_schema: bool = True) -> None:
+        self._conn = await open_connection(self._db_url)
+        if run_schema:
+            await apply_schema(self._conn)
+        self._history_store = SQLiteHistoryStore(self._conn)
+        self._usage_store = SQLiteUsageStore(self._conn)
+        self._runs_store = SQLiteRunStore(self._conn)
+        self._scheduled_loops_store = SQLiteScheduledLoopStore(self._conn)
+        self._session_turn_lock_store = SQLiteSessionTurnLockStore(self._conn)
+
+    async def close(self) -> None:
+        if self._conn is not None:
+            await self._conn.close()
+            self._conn = None
+            self._history_store = None
+            self._usage_store = None
+            self._runs_store = None
+            self._scheduled_loops_store = None
+            self._session_turn_lock_store = None
+
+    def history(self) -> SQLiteHistoryStore:
+        if self._history_store is None:
+            raise RuntimeError("SQLiteStorageBackend.open() has not been called")
+        return self._history_store
+
+    def usage(self) -> SQLiteUsageStore:
+        if self._usage_store is None:
+            raise RuntimeError("SQLiteStorageBackend.open() has not been called")
+        return self._usage_store
+
+    def runs(self) -> SQLiteRunStore:
+        if self._runs_store is None:
+            raise RuntimeError("SQLiteStorageBackend.open() has not been called")
+        return self._runs_store
+
+    def scheduled_loops(self) -> SQLiteScheduledLoopStore:
+        if self._scheduled_loops_store is None:
+            raise RuntimeError("SQLiteStorageBackend.open() has not been called")
+        return self._scheduled_loops_store
+
+    def session_turns(self) -> SQLiteSessionTurnLockStore:
+        if self._session_turn_lock_store is None:
+            raise RuntimeError("SQLiteStorageBackend.open() has not been called")
+        return self._session_turn_lock_store

monkeybot/core/persistence/thread_summary.py

@@ -0,0 +1,61 @@
+"""Shared helpers for listing persisted chat threads."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from monkeybot.core.llm.provider import Message
+from monkeybot.core.types.content_blocks import Text
+
+
+@dataclass(frozen=True)
+class ChatThreadSummary:
+    """One row in a chat-thread picker."""
+
+    thread_id: str
+    last_message_at: int
+    message_count: int
+    preview: str
+
+
+def preview_from_content_blob(content_blob: str, *, max_len: int = 120) -> str:
+    """Build a one-line preview from stored JSON content blocks."""
+    try:
+        raw = json.loads(content_blob)
+    except json.JSONDecodeError:
+        return ""
+    if not isinstance(raw, list):
+        return ""
+    parts: list[str] = []
+    for item in raw:
+        if isinstance(item, dict) and item.get("type") == "text":
+            text = item.get("text")
+            if isinstance(text, str) and text.strip():
+                parts.append(text.strip())
+    joined = " ".join(parts).replace("\n", " ").strip()
+    if len(joined) <= max_len:
+        return joined
+    return joined[: max_len - 1].rstrip() + "…"
+
+
+def text_from_message(message: Message) -> str:
+    """Concatenate Text blocks from a stored message."""
+    parts: list[str] = []
+    for block in message.content:
+        if isinstance(block, Text) and block.text.strip():
+            parts.append(block.text.strip())
+    return "\n".join(parts).strip()
+
+
+def messages_to_wire(messages: list[Message]) -> list[dict[str, str]]:
+    """Serialize user/assistant turns for the chat-history API."""
+    out: list[dict[str, str]] = []
+    for msg in messages:
+        if msg.role not in ("user", "assistant"):
+            continue
+        text = text_from_message(msg)
+        if not text:
+            continue
+        out.append({"role": msg.role, "text": text})
+    return out

monkeybot/core/persistence/transcript.py

@@ -0,0 +1,194 @@
+"""Session transcript capture for harness debugging (internal use only).
+
+Writes one append-only NDJSON file per session under
+``{workspace_root}/.monkeybot/transcripts/{session_id}.ndjson``: a manifest
+record on the first write, followed by durable :class:`~monkeybot.core.runtime.events.AgentEvent`
+boundaries (OpenCode V2-style), plus raw provider request/response records.
+
+Live-only streaming deltas (``AssistantDelta``, ``ToolInputDelta``, …) are
+skipped by default so the transcript is a replay-grade durable log. Set
+``MONKEYBOT_TRANSCRIPT_INCLUDE_LIVE=1`` to capture every SSE event.
+
+Not surfaced to the agent or any tool; gated by ``MONKEYBOT_TRANSCRIPT_ENABLED``
+(default off) and wired only from the gateway loop (``GatewayLoopPort.start_turn``
+and the provider call site in ``core/runtime/loop.py``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from monkeybot.core.path_safety import sanitize_path_component
+from monkeybot.core.runtime.events import AgentEvent, event_to_json, is_durable_event
+
+logger = logging.getLogger(__name__)
+
+_TRANSCRIPT_REL_DIR = Path(".monkeybot") / "transcripts"
+
+
+def transcript_enabled_from_env() -> bool:
+    """Opt-in only; default off (``MONKEYBOT_TRANSCRIPT_ENABLED``)."""
+    raw = os.environ.get("MONKEYBOT_TRANSCRIPT_ENABLED", "false").strip().lower()
+    return raw in ("1", "true", "yes", "on")
+
+
+def transcript_include_live_from_env() -> bool:
+    """When true, write live-only streaming events too (default durable-only)."""
+    raw = os.environ.get("MONKEYBOT_TRANSCRIPT_INCLUDE_LIVE", "false").strip().lower()
+    return raw in ("1", "true", "yes", "on")
+
+
+def _now_iso() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime()) + f".{int(time.time() * 1000) % 1000:03d}Z"
+
+
+class TranscriptWriter:
+    """Append-only NDJSON transcript writer for one gateway session.
+
+    One instance per ``session_id``; safe for concurrent turns on the same
+    session via an internal lock. All file I/O runs in ``asyncio.to_thread``.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        *,
+        workspace_root: Path,
+        include_live: bool | None = None,
+    ) -> None:
+        self._session_id = session_id
+        safe_id = sanitize_path_component(session_id)
+        self._path = workspace_root.resolve() / _TRANSCRIPT_REL_DIR / f"{safe_id}.ndjson"
+        self._lock = asyncio.Lock()
+        self._manifest_written = False
+        self._seq = 0
+        self._include_live = (
+            transcript_include_live_from_env() if include_live is None else include_live
+        )
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    async def ensure_manifest(self, **manifest_fields: Any) -> None:
+        """Write the manifest as line 1 if this is a new transcript file (idempotent)."""
+        if self._manifest_written:
+            return
+        async with self._lock:
+            if self._manifest_written:
+                return
+
+            def _write_if_new() -> None:
+                self._path.parent.mkdir(parents=True, exist_ok=True)
+                if self._path.exists():
+                    return
+                record = {
+                    "type": "SessionManifest",
+                    "session_id": self._session_id,
+                    "started_at": _now_iso(),
+                    "durable_only": not self._include_live,
+                    **manifest_fields,
+                }
+                line = json.dumps(record, ensure_ascii=False, separators=(",", ":"))
+                with self._path.open("a", encoding="utf-8") as fh:
+                    fh.write(line + "\n")
+
+            try:
+                await asyncio.to_thread(_write_if_new)
+            except OSError:
+                logger.warning("transcript manifest write failed for %s", self._session_id, exc_info=True)
+            self._manifest_written = True
+
+    async def _append_line(self, record: dict[str, Any]) -> None:
+        async with self._lock:
+            self._seq += 1
+            line = json.dumps({"seq": self._seq, **record}, ensure_ascii=False, separators=(",", ":"))
+
+            def _append() -> None:
+                self._path.parent.mkdir(parents=True, exist_ok=True)
+                with self._path.open("a", encoding="utf-8") as fh:
+                    fh.write(line + "\n")
+
+            try:
+                await asyncio.to_thread(_append)
+            except OSError:
+                logger.warning("transcript append failed for %s", self._session_id, exc_info=True)
+
+    async def write_user_message(self, *, request_id: str, content: str) -> None:
+        """Append the incoming user turn (not an ``AgentEvent``; harness-internal)."""
+        await self._append_line(
+            {"ts": _now_iso(), "type": "UserMessage", "request_id": request_id, "content": content}
+        )
+
+    async def write_event(self, event: AgentEvent) -> None:
+        """Append one harness ``AgentEvent`` (durable by default; same JSON as SSE)."""
+        if not self._include_live and not is_durable_event(event):
+            return
+        payload = json.loads(event_to_json(event))
+        await self._append_line({"ts": _now_iso(), **payload})
+
+    async def write_provider_request(
+        self,
+        *,
+        request_id: str,
+        inner_turn: int,
+        model: str,
+        messages: list[dict[str, object]],
+        message_offset: int = 0,
+        messages_reset: bool = False,
+        tools: list[dict[str, object]] | None = None,
+        thinking_budget: int | None,
+    ) -> None:
+        record: dict[str, Any] = {
+            "ts": _now_iso(),
+            "type": "ProviderRequest",
+            "request_id": request_id,
+            "inner_turn": inner_turn,
+            "model": model,
+            "message_offset": message_offset,
+            "messages": messages,
+            "thinking_budget": thinking_budget,
+        }
+        if messages_reset:
+            record["messages_reset"] = True
+        if tools is not None:
+            record["tools"] = tools
+        await self._append_line(record)
+
+    async def write_provider_response(
+        self,
+        *,
+        request_id: str,
+        inner_turn: int,
+        model: str,
+        text: str,
+        thinking: str,
+        tool_requests: list[dict[str, object]],
+        usage: dict[str, object],
+    ) -> None:
+        await self._append_line(
+            {
+                "ts": _now_iso(),
+                "type": "ProviderResponse",
+                "request_id": request_id,
+                "inner_turn": inner_turn,
+                "model": model,
+                "text": text,
+                "thinking": thinking,
+                "tool_requests": tool_requests,
+                "usage": usage,
+            }
+        )
+
+
+__all__ = [
+    "TranscriptWriter",
+    "transcript_enabled_from_env",
+    "transcript_include_live_from_env",
+]

monkeybot/core/persistence/usage.py

@@ -0,0 +1,149 @@
+"""SQLite-backed usage store."""
+
+from __future__ import annotations
+
+import time
+
+import aiosqlite
+
+from monkeybot.core.llm.usage import Usage, UsageSummary
+
+
+class SQLiteUsageStore:
+    """Insert ``turn_usage`` rows and compute summaries."""
+
+    def __init__(self, conn: aiosqlite.Connection) -> None:
+        self._conn = conn
+
+    async def record(
+        self,
+        thread_id: str,
+        model: str,
+        usage: Usage,
+        run_id: str | None = None,
+        *,
+        context_json: str | None = None,
+    ) -> None:
+        """Persist one usage row at ``created_at`` = now (ms)."""
+        now_ms = int(time.time() * 1000)
+        await self._conn.execute(
+            """
+            INSERT INTO turn_usage(
+                thread_id, run_id, model,
+                input_tokens, output_tokens, cached_tokens,
+                cost_usd, duration_ms, created_at, context_json,
+                estimated_prompt_tokens, cache_read_tokens, cache_creation_tokens
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                thread_id,
+                run_id,
+                model,
+                usage.input_tokens,
+                usage.output_tokens,
+                usage.cached_tokens,
+                usage.cost_usd,
+                usage.duration_ms,
+                now_ms,
+                context_json,
+                usage.estimated_prompt_tokens,
+                usage.cache_read_tokens,
+                usage.cache_creation_tokens,
+            ),
+        )
+        await self._conn.commit()
+
+    async def summary(
+        self,
+        thread_id: str | None = None,
+        since_ms: int | None = None,
+    ) -> UsageSummary:
+        """Aggregate totals over matching rows."""
+        clauses: list[str] = []
+        params: list[object] = []
+        if thread_id is not None:
+            clauses.append("thread_id = ?")
+            params.append(thread_id)
+        if since_ms is not None:
+            clauses.append("created_at >= ?")
+            params.append(since_ms)
+        where_sql = ""
+        if clauses:
+            where_sql = "WHERE " + " AND ".join(clauses)
+
+        sql = f"""
+            SELECT
+                COUNT(*) AS turns,
+                COALESCE(SUM(input_tokens), 0) AS input_tokens,
+                COALESCE(SUM(output_tokens), 0) AS output_tokens,
+                COALESCE(SUM(cached_tokens), 0) AS cached_tokens,
+                COALESCE(SUM(cost_usd), 0.0) AS cost_usd,
+                MIN(created_at) AS period_start_ms,
+                MAX(created_at) AS period_end_ms,
+                COALESCE(SUM(cache_read_tokens), 0) AS cache_read_tokens,
+                COALESCE(SUM(cache_creation_tokens), 0) AS cache_creation_tokens
+            FROM turn_usage
+            {where_sql}
+        """
+
+        cursor = await self._conn.execute(sql, params)
+        row = await cursor.fetchone()
+        await cursor.close()
+        if row is None:
+            raise RuntimeError("usage summary query returned no row")
+
+        turns = int(row[0])
+        if turns == 0:
+            return UsageSummary(
+                turns=0,
+                input_tokens=0,
+                output_tokens=0,
+                cached_tokens=0,
+                cost_usd=0.0,
+                period_start_ms=None,
+                period_end_ms=None,
+                last_prompt_tokens=0,
+                last_estimated_prompt_tokens=0,
+                cache_read_tokens=0,
+                cache_creation_tokens=0,
+            )
+
+        period_start = row[5]
+        period_end = row[6]
+        last_pt = 0
+        last_est = 0
+        if thread_id is not None:
+            lp_clauses: list[str] = ["thread_id = ?"]
+            lp_params: list[object] = [thread_id]
+            if since_ms is not None:
+                lp_clauses.append("created_at >= ?")
+                lp_params.append(since_ms)
+            lp_where = "WHERE " + " AND ".join(lp_clauses)
+            cur2 = await self._conn.execute(
+                f"""
+                SELECT input_tokens, estimated_prompt_tokens FROM turn_usage
+                {lp_where}
+                ORDER BY created_at DESC
+                LIMIT 1
+                """,
+                lp_params,
+            )
+            row2 = await cur2.fetchone()
+            await cur2.close()
+            if row2 is not None:
+                last_pt = int(row2[0])
+                last_est = int(row2[1])
+        return UsageSummary(
+            turns=turns,
+            input_tokens=int(row[1]),
+            output_tokens=int(row[2]),
+            cached_tokens=int(row[3]),
+            cost_usd=float(row[4]),
+            period_start_ms=int(period_start) if period_start is not None else None,
+            period_end_ms=int(period_end) if period_end is not None else None,
+            last_prompt_tokens=last_pt,
+            last_estimated_prompt_tokens=last_est,
+            cache_read_tokens=int(row[7]),
+            cache_creation_tokens=int(row[8]),
+        )