monkeybot 2.1.1__py3-none-any.whl

monkeybot/core/persistence/postgres.py

@@ -0,0 +1,895 @@
+"""PostgreSQL storage backend (requires ``pip install 'monkeybot[postgres]'``)."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from typing import cast
+
+import asyncpg
+
+from monkeybot.core.llm.provider import Message, Role
+from monkeybot.core.llm.usage import Usage, UsageSummary
+from monkeybot.core.persistence.durable_runs import (
+    _SUBAGENT_COLUMNS,
+    SubagentEnvelope,
+    SubagentRunRow,
+    _tuple_to_run_row,
+)
+from monkeybot.core.persistence.scheduled_loops import (
+    ScheduledLoopCreate,
+    ScheduledLoopRow,
+    _SCHEDULED_LOOP_COLUMNS,
+    _loop_id_from_create,
+    _row_from_tuple,
+    validate_loop_guards,
+)
+from monkeybot.core.persistence.thread_summary import ChatThreadSummary, preview_from_content_blob
+from monkeybot.core.types.content_blocks import ContentBlock
+
+logger = logging.getLogger(__name__)
+
+_VALID_ROLES: tuple[str, ...] = ("user", "assistant", "system")
+
+_SCHEMA_DDLS: tuple[str, ...] = (
+    """CREATE TABLE IF NOT EXISTS conversation_history (
+    id BIGSERIAL PRIMARY KEY,
+    thread_id TEXT NOT NULL,
+    role TEXT NOT NULL,
+    content TEXT NOT NULL,
+    created_at BIGINT 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 BIGINT,
+    finished_at BIGINT,
+    scratch_dir TEXT,
+    worker_id TEXT,
+    claimed_at BIGINT
+)""",
+    """CREATE TABLE IF NOT EXISTS turn_usage (
+    id BIGSERIAL PRIMARY KEY,
+    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 DOUBLE PRECISION NOT NULL,
+    duration_ms INTEGER NOT NULL,
+    created_at BIGINT 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_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)",
+    "ALTER TABLE turn_usage ADD COLUMN IF NOT EXISTS cache_read_tokens INTEGER NOT NULL DEFAULT 0",
+    "ALTER TABLE turn_usage ADD COLUMN IF NOT EXISTS cache_creation_tokens INTEGER NOT NULL DEFAULT 0",
+    "ALTER TABLE subagent_runs ADD COLUMN IF NOT EXISTS worker_id TEXT",
+    "ALTER TABLE subagent_runs ADD COLUMN IF NOT EXISTS claimed_at BIGINT",
+    """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 BIGINT NOT NULL,
+    max_ticks INTEGER,
+    max_runtime_ms BIGINT,
+    skip_if_busy INTEGER NOT NULL DEFAULT 1,
+    tick_index INTEGER NOT NULL DEFAULT 0,
+    next_tick_at_ms BIGINT NOT NULL,
+    started_at_ms BIGINT NOT NULL,
+    last_tick_at_ms BIGINT,
+    last_error TEXT,
+    stop_reason TEXT,
+    tick_in_flight INTEGER NOT NULL DEFAULT 0,
+    worker_id TEXT,
+    claimed_at_ms BIGINT
+)""",
+    """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 BIGINT
+)""",
+)
+
+
+async def _apply_schema(pool: asyncpg.Pool) -> None:
+    async with pool.acquire() as conn:
+        for ddl in _SCHEMA_DDLS:
+            await conn.execute(ddl)
+
+
+class PostgresHistoryStore:
+    """asyncpg-backed conversation history store."""
+
+    def __init__(self, pool: asyncpg.Pool) -> None:
+        self._pool = pool
+
+    async def _insert_message(self, conn: asyncpg.Connection, thread_id: str, message: Message) -> None:
+        role = message.role
+        if role not in _VALID_ROLES:
+            raise ValueError(f"invalid role: {role!r}")
+        payload = json.dumps(
+            [b.to_dict() for b in message.content],
+            separators=(",", ":"),
+            ensure_ascii=False,
+        )
+        created_at = int(time.time() * 1000)
+        await conn.execute(
+            """
+            INSERT INTO conversation_history(thread_id, role, content, created_at)
+            VALUES ($1, $2, $3, $4)
+            """,
+            thread_id,
+            message.role,
+            payload,
+            created_at,
+        )
+
+    async def append(self, thread_id: str, message: Message) -> None:
+        async with self._pool.acquire() as conn:
+            await self._insert_message(conn, thread_id, message)
+
+    async def load(self, thread_id: str, limit: int = 100) -> list[Message]:
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(
+                """
+                SELECT id, role, content
+                FROM conversation_history
+                WHERE thread_id = $1
+                ORDER BY created_at DESC, id DESC
+                LIMIT $2
+                """,
+                thread_id,
+                limit,
+            )
+        rows_chrono = list(reversed(rows))
+        out: list[Message] = []
+        for row in rows_chrono:
+            row_id = int(row["id"])
+            role = row["role"]
+            content_blob = row["content"]
+            try:
+                raw = json.loads(content_blob)
+                if not isinstance(raw, list):
+                    raise ValueError("stored content must be a JSON array")
+                blocks = [ContentBlock.from_dict(b) for b in raw]
+            except (json.JSONDecodeError, ValueError, TypeError) as exc:
+                logger.error(
+                    "Unparseable history row id=%s thread_id=%s",
+                    row_id,
+                    thread_id,
+                    exc_info=True,
+                )
+                raise ValueError(f"history row {row_id} unparseable: {exc}") from exc
+            if role not in _VALID_ROLES:
+                raise ValueError(f"history row {row_id} has invalid role: {role!r}")
+            out.append(Message(role=cast(Role, role), content=blocks))
+        return out
+
+    async def clear(self, thread_id: str) -> None:
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                "DELETE FROM conversation_history WHERE thread_id = $1", thread_id
+            )
+
+    async def reset(self, thread_id: str, messages: list[Message]) -> None:
+        """Replace thread history atomically (single transaction)."""
+        async with self._pool.acquire() as conn, conn.transaction():
+            await conn.execute(
+                "DELETE FROM conversation_history WHERE thread_id = $1", thread_id
+            )
+            for msg in messages:
+                await self._insert_message(conn, thread_id, msg)
+
+    async def list_threads(self, limit: int = 50) -> list[ChatThreadSummary]:
+        cap = max(1, min(limit, 200))
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(
+                """
+                SELECT
+                    h.thread_id,
+                    MAX(h.created_at) AS last_message_at,
+                    COUNT(*)::int AS message_count,
+                    (
+                        SELECT h2.content
+                        FROM conversation_history h2
+                        WHERE h2.thread_id = h.thread_id
+                        ORDER BY h2.created_at DESC, h2.id DESC
+                        LIMIT 1
+                    ) AS last_content
+                FROM conversation_history h
+                GROUP BY h.thread_id
+                ORDER BY last_message_at DESC
+                LIMIT $1
+                """,
+                cap,
+            )
+        out: list[ChatThreadSummary] = []
+        for row in rows:
+            preview = preview_from_content_blob(str(row["last_content"] or ""))
+            out.append(
+                ChatThreadSummary(
+                    thread_id=str(row["thread_id"]),
+                    last_message_at=int(row["last_message_at"]),
+                    message_count=int(row["message_count"]),
+                    preview=preview or "(empty)",
+                )
+            )
+        return out
+
+
+class PostgresUsageStore:
+    """asyncpg-backed usage store."""
+
+    def __init__(self, pool: asyncpg.Pool) -> None:
+        self._pool = pool
+
+    async def record(
+        self,
+        thread_id: str,
+        model: str,
+        usage: Usage,
+        run_id: str | None = None,
+        *,
+        context_json: str | None = None,
+    ) -> None:
+        now_ms = int(time.time() * 1000)
+        async with self._pool.acquire() as conn:
+            await 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 ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+                """,
+                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,
+            )
+
+    async def summary(
+        self,
+        thread_id: str | None = None,
+        since_ms: int | None = None,
+    ) -> UsageSummary:
+        clauses: list[str] = []
+        params: list[object] = []
+        idx = 1
+        if thread_id is not None:
+            clauses.append(f"thread_id = ${idx}")
+            params.append(thread_id)
+            idx += 1
+        if since_ms is not None:
+            clauses.append(f"created_at >= ${idx}")
+            params.append(since_ms)
+            idx += 1
+        where_sql = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+
+        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}
+        """
+
+        async with self._pool.acquire() as conn:
+            row = await conn.fetchrow(sql, *params)
+
+        if row is None:
+            raise RuntimeError("usage summary query returned no row")
+
+        turns = int(row["turns"])
+        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,
+            )
+
+        last_pt = 0
+        last_est = 0
+        if thread_id is not None:
+            lp_clauses: list[str] = ["thread_id = $1"]
+            lp_params: list[object] = [thread_id]
+            if since_ms is not None:
+                lp_clauses.append("created_at >= $2")
+                lp_params.append(since_ms)
+            lp_where = "WHERE " + " AND ".join(lp_clauses)
+            async with self._pool.acquire() as conn:
+                row2 = await conn.fetchrow(
+                    f"""
+                    SELECT input_tokens, estimated_prompt_tokens FROM turn_usage
+                    {lp_where}
+                    ORDER BY created_at DESC
+                    LIMIT 1
+                    """,
+                    *lp_params,
+                )
+            if row2 is not None:
+                last_pt = int(row2["input_tokens"])
+                last_est = int(row2["estimated_prompt_tokens"])
+
+        return UsageSummary(
+            turns=turns,
+            input_tokens=int(row["input_tokens"]),
+            output_tokens=int(row["output_tokens"]),
+            cached_tokens=int(row["cached_tokens"]),
+            cost_usd=float(row["cost_usd"]),
+            period_start_ms=int(row["period_start_ms"]) if row["period_start_ms"] is not None else None,
+            period_end_ms=int(row["period_end_ms"]) if row["period_end_ms"] is not None else None,
+            last_prompt_tokens=last_pt,
+            last_estimated_prompt_tokens=last_est,
+            cache_read_tokens=int(row["cache_read_tokens"]),
+            cache_creation_tokens=int(row["cache_creation_tokens"]),
+        )
+
+
+class PostgresRunStore:
+    """asyncpg-backed subagent run lifecycle store."""
+
+    def __init__(self, pool: asyncpg.Pool) -> None:
+        self._pool = pool
+
+    async def record_pending(
+        self,
+        run_id: str,
+        parent_run_id: str | None,
+        script: str,
+        envelope: SubagentEnvelope,
+        scratch_dir: object,
+    ) -> None:
+        await self._record_run("pending", run_id, parent_run_id, script, envelope, scratch_dir)
+
+    async def record_started(
+        self,
+        run_id: str,
+        parent_run_id: str | None,
+        script: str,
+        envelope: SubagentEnvelope,
+        scratch_dir: object,
+    ) -> None:
+        await self._record_run("running", run_id, parent_run_id, script, envelope, scratch_dir)
+
+    async def _record_run(
+        self,
+        status: str,
+        run_id: str,
+        parent_run_id: str | None,
+        script: str,
+        envelope: SubagentEnvelope,
+        scratch_dir: object,
+    ) -> None:
+        now_ms = int(time.time() * 1000)
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                """
+                INSERT INTO subagent_runs(
+                    run_id, parent_run_id, script, envelope_json,
+                    status, result_json, error_json, started_at, finished_at, scratch_dir,
+                    worker_id, claimed_at
+                )
+                VALUES ($1, $2, $3, $4, $5, NULL, NULL, $6, NULL, $7, NULL, NULL)
+                """,
+                run_id,
+                parent_run_id,
+                script,
+                envelope.to_json(),
+                status,
+                now_ms,
+                str(scratch_dir),
+            )
+
+    async def claim(self, run_id: str, worker_id: str) -> bool:
+        now_ms = int(time.time() * 1000)
+        async with self._pool.acquire() as conn:
+            row = await conn.fetchrow(
+                """
+                UPDATE subagent_runs
+                SET status = 'running',
+                    worker_id = $2,
+                    claimed_at = $3
+                WHERE run_id = $1 AND status = 'pending'
+                RETURNING run_id
+                """,
+                run_id,
+                worker_id,
+                now_ms,
+            )
+        return row is not None
+
+    async def reset_stale_claims(self, stale_after_ms: int) -> int:
+        cutoff = int(time.time() * 1000) - stale_after_ms
+        async with self._pool.acquire() as conn:
+            result = await conn.execute(
+                """
+                UPDATE subagent_runs
+                SET status = 'pending',
+                    worker_id = NULL,
+                    claimed_at = NULL
+                WHERE status = 'running'
+                  AND claimed_at IS NOT NULL
+                  AND claimed_at < $1
+                """,
+                cutoff,
+            )
+        try:
+            return int(result.split()[-1])
+        except (ValueError, IndexError):
+            return 0
+
+    async def record_completed(self, run_id: str, result_json: str) -> None:
+        now_ms = int(time.time() * 1000)
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                """
+                UPDATE subagent_runs
+                SET status = 'completed',
+                    result_json = $1,
+                    finished_at = $2,
+                    error_json = NULL
+                WHERE run_id = $3
+                """,
+                result_json,
+                now_ms,
+                run_id,
+            )
+
+    async def record_failed(self, run_id: str, error: str) -> None:
+        now_ms = int(time.time() * 1000)
+        err_payload = json.dumps({"message": error})
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                """
+                UPDATE subagent_runs
+                SET status = 'failed',
+                    error_json = $1,
+                    finished_at = $2
+                WHERE run_id = $3
+                """,
+                err_payload,
+                now_ms,
+                run_id,
+            )
+
+    async def pending_runs(self) -> list[SubagentRunRow]:
+        columns = ", ".join(_SUBAGENT_COLUMNS)
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(
+                f"""
+                SELECT {columns} FROM subagent_runs
+                WHERE status = 'pending'
+                ORDER BY started_at ASC
+                """
+            )
+        return [_tuple_to_run_row(tuple(row)) for row in rows]
+
+    async def get_run(self, run_id: str) -> SubagentRunRow | None:
+        columns = ", ".join(_SUBAGENT_COLUMNS)
+        async with self._pool.acquire() as conn:
+            row = await conn.fetchrow(
+                f"SELECT {columns} FROM subagent_runs WHERE run_id = $1",
+                run_id,
+            )
+        if row is None:
+            return None
+        return _tuple_to_run_row(tuple(row))
+
+
+class PostgresScheduledLoopStore:
+    """Postgres persistence for scheduled agent loops."""
+
+    def __init__(self, pool: asyncpg.Pool) -> None:
+        self._pool = pool
+
+    async def create(self, spec: ScheduledLoopCreate) -> ScheduledLoopRow:
+        loop_id = _loop_id_from_create(spec)
+        if await self.get(loop_id) is not None:
+            raise ValueError(f"scheduled loop already exists: {loop_id}")
+        validate_loop_guards(
+            max_ticks=spec.max_ticks,
+            max_runtime_ms=spec.max_runtime_ms,
+            unbounded=spec.unbounded,
+        )
+        now_ms = int(time.time() * 1000)
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                """
+                INSERT INTO scheduled_loops(
+                    loop_id, session_id, status, prompt, interval_ms,
+                    max_ticks, max_runtime_ms, skip_if_busy, tick_index,
+                    next_tick_at_ms, started_at_ms, last_tick_at_ms,
+                    last_error, stop_reason, tick_in_flight, worker_id, claimed_at_ms
+                ) VALUES ($1, $2, 'active', $3, $4, $5, $6, $7, 0, $8, $8, NULL, NULL, NULL, 0, NULL, NULL)
+                """,
+                loop_id,
+                spec.session_id.strip() or "loop-main",
+                spec.prompt.strip(),
+                spec.interval_ms,
+                spec.max_ticks,
+                spec.max_runtime_ms,
+                1 if spec.skip_if_busy else 0,
+                now_ms,
+            )
+        row = await self.get(loop_id)
+        if row is None:
+            raise RuntimeError("failed to read scheduled loop after insert")
+        return row
+
+    async def get(self, loop_id: str) -> ScheduledLoopRow | None:
+        columns = ", ".join(_SCHEDULED_LOOP_COLUMNS)
+        async with self._pool.acquire() as conn:
+            row = await conn.fetchrow(
+                f"SELECT {columns} FROM scheduled_loops WHERE loop_id = $1",
+                loop_id,
+            )
+        if row is None:
+            return None
+        return _row_from_tuple(tuple(row))
+
+    async def list_all(self) -> list[ScheduledLoopRow]:
+        columns = ", ".join(_SCHEDULED_LOOP_COLUMNS)
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(
+                f"SELECT {columns} FROM scheduled_loops ORDER BY started_at_ms DESC"
+            )
+        return [_row_from_tuple(tuple(r)) for r in rows]
+
+    async def list_due(self, now_ms: int) -> list[ScheduledLoopRow]:
+        columns = ", ".join(_SCHEDULED_LOOP_COLUMNS)
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(
+                f"""
+                SELECT {columns} FROM scheduled_loops
+                WHERE status = 'active'
+                  AND tick_in_flight = 0
+                  AND next_tick_at_ms <= $1
+                ORDER BY next_tick_at_ms ASC
+                """,
+                now_ms,
+            )
+        return [_row_from_tuple(tuple(r)) for r in rows]
+
+    async def claim_tick(self, loop_id: str, worker_id: str) -> ScheduledLoopRow | None:
+        now_ms = int(time.time() * 1000)
+        async with self._pool.acquire() as conn:
+            status = await conn.execute(
+                """
+                UPDATE scheduled_loops
+                SET tick_in_flight = 1, worker_id = $1, claimed_at_ms = $2
+                WHERE loop_id = $3
+                  AND status = 'active'
+                  AND tick_in_flight = 0
+                  AND next_tick_at_ms <= $2
+                """,
+                worker_id,
+                now_ms,
+                loop_id,
+            )
+        if status.split()[-1] != "1":
+            return None
+        return await self.get(loop_id)
+
+    async def release_stale_claims(self, stale_after_ms: int) -> int:
+        cutoff = int(time.time() * 1000) - stale_after_ms
+        async with self._pool.acquire() as conn:
+            status = await conn.execute(
+                """
+                UPDATE scheduled_loops
+                SET tick_in_flight = 0, worker_id = NULL, claimed_at_ms = NULL,
+                    last_error = COALESCE(last_error, 'stale tick claim released')
+                WHERE tick_in_flight = 1
+                  AND claimed_at_ms IS NOT NULL
+                  AND claimed_at_ms < $1
+                """,
+                cutoff,
+            )
+        return int(status.split()[-1])
+
+    async def complete_tick(
+        self,
+        loop_id: str,
+        *,
+        worker_id: str,
+        error: str | None = None,
+    ) -> ScheduledLoopRow | None:
+        row = await self.get(loop_id)
+        if row is None or not row.tick_in_flight or row.worker_id != worker_id:
+            return None
+        now_ms = int(time.time() * 1000)
+        tick_index = row.tick_index + 1
+        stop_reason: str | None = None
+        status = row.status
+        if error:
+            status = "failed"
+            stop_reason = "tick_error"
+        elif row.max_ticks is not None and tick_index >= row.max_ticks:
+            status = "completed"
+            stop_reason = "max_ticks"
+        elif row.max_runtime_ms is not None and (now_ms - row.started_at_ms) >= row.max_runtime_ms:
+            status = "completed"
+            stop_reason = "max_runtime"
+        next_tick = now_ms + row.interval_ms if status == "active" else row.next_tick_at_ms
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                """
+                UPDATE scheduled_loops
+                SET tick_index = $1, last_tick_at_ms = $2, last_error = $3,
+                    status = $4, stop_reason = $5, next_tick_at_ms = $6,
+                    tick_in_flight = 0, worker_id = NULL, claimed_at_ms = NULL
+                WHERE loop_id = $7 AND worker_id = $8 AND tick_in_flight = 1
+                """,
+                tick_index,
+                now_ms,
+                error,
+                status,
+                stop_reason,
+                next_tick,
+                loop_id,
+                worker_id,
+            )
+        return await self.get(loop_id)
+
+    async def defer_tick(self, loop_id: str, *, worker_id: str, reason: str) -> None:
+        row = await self.get(loop_id)
+        if row is None or row.worker_id != worker_id:
+            return
+        now_ms = int(time.time() * 1000)
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                """
+                UPDATE scheduled_loops
+                SET tick_in_flight = 0, worker_id = NULL, claimed_at_ms = NULL,
+                    next_tick_at_ms = $1, last_error = $2
+                WHERE loop_id = $3 AND worker_id = $4
+                """,
+                now_ms + row.interval_ms,
+                reason,
+                loop_id,
+                worker_id,
+            )
+
+    async def renew_tick_claim(self, loop_id: str, worker_id: str) -> bool:
+        now_ms = int(time.time() * 1000)
+        async with self._pool.acquire() as conn:
+            status = await conn.execute(
+                """
+                UPDATE scheduled_loops
+                SET claimed_at_ms = $1
+                WHERE loop_id = $2
+                  AND worker_id = $3
+                  AND tick_in_flight = 1
+                """,
+                now_ms,
+                loop_id,
+                worker_id,
+            )
+        return bool(status.split()[-1] == "1")
+
+    async def pause(self, loop_id: str) -> bool:
+        async with self._pool.acquire() as conn:
+            status = await conn.execute(
+                """
+                UPDATE scheduled_loops
+                SET status = 'paused', tick_in_flight = 0, worker_id = NULL, claimed_at_ms = NULL
+                WHERE loop_id = $1
+                """,
+                loop_id,
+            )
+        return bool(status.split()[-1] == "1")
+
+    async def resume(self, loop_id: str) -> bool:
+        now_ms = int(time.time() * 1000)
+        async with self._pool.acquire() as conn:
+            status = await conn.execute(
+                """
+                UPDATE scheduled_loops
+                SET status = 'active', stop_reason = NULL, next_tick_at_ms = $1,
+                    tick_in_flight = 0, worker_id = NULL, claimed_at_ms = NULL
+                WHERE loop_id = $2 AND status = 'paused'
+                """,
+                now_ms,
+                loop_id,
+            )
+        return bool(status.split()[-1] == "1")
+
+    async def stop(self, loop_id: str, *, stop_reason: str = "manual") -> bool:
+        async with self._pool.acquire() as conn:
+            status = await conn.execute(
+                """
+                UPDATE scheduled_loops
+                SET status = 'completed', stop_reason = $1,
+                    tick_in_flight = 0, worker_id = NULL, claimed_at_ms = NULL
+                WHERE loop_id = $2
+                """,
+                stop_reason,
+                loop_id,
+            )
+        return bool(status.split()[-1] == "1")
+
+
+class PostgresSessionTurnLockStore:
+    """Postgres-backed exclusive turn lock per session."""
+
+    def __init__(self, pool: asyncpg.Pool) -> None:
+        self._pool = pool
+
+    async def release_stale_claims(self, stale_after_ms: int) -> int:
+        cutoff = int(time.time() * 1000) - stale_after_ms
+        async with self._pool.acquire() as conn:
+            status = await conn.execute(
+                """
+                UPDATE session_turn_locks
+                SET request_id = NULL, claimed_at_ms = NULL
+                WHERE request_id IS NOT NULL
+                  AND claimed_at_ms IS NOT NULL
+                  AND claimed_at_ms < $1
+                """,
+                cutoff,
+            )
+        return int(status.split()[-1])
+
+    async def try_acquire(self, session_id: str, request_id: str) -> bool:
+        from monkeybot.core.persistence.session_turn_locks import session_turn_stale_ms
+
+        await self.release_stale_claims(session_turn_stale_ms())
+        now_ms = int(time.time() * 1000)
+        async with self._pool.acquire() as conn:
+            row = await conn.fetchrow(
+                """
+                UPDATE session_turn_locks
+                SET request_id = $2, claimed_at_ms = $3
+                WHERE session_id = $1 AND request_id IS NULL
+                RETURNING session_id
+                """,
+                session_id,
+                request_id,
+                now_ms,
+            )
+            if row is not None:
+                return True
+            try:
+                await conn.execute(
+                    """
+                    INSERT INTO session_turn_locks (session_id, request_id, claimed_at_ms)
+                    VALUES ($1, $2, $3)
+                    """,
+                    session_id,
+                    request_id,
+                    now_ms,
+                )
+                return True
+            except asyncpg.UniqueViolationError:
+                return False
+
+    async def release(self, session_id: str, request_id: str) -> None:
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                """
+                UPDATE session_turn_locks
+                SET request_id = NULL, claimed_at_ms = NULL
+                WHERE session_id = $1 AND request_id = $2
+                """,
+                session_id,
+                request_id,
+            )
+
+    async def is_busy(self, session_id: str) -> bool:
+        async with self._pool.acquire() as conn:
+            row = await conn.fetchrow(
+                """
+                SELECT 1 FROM session_turn_locks
+                WHERE session_id = $1 AND request_id IS NOT NULL
+                LIMIT 1
+                """,
+                session_id,
+            )
+        return row is not None
+
+
+class PostgresStorageBackend:
+    """Postgres-backed storage backend using an asyncpg connection pool."""
+
+    def __init__(self, db_url: str) -> None:
+        self._db_url = db_url
+        self._pool: asyncpg.Pool | None = None
+        self._history_store: PostgresHistoryStore | None = None
+        self._usage_store: PostgresUsageStore | None = None
+        self._runs_store: PostgresRunStore | None = None
+        self._scheduled_loops_store: PostgresScheduledLoopStore | None = None
+        self._session_turn_lock_store: PostgresSessionTurnLockStore | None = None
+
+    async def open(self, *, run_schema: bool = True) -> None:
+        min_size = int(os.environ.get("POSTGRES_POOL_MIN", "1"))
+        max_size = int(os.environ.get("POSTGRES_POOL_MAX", "5"))
+        self._pool = await asyncpg.create_pool(
+            self._db_url, min_size=min_size, max_size=max_size
+        )
+        if run_schema:
+            await _apply_schema(self._pool)
+        self._history_store = PostgresHistoryStore(self._pool)
+        self._usage_store = PostgresUsageStore(self._pool)
+        self._runs_store = PostgresRunStore(self._pool)
+        self._scheduled_loops_store = PostgresScheduledLoopStore(self._pool)
+        self._session_turn_lock_store = PostgresSessionTurnLockStore(self._pool)
+
+    async def close(self) -> None:
+        if self._pool is not None:
+            await self._pool.close()
+            self._pool = 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) -> PostgresHistoryStore:
+        if self._history_store is None:
+            raise RuntimeError("PostgresStorageBackend.open() has not been called")
+        return self._history_store
+
+    def usage(self) -> PostgresUsageStore:
+        if self._usage_store is None:
+            raise RuntimeError("PostgresStorageBackend.open() has not been called")
+        return self._usage_store
+
+    def runs(self) -> PostgresRunStore:
+        if self._runs_store is None:
+            raise RuntimeError("PostgresStorageBackend.open() has not been called")
+        return self._runs_store
+
+    def scheduled_loops(self) -> PostgresScheduledLoopStore:
+        if self._scheduled_loops_store is None:
+            raise RuntimeError("PostgresStorageBackend.open() has not been called")
+        return self._scheduled_loops_store
+
+    def session_turns(self) -> PostgresSessionTurnLockStore:
+        if self._session_turn_lock_store is None:
+            raise RuntimeError("PostgresStorageBackend.open() has not been called")
+        return self._session_turn_lock_store