feat: add is_chat field to board memory and task_id to approvals, update pagination and response models

2026-02-06 19:11:11 +05:30
parent d86fe0a7a6
commit 6c14af0451
76 changed files with 2070 additions and 571 deletions
--- a/backend/.gitignore
+++ b/backend/.gitignore
@@ -3,3 +3,7 @@ __pycache__/
 .venv/
 .env
 .runlogs/
+
+# Generated on demand from uv.lock (single source of truth is pyproject.toml + uv.lock).
+requirements.txt
+requirements-dev.txt
--- a/backend/alembic/versions/1d844b04ee06_add_approvals_task_id.py
+++ b/backend/alembic/versions/1d844b04ee06_add_approvals_task_id.py
@@ -0,0 +1,101 @@
+"""add approvals task_id
+
+Revision ID: 1d844b04ee06
+Revises: a5aab244d32d
+Create Date: 2026-02-06 17:26:43.336466
+
+"""
+
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "1d844b04ee06"
+down_revision = "a5aab244d32d"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # This migration may run in databases where the column/index/constraint were created via
+    # SQLModel `create_all()` (or a previous hotfix). Make it idempotent to avoid blocking
+    # upgrades in dev environments.
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+
+    approval_cols = {c["name"] for c in inspector.get_columns("approvals")}
+    if "task_id" not in approval_cols:
+        op.add_column("approvals", sa.Column("task_id", sa.Uuid(), nullable=True))
+
+    approval_index_names = {i["name"] for i in inspector.get_indexes("approvals")}
+    if "ix_approvals_task_id" not in approval_index_names:
+        op.create_index("ix_approvals_task_id", "approvals", ["task_id"], unique=False)
+
+    # Backfill from legacy JSON payload keys when they contain a valid UUID.
+    op.execute(
+        """
+        WITH src AS (
+          SELECT
+            id,
+            COALESCE(
+              payload->>'task_id',
+              payload->>'taskId',
+              payload->>'taskID'
+            ) AS task_id_str
+          FROM approvals
+          WHERE task_id IS NULL
+        ),
+        valid AS (
+          SELECT
+            id,
+            task_id_str::uuid AS task_id
+          FROM src
+          WHERE task_id_str ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+        ),
+        existing AS (
+          SELECT v.id, v.task_id
+          FROM valid AS v
+          JOIN tasks AS t ON t.id = v.task_id
+        )
+        UPDATE approvals AS a
+        SET task_id = existing.task_id
+        FROM existing
+        WHERE a.id = existing.id;
+        """
+    )
+
+    # Avoid FK failures if any approvals point at deleted tasks.
+    op.execute(
+        """
+        UPDATE approvals AS a
+        SET task_id = NULL
+        WHERE task_id IS NOT NULL
+          AND NOT EXISTS (
+            SELECT 1 FROM tasks AS t WHERE t.id = a.task_id
+          );
+        """
+    )
+
+    approval_fks = inspector.get_foreign_keys("approvals")
+    has_task_fk = any(
+        (fk.get("referred_table") == "tasks" and "task_id" in (fk.get("constrained_columns") or []))
+        for fk in approval_fks
+    )
+    if not has_task_fk:
+        op.create_foreign_key(
+            "fk_approvals_task_id_tasks",
+            "approvals",
+            "tasks",
+            ["task_id"],
+            ["id"],
+            ondelete="SET NULL",
+        )
+
+
+def downgrade() -> None:
+    op.drop_constraint("fk_approvals_task_id_tasks", "approvals", type_="foreignkey")
+    op.drop_index("ix_approvals_task_id", table_name="approvals")
+    op.drop_column("approvals", "task_id")
--- a/backend/alembic/versions/a5aab244d32d_add_board_memory_is_chat.py
+++ b/backend/alembic/versions/a5aab244d32d_add_board_memory_is_chat.py
@@ -0,0 +1,60 @@
+"""add board memory is_chat
+
+Revision ID: a5aab244d32d
+Revises: 3b9b2f1a6c2d
+Create Date: 2026-02-06 17:57:02.110572
+
+"""
+
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "a5aab244d32d"
+down_revision = "3b9b2f1a6c2d"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Idempotent: the column/indexes might already exist if the table was created via
+    # SQLModel `create_all()`.
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+
+    memory_cols = {c["name"] for c in inspector.get_columns("board_memory")}
+    if "is_chat" not in memory_cols:
+        op.add_column(
+            "board_memory",
+            sa.Column("is_chat", sa.Boolean(), server_default=sa.text("false"), nullable=False),
+        )
+
+    memory_index_names = {i["name"] for i in inspector.get_indexes("board_memory")}
+    if "ix_board_memory_is_chat" not in memory_index_names:
+        op.create_index("ix_board_memory_is_chat", "board_memory", ["is_chat"], unique=False)
+    if "ix_board_memory_board_id_is_chat_created_at" not in memory_index_names:
+        op.create_index(
+            "ix_board_memory_board_id_is_chat_created_at",
+            "board_memory",
+            ["board_id", "is_chat", "created_at"],
+            unique=False,
+        )
+
+    # Backfill from existing tags arrays.
+    op.execute(
+        """
+        UPDATE board_memory
+        SET is_chat = TRUE
+        WHERE tags IS NOT NULL
+          AND tags::jsonb @> '["chat"]'::jsonb;
+        """
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_board_memory_board_id_is_chat_created_at", table_name="board_memory")
+    op.drop_index("ix_board_memory_is_chat", table_name="board_memory")
+    op.drop_column("board_memory", "is_chat")
--- a/backend/app/api/activity.py
+++ b/backend/app/api/activity.py
@@ -1,27 +1,27 @@
 from __future__ import annotations

-from fastapi import APIRouter, Depends, Query
+from fastapi import APIRouter, Depends
 from sqlalchemy import desc
 from sqlmodel import col, select
 from sqlmodel.ext.asyncio.session import AsyncSession

 from app.api.deps import ActorContext, require_admin_or_agent
+from app.db.pagination import paginate
 from app.db.session import get_session
 from app.models.activity_events import ActivityEvent
 from app.schemas.activity_events import ActivityEventRead
+from app.schemas.pagination import DefaultLimitOffsetPage

 router = APIRouter(prefix="/activity", tags=["activity"])


-@router.get("", response_model=list[ActivityEventRead])
+@router.get("", response_model=DefaultLimitOffsetPage[ActivityEventRead])
 async def list_activity(
-    limit: int = Query(50, ge=1, le=200),
-    offset: int = Query(0, ge=0),
    session: AsyncSession = Depends(get_session),
    actor: ActorContext = Depends(require_admin_or_agent),
-) -> list[ActivityEvent]:
+) -> DefaultLimitOffsetPage[ActivityEventRead]:
    statement = select(ActivityEvent)
    if actor.actor_type == "agent" and actor.agent:
        statement = statement.where(ActivityEvent.agent_id == actor.agent.id)
-    statement = statement.order_by(desc(col(ActivityEvent.created_at))).offset(offset).limit(limit)
-    return list(await session.exec(statement))
+    statement = statement.order_by(desc(col(ActivityEvent.created_at)))
+    return await paginate(session, statement)
--- a/backend/app/api/agent.py
+++ b/backend/app/api/agent.py
@@ -1,9 +1,11 @@
 from __future__ import annotations

+from collections.abc import Sequence
+from typing import Any, cast
 from uuid import UUID

 from fastapi import APIRouter, Depends, HTTPException, Query, status
-from sqlmodel import select
+from sqlmodel import col, select
 from sqlmodel.ext.asyncio.session import AsyncSession

 from app.api import agents as agents_api
@@ -13,6 +15,7 @@ from app.api import board_onboarding as onboarding_api
 from app.api import tasks as tasks_api
 from app.api.deps import ActorContext, get_board_or_404, get_task_or_404
 from app.core.agent_auth import AgentAuthContext, get_agent_auth_context
+from app.db.pagination import paginate
 from app.db.session import get_session
 from app.integrations.openclaw_gateway import GatewayConfig as GatewayClientConfig
 from app.integrations.openclaw_gateway import OpenClawGatewayError, ensure_session, send_message
@@ -30,6 +33,7 @@ from app.schemas.board_memory import BoardMemoryCreate, BoardMemoryRead
 from app.schemas.board_onboarding import BoardOnboardingAgentUpdate, BoardOnboardingRead
 from app.schemas.boards import BoardRead
 from app.schemas.common import OkResponse
+from app.schemas.pagination import DefaultLimitOffsetPage
 from app.schemas.tasks import TaskCommentCreate, TaskCommentRead, TaskCreate, TaskRead, TaskUpdate
 from app.services.activity_log import record_activity

@@ -54,15 +58,16 @@ async def _gateway_config(session: AsyncSession, board: Board) -> GatewayClientC
    return GatewayClientConfig(url=gateway.url, token=gateway.token)


-@router.get("/boards", response_model=list[BoardRead])
+@router.get("/boards", response_model=DefaultLimitOffsetPage[BoardRead])
 async def list_boards(
    session: AsyncSession = Depends(get_session),
    agent_ctx: AgentAuthContext = Depends(get_agent_auth_context),
-) -> list[Board]:
+) -> DefaultLimitOffsetPage[BoardRead]:
+    statement = select(Board)
    if agent_ctx.agent.board_id:
-        board = await session.get(Board, agent_ctx.agent.board_id)
-        return [board] if board else []
-    return list(await session.exec(select(Board)))
+        statement = statement.where(col(Board.id) == agent_ctx.agent.board_id)
+    statement = statement.order_by(col(Board.created_at).desc())
+    return await paginate(session, statement)


@router.get("/boards/{board_id}", response_model=BoardRead)
@@ -74,13 +79,12 @@ def get_board(
    return board


-@router.get("/agents", response_model=list[AgentRead])
+@router.get("/agents", response_model=DefaultLimitOffsetPage[AgentRead])
 async def list_agents(
    board_id: UUID | None = Query(default=None),
-    limit: int | None = Query(default=None, ge=1, le=200),
    session: AsyncSession = Depends(get_session),
    agent_ctx: AgentAuthContext = Depends(get_agent_auth_context),
-) -> list[AgentRead]:
+) -> DefaultLimitOffsetPage[AgentRead]:
    statement = select(Agent)
    if agent_ctx.agent.board_id:
        if board_id and board_id != agent_ctx.agent.board_id:
@@ -88,32 +92,33 @@ async def list_agents(
        statement = statement.where(Agent.board_id == agent_ctx.agent.board_id)
    elif board_id:
        statement = statement.where(Agent.board_id == board_id)
-    if limit is not None:
-        statement = statement.limit(limit)
-    agents = list(await session.exec(statement))
    main_session_keys = await agents_api._get_gateway_main_session_keys(session)
-    return [
-        agents_api._to_agent_read(agents_api._with_computed_status(agent), main_session_keys)
-        for agent in agents
-    ]
+    statement = statement.order_by(col(Agent.created_at).desc())
+
+    def _transform(items: Sequence[Any]) -> Sequence[Any]:
+        agents = cast(Sequence[Agent], items)
+        return [
+            agents_api._to_agent_read(agents_api._with_computed_status(agent), main_session_keys)
+            for agent in agents
+        ]
+
+    return await paginate(session, statement, transformer=_transform)


-@router.get("/boards/{board_id}/tasks", response_model=list[TaskRead])
+@router.get("/boards/{board_id}/tasks", response_model=DefaultLimitOffsetPage[TaskRead])
 async def list_tasks(
    status_filter: str | None = Query(default=None, alias="status"),
    assigned_agent_id: UUID | None = None,
    unassigned: bool | None = None,
-    limit: int | None = Query(default=None, ge=1, le=200),
    board: Board = Depends(get_board_or_404),
    session: AsyncSession = Depends(get_session),
    agent_ctx: AgentAuthContext = Depends(get_agent_auth_context),
-) -> list[Task]:
+) -> DefaultLimitOffsetPage[TaskRead]:
    _guard_board_access(agent_ctx, board)
    return await tasks_api.list_tasks(
        status_filter=status_filter,
        assigned_agent_id=assigned_agent_id,
        unassigned=unassigned,
-        limit=limit,
        board=board,
        session=session,
        actor=_actor(agent_ctx),
@@ -185,12 +190,15 @@ async def update_task(
    )


-@router.get("/boards/{board_id}/tasks/{task_id}/comments", response_model=list[TaskCommentRead])
+@router.get(
+    "/boards/{board_id}/tasks/{task_id}/comments",
+    response_model=DefaultLimitOffsetPage[TaskCommentRead],
+)
 async def list_task_comments(
    task: Task = Depends(get_task_or_404),
    session: AsyncSession = Depends(get_session),
    agent_ctx: AgentAuthContext = Depends(get_agent_auth_context),
-) -> list[ActivityEvent]:
+) -> DefaultLimitOffsetPage[TaskCommentRead]:
    if agent_ctx.agent.board_id and task.board_id and agent_ctx.agent.board_id != task.board_id:
        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
    return await tasks_api.list_task_comments(
@@ -217,18 +225,14 @@ async def create_task_comment(
    )


-@router.get("/boards/{board_id}/memory", response_model=list[BoardMemoryRead])
+@router.get("/boards/{board_id}/memory", response_model=DefaultLimitOffsetPage[BoardMemoryRead])
 async def list_board_memory(
-    limit: int = Query(default=50, ge=1, le=200),
-    offset: int = Query(default=0, ge=0),
    board: Board = Depends(get_board_or_404),
    session: AsyncSession = Depends(get_session),
    agent_ctx: AgentAuthContext = Depends(get_agent_auth_context),
-) -> list[BoardMemory]:
+) -> DefaultLimitOffsetPage[BoardMemoryRead]:
    _guard_board_access(agent_ctx, board)
    return await board_memory_api.list_board_memory(
-        limit=limit,
-        offset=offset,
        board=board,
        session=session,
        actor=_actor(agent_ctx),
@@ -251,13 +255,16 @@ async def create_board_memory(
    )


-@router.get("/boards/{board_id}/approvals", response_model=list[ApprovalRead])
+@router.get(
+    "/boards/{board_id}/approvals",
+    response_model=DefaultLimitOffsetPage[ApprovalRead],
+)
 async def list_approvals(
    status_filter: ApprovalStatus | None = Query(default=None, alias="status"),
    board: Board = Depends(get_board_or_404),
    session: AsyncSession = Depends(get_session),
    agent_ctx: AgentAuthContext = Depends(get_agent_auth_context),
-) -> list[Approval]:
+) -> DefaultLimitOffsetPage[ApprovalRead]:
    _guard_board_access(agent_ctx, board)
    return await approvals_api.list_approvals(
        status_filter=status_filter,
--- a/backend/app/api/agents.py
+++ b/backend/app/api/agents.py
@@ -3,8 +3,9 @@ from __future__ import annotations
 import asyncio
 import json
 import re
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Sequence
 from datetime import datetime, timedelta, timezone
+from typing import Any, cast
 from uuid import UUID, uuid4

 from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
@@ -17,6 +18,7 @@ from app.api.deps import ActorContext, require_admin_auth, require_admin_or_agen
 from app.core.agent_tokens import generate_agent_token, hash_agent_token
 from app.core.auth import AuthContext
 from app.core.time import utcnow
+from app.db.pagination import paginate
 from app.db.session import async_session_maker, get_session
 from app.integrations.openclaw_gateway import GatewayConfig as GatewayClientConfig
 from app.integrations.openclaw_gateway import OpenClawGatewayError, ensure_session, send_message
@@ -33,6 +35,7 @@ from app.schemas.agents import (
    AgentRead,
    AgentUpdate,
 )
+from app.schemas.pagination import DefaultLimitOffsetPage
 from app.services.activity_log import record_activity
 from app.services.agent_provisioning import (
    DEFAULT_HEARTBEAT_CONFIG,
@@ -231,14 +234,28 @@ async def _send_wakeup_message(
    await send_message(message, session_key=session_key, config=config, deliver=True)


-@router.get("", response_model=list[AgentRead])
+@router.get("", response_model=DefaultLimitOffsetPage[AgentRead])
 async def list_agents(
+    board_id: UUID | None = Query(default=None),
+    gateway_id: UUID | None = Query(default=None),
    session: AsyncSession = Depends(get_session),
    auth: AuthContext = Depends(require_admin_auth),
-) -> list[AgentRead]:
-    agents = list(await session.exec(select(Agent)))
+) -> DefaultLimitOffsetPage[AgentRead]:
    main_session_keys = await _get_gateway_main_session_keys(session)
-    return [_to_agent_read(_with_computed_status(agent), main_session_keys) for agent in agents]
+    statement = select(Agent)
+    if board_id is not None:
+        statement = statement.where(col(Agent.board_id) == board_id)
+    if gateway_id is not None:
+        statement = statement.join(Board, col(Agent.board_id) == col(Board.id)).where(
+            col(Board.gateway_id) == gateway_id
+        )
+    statement = statement.order_by(col(Agent.created_at).desc())
+
+    def _transform(items: Sequence[Any]) -> Sequence[Any]:
+        agents = cast(Sequence[Agent], items)
+        return [_to_agent_read(_with_computed_status(agent), main_session_keys) for agent in agents]
+
+    return await paginate(session, statement, transformer=_transform)


@router.get("/stream")
--- a/backend/app/api/approvals.py
+++ b/backend/app/api/approvals.py
@@ -7,7 +7,7 @@ from datetime import datetime, timezone
 from uuid import UUID

 from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
-from sqlalchemy import asc, or_
+from sqlalchemy import asc, case, func, or_
 from sqlmodel import col, select
 from sqlmodel.ext.asyncio.session import AsyncSession
 from sse_starlette.sse import EventSourceResponse
@@ -15,13 +15,32 @@ from sse_starlette.sse import EventSourceResponse
 from app.api.deps import ActorContext, get_board_or_404, require_admin_auth, require_admin_or_agent
 from app.core.auth import AuthContext
 from app.core.time import utcnow
+from app.db.pagination import paginate
 from app.db.session import async_session_maker, get_session
 from app.models.approvals import Approval
 from app.models.boards import Board
 from app.schemas.approvals import ApprovalCreate, ApprovalRead, ApprovalStatus, ApprovalUpdate
+from app.schemas.pagination import DefaultLimitOffsetPage

 router = APIRouter(prefix="/boards/{board_id}/approvals", tags=["approvals"])

+TASK_ID_KEYS: tuple[str, ...] = ("task_id", "taskId", "taskID")
+
+
+def _extract_task_id(payload: dict[str, object] | None) -> UUID | None:
+    if not payload:
+        return None
+    for key in TASK_ID_KEYS:
+        value = payload.get(key)
+        if isinstance(value, UUID):
+            return value
+        if isinstance(value, str):
+            try:
+                return UUID(value)
+            except ValueError:
+                continue
+    return None
+

 def _parse_since(value: str | None) -> datetime | None:
    if not value:
@@ -66,13 +85,13 @@ async def _fetch_approval_events(
    return list(await session.exec(statement))


-@router.get("", response_model=list[ApprovalRead])
+@router.get("", response_model=DefaultLimitOffsetPage[ApprovalRead])
 async def list_approvals(
    status_filter: ApprovalStatus | None = Query(default=None, alias="status"),
    board: Board = Depends(get_board_or_404),
    session: AsyncSession = Depends(get_session),
    actor: ActorContext = Depends(require_admin_or_agent),
-) -> list[Approval]:
+) -> DefaultLimitOffsetPage[ApprovalRead]:
    if actor.actor_type == "agent" and actor.agent:
        if actor.agent.board_id and actor.agent.board_id != board.id:
            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
@@ -80,7 +99,7 @@ async def list_approvals(
    if status_filter:
        statement = statement.where(col(Approval.status) == status_filter)
    statement = statement.order_by(col(Approval.created_at).desc())
-    return list(await session.exec(statement))
+    return await paginate(session, statement)


@router.get("/stream")
@@ -103,11 +122,53 @@ async def stream_approvals(
                break
            async with async_session_maker() as session:
                approvals = await _fetch_approval_events(session, board.id, last_seen)
+                pending_approvals_count = int(
+                    (
+                        await session.exec(
+                            select(func.count(col(Approval.id)))
+                            .where(col(Approval.board_id) == board.id)
+                            .where(col(Approval.status) == "pending")
+                        )
+                    ).one()
+                )
+                task_ids = {approval.task_id for approval in approvals if approval.task_id is not None}
+                counts_by_task_id: dict[UUID, tuple[int, int]] = {}
+                if task_ids:
+                    rows = list(
+                        await session.exec(
+                            select(
+                                col(Approval.task_id),
+                                func.count(col(Approval.id)).label("total"),
+                                func.sum(
+                                    case((col(Approval.status) == "pending", 1), else_=0)
+                                ).label("pending"),
+                            )
+                            .where(col(Approval.board_id) == board.id)
+                            .where(col(Approval.task_id).in_(task_ids))
+                            .group_by(col(Approval.task_id))
+                        )
+                    )
+                    for task_id, total, pending in rows:
+                        if task_id is None:
+                            continue
+                        counts_by_task_id[task_id] = (int(total or 0), int(pending or 0))
            for approval in approvals:
                updated_at = _approval_updated_at(approval)
                if updated_at > last_seen:
                    last_seen = updated_at
-                payload = {"approval": _serialize_approval(approval)}
+                payload: dict[str, object] = {
+                    "approval": _serialize_approval(approval),
+                    "pending_approvals_count": pending_approvals_count,
+                }
+                if approval.task_id is not None:
+                    counts = counts_by_task_id.get(approval.task_id)
+                    if counts is not None:
+                        total, pending = counts
+                        payload["task_counts"] = {
+                            "task_id": str(approval.task_id),
+                            "approvals_count": total,
+                            "approvals_pending_count": pending,
+                        }
                yield {"event": "approval", "data": json.dumps(payload)}
            await asyncio.sleep(2)

@@ -124,8 +185,10 @@ async def create_approval(
    if actor.actor_type == "agent" and actor.agent:
        if actor.agent.board_id and actor.agent.board_id != board.id:
            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
+    task_id = payload.task_id or _extract_task_id(payload.payload)
    approval = Approval(
        board_id=board.id,
+        task_id=task_id,
        agent_id=payload.agent_id,
        action_type=payload.action_type,
        payload=payload.payload,
--- a/backend/app/api/board_memory.py
+++ b/backend/app/api/board_memory.py
@@ -8,6 +8,7 @@ from datetime import datetime, timezone
 from uuid import UUID

 from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
+from sqlalchemy import func
 from sqlmodel import col, select
 from sqlmodel.ext.asyncio.session import AsyncSession
 from sse_starlette.sse import EventSourceResponse
@@ -15,6 +16,7 @@ from sse_starlette.sse import EventSourceResponse
 from app.api.deps import ActorContext, get_board_or_404, require_admin_or_agent
 from app.core.config import settings
 from app.core.time import utcnow
+from app.db.pagination import paginate
 from app.db.session import async_session_maker, get_session
 from app.integrations.openclaw_gateway import GatewayConfig as GatewayClientConfig
 from app.integrations.openclaw_gateway import OpenClawGatewayError, ensure_session, send_message
@@ -23,6 +25,7 @@ from app.models.board_memory import BoardMemory
 from app.models.boards import Board
 from app.models.gateways import Gateway
 from app.schemas.board_memory import BoardMemoryCreate, BoardMemoryRead
+from app.schemas.pagination import DefaultLimitOffsetPage

 router = APIRouter(prefix="/boards/{board_id}/memory", tags=["board-memory"])

@@ -90,11 +93,19 @@ async def _fetch_memory_events(
    session: AsyncSession,
    board_id: UUID,
    since: datetime,
+    is_chat: bool | None = None,
 ) -> list[BoardMemory]:
    statement = (
        select(BoardMemory)
        .where(col(BoardMemory.board_id) == board_id)
-        .where(col(BoardMemory.created_at) >= since)
+        # Old/invalid rows (empty/whitespace-only content) can exist; exclude them to
+        # satisfy the NonEmptyStr response schema.
+        .where(func.length(func.trim(col(BoardMemory.content))) > 0)
+    )
+    if is_chat is not None:
+        statement = statement.where(col(BoardMemory.is_chat) == is_chat)
+    statement = (
+        statement.where(col(BoardMemory.created_at) >= since)
        .order_by(col(BoardMemory.created_at))
    )
    return list(await session.exec(statement))
@@ -159,25 +170,27 @@ async def _notify_chat_targets(
            continue


-@router.get("", response_model=list[BoardMemoryRead])
+@router.get("", response_model=DefaultLimitOffsetPage[BoardMemoryRead])
 async def list_board_memory(
-    limit: int = Query(default=50, ge=1, le=200),
-    offset: int = Query(default=0, ge=0),
+    is_chat: bool | None = Query(default=None),
    board: Board = Depends(get_board_or_404),
    session: AsyncSession = Depends(get_session),
    actor: ActorContext = Depends(require_admin_or_agent),
-) -> list[BoardMemory]:
+) -> DefaultLimitOffsetPage[BoardMemoryRead]:
    if actor.actor_type == "agent" and actor.agent:
        if actor.agent.board_id and actor.agent.board_id != board.id:
            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
    statement = (
        select(BoardMemory)
        .where(col(BoardMemory.board_id) == board.id)
-        .order_by(col(BoardMemory.created_at).desc())
-        .offset(offset)
-        .limit(limit)
+        # Old/invalid rows (empty/whitespace-only content) can exist; exclude them to
+        # satisfy the NonEmptyStr response schema.
+        .where(func.length(func.trim(col(BoardMemory.content))) > 0)
    )
-    return list(await session.exec(statement))
+    if is_chat is not None:
+        statement = statement.where(col(BoardMemory.is_chat) == is_chat)
+    statement = statement.order_by(col(BoardMemory.created_at).desc())
+    return await paginate(session, statement)


@router.get("/stream")
@@ -186,6 +199,7 @@ async def stream_board_memory(
    board: Board = Depends(get_board_or_404),
    actor: ActorContext = Depends(require_admin_or_agent),
    since: str | None = Query(default=None),
+    is_chat: bool | None = Query(default=None),
 ) -> EventSourceResponse:
    if actor.actor_type == "agent" and actor.agent:
        if actor.agent.board_id and actor.agent.board_id != board.id:
@@ -199,7 +213,12 @@ async def stream_board_memory(
            if await request.is_disconnected():
                break
            async with async_session_maker() as session:
-                memories = await _fetch_memory_events(session, board.id, last_seen)
+                memories = await _fetch_memory_events(
+                    session,
+                    board.id,
+                    last_seen,
+                    is_chat=is_chat,
+                )
            for memory in memories:
                if memory.created_at > last_seen:
                    last_seen = memory.created_at
@@ -231,6 +250,7 @@ async def create_board_memory(
        board_id=board.id,
        content=payload.content,
        tags=payload.tags,
+        is_chat=is_chat,
        source=source,
    )
    session.add(memory)
--- a/backend/app/api/board_onboarding.py
+++ b/backend/app/api/board_onboarding.py
@@ -2,7 +2,6 @@ from __future__ import annotations

 import logging
 import re
-from datetime import datetime
 from uuid import uuid4

 from fastapi import APIRouter, Depends, HTTPException, status
--- a/backend/app/api/boards.py
+++ b/backend/app/api/boards.py
@@ -1,10 +1,11 @@
 from __future__ import annotations

 import re
-from uuid import uuid4
+from uuid import UUID, uuid4

-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy import delete
+from sqlalchemy import func
 from sqlmodel import col, select
 from sqlmodel.ext.asyncio.session import AsyncSession

@@ -12,6 +13,7 @@ from app.api.deps import ActorContext, get_board_or_404, require_admin_auth, req
 from app.core.auth import AuthContext
 from app.core.time import utcnow
 from app.db import crud
+from app.db.pagination import paginate
 from app.db.session import get_session
 from app.integrations.openclaw_gateway import GatewayConfig as GatewayClientConfig
 from app.integrations.openclaw_gateway import (
@@ -31,6 +33,9 @@ from app.models.task_fingerprints import TaskFingerprint
 from app.models.tasks import Task
 from app.schemas.common import OkResponse
 from app.schemas.boards import BoardCreate, BoardRead, BoardUpdate
+from app.schemas.pagination import DefaultLimitOffsetPage
+from app.schemas.view_models import BoardSnapshot
+from app.services.board_snapshot import build_board_snapshot

 router = APIRouter(prefix="/boards", tags=["boards"])

@@ -149,12 +154,17 @@ async def _cleanup_agent_on_gateway(
    )


-@router.get("", response_model=list[BoardRead])
+@router.get("", response_model=DefaultLimitOffsetPage[BoardRead])
 async def list_boards(
+    gateway_id: UUID | None = Query(default=None),
    session: AsyncSession = Depends(get_session),
    actor: ActorContext = Depends(require_admin_or_agent),
-) -> list[Board]:
-    return list(await session.exec(select(Board)))
+) -> DefaultLimitOffsetPage[BoardRead]:
+    statement = select(Board)
+    if gateway_id is not None:
+        statement = statement.where(col(Board.gateway_id) == gateway_id)
+    statement = statement.order_by(func.lower(col(Board.name)).asc(), col(Board.created_at).desc())
+    return await paginate(session, statement)


@router.post("", response_model=BoardRead)
@@ -175,6 +185,18 @@ def get_board(
    return board


+@router.get("/{board_id}/snapshot", response_model=BoardSnapshot)
+async def get_board_snapshot(
+    board: Board = Depends(get_board_or_404),
+    session: AsyncSession = Depends(get_session),
+    actor: ActorContext = Depends(require_admin_or_agent),
+) -> BoardSnapshot:
+    if actor.actor_type == "agent" and actor.agent:
+        if actor.agent.board_id and actor.agent.board_id != board.id:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
+    return await build_board_snapshot(session, board)
+
+
@router.patch("/{board_id}", response_model=BoardRead)
 async def update_board(
    payload: BoardUpdate,
--- a/backend/app/api/gateways.py
+++ b/backend/app/api/gateways.py
@@ -1,15 +1,15 @@
 from __future__ import annotations

-from datetime import datetime
 from uuid import UUID

 from fastapi import APIRouter, Depends, HTTPException, status
-from sqlmodel import select
+from sqlmodel import col, select
 from sqlmodel.ext.asyncio.session import AsyncSession

 from app.core.agent_tokens import generate_agent_token, hash_agent_token
 from app.core.auth import AuthContext, get_auth_context
 from app.core.time import utcnow
+from app.db.pagination import paginate
 from app.db.session import get_session
 from app.integrations.openclaw_gateway import GatewayConfig as GatewayClientConfig
 from app.integrations.openclaw_gateway import OpenClawGatewayError, ensure_session, send_message
@@ -17,6 +17,7 @@ from app.models.agents import Agent
 from app.models.gateways import Gateway
 from app.schemas.common import OkResponse
 from app.schemas.gateways import GatewayCreate, GatewayRead, GatewayUpdate
+from app.schemas.pagination import DefaultLimitOffsetPage
 from app.services.agent_provisioning import DEFAULT_HEARTBEAT_CONFIG, provision_main_agent

 router = APIRouter(prefix="/gateways", tags=["gateways"])
@@ -362,12 +363,13 @@ async def _send_skyll_disable_message(gateway: Gateway) -> None:
    )


-@router.get("", response_model=list[GatewayRead])
+@router.get("", response_model=DefaultLimitOffsetPage[GatewayRead])
 async def list_gateways(
    session: AsyncSession = Depends(get_session),
    auth: AuthContext = Depends(get_auth_context),
-) -> list[Gateway]:
-    return list(await session.exec(select(Gateway)))
+) -> DefaultLimitOffsetPage[GatewayRead]:
+    statement = select(Gateway).order_by(col(Gateway.created_at).desc())
+    return await paginate(session, statement)


@router.post("", response_model=GatewayRead)
--- a/backend/app/api/tasks.py
+++ b/backend/app/api/tasks.py
@@ -25,16 +25,19 @@ from app.api.deps import (
 )
 from app.core.auth import AuthContext
 from app.core.time import utcnow
+from app.db.pagination import paginate
 from app.db.session import async_session_maker, get_session
 from app.integrations.openclaw_gateway import GatewayConfig as GatewayClientConfig
 from app.integrations.openclaw_gateway import OpenClawGatewayError, ensure_session, send_message
 from app.models.activity_events import ActivityEvent
 from app.models.agents import Agent
+from app.models.approvals import Approval
 from app.models.boards import Board
 from app.models.gateways import Gateway
 from app.models.task_fingerprints import TaskFingerprint
 from app.models.tasks import Task
 from app.schemas.common import OkResponse
+from app.schemas.pagination import DefaultLimitOffsetPage
 from app.schemas.tasks import TaskCommentCreate, TaskCommentRead, TaskCreate, TaskRead, TaskUpdate
 from app.services.activity_log import record_activity

@@ -410,16 +413,18 @@ async def stream_tasks(
    return EventSourceResponse(event_generator(), ping=15)


-@router.get("", response_model=list[TaskRead])
+@router.get("", response_model=DefaultLimitOffsetPage[TaskRead])
 async def list_tasks(
    status_filter: str | None = Query(default=None, alias="status"),
    assigned_agent_id: UUID | None = None,
    unassigned: bool | None = None,
-    limit: int | None = Query(default=None, ge=1, le=200),
    board: Board = Depends(get_board_or_404),
    session: AsyncSession = Depends(get_session),
    actor: ActorContext = Depends(require_admin_or_agent),
-) -> list[Task]:
+) -> DefaultLimitOffsetPage[TaskRead]:
+    if actor.actor_type == "agent" and actor.agent:
+        if actor.agent.board_id and actor.agent.board_id != board.id:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
    statement = select(Task).where(Task.board_id == board.id)
    if status_filter:
        statuses = [s.strip() for s in status_filter.split(",") if s.strip()]
@@ -434,9 +439,8 @@ async def list_tasks(
        statement = statement.where(col(Task.assigned_agent_id) == assigned_agent_id)
    if unassigned:
        statement = statement.where(col(Task.assigned_agent_id).is_(None))
-    if limit is not None:
-        statement = statement.limit(limit)
-    return list(await session.exec(statement))
+    statement = statement.order_by(col(Task.created_at).desc())
+    return await paginate(session, statement)


@router.post("", response_model=TaskRead)
@@ -661,17 +665,18 @@ async def delete_task(
 ) -> OkResponse:
    await session.execute(delete(ActivityEvent).where(col(ActivityEvent.task_id) == task.id))
    await session.execute(delete(TaskFingerprint).where(col(TaskFingerprint.task_id) == task.id))
+    await session.execute(delete(Approval).where(col(Approval.task_id) == task.id))
    await session.delete(task)
    await session.commit()
    return OkResponse()


-@router.get("/{task_id}/comments", response_model=list[TaskCommentRead])
+@router.get("/{task_id}/comments", response_model=DefaultLimitOffsetPage[TaskCommentRead])
 async def list_task_comments(
    task: Task = Depends(get_task_or_404),
    session: AsyncSession = Depends(get_session),
    actor: ActorContext = Depends(require_admin_or_agent),
-) -> list[ActivityEvent]:
+) -> DefaultLimitOffsetPage[TaskCommentRead]:
    if actor.actor_type == "agent" and actor.agent:
        if actor.agent.board_id and task.board_id and actor.agent.board_id != task.board_id:
            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
@@ -681,7 +686,7 @@ async def list_task_comments(
        .where(col(ActivityEvent.event_type) == "task.comment")
        .order_by(asc(col(ActivityEvent.created_at)))
    )
-    return list(await session.exec(statement))
+    return await paginate(session, statement)


@router.post("/{task_id}/comments", response_model=TaskCommentRead)
--- a/backend/app/core/config.py
+++ b/backend/app/core/config.py
@@ -1,11 +1,20 @@
 from __future__ import annotations

+from pathlib import Path
+from typing import Self
+
+from pydantic import model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict

+BACKEND_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_ENV_FILE = BACKEND_ROOT / ".env"
+

 class Settings(BaseSettings):
    model_config = SettingsConfigDict(
-        env_file=".env",
+        # Load `backend/.env` regardless of current working directory.
+        # (Important when running uvicorn from repo root or via a process manager.)
+        env_file=[DEFAULT_ENV_FILE, ".env"],
        env_file_encoding="utf-8",
        extra="ignore",
    )
@@ -30,5 +39,13 @@ class Settings(BaseSettings):
    log_format: str = "text"
    log_use_utc: bool = False

+    @model_validator(mode="after")
+    def _defaults(self) -> Self:
+        # In dev, default to applying Alembic migrations at startup to avoid schema drift
+        # (e.g. missing newly-added columns).
+        if "db_auto_migrate" not in self.model_fields_set and self.environment == "dev":
+            self.db_auto_migrate = True
+        return self
+

 settings = Settings()
--- a/backend/app/core/time.py
+++ b/backend/app/core/time.py
@@ -8,4 +8,3 @@ def utcnow() -> datetime:

    # Keep naive UTC values for compatibility with existing DB schema/queries.
    return datetime.now(UTC).replace(tzinfo=None)
-
--- a/backend/app/db/pagination.py
+++ b/backend/app/db/pagination.py
@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any, TypeVar, cast
+
+from fastapi_pagination.ext.sqlalchemy import paginate as _paginate
+from sqlmodel.ext.asyncio.session import AsyncSession
+from sqlmodel.sql.expression import Select, SelectOfScalar
+
+from app.schemas.pagination import DefaultLimitOffsetPage
+
+T = TypeVar("T")
+
+Transformer = Callable[[Sequence[Any]], Sequence[Any] | Awaitable[Sequence[Any]]]
+
+
+async def paginate(
+    session: AsyncSession,
+    statement: Select[Any] | SelectOfScalar[Any],
+    *,
+    transformer: Transformer | None = None,
+) -> DefaultLimitOffsetPage[T]:
+    # fastapi-pagination is not fully typed (it returns Any), but response_model validation
+    # ensures runtime correctness. Centralize casts here to keep strict mypy clean.
+    return cast(
+        DefaultLimitOffsetPage[T],
+        await _paginate(session, statement, transformer=transformer),
+    )
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -5,6 +5,7 @@ from contextlib import asynccontextmanager

 from fastapi import APIRouter, FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi_pagination import add_pagination

 from app.api.activity import router as activity_router
 from app.api.agent import router as agent_router
@@ -75,3 +76,5 @@ api_v1.include_router(approvals_router)
 api_v1.include_router(tasks_router)
 api_v1.include_router(users_router)
 app.include_router(api_v1)
+
+add_pagination(app)
--- a/backend/app/models/approvals.py
+++ b/backend/app/models/approvals.py
@@ -14,6 +14,7 @@ class Approval(SQLModel, table=True):

    id: UUID = Field(default_factory=uuid4, primary_key=True)
    board_id: UUID = Field(foreign_key="boards.id", index=True)
+    task_id: UUID | None = Field(default=None, foreign_key="tasks.id", index=True)
    agent_id: UUID | None = Field(default=None, foreign_key="agents.id", index=True)
    action_type: str
    payload: dict[str, object] | None = Field(default=None, sa_column=Column(JSON))
--- a/backend/app/models/board_memory.py
+++ b/backend/app/models/board_memory.py
@@ -16,5 +16,6 @@ class BoardMemory(SQLModel, table=True):
    board_id: UUID = Field(foreign_key="boards.id", index=True)
    content: str
    tags: list[str] | None = Field(default=None, sa_column=Column(JSON))
+    is_chat: bool = Field(default=False, index=True)
    source: str | None = None
    created_at: datetime = Field(default_factory=utcnow)
--- a/backend/app/schemas/approvals.py
+++ b/backend/app/schemas/approvals.py
@@ -13,6 +13,7 @@ ApprovalStatus = Literal["pending", "approved", "rejected"]

 class ApprovalBase(SQLModel):
    action_type: str
+    task_id: UUID | None = None
    payload: dict[str, object] | None = None
    confidence: int
    rubric_scores: dict[str, int] | None = None
--- a/backend/app/schemas/board_memory.py
+++ b/backend/app/schemas/board_memory.py
@@ -9,12 +9,18 @@ from app.schemas.common import NonEmptyStr


 class BoardMemoryCreate(SQLModel):
+    # For writes, reject blank/whitespace-only content.
    content: NonEmptyStr
    tags: list[str] | None = None
    source: str | None = None


-class BoardMemoryRead(BoardMemoryCreate):
+class BoardMemoryRead(SQLModel):
    id: UUID
    board_id: UUID
+    # For reads, allow legacy rows that may have empty content (avoid response validation 500s).
+    content: str
+    tags: list[str] | None = None
+    source: str | None = None
+    is_chat: bool = False
    created_at: datetime
--- a/backend/app/schemas/pagination.py
+++ b/backend/app/schemas/pagination.py
@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import TypeVar
+
+from fastapi import Query
+from fastapi_pagination.customization import CustomizedPage, UseParamsFields
+from fastapi_pagination.limit_offset import LimitOffsetPage
+
+T = TypeVar("T")
+
+
+# Project-wide default pagination response model.
+# - Keep `limit` / `offset` naming (matches existing API conventions).
+# - Cap list endpoints to 200 items per request (matches prior route-level constraints).
+DefaultLimitOffsetPage = CustomizedPage[
+    LimitOffsetPage[T],
+    UseParamsFields(
+        limit=Query(200, ge=1, le=200),
+        offset=Query(0, ge=0),
+    ),
+]
--- a/backend/app/schemas/view_models.py
+++ b/backend/app/schemas/view_models.py
@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from sqlmodel import SQLModel
+
+from app.schemas.agents import AgentRead
+from app.schemas.approvals import ApprovalRead
+from app.schemas.board_memory import BoardMemoryRead
+from app.schemas.boards import BoardRead
+from app.schemas.tasks import TaskRead
+
+
+class TaskCardRead(TaskRead):
+    assignee: str | None = None
+    approvals_count: int = 0
+    approvals_pending_count: int = 0
+
+
+class BoardSnapshot(SQLModel):
+    board: BoardRead
+    tasks: list[TaskCardRead]
+    agents: list[AgentRead]
+    approvals: list[ApprovalRead]
+    chat_messages: list[BoardMemoryRead]
+    pending_approvals_count: int = 0
--- a/backend/app/services/board_snapshot.py
+++ b/backend/app/services/board_snapshot.py
@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from datetime import timedelta
+from uuid import UUID
+
+from sqlalchemy import case, func
+from sqlmodel import col, select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from app.core.time import utcnow
+from app.models.agents import Agent
+from app.models.approvals import Approval
+from app.models.board_memory import BoardMemory
+from app.models.boards import Board
+from app.models.gateways import Gateway
+from app.models.tasks import Task
+from app.schemas.agents import AgentRead
+from app.schemas.approvals import ApprovalRead
+from app.schemas.board_memory import BoardMemoryRead
+from app.schemas.boards import BoardRead
+from app.schemas.view_models import BoardSnapshot, TaskCardRead
+
+OFFLINE_AFTER = timedelta(minutes=10)
+
+
+def _computed_agent_status(agent: Agent) -> str:
+    now = utcnow()
+    if agent.status in {"deleting", "updating"}:
+        return agent.status
+    if agent.last_seen_at is None:
+        return "provisioning"
+    if now - agent.last_seen_at > OFFLINE_AFTER:
+        return "offline"
+    return agent.status
+
+
+async def _gateway_main_session_keys(session: AsyncSession) -> set[str]:
+    keys = (await session.exec(select(Gateway.main_session_key))).all()
+    return {key for key in keys if key}
+
+
+def _agent_to_read(agent: Agent, main_session_keys: set[str]) -> AgentRead:
+    model = AgentRead.model_validate(agent, from_attributes=True)
+    computed_status = _computed_agent_status(agent)
+    is_gateway_main = bool(agent.openclaw_session_id and agent.openclaw_session_id in main_session_keys)
+    return model.model_copy(update={"status": computed_status, "is_gateway_main": is_gateway_main})
+
+
+def _memory_to_read(memory: BoardMemory) -> BoardMemoryRead:
+    return BoardMemoryRead.model_validate(memory, from_attributes=True)
+
+
+def _approval_to_read(approval: Approval) -> ApprovalRead:
+    return ApprovalRead.model_validate(approval, from_attributes=True)
+
+
+def _task_to_card(
+    task: Task,
+    *,
+    agent_name_by_id: dict[UUID, str],
+    counts_by_task_id: dict[UUID, tuple[int, int]],
+) -> TaskCardRead:
+    card = TaskCardRead.model_validate(task, from_attributes=True)
+    approvals_count, approvals_pending_count = counts_by_task_id.get(task.id, (0, 0))
+    assignee = (
+        agent_name_by_id.get(task.assigned_agent_id) if task.assigned_agent_id is not None else None
+    )
+    return card.model_copy(
+        update={
+            "assignee": assignee,
+            "approvals_count": approvals_count,
+            "approvals_pending_count": approvals_pending_count,
+        }
+    )
+
+
+async def build_board_snapshot(session: AsyncSession, board: Board) -> BoardSnapshot:
+    board_read = BoardRead.model_validate(board, from_attributes=True)
+
+    tasks = list(
+        await session.exec(
+            select(Task).where(col(Task.board_id) == board.id).order_by(col(Task.created_at).desc())
+        )
+    )
+
+    main_session_keys = await _gateway_main_session_keys(session)
+    agents = list(
+        await session.exec(
+            select(Agent).where(col(Agent.board_id) == board.id).order_by(col(Agent.created_at).desc())
+        )
+    )
+    agent_reads = [_agent_to_read(agent, main_session_keys) for agent in agents]
+    agent_name_by_id = {agent.id: agent.name for agent in agents}
+
+    pending_approvals_count = int(
+        (await session.exec(
+            select(func.count(col(Approval.id)))
+            .where(col(Approval.board_id) == board.id)
+            .where(col(Approval.status) == "pending")
+        )).one()
+    )
+
+    approvals = list(
+        await session.exec(
+            select(Approval)
+            .where(col(Approval.board_id) == board.id)
+            .order_by(col(Approval.created_at).desc())
+            .limit(200)
+        )
+    )
+    approval_reads = [_approval_to_read(approval) for approval in approvals]
+
+    counts_by_task_id: dict[UUID, tuple[int, int]] = {}
+    rows = list(
+        await session.exec(
+            select(
+                col(Approval.task_id),
+                func.count(col(Approval.id)).label("total"),
+                func.sum(case((col(Approval.status) == "pending", 1), else_=0)).label("pending"),
+            )
+            .where(col(Approval.board_id) == board.id)
+            .where(col(Approval.task_id).is_not(None))
+            .group_by(col(Approval.task_id))
+        )
+    )
+    for task_id, total, pending in rows:
+        if task_id is None:
+            continue
+        counts_by_task_id[task_id] = (int(total or 0), int(pending or 0))
+
+    task_cards = [
+        _task_to_card(task, agent_name_by_id=agent_name_by_id, counts_by_task_id=counts_by_task_id)
+        for task in tasks
+    ]
+
+    chat_messages = list(
+        await session.exec(
+            select(BoardMemory)
+            .where(col(BoardMemory.board_id) == board.id)
+            .where(col(BoardMemory.is_chat).is_(True))
+            # Old/invalid rows (empty/whitespace-only content) can exist; exclude them to
+            # satisfy the NonEmptyStr response schema.
+            .where(func.length(func.trim(col(BoardMemory.content))) > 0)
+            .order_by(col(BoardMemory.created_at).desc())
+            .limit(200)
+        )
+    )
+    chat_messages.sort(key=lambda item: item.created_at)
+    chat_reads = [_memory_to_read(memory) for memory in chat_messages]
+
+    return BoardSnapshot(
+        board=board_read,
+        tasks=task_cards,
+        agents=agent_reads,
+        approvals=approval_reads,
+        chat_messages=chat_reads,
+        pending_approvals_count=pending_approvals_count,
+    )
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@@ -12,7 +12,7 @@ name = "openclaw-agency-backend"
 version = "0.1.0"
 requires-python = ">=3.12"
 dependencies = [
-  "fastapi==0.115.4",
+  "fastapi==0.128.0",
  "uvicorn[standard]==0.30.6",
  "sqlmodel==0.0.22",
  "sqlalchemy==2.0.34",
@@ -25,7 +25,8 @@ dependencies = [
  "redis==5.1.1",
  "fastapi-clerk-auth==0.0.9",
  "sse-starlette==2.1.3",
-  "jinja2"
+  "jinja2==3.1.6",
+  "fastapi-pagination==0.15.9",
 ]

 [project.optional-dependencies]
--- a/backend/requirements-dev.txt
+++ b/backend/requirements-dev.txt
@@ -1,4 +0,0 @@
-pytest==8.3.3
-pytest-asyncio==0.24.0
-ruff==0.6.9
-mypy==1.11.2
--- a/backend/requirements.txt
+++ b/backend/requirements.txt
@@ -1,14 +0,0 @@
-fastapi==0.115.4
-uvicorn[standard]==0.30.6
-sqlmodel==0.0.22
-sqlalchemy==2.0.34
-alembic==1.13.2
-psycopg[binary]==3.2.1
-pydantic-settings==2.5.2
-python-dotenv==1.0.1
-websockets==12.0
-rq==1.16.2
-redis==5.1.1
-fastapi-clerk-auth==0.0.9
-sse-starlette==2.1.3
-jinja2==3.1.6
--- a/backend/uv.lock
+++ b/backend/uv.lock
@@ -16,6 +16,15 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/df/ed/c884465c33c25451e4a5cd4acad154c29e5341e3214e220e7f3478aa4b0d/alembic-1.13.2-py3-none-any.whl", hash = "sha256:6b8733129a6224a9a711e17c99b08462dbf7cc9670ba8f2e2ae9af860ceb1953", size = 232990, upload-time = "2024-06-26T15:46:21.088Z" },
 ]

+[[package]]
+name = "annotated-doc"
+version = "0.0.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/57/ba/046ceea27344560984e26a590f90bc7f4a75b06701f653222458922b558c/annotated_doc-0.0.4.tar.gz", hash = "sha256:fbcda96e87e9c92ad167c2e53839e57503ecfda18804ea28102353485033faa4", size = 7288, upload-time = "2025-11-10T22:07:42.062Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/d3/26bf1008eb3d2daa8ef4cacc7f3bfdc11818d111f7e2d0201bc6e3b49d45/annotated_doc-0.0.4-py3-none-any.whl", hash = "sha256:571ac1dc6991c450b25a9c2d84a3705e2ae7a53467b5d111c24fa8baabbed320", size = 5303, upload-time = "2025-11-10T22:07:40.673Z" },
+]
+
 [[package]]
 name = "annotated-types"
 version = "0.7.0"
@@ -177,16 +186,17 @@ wheels = [

 [[package]]
 name = "fastapi"
-version = "0.115.4"
+version = "0.128.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
+    { name = "annotated-doc" },
    { name = "pydantic" },
    { name = "starlette" },
    { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/a9/db/5781f19bd30745885e0737ff3fdd4e63e7bc691710f9da691128bb0dc73b/fastapi-0.115.4.tar.gz", hash = "sha256:db653475586b091cb8b2fec2ac54a680ac6a158e07406e1abae31679e8826349", size = 300737, upload-time = "2024-10-27T22:02:04.678Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/52/08/8c8508db6c7b9aae8f7175046af41baad690771c9bcde676419965e338c7/fastapi-0.128.0.tar.gz", hash = "sha256:1cc179e1cef10a6be60ffe429f79b829dce99d8de32d7acb7e6c8dfdf7f2645a", size = 365682, upload-time = "2025-12-27T15:21:13.714Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/99/f6/af0d1f58f86002be0cf1e2665cdd6f7a4a71cdc8a7a9438cdc9e3b5375fe/fastapi-0.115.4-py3-none-any.whl", hash = "sha256:0b504a063ffb3cf96a5e27dc1bc32c80ca743a2528574f9cdc77daa2d31b4742", size = 94732, upload-time = "2024-10-27T22:02:00.974Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/05/5cbb59154b093548acd0f4c7c474a118eda06da25aa75c616b72d8fcd92a/fastapi-0.128.0-py3-none-any.whl", hash = "sha256:aebd93f9716ee3b4f4fcfe13ffb7cf308d99c9f3ab5622d8877441072561582d", size = 103094, upload-time = "2025-12-27T15:21:12.154Z" },
 ]

 [[package]]
@@ -203,6 +213,20 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/79/4e/058ecbe4fa0d470c3979f1272c0199cc47afb0ed935edb07b55441be8994/fastapi_clerk_auth-0.0.9-py3-none-any.whl", hash = "sha256:f9a47cfc65a2562c144a798ce0022a288799dac1149001b5a109865d578b2647", size = 6464, upload-time = "2025-11-11T06:12:35.655Z" },
 ]

+[[package]]
+name = "fastapi-pagination"
+version = "0.15.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "fastapi" },
+    { name = "pydantic" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/48/4b/057fea634912ba285e71fa9b65594c9cc90f589ad25ccbdc7549202c12a2/fastapi_pagination-0.15.9.tar.gz", hash = "sha256:e24b0419a6077a75f38970ada2a57e277845fb177cc2da7300374ee8be32e8b5", size = 574790, upload-time = "2026-02-02T18:29:20.863Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c8/7e/7d1a66b618309ef3d1d969ccab187a8c09444e6eb8d3abcd3bc12f145578/fastapi_pagination-0.15.9-py3-none-any.whl", hash = "sha256:21f5ab465fb75e21a3454234603071711b679b1973ba2428e7a63db2221abc09", size = 60100, upload-time = "2026-02-02T18:29:19.363Z" },
+]
+
 [[package]]
 name = "flake8"
 version = "7.1.1"
@@ -226,7 +250,6 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/f9/c8/9d76a66421d1ae24340dfae7e79c313957f6e3195c144d2c73333b5bfe34/greenlet-3.3.1-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:7e806ca53acf6d15a888405880766ec84721aa4181261cd11a457dfe9a7a4975", size = 276443, upload-time = "2026-01-23T15:30:10.066Z" },
    { url = "https://files.pythonhosted.org/packages/81/99/401ff34bb3c032d1f10477d199724f5e5f6fbfb59816ad1455c79c1eb8e7/greenlet-3.3.1-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d842c94b9155f1c9b3058036c24ffb8ff78b428414a19792b2380be9cecf4f36", size = 597359, upload-time = "2026-01-23T16:00:57.394Z" },
    { url = "https://files.pythonhosted.org/packages/2b/bc/4dcc0871ed557792d304f50be0f7487a14e017952ec689effe2180a6ff35/greenlet-3.3.1-cp312-cp312-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:20fedaadd422fa02695f82093f9a98bad3dab5fcda793c658b945fcde2ab27ba", size = 607805, upload-time = "2026-01-23T16:05:28.068Z" },
-    { url = "https://files.pythonhosted.org/packages/3b/cd/7a7ca57588dac3389e97f7c9521cb6641fd8b6602faf1eaa4188384757df/greenlet-3.3.1-cp312-cp312-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c620051669fd04ac6b60ebc70478210119c56e2d5d5df848baec4312e260e4ca", size = 622363, upload-time = "2026-01-23T16:15:54.754Z" },
    { url = "https://files.pythonhosted.org/packages/cf/05/821587cf19e2ce1f2b24945d890b164401e5085f9d09cbd969b0c193cd20/greenlet-3.3.1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:14194f5f4305800ff329cbf02c5fcc88f01886cadd29941b807668a45f0d2336", size = 609947, upload-time = "2026-01-23T15:32:51.004Z" },
    { url = "https://files.pythonhosted.org/packages/a4/52/ee8c46ed9f8babaa93a19e577f26e3d28a519feac6350ed6f25f1afee7e9/greenlet-3.3.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:7b2fe4150a0cf59f847a67db8c155ac36aed89080a6a639e9f16df5d6c6096f1", size = 1567487, upload-time = "2026-01-23T16:04:22.125Z" },
    { url = "https://files.pythonhosted.org/packages/8f/7c/456a74f07029597626f3a6db71b273a3632aecb9afafeeca452cfa633197/greenlet-3.3.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:49f4ad195d45f4a66a0eb9c1ba4832bb380570d361912fa3554746830d332149", size = 1636087, upload-time = "2026-01-23T15:33:47.486Z" },
@@ -235,7 +258,6 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/ec/ab/d26750f2b7242c2b90ea2ad71de70cfcd73a948a49513188a0fc0d6fc15a/greenlet-3.3.1-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:7ab327905cabb0622adca5971e488064e35115430cec2c35a50fd36e72a315b3", size = 275205, upload-time = "2026-01-23T15:30:24.556Z" },
    { url = "https://files.pythonhosted.org/packages/10/d3/be7d19e8fad7c5a78eeefb2d896a08cd4643e1e90c605c4be3b46264998f/greenlet-3.3.1-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:65be2f026ca6a176f88fb935ee23c18333ccea97048076aef4db1ef5bc0713ac", size = 599284, upload-time = "2026-01-23T16:00:58.584Z" },
    { url = "https://files.pythonhosted.org/packages/ae/21/fe703aaa056fdb0f17e5afd4b5c80195bbdab701208918938bd15b00d39b/greenlet-3.3.1-cp313-cp313-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7a3ae05b3d225b4155bda56b072ceb09d05e974bc74be6c3fc15463cf69f33fd", size = 610274, upload-time = "2026-01-23T16:05:29.312Z" },
-    { url = "https://files.pythonhosted.org/packages/06/00/95df0b6a935103c0452dad2203f5be8377e551b8466a29650c4c5a5af6cc/greenlet-3.3.1-cp313-cp313-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:12184c61e5d64268a160226fb4818af4df02cfead8379d7f8b99a56c3a54ff3e", size = 624375, upload-time = "2026-01-23T16:15:55.915Z" },
    { url = "https://files.pythonhosted.org/packages/cb/86/5c6ab23bb3c28c21ed6bebad006515cfe08b04613eb105ca0041fecca852/greenlet-3.3.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6423481193bbbe871313de5fd06a082f2649e7ce6e08015d2a76c1e9186ca5b3", size = 612904, upload-time = "2026-01-23T15:32:52.317Z" },
    { url = "https://files.pythonhosted.org/packages/c2/f3/7949994264e22639e40718c2daf6f6df5169bf48fb038c008a489ec53a50/greenlet-3.3.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:33a956fe78bbbda82bfc95e128d61129b32d66bcf0a20a1f0c08aa4839ffa951", size = 1567316, upload-time = "2026-01-23T16:04:23.316Z" },
    { url = "https://files.pythonhosted.org/packages/8d/6e/d73c94d13b6465e9f7cd6231c68abde838bb22408596c05d9059830b7872/greenlet-3.3.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:4b065d3284be43728dd280f6f9a13990b56470b81be20375a207cdc814a983f2", size = 1636549, upload-time = "2026-01-23T15:33:48.643Z" },
@@ -244,7 +266,6 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/ae/fb/011c7c717213182caf78084a9bea51c8590b0afda98001f69d9f853a495b/greenlet-3.3.1-cp314-cp314-macosx_11_0_universal2.whl", hash = "sha256:bd59acd8529b372775cd0fcbc5f420ae20681c5b045ce25bd453ed8455ab99b5", size = 275737, upload-time = "2026-01-23T15:32:16.889Z" },
    { url = "https://files.pythonhosted.org/packages/41/2e/a3a417d620363fdbb08a48b1dd582956a46a61bf8fd27ee8164f9dfe87c2/greenlet-3.3.1-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b31c05dd84ef6871dd47120386aed35323c944d86c3d91a17c4b8d23df62f15b", size = 646422, upload-time = "2026-01-23T16:01:00.354Z" },
    { url = "https://files.pythonhosted.org/packages/b4/09/c6c4a0db47defafd2d6bab8ddfe47ad19963b4e30f5bed84d75328059f8c/greenlet-3.3.1-cp314-cp314-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:02925a0bfffc41e542c70aa14c7eda3593e4d7e274bfcccca1827e6c0875902e", size = 658219, upload-time = "2026-01-23T16:05:30.956Z" },
-    { url = "https://files.pythonhosted.org/packages/e2/89/b95f2ddcc5f3c2bc09c8ee8d77be312df7f9e7175703ab780f2014a0e781/greenlet-3.3.1-cp314-cp314-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:3e0f3878ca3a3ff63ab4ea478585942b53df66ddde327b59ecb191b19dbbd62d", size = 671455, upload-time = "2026-01-23T16:15:57.232Z" },
    { url = "https://files.pythonhosted.org/packages/80/38/9d42d60dffb04b45f03dbab9430898352dba277758640751dc5cc316c521/greenlet-3.3.1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:34a729e2e4e4ffe9ae2408d5ecaf12f944853f40ad724929b7585bca808a9d6f", size = 660237, upload-time = "2026-01-23T15:32:53.967Z" },
    { url = "https://files.pythonhosted.org/packages/96/61/373c30b7197f9e756e4c81ae90a8d55dc3598c17673f91f4d31c3c689c3f/greenlet-3.3.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:aec9ab04e82918e623415947921dea15851b152b822661cce3f8e4393c3df683", size = 1615261, upload-time = "2026-01-23T16:04:25.066Z" },
    { url = "https://files.pythonhosted.org/packages/fd/d3/ca534310343f5945316f9451e953dcd89b36fe7a19de652a1dc5a0eeef3f/greenlet-3.3.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:71c767cf281a80d02b6c1bdc41c9468e1f5a494fb11bc8688c360524e273d7b1", size = 1683719, upload-time = "2026-01-23T15:33:50.61Z" },
@@ -253,7 +274,6 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/28/24/cbbec49bacdcc9ec652a81d3efef7b59f326697e7edf6ed775a5e08e54c2/greenlet-3.3.1-cp314-cp314t-macosx_11_0_universal2.whl", hash = "sha256:3e63252943c921b90abb035ebe9de832c436401d9c45f262d80e2d06cc659242", size = 282706, upload-time = "2026-01-23T15:33:05.525Z" },
    { url = "https://files.pythonhosted.org/packages/86/2e/4f2b9323c144c4fe8842a4e0d92121465485c3c2c5b9e9b30a52e80f523f/greenlet-3.3.1-cp314-cp314t-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:76e39058e68eb125de10c92524573924e827927df5d3891fbc97bd55764a8774", size = 651209, upload-time = "2026-01-23T16:01:01.517Z" },
    { url = "https://files.pythonhosted.org/packages/d9/87/50ca60e515f5bb55a2fbc5f0c9b5b156de7d2fc51a0a69abc9d23914a237/greenlet-3.3.1-cp314-cp314t-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:c9f9d5e7a9310b7a2f416dd13d2e3fd8b42d803968ea580b7c0f322ccb389b97", size = 654300, upload-time = "2026-01-23T16:05:32.199Z" },
-    { url = "https://files.pythonhosted.org/packages/7c/25/c51a63f3f463171e09cb586eb64db0861eb06667ab01a7968371a24c4f3b/greenlet-3.3.1-cp314-cp314t-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:4b9721549a95db96689458a1e0ae32412ca18776ed004463df3a9299c1b257ab", size = 662574, upload-time = "2026-01-23T16:15:58.364Z" },
    { url = "https://files.pythonhosted.org/packages/1d/94/74310866dfa2b73dd08659a3d18762f83985ad3281901ba0ee9a815194fb/greenlet-3.3.1-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:92497c78adf3ac703b57f1e3813c2d874f27f71a178f9ea5887855da413cd6d2", size = 653842, upload-time = "2026-01-23T15:32:55.671Z" },
    { url = "https://files.pythonhosted.org/packages/97/43/8bf0ffa3d498eeee4c58c212a3905dd6146c01c8dc0b0a046481ca29b18c/greenlet-3.3.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:ed6b402bc74d6557a705e197d47f9063733091ed6357b3de33619d8a8d93ac53", size = 1614917, upload-time = "2026-01-23T16:04:26.276Z" },
    { url = "https://files.pythonhosted.org/packages/89/90/a3be7a5f378fc6e84abe4dcfb2ba32b07786861172e502388b4c90000d1b/greenlet-3.3.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:59913f1e5ada20fde795ba906916aea25d442abcc0593fba7e26c92b7ad76249", size = 1676092, upload-time = "2026-01-23T15:33:52.176Z" },
@@ -456,6 +476,7 @@ dependencies = [
    { name = "alembic" },
    { name = "fastapi" },
    { name = "fastapi-clerk-auth" },
+    { name = "fastapi-pagination" },
    { name = "jinja2" },
    { name = "psycopg", extra = ["binary"] },
    { name = "pydantic-settings" },
@@ -484,11 +505,12 @@ dev = [
 requires-dist = [
    { name = "alembic", specifier = "==1.13.2" },
    { name = "black", marker = "extra == 'dev'", specifier = "==24.10.0" },
-    { name = "fastapi", specifier = "==0.115.4" },
+    { name = "fastapi", specifier = "==0.128.0" },
    { name = "fastapi-clerk-auth", specifier = "==0.0.9" },
+    { name = "fastapi-pagination", specifier = "==0.15.9" },
    { name = "flake8", marker = "extra == 'dev'", specifier = "==7.1.1" },
    { name = "isort", marker = "extra == 'dev'", specifier = "==5.13.2" },
-    { name = "jinja2" },
+    { name = "jinja2", specifier = "==3.1.6" },
    { name = "mypy", marker = "extra == 'dev'", specifier = "==1.11.2" },
    { name = "psycopg", extras = ["binary"], specifier = "==3.2.1" },
    { name = "pydantic-settings", specifier = "==2.5.2" },