remdb 0.3.180__py3-none-any.whl → 0.3.258__py3-none-any.whl

rem/services/session/pydantic_messages.py

@@ -0,0 +1,310 @@
+"""Convert stored session messages to pydantic-ai native message format.
+
+This module enables proper conversation history replay by converting our simplified
+storage format into pydantic-ai's native ModelRequest/ModelResponse types.
+
+Key insight: When we store tool results, we only store the result (ToolReturnPart).
+But LLM APIs require matching ToolCallPart for each ToolReturnPart. So we synthesize
+the ToolCallPart from stored metadata (tool_name, tool_call_id) and arguments.
+
+Tool arguments can come from two places:
+- Parent tool calls (ask_agent): tool_arguments stored in metadata (content = result)
+- Child tool calls (register_metadata): arguments parsed from content (content = args as JSON)
+
+Storage format (our simplified format):
+    {"role": "user", "content": "..."}
+    {"role": "assistant", "content": "..."}
+    {"role": "tool", "content": "{...}", "tool_name": "...", "tool_call_id": "...", "tool_arguments": {...}}  # optional
+
+Pydantic-ai format (what the LLM expects):
+    ModelRequest(parts=[UserPromptPart(content="...")])
+    ModelResponse(parts=[TextPart(content="..."), ToolCallPart(...)])  # Call
+    ModelRequest(parts=[ToolReturnPart(...)])  # Result
+
+Example usage:
+    from rem.services.session.pydantic_messages import session_to_pydantic_messages
+
+    # Load session history
+    session_history = await store.load_session_messages(session_id)
+
+    # Convert to pydantic-ai format
+    message_history = session_to_pydantic_messages(session_history)
+
+    # Use with agent.run()
+    result = await agent.run(user_prompt, message_history=message_history)
+"""
+
+import json
+import re
+from typing import Any
+
+from loguru import logger
+from pydantic_ai.messages import (
+    ModelMessage,
+    ModelRequest,
+    ModelResponse,
+    SystemPromptPart,
+    TextPart,
+    ToolCallPart,
+    ToolReturnPart,
+    UserPromptPart,
+)
+
+
+def _sanitize_tool_name(tool_name: str) -> str:
+    """Sanitize tool name for OpenAI API compatibility.
+
+    OpenAI requires tool names to match pattern: ^[a-zA-Z0-9_-]+$
+    This replaces invalid characters (like colons) with underscores.
+    """
+    return re.sub(r'[^a-zA-Z0-9_-]', '_', tool_name)
+
+
+def session_to_pydantic_messages(
+    session_history: list[dict[str, Any]],
+    system_prompt: str | None = None,
+) -> list[ModelMessage]:
+    """Convert stored session messages to pydantic-ai ModelMessage format.
+
+    Handles the conversion of our simplified storage format to pydantic-ai's
+    native message types, including synthesizing ToolCallPart for tool results.
+
+    IMPORTANT: pydantic-ai only auto-adds system prompts when message_history is empty.
+    When passing message_history to agent.run(), you MUST include the system prompt
+    via the system_prompt parameter here.
+
+    Args:
+        session_history: List of message dicts from SessionMessageStore.load_session_messages()
+            Each dict has: role, content, and optionally tool_name, tool_call_id, tool_arguments
+        system_prompt: The agent's system prompt (from schema description). This is REQUIRED
+            for proper agent behavior on subsequent turns, as pydantic-ai won't add it
+            automatically when message_history is provided.
+
+    Returns:
+        List of ModelMessage (ModelRequest | ModelResponse) ready for agent.run(message_history=...)
+
+    Note:
+        - System prompts ARE included as SystemPromptPart when system_prompt is provided
+        - Tool results require synthesized ToolCallPart to satisfy LLM API requirements
+        - The first message in session_history should be "user" role (from context builder)
+    """
+    messages: list[ModelMessage] = []
+
+    # CRITICAL: Prepend agent's system prompt if provided
+    # This ensures the agent's instructions are present on every turn
+    # pydantic-ai only auto-adds system prompts when message_history is empty
+    if system_prompt:
+        messages.append(ModelRequest(parts=[SystemPromptPart(content=system_prompt)]))
+        logger.debug(f"Prepended agent system prompt ({len(system_prompt)} chars) to message history")
+
+    # Track pending tool results to batch them with assistant responses
+    # When we see a tool message, we need to:
+    # 1. Add a ModelResponse with ToolCallPart (synthesized)
+    # 2. Add a ModelRequest with ToolReturnPart (actual result)
+
+    i = 0
+    while i < len(session_history):
+        msg = session_history[i]
+        role = msg.get("role", "")
+        content = msg.get("content") or ""
+
+        if role == "user":
+            # User messages become ModelRequest with UserPromptPart
+            messages.append(ModelRequest(parts=[UserPromptPart(content=content)]))
+
+        elif role == "assistant":
+            # Assistant text becomes ModelResponse with TextPart
+            # Check if there are following tool messages that should be grouped
+            tool_calls = []
+            tool_returns = []
+
+            # Look ahead for tool messages that follow this assistant message
+            j = i + 1
+            while j < len(session_history) and session_history[j].get("role") == "tool":
+                tool_msg = session_history[j]
+                tool_name = tool_msg.get("tool_name", "unknown_tool")
+                tool_call_id = tool_msg.get("tool_call_id", f"call_{j}")
+                tool_content = tool_msg.get("content") or "{}"
+
+                # tool_arguments: prefer explicit field, fallback to parsing content
+                tool_arguments = tool_msg.get("tool_arguments")
+                if tool_arguments is None and isinstance(tool_content, str) and tool_content:
+                    try:
+                        tool_arguments = json.loads(tool_content)
+                    except json.JSONDecodeError:
+                        tool_arguments = {}
+
+                # Parse tool content if it's a JSON string
+                if isinstance(tool_content, str):
+                    try:
+                        tool_result = json.loads(tool_content)
+                    except json.JSONDecodeError:
+                        tool_result = {"raw": tool_content}
+                else:
+                    tool_result = tool_content
+
+                # Sanitize tool name for OpenAI API compatibility
+                safe_tool_name = _sanitize_tool_name(tool_name)
+
+                # Synthesize ToolCallPart (what the model "called")
+                tool_calls.append(ToolCallPart(
+                    tool_name=safe_tool_name,
+                    args=tool_arguments if tool_arguments else {},
+                    tool_call_id=tool_call_id,
+                ))
+
+                # Create ToolReturnPart (the actual result)
+                tool_returns.append(ToolReturnPart(
+                    tool_name=safe_tool_name,
+                    content=tool_result,
+                    tool_call_id=tool_call_id,
+                ))
+
+                j += 1
+
+            # Build the assistant's ModelResponse
+            response_parts = []
+
+            # Add tool calls first (if any)
+            response_parts.extend(tool_calls)
+
+            # Add text content (if any)
+            if content:
+                response_parts.append(TextPart(content=content))
+
+            # Only add ModelResponse if we have parts
+            if response_parts:
+                messages.append(ModelResponse(
+                    parts=response_parts,
+                    model_name="recovered",  # We don't store model name
+                ))
+
+            # Add tool returns as ModelRequest (required by LLM API)
+            if tool_returns:
+                messages.append(ModelRequest(parts=tool_returns))
+
+            # Skip the tool messages we just processed
+            i = j - 1
+
+        elif role == "tool":
+            # Orphan tool message (no preceding assistant) - synthesize both parts
+            tool_name = msg.get("tool_name", "unknown_tool")
+            tool_call_id = msg.get("tool_call_id", f"call_{i}")
+            tool_content = msg.get("content") or "{}"
+
+            # tool_arguments: prefer explicit field, fallback to parsing content
+            tool_arguments = msg.get("tool_arguments")
+            if tool_arguments is None and isinstance(tool_content, str) and tool_content:
+                try:
+                    tool_arguments = json.loads(tool_content)
+                except json.JSONDecodeError:
+                    tool_arguments = {}
+
+            # Parse tool content
+            if isinstance(tool_content, str):
+                try:
+                    tool_result = json.loads(tool_content)
+                except json.JSONDecodeError:
+                    tool_result = {"raw": tool_content}
+            else:
+                tool_result = tool_content
+
+            # Sanitize tool name for OpenAI API compatibility
+            safe_tool_name = _sanitize_tool_name(tool_name)
+
+            # Synthesize the tool call (ModelResponse with ToolCallPart)
+            messages.append(ModelResponse(
+                parts=[ToolCallPart(
+                    tool_name=safe_tool_name,
+                    args=tool_arguments if tool_arguments else {},
+                    tool_call_id=tool_call_id,
+                )],
+                model_name="recovered",
+            ))
+
+            # Add the tool return (ModelRequest with ToolReturnPart)
+            messages.append(ModelRequest(
+                parts=[ToolReturnPart(
+                    tool_name=safe_tool_name,
+                    content=tool_result,
+                    tool_call_id=tool_call_id,
+                )]
+            ))
+
+        elif role == "system":
+            # Skip system messages - pydantic-ai handles these via Agent.system_prompt
+            logger.debug("Skipping system message in session history (handled by Agent)")
+
+        else:
+            logger.warning(f"Unknown message role in session history: {role}")
+
+        i += 1
+
+    logger.debug(f"Converted {len(session_history)} stored messages to {len(messages)} pydantic-ai messages")
+    return messages
+
+
+def audit_session_history(
+    session_id: str,
+    agent_name: str,
+    prompt: str,
+    raw_session_history: list[dict[str, Any]],
+    pydantic_messages_count: int,
+) -> None:
+    """
+    Dump session history to a YAML file for debugging.
+
+    Only runs when DEBUG__AUDIT_SESSION=true. Writes to DEBUG__AUDIT_DIR (default /tmp).
+    Appends to the same file for a session, so all agent invocations are in one place.
+
+    Args:
+        session_id: The session identifier
+        agent_name: Name of the agent being invoked
+        prompt: The prompt being sent to the agent
+        raw_session_history: The raw session messages from the database
+        pydantic_messages_count: Count of converted pydantic-ai messages
+    """
+    from ...settings import settings
+
+    if not settings.debug.audit_session:
+        return
+
+    try:
+        import yaml
+        from pathlib import Path
+        from ...utils.date_utils import utc_now, to_iso
+
+        audit_dir = Path(settings.debug.audit_dir)
+        audit_dir.mkdir(parents=True, exist_ok=True)
+        audit_file = audit_dir / f"{session_id}.yaml"
+
+        # Create entry for this agent invocation
+        entry = {
+            "timestamp": to_iso(utc_now()),
+            "agent_name": agent_name,
+            "prompt": prompt,
+            "raw_history_count": len(raw_session_history),
+            "pydantic_messages_count": pydantic_messages_count,
+            "raw_session_history": raw_session_history,
+        }
+
+        # Load existing data or create new
+        existing_data: dict[str, Any] = {"session_id": session_id, "invocations": []}
+        if audit_file.exists():
+            with open(audit_file) as f:
+                loaded = yaml.safe_load(f)
+                if loaded:
+                    # Ensure session_id is always present (backfill if missing)
+                    existing_data = {
+                        "session_id": loaded.get("session_id", session_id),
+                        "invocations": loaded.get("invocations", []),
+                    }
+
+        # Append this invocation
+        existing_data["invocations"].append(entry)
+
+        with open(audit_file, "w") as f:
+            yaml.dump(existing_data, f, default_flow_style=False, allow_unicode=True)
+        logger.info(f"DEBUG: Session audit updated: {audit_file}")
+    except Exception as e:
+        logger.warning(f"DEBUG: Failed to dump session audit: {e}")

rem/services/session/reload.py

@@ -12,7 +12,8 @@ Design Pattern:
 
 Message Types on Reload:
 - user: Returned as-is
-- tool: Returned as-is with metadata (tool_call_id, tool_name, tool_arguments)
+- tool: Returned with metadata (tool_call_id, tool_name). tool_arguments may be in
+  metadata (parent calls) or parsed from content (child calls) by pydantic_messages.py
 - assistant: Compressed on load if long (>400 chars), with REM LOOKUP for recovery
 """
 

rem/settings.py

@@ -424,6 +424,49 @@ class AuthSettings(BaseSettings):
     google: GoogleOAuthSettings = Field(default_factory=GoogleOAuthSettings)
     microsoft: MicrosoftOAuthSettings = Field(default_factory=MicrosoftOAuthSettings)
 
+    # Pre-approved login codes (bypass email verification)
+    # Format: comma-separated codes with prefix A=admin, B=normal user
+    # Example: "A12345,A67890,B11111,B22222"
+    preapproved_codes: str = Field(
+        default="",
+        description=(
+            "Comma-separated list of pre-approved login codes. "
+            "Prefix A = admin user, B = normal user. "
+            "Example: 'A12345,A67890,B11111'. "
+            "Users can login with these codes without email verification."
+        ),
+    )
+
+    def check_preapproved_code(self, code: str) -> dict | None:
+        """
+        Check if a code is in the pre-approved list.
+
+        Args:
+            code: The code to check (including prefix)
+
+        Returns:
+            Dict with 'role' key if valid, None if not found.
+            - A prefix -> role='admin'
+            - B prefix -> role='user'
+        """
+        if not self.preapproved_codes:
+            return None
+
+        codes = [c.strip().upper() for c in self.preapproved_codes.split(",") if c.strip()]
+        code_upper = code.strip().upper()
+
+        if code_upper not in codes:
+            return None
+
+        # Parse prefix to determine role
+        if code_upper.startswith("A"):
+            return {"role": "admin", "code": code_upper}
+        elif code_upper.startswith("B"):
+            return {"role": "user", "code": code_upper}
+        else:
+            # Unknown prefix, treat as user
+            return {"role": "user", "code": code_upper}
+
     @field_validator("session_secret", mode="before")
     @classmethod
     def generate_dev_secret(cls, v: str | None, info: ValidationInfo) -> str:
@@ -722,7 +765,7 @@ class DataLakeSettings(BaseSettings):
         │       └── cpt/                # CPT codes
         └── calibration/                # Agent calibration
             ├── experiments/            # Experiment configs + results
-            │   └── {agent}/{task}/     # e.g., siggy/risk-assessment
+            │   └── {agent}/{task}/     # e.g., rem/risk-assessment
             └── datasets/               # Shared evaluation datasets
 
     Experiment Storage:
@@ -1598,7 +1641,7 @@ class EmailSettings(BaseSettings):
             "Existing users can always login regardless of domain. "
             "New users must have an email from a trusted domain. "
             "Empty string means all domains are allowed. "
-            "Example: 'siggymd.ai,example.com'"
+            "Example: 'mycompany.com,example.com'"
         ),
     )
 
@@ -1651,6 +1694,33 @@ class EmailSettings(BaseSettings):
         return kwargs
 
 
+class DebugSettings(BaseSettings):
+    """
+    Debug settings for development and troubleshooting.
+
+    Environment variables:
+        DEBUG__AUDIT_SESSION - Dump session history to /tmp/{session_id}.yaml
+        DEBUG__AUDIT_DIR - Directory for session audit files (default: /tmp)
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="DEBUG__",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    audit_session: bool = Field(
+        default=False,
+        description="When true, dump full session history to audit files for debugging",
+    )
+
+    audit_dir: str = Field(
+        default="/tmp",
+        description="Directory for session audit files",
+    )
+
+
 class TestSettings(BaseSettings):
     """
     Test environment settings.
@@ -1767,16 +1837,31 @@ class Settings(BaseSettings):
     schema_search: SchemaSettings = Field(default_factory=SchemaSettings)
     email: EmailSettings = Field(default_factory=EmailSettings)
     test: TestSettings = Field(default_factory=TestSettings)
+    debug: DebugSettings = Field(default_factory=DebugSettings)
 
 
-# Auto-load .env file from current directory if it exists
-# This happens BEFORE config file loading, so .env takes precedence
+# Auto-load .env file from current directory or parent directories
+# This happens BEFORE config file loading, so .env takes precedence over shell env vars
 from pathlib import Path
 from dotenv import load_dotenv
 
-_dotenv_path = Path(".env")
-if _dotenv_path.exists():
-    load_dotenv(_dotenv_path, override=False)  # Don't override existing env vars
+
+def _find_dotenv() -> Path | None:
+    """Search for .env in current dir and up to 3 parent directories."""
+    current = Path.cwd()
+    for _ in range(4):  # Current + 3 parents
+        env_path = current / ".env"
+        if env_path.exists():
+            return env_path
+        if current.parent == current:  # Reached root
+            break
+        current = current.parent
+    return None
+
+
+_dotenv_path = _find_dotenv()
+if _dotenv_path:
+    load_dotenv(_dotenv_path, override=True)  # .env takes precedence over shell env vars
     logger.debug(f"Loaded environment from {_dotenv_path.resolve()}")
 
 # Load configuration from ~/.rem/config.yaml before initializing settings

rem/sql/migrations/001_install.sql

@@ -121,18 +121,18 @@ CREATE UNLOGGED TABLE IF NOT EXISTS kv_store (
     entity_key VARCHAR(255) NOT NULL,
     entity_type VARCHAR(100) NOT NULL,
     entity_id UUID NOT NULL,
-    tenant_id VARCHAR(100) NOT NULL,
+    tenant_id VARCHAR(100),  -- NULL = public/shared data
     user_id VARCHAR(100),
     content_summary TEXT,
     metadata JSONB DEFAULT '{}',
     graph_edges JSONB DEFAULT '[]'::jsonb,  -- Cached edges for fast graph traversal
     created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-
-    -- Composite primary key: entity_key unique per tenant
-    PRIMARY KEY (tenant_id, entity_key)
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
 );
 
+-- Unique constraint on (tenant_id, entity_key) using COALESCE to handle NULL tenant_id
+CREATE UNIQUE INDEX IF NOT EXISTS idx_kv_store_tenant_key ON kv_store (COALESCE(tenant_id, ''), entity_key);
+
 -- Index for user-scoped lookups (when user_id IS NOT NULL)
 CREATE INDEX IF NOT EXISTS idx_kv_store_user ON kv_store (tenant_id, user_id)
 WHERE user_id IS NOT NULL;
@@ -173,7 +173,7 @@ COMMENT ON COLUMN kv_store.entity_id IS
 'UUID from primary table for reverse lookup';
 
 COMMENT ON COLUMN kv_store.tenant_id IS
-'Tenant identifier for multi-tenancy isolation';
+'Tenant identifier for multi-tenancy isolation. NULL = public/shared data visible to all.';
 
 COMMENT ON COLUMN kv_store.user_id IS
 'Optional user scoping. NULL = system-level entity, visible to all users in tenant';
@@ -271,8 +271,12 @@ BEGIN
     AND kv.entity_key = normalize_key(p_entity_key)
     LIMIT 1;
 
-    -- If not found, return empty
+    -- If not found, check if cache is empty and maybe trigger rebuild
     IF entity_table IS NULL THEN
+        -- SELF-HEALING: Check if this is because cache is empty
+        IF rem_kv_store_empty(effective_user_id) THEN
+            PERFORM maybe_trigger_kv_rebuild(effective_user_id, 'rem_lookup');
+        END IF;
         RETURN;
     END IF;
 
@@ -357,6 +361,7 @@ DECLARE
     entities_by_table JSONB := '{}'::jsonb;
     table_keys JSONB;
     effective_user_id VARCHAR(100);
+    v_found_any BOOLEAN := FALSE;
 BEGIN
     effective_user_id := COALESCE(p_user_id, p_tenant_id);
 
@@ -373,6 +378,7 @@ BEGIN
         ORDER BY sim_score DESC
         LIMIT p_limit
     LOOP
+        v_found_any := TRUE;
         -- Build JSONB mapping {table: [keys]}
         IF entities_by_table ? kv_matches.entity_type THEN
             table_keys := entities_by_table->kv_matches.entity_type;
@@ -390,6 +396,11 @@ BEGIN
         END IF;
     END LOOP;
 
+    -- SELF-HEALING: If no matches and cache is empty, trigger rebuild
+    IF NOT v_found_any AND rem_kv_store_empty(effective_user_id) THEN
+        PERFORM maybe_trigger_kv_rebuild(effective_user_id, 'rem_fuzzy');
+    END IF;
+
     -- Fetch full records using rem_fetch (which now supports NULL user_id)
     RETURN QUERY
     SELECT
@@ -436,9 +447,25 @@ DECLARE
     entities_by_table JSONB := '{}'::jsonb;
     table_keys JSONB;
     effective_user_id VARCHAR(100);
+    v_found_start BOOLEAN := FALSE;
 BEGIN
     effective_user_id := COALESCE(p_user_id, p_tenant_id);
 
+    -- Check if start entity exists in kv_store
+    SELECT TRUE INTO v_found_start
+    FROM kv_store kv
+    WHERE (kv.user_id = effective_user_id OR kv.user_id IS NULL)
+    AND kv.entity_key = normalize_key(p_entity_key)
+    LIMIT 1;
+
+    -- SELF-HEALING: If start not found and cache is empty, trigger rebuild
+    IF NOT COALESCE(v_found_start, FALSE) THEN
+        IF rem_kv_store_empty(effective_user_id) THEN
+            PERFORM maybe_trigger_kv_rebuild(effective_user_id, 'rem_traverse');
+        END IF;
+        RETURN;
+    END IF;
+
     FOR graph_keys IN
         WITH RECURSIVE graph_traversal AS (
             -- Base case: Find starting entity (user-owned OR public)
@@ -789,6 +816,97 @@ $$ LANGUAGE plpgsql STABLE;
 COMMENT ON FUNCTION fn_get_shared_messages IS
 'Get messages from sessions shared by a specific user with the recipient.';
 
+-- ============================================================================
+-- SESSIONS WITH USER INFO
+-- ============================================================================
+-- Function to list sessions with user details (name, email) for admin views
+
+-- List sessions with user info, CTE pagination
+-- Note: messages.session_id stores the session UUID (sessions.id)
+CREATE OR REPLACE FUNCTION fn_list_sessions_with_user(
+    p_user_id VARCHAR(256) DEFAULT NULL,  -- Filter by user_id (NULL = all users, admin only)
+    p_user_name VARCHAR(256) DEFAULT NULL,  -- Filter by user name (partial match, admin only)
+    p_user_email VARCHAR(256) DEFAULT NULL,  -- Filter by user email (partial match, admin only)
+    p_mode VARCHAR(50) DEFAULT NULL,  -- Filter by session mode
+    p_page INTEGER DEFAULT 1,
+    p_page_size INTEGER DEFAULT 50
+)
+RETURNS TABLE(
+    id UUID,
+    name VARCHAR(256),
+    mode TEXT,
+    description TEXT,
+    user_id VARCHAR(256),
+    user_name VARCHAR(256),
+    user_email VARCHAR(256),
+    message_count INTEGER,
+    total_tokens INTEGER,
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP,
+    metadata JSONB,
+    total_count BIGINT
+) AS $$
+BEGIN
+    RETURN QUERY
+    WITH session_msg_counts AS (
+        -- Count messages per session (joining on session UUID)
+        SELECT
+            m.session_id,
+            COUNT(*)::INTEGER as actual_message_count
+        FROM messages m
+        GROUP BY m.session_id
+    ),
+    filtered_sessions AS (
+        SELECT
+            s.id,
+            s.name,
+            s.mode,
+            s.description,
+            s.user_id,
+            COALESCE(u.name, s.user_id)::VARCHAR(256) AS user_name,
+            u.email::VARCHAR(256) AS user_email,
+            COALESCE(mc.actual_message_count, 0) AS message_count,
+            s.total_tokens,
+            s.created_at,
+            s.updated_at,
+            s.metadata
+        FROM sessions s
+        LEFT JOIN users u ON u.id::text = s.user_id
+        LEFT JOIN session_msg_counts mc ON mc.session_id = s.id::text
+        WHERE s.deleted_at IS NULL
+          AND (p_user_id IS NULL OR s.user_id = p_user_id)
+          AND (p_user_name IS NULL OR u.name ILIKE '%' || p_user_name || '%')
+          AND (p_user_email IS NULL OR u.email ILIKE '%' || p_user_email || '%')
+          AND (p_mode IS NULL OR s.mode = p_mode)
+    ),
+    counted AS (
+        SELECT *, COUNT(*) OVER () AS total_count
+        FROM filtered_sessions
+    )
+    SELECT
+        c.id,
+        c.name,
+        c.mode,
+        c.description,
+        c.user_id,
+        c.user_name,
+        c.user_email,
+        c.message_count,
+        c.total_tokens,
+        c.created_at,
+        c.updated_at,
+        c.metadata,
+        c.total_count
+    FROM counted c
+    ORDER BY c.created_at DESC
+    LIMIT p_page_size
+    OFFSET (p_page - 1) * p_page_size;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+COMMENT ON FUNCTION fn_list_sessions_with_user IS
+'List sessions with user details and computed message counts. Joins messages on session name.';
+
 -- ============================================================================
 -- RECORD INSTALLATION
 -- ============================================================================