gora-cli 0.1.2__py3-none-any.whl

gora/store.py

@@ -0,0 +1,935 @@
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+import re
+import sqlite3
+import sys
+from typing import Iterable
+
+from .parsers import ChatMessage, ChatSession, is_image_reference_text, is_title_noise_text
+
+
+PARSER_VERSION = 2
+DEFAULT_ROLES: tuple[str, ...] | None = None
+
+
+def default_db_path() -> Path:
+    override = os.environ.get("GORA_DB")
+    if override:
+        return Path(override).expanduser()
+
+    xdg_data_home = os.environ.get("XDG_DATA_HOME")
+    if xdg_data_home:
+        return Path(xdg_data_home).expanduser() / "gora" / "history.sqlite"
+
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "gora" / "history.sqlite"
+
+    return Path.home() / ".local" / "share" / "gora" / "history.sqlite"
+
+
+def connect(db_path: Path | None = None) -> sqlite3.Connection:
+    path = db_path or default_db_path()
+    _prepare_db_path(path, secure_parent=db_path is None and not os.environ.get("GORA_DB"))
+    connection = sqlite3.connect(path)
+    connection.row_factory = sqlite3.Row
+    init_db(connection)
+    _secure_sqlite_files(path)
+    return connection
+
+
+def _prepare_db_path(path: Path, *, secure_parent: bool) -> None:
+    if secure_parent:
+        path.parent.mkdir(parents=True, mode=0o700, exist_ok=True)
+        _chmod(path.parent, 0o700)
+    else:
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+    if path.exists():
+        _chmod(path, 0o600)
+        return
+
+    descriptor = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    os.close(descriptor)
+
+
+def _secure_sqlite_files(path: Path) -> None:
+    for candidate in (path, path.with_name(f"{path.name}-journal"), path.with_name(f"{path.name}-wal"), path.with_name(f"{path.name}-shm")):
+        if candidate.exists():
+            _chmod(candidate, 0o600)
+
+
+def _chmod(path: Path, mode: int) -> None:
+    try:
+        path.chmod(mode)
+    except OSError:
+        pass
+
+
+def init_db(connection: sqlite3.Connection) -> None:
+    connection.execute("PRAGMA foreign_keys = ON")
+    connection.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS sessions (
+            session_key TEXT PRIMARY KEY,
+            provider TEXT NOT NULL,
+            session_id TEXT NOT NULL,
+            source_path TEXT NOT NULL UNIQUE,
+            parent_session_key TEXT,
+            parent_session_id TEXT,
+            thread_source TEXT,
+            source_label TEXT,
+            parser_version INTEGER NOT NULL DEFAULT 2,
+            cwd TEXT,
+            title TEXT,
+            started_at TEXT,
+            updated_at TEXT,
+            message_count INTEGER NOT NULL DEFAULT 0,
+            source_mtime REAL NOT NULL,
+            source_size INTEGER NOT NULL,
+            imported_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+        );
+
+        CREATE TABLE IF NOT EXISTS messages (
+            message_key TEXT PRIMARY KEY,
+            session_key TEXT NOT NULL REFERENCES sessions(session_key) ON DELETE CASCADE,
+            provider TEXT NOT NULL,
+            role TEXT NOT NULL,
+            timestamp TEXT,
+            ordinal INTEGER NOT NULL,
+            raw_type TEXT,
+            model TEXT,
+            model_provider TEXT,
+            text TEXT NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS session_models (
+            session_key TEXT NOT NULL REFERENCES sessions(session_key) ON DELETE CASCADE,
+            model TEXT NOT NULL,
+            model_provider TEXT NOT NULL DEFAULT '',
+            message_count INTEGER NOT NULL DEFAULT 0,
+            PRIMARY KEY (session_key, model, model_provider)
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_sessions_provider_updated
+            ON sessions(provider, updated_at DESC);
+        CREATE INDEX IF NOT EXISTS idx_sessions_cwd
+            ON sessions(cwd);
+        CREATE INDEX IF NOT EXISTS idx_messages_session_ordinal
+            ON messages(session_key, ordinal);
+        CREATE INDEX IF NOT EXISTS idx_messages_role
+            ON messages(role);
+        CREATE INDEX IF NOT EXISTS idx_session_models_model
+            ON session_models(model, model_provider);
+        """
+    )
+    connection.execute(
+        """
+        CREATE VIRTUAL TABLE IF NOT EXISTS message_fts
+        USING fts5(
+            text,
+            message_key UNINDEXED,
+            session_key UNINDEXED,
+            provider UNINDEXED,
+            role UNINDEXED,
+            cwd UNINDEXED,
+            tokenize='unicode61'
+        )
+        """
+    )
+    _migrate_db(connection)
+    connection.commit()
+
+
+def _migrate_db(connection: sqlite3.Connection) -> None:
+    session_columns = {
+        row["name"]
+        for row in connection.execute("PRAGMA table_info(sessions)")
+    }
+    for column in ("parent_session_key", "parent_session_id", "thread_source", "source_label"):
+        if column not in session_columns:
+            connection.execute(f"ALTER TABLE sessions ADD COLUMN {column} TEXT")
+    if "parser_version" not in session_columns:
+        connection.execute("ALTER TABLE sessions ADD COLUMN parser_version INTEGER NOT NULL DEFAULT 0")
+
+    message_columns = {
+        row["name"]
+        for row in connection.execute("PRAGMA table_info(messages)")
+    }
+    if "model" not in message_columns:
+        connection.execute("ALTER TABLE messages ADD COLUMN model TEXT")
+    if "model_provider" not in message_columns:
+        connection.execute("ALTER TABLE messages ADD COLUMN model_provider TEXT")
+
+    connection.execute(
+        """
+        CREATE TABLE IF NOT EXISTS session_models (
+            session_key TEXT NOT NULL REFERENCES sessions(session_key) ON DELETE CASCADE,
+            model TEXT NOT NULL,
+            model_provider TEXT NOT NULL DEFAULT '',
+            message_count INTEGER NOT NULL DEFAULT 0,
+            PRIMARY KEY (session_key, model, model_provider)
+        )
+        """
+    )
+    connection.execute(
+        "CREATE INDEX IF NOT EXISTS idx_messages_model ON messages(model)"
+    )
+    connection.execute(
+        "CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_key)"
+    )
+    connection.execute(
+        "CREATE INDEX IF NOT EXISTS idx_session_models_model ON session_models(model, model_provider)"
+    )
+
+
+def upsert_session(
+    connection: sqlite3.Connection,
+    session: ChatSession,
+    *,
+    force: bool = False,
+) -> bool:
+    source_path = str(session.source_path)
+    existing = connection.execute(
+        """
+        SELECT *
+        FROM sessions
+        WHERE source_path = ?
+        """,
+        (source_path,),
+    ).fetchone()
+    if (
+        existing
+        and not force
+        and existing["source_mtime"] == session.source_mtime
+        and existing["source_size"] == session.source_size
+        and existing["parser_version"] == PARSER_VERSION
+        and _session_metadata_matches(existing, session)
+        and _merged_title(existing["title"], session.title) == existing["title"]
+    ):
+        return False
+
+    with connection:
+        if not existing:
+            session_key = choose_session_key(connection, session)
+            _insert_session(connection, session_key, session)
+            _insert_messages(connection, session_key, session.messages, cwd=session.cwd, start_ordinal=0)
+            _refresh_session_models(connection, session_key)
+            return True
+
+        changed = _merge_session(connection, existing, session)
+    return changed > 0
+
+
+def source_is_current(connection: sqlite3.Connection, source_path: Path) -> bool:
+    try:
+        stat = source_path.stat()
+    except OSError:
+        return False
+    existing = connection.execute(
+        """
+        SELECT source_mtime, source_size, parser_version
+        FROM sessions
+        WHERE source_path = ?
+        """,
+        (str(source_path),),
+    ).fetchone()
+    return bool(
+        existing
+        and existing["source_mtime"] == stat.st_mtime
+        and existing["source_size"] == stat.st_size
+        and existing["parser_version"] == PARSER_VERSION
+    )
+
+
+def _insert_session(connection: sqlite3.Connection, session_key: str, session: ChatSession) -> None:
+    connection.execute(
+        """
+        INSERT INTO sessions (
+            session_key, provider, session_id, source_path,
+            parent_session_key, parent_session_id, thread_source, source_label,
+            parser_version, cwd, title,
+            started_at, updated_at, message_count, source_mtime, source_size
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            session_key,
+            session.provider,
+            session.session_id,
+            str(session.source_path),
+            parent_session_key(session),
+            session.parent_session_id,
+            session.thread_source,
+            session.source_label,
+            PARSER_VERSION,
+            session.cwd,
+            session.title,
+            session.started_at,
+            session.updated_at,
+            len(session.messages),
+            session.source_mtime,
+            session.source_size,
+        ),
+    )
+
+
+def _merge_session(
+    connection: sqlite3.Connection,
+    existing: sqlite3.Row,
+    session: ChatSession,
+) -> int:
+    session_key = existing["session_key"]
+    existing_rows = list(
+        connection.execute(
+            """
+            SELECT message_key, role, timestamp, text, ordinal, model, model_provider
+            FROM messages
+            WHERE session_key = ?
+            ORDER BY ordinal ASC
+            """,
+            (session_key,),
+        )
+    )
+    existing_by_fingerprint: dict[str, list[sqlite3.Row]] = {}
+    for row in existing_rows:
+        fingerprint = _message_fingerprint(row["role"], row["timestamp"], row["text"])
+        existing_by_fingerprint.setdefault(fingerprint, []).append(row)
+
+    new_messages: list[ChatMessage] = []
+    updated = 0
+    for message in session.messages:
+        fingerprint = _message_fingerprint(message.role, message.timestamp, message.text)
+        if existing_by_fingerprint.get(fingerprint):
+            existing_row = existing_by_fingerprint[fingerprint].pop(0)
+            updated += _update_message_metadata(connection, existing_row, message)
+            continue
+        new_messages.append(message)
+
+    start_ordinal = max((row["ordinal"] for row in existing_rows), default=-1) + 1
+    _insert_messages(connection, session_key, new_messages, cwd=session.cwd, start_ordinal=start_ordinal)
+    metadata_updated = _update_session_metadata(connection, existing, session)
+    if new_messages or updated:
+        _refresh_session_models(connection, session_key)
+    return len(new_messages) + updated + metadata_updated
+
+
+def _insert_messages(
+    connection: sqlite3.Connection,
+    session_key: str,
+    messages: Iterable[ChatMessage],
+    *,
+    cwd: str | None,
+    start_ordinal: int,
+) -> None:
+    message_rows: list[tuple[object, ...]] = []
+    fts_rows: list[tuple[object, ...]] = []
+    for offset, message in enumerate(messages):
+        ordinal = start_ordinal + offset
+        message_key = f"{session_key}:{ordinal}"
+        provider = session_key.split(":", 1)[0]
+        message_rows.append(
+            (
+                message_key,
+                session_key,
+                provider,
+                message.role,
+                message.timestamp,
+                ordinal,
+                message.raw_type,
+                message.model,
+                message.model_provider,
+                message.text,
+            )
+        )
+        fts_rows.append(
+            (
+                message.text,
+                message_key,
+                session_key,
+                provider,
+                message.role,
+                cwd,
+            )
+        )
+
+    if not message_rows:
+        return
+
+    connection.executemany(
+        """
+        INSERT INTO messages (
+            message_key, session_key, provider, role, timestamp,
+            ordinal, raw_type, model, model_provider, text
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        message_rows,
+    )
+    connection.executemany(
+        """
+        INSERT INTO message_fts (
+            text, message_key, session_key, provider, role, cwd
+        )
+        VALUES (?, ?, ?, ?, ?, ?)
+        """,
+        fts_rows,
+    )
+
+
+def _update_message_metadata(
+    connection: sqlite3.Connection,
+    row: sqlite3.Row,
+    message: ChatMessage,
+) -> int:
+    updates: list[str] = []
+    params: list[object] = []
+    if message.model and row["model"] != message.model:
+        updates.append("model = ?")
+        params.append(message.model)
+    if message.model_provider and row["model_provider"] != message.model_provider:
+        updates.append("model_provider = ?")
+        params.append(message.model_provider)
+    if not updates:
+        return 0
+
+    params.append(row["message_key"])
+    connection.execute(
+        f"""
+        UPDATE messages
+        SET {", ".join(updates)}
+        WHERE message_key = ?
+        """,
+        params,
+    )
+    return 1
+
+
+def _refresh_session_models(connection: sqlite3.Connection, session_key: str) -> None:
+    connection.execute("DELETE FROM session_models WHERE session_key = ?", (session_key,))
+    connection.execute(
+        """
+        INSERT INTO session_models (session_key, model, model_provider, message_count)
+        SELECT session_key, model, COALESCE(model_provider, ''), COUNT(*) AS message_count
+        FROM messages
+        WHERE session_key = ?
+          AND model IS NOT NULL
+          AND model != ''
+        GROUP BY session_key, model, COALESCE(model_provider, '')
+        """,
+        (session_key,),
+    )
+
+
+def _update_session_metadata(
+    connection: sqlite3.Connection,
+    existing: sqlite3.Row,
+    session: ChatSession,
+) -> int:
+    message_count = int(
+        connection.execute(
+            "SELECT COUNT(*) AS count FROM messages WHERE session_key = ?",
+            (existing["session_key"],),
+        ).fetchone()["count"]
+    )
+    title = _merged_title(existing["title"], session.title)
+    connection.execute(
+        """
+        UPDATE sessions
+        SET cwd = ?,
+            title = ?,
+            parent_session_key = ?,
+            parent_session_id = ?,
+            thread_source = ?,
+            source_label = ?,
+            parser_version = ?,
+            started_at = ?,
+            updated_at = ?,
+            message_count = ?,
+            source_mtime = ?,
+            source_size = ?,
+            imported_at = CURRENT_TIMESTAMP
+        WHERE session_key = ?
+        """,
+        (
+            session.cwd or existing["cwd"],
+            title,
+            parent_session_key(session),
+            session.parent_session_id,
+            session.thread_source,
+            session.source_label,
+            PARSER_VERSION,
+            _earlier_time(existing["started_at"], session.started_at),
+            _later_time(existing["updated_at"], session.updated_at),
+            message_count,
+            session.source_mtime,
+            session.source_size,
+            existing["session_key"],
+        ),
+    )
+    changed = (
+        title != existing["title"]
+        or existing["parent_session_key"] != parent_session_key(session)
+        or existing["parent_session_id"] != session.parent_session_id
+        or existing["thread_source"] != session.thread_source
+        or existing["source_label"] != session.source_label
+        or existing["parser_version"] != PARSER_VERSION
+    )
+    return 1 if changed else 0
+
+
+def _session_metadata_matches(existing: sqlite3.Row, session: ChatSession) -> bool:
+    return (
+        existing["parent_session_key"] == parent_session_key(session)
+        and existing["parent_session_id"] == session.parent_session_id
+        and existing["thread_source"] == session.thread_source
+        and existing["source_label"] == session.source_label
+    )
+
+
+def _merged_title(existing_title: str | None, parsed_title: str | None) -> str | None:
+    if parsed_title and not is_title_noise_text(parsed_title):
+        if not existing_title or is_title_noise_text(existing_title) or is_image_reference_text(existing_title):
+            return parsed_title
+    if existing_title and not is_title_noise_text(existing_title) and not is_image_reference_text(existing_title):
+        return existing_title
+    return parsed_title
+
+
+def _message_fingerprint(role: str, timestamp: str | None, text: str) -> str:
+    digest = hashlib.sha1()
+    digest.update(role.encode("utf-8", errors="replace"))
+    digest.update(b"\0")
+    digest.update((timestamp or "").encode("utf-8", errors="replace"))
+    digest.update(b"\0")
+    digest.update(text.encode("utf-8", errors="replace"))
+    return digest.hexdigest()
+
+
+def _earlier_time(left: str | None, right: str | None) -> str | None:
+    if not left:
+        return right
+    if not right:
+        return left
+    return min(left, right)
+
+
+def _later_time(left: str | None, right: str | None) -> str | None:
+    if not left:
+        return right
+    if not right:
+        return left
+    return max(left, right)
+
+
+def list_sessions(
+    connection: sqlite3.Connection,
+    *,
+    providers: Iterable[str] | None = None,
+    cwd: str | None = None,
+    models: Iterable[str] | None = None,
+    include_children: bool = False,
+    limit: int = 20,
+) -> list[sqlite3.Row]:
+    where, params = _session_filters(
+        providers=providers,
+        cwd=cwd,
+        models=models,
+        include_children=include_children,
+    )
+    params.append(limit)
+    return list(
+        connection.execute(
+            f"""
+            SELECT s.*,
+                   (
+                       SELECT GROUP_CONCAT(model)
+                       FROM (
+                           SELECT DISTINCT model
+                           FROM session_models sm
+                           WHERE sm.session_key = s.session_key
+                           ORDER BY model
+                       )
+                   ) AS models
+            FROM sessions s
+            {where}
+            ORDER BY COALESCE(s.updated_at, s.started_at, s.imported_at) DESC
+            LIMIT ?
+            """,
+            params,
+        )
+    )
+
+
+def search_messages(
+    connection: sqlite3.Connection,
+    query: str,
+    *,
+    providers: Iterable[str] | None = None,
+    cwd: str | None = None,
+    models: Iterable[str] | None = None,
+    roles: Iterable[str] | None = DEFAULT_ROLES,
+    include_children: bool = False,
+    limit: int = 20,
+) -> list[sqlite3.Row]:
+    provider_values = tuple(providers or ())
+    role_values = tuple(roles or ())
+    filters: list[str] = []
+    params: list[object] = [to_fts_query(query)]
+
+    if provider_values:
+        filters.append(_in_clause("m.provider", provider_values, params))
+    if role_values:
+        filters.append(_in_clause("m.role", role_values, params))
+    if cwd:
+        filters.append("s.cwd LIKE ?")
+        params.append(f"%{cwd}%")
+    if not include_children:
+        filters.append(_root_session_filter("s"))
+    _append_model_filter(filters, params, models, session_column="m.session_key")
+
+    where = ""
+    if filters:
+        where = "AND " + " AND ".join(filters)
+
+    params.append(limit)
+    try:
+        return list(
+            connection.execute(
+                f"""
+                SELECT
+                    m.message_key, m.session_key, m.provider, m.role, m.timestamp,
+                    m.ordinal, m.model, m.model_provider, m.text,
+                    s.session_id, s.cwd, s.title, s.source_path,
+                    s.parent_session_key, s.parent_session_id, s.thread_source, s.source_label,
+                    (
+                        SELECT GROUP_CONCAT(model)
+                        FROM (
+                            SELECT DISTINCT model
+                            FROM session_models sm
+                            WHERE sm.session_key = m.session_key
+                            ORDER BY model
+                        )
+                    ) AS models,
+                    snippet(message_fts, 0, '[', ']', '...', 18) AS snippet
+                FROM message_fts
+                JOIN messages m ON m.message_key = message_fts.message_key
+                JOIN sessions s ON s.session_key = m.session_key
+                WHERE message_fts MATCH ?
+                {where}
+                ORDER BY bm25(message_fts), COALESCE(m.timestamp, s.updated_at) DESC
+                LIMIT ?
+                """,
+                params,
+            )
+        )
+    except sqlite3.OperationalError:
+        return _like_search(
+            connection,
+            query,
+            providers=provider_values,
+            cwd=cwd,
+            models=tuple(models or ()),
+            roles=role_values,
+            include_children=include_children,
+            limit=limit,
+        )
+
+
+def get_session_messages(
+    connection: sqlite3.Connection,
+    session_ref: str,
+    *,
+    roles: Iterable[str] | None = DEFAULT_ROLES,
+) -> tuple[sqlite3.Row, list[sqlite3.Row]]:
+    candidates = list(
+        connection.execute(
+            """
+            SELECT *
+            FROM sessions
+            WHERE session_key = ?
+               OR session_id = ?
+               OR session_key LIKE ?
+               OR session_id LIKE ?
+            ORDER BY updated_at DESC
+            LIMIT 5
+            """,
+            (session_ref, session_ref, f"{session_ref}%", f"{session_ref}%"),
+        )
+    )
+    if not candidates:
+        raise LookupError(f"no session matched {session_ref!r}")
+    if len(candidates) > 1:
+        names = ", ".join(row["session_key"] for row in candidates)
+        raise LookupError(f"ambiguous session reference {session_ref!r}: {names}")
+
+    session = candidates[0]
+    params: list[object] = [session["session_key"]]
+    role_values = tuple(roles or ())
+    role_sql = ""
+    if role_values:
+        role_sql = "AND " + _in_clause("role", role_values, params)
+
+    messages = list(
+        connection.execute(
+            f"""
+            SELECT *
+            FROM messages
+            WHERE session_key = ?
+            {role_sql}
+            ORDER BY
+                CASE WHEN timestamp IS NULL OR timestamp = '' THEN 1 ELSE 0 END,
+                timestamp ASC,
+                ordinal ASC
+            """,
+            params,
+        )
+    )
+    return session, messages
+
+
+def provider_counts(connection: sqlite3.Connection) -> dict[str, int]:
+    return {
+        row["provider"]: row["count"]
+        for row in connection.execute(
+            "SELECT provider, COUNT(*) AS count FROM sessions GROUP BY provider ORDER BY provider"
+        )
+    }
+
+
+def model_counts(connection: sqlite3.Connection) -> list[sqlite3.Row]:
+    return list(
+        connection.execute(
+            """
+            SELECT model,
+                   model_provider,
+                   COUNT(DISTINCT session_key) AS sessions,
+                   SUM(message_count) AS messages
+            FROM session_models
+            GROUP BY model, model_provider
+            ORDER BY sessions DESC, messages DESC, model ASC, model_provider ASC
+            """
+        )
+    )
+
+
+def repo_counts(
+    connection: sqlite3.Connection,
+    *,
+    providers: Iterable[str] | None = None,
+    models: Iterable[str] | None = None,
+    include_children: bool = False,
+    limit: int = 20,
+) -> list[sqlite3.Row]:
+    filters = ["s.cwd IS NOT NULL", "s.cwd != ''"]
+    params: list[object] = []
+
+    provider_values = tuple(providers or ())
+    if provider_values:
+        filters.append(_in_clause("s.provider", provider_values, params))
+    if not include_children:
+        filters.append(_root_session_filter("s"))
+    _append_model_filter(filters, params, models, session_column="s.session_key")
+
+    params.append(limit)
+    return list(
+        connection.execute(
+            f"""
+            WITH filtered_sessions AS (
+                SELECT s.*
+                FROM sessions s
+                WHERE {" AND ".join(filters)}
+            )
+            SELECT fs.cwd,
+                   COUNT(DISTINCT fs.session_key) AS sessions,
+                   (
+                       SELECT GROUP_CONCAT(provider)
+                       FROM (
+                           SELECT DISTINCT fs_provider.provider
+                           FROM filtered_sessions fs_provider
+                           WHERE fs_provider.cwd = fs.cwd
+                           ORDER BY fs_provider.provider
+                       )
+                   ) AS providers,
+                   (
+                       SELECT GROUP_CONCAT(model)
+                       FROM (
+                           SELECT DISTINCT sm.model
+                           FROM session_models sm
+                           JOIN filtered_sessions fs_model ON fs_model.session_key = sm.session_key
+                           WHERE fs_model.cwd = fs.cwd
+                           ORDER BY sm.model
+                       )
+                   ) AS models,
+                   MAX(COALESCE(fs.updated_at, fs.started_at, fs.imported_at)) AS updated_at
+            FROM filtered_sessions fs
+            GROUP BY fs.cwd
+            ORDER BY sessions DESC, updated_at DESC, fs.cwd ASC
+            LIMIT ?
+            """,
+            params,
+        )
+    )
+
+
+def make_session_key(provider: str, session_id: str) -> str:
+    return f"{provider}:{session_id}"
+
+
+def parent_session_key(session: ChatSession) -> str | None:
+    if not session.parent_session_id:
+        return None
+    return make_session_key(session.provider, session.parent_session_id)
+
+
+def choose_session_key(connection: sqlite3.Connection, session: ChatSession) -> str:
+    base_key = make_session_key(session.provider, session.session_id)
+    existing = connection.execute(
+        "SELECT source_path FROM sessions WHERE session_key = ?",
+        (base_key,),
+    ).fetchone()
+    if not existing or existing["source_path"] == str(session.source_path):
+        return base_key
+
+    digest = hashlib.sha1(str(session.source_path).encode("utf-8")).hexdigest()[:10]
+    return f"{base_key}:{digest}"
+
+
+def to_fts_query(query: str) -> str:
+    terms = [term for term in re.findall(r'"[^"]+"|\S+', query) if term.strip()]
+    if not terms:
+        return '""'
+
+    escaped: list[str] = []
+    for term in terms:
+        term = term.strip()
+        if term.startswith('"') and term.endswith('"') and len(term) > 1:
+            term = term[1:-1]
+        term = term.replace('"', '""')
+        escaped.append(f'"{term}"')
+    return " AND ".join(escaped)
+
+
+def _like_search(
+    connection: sqlite3.Connection,
+    query: str,
+    *,
+    providers: Iterable[str],
+    cwd: str | None,
+    models: Iterable[str],
+    roles: Iterable[str],
+    include_children: bool,
+    limit: int,
+) -> list[sqlite3.Row]:
+    filters = ["m.text LIKE ?"]
+    params: list[object] = [f"%{query}%"]
+
+    provider_values = tuple(providers)
+    if provider_values:
+        filters.append(_in_clause("m.provider", provider_values, params))
+
+    role_values = tuple(roles)
+    if role_values:
+        filters.append(_in_clause("m.role", role_values, params))
+
+    if cwd:
+        filters.append("s.cwd LIKE ?")
+        params.append(f"%{cwd}%")
+    if not include_children:
+        filters.append(_root_session_filter("s"))
+    _append_model_filter(filters, params, models, session_column="m.session_key")
+
+    params.append(limit)
+    return list(
+        connection.execute(
+            f"""
+            SELECT
+                m.message_key, m.session_key, m.provider, m.role, m.timestamp,
+                m.ordinal, m.model, m.model_provider, m.text,
+                s.session_id, s.cwd, s.title, s.source_path,
+                s.parent_session_key, s.parent_session_id, s.thread_source, s.source_label,
+                (
+                    SELECT GROUP_CONCAT(model)
+                    FROM (
+                        SELECT DISTINCT model
+                        FROM session_models sm
+                        WHERE sm.session_key = m.session_key
+                        ORDER BY model
+                    )
+                ) AS models,
+                m.text AS snippet
+            FROM messages m
+            JOIN sessions s ON s.session_key = m.session_key
+            WHERE {" AND ".join(filters)}
+            ORDER BY COALESCE(m.timestamp, s.updated_at) DESC
+            LIMIT ?
+            """,
+            params,
+        )
+    )
+
+
+def _session_filters(
+    *,
+    providers: Iterable[str] | None,
+    cwd: str | None,
+    models: Iterable[str] | None,
+    include_children: bool,
+) -> tuple[str, list[object]]:
+    filters: list[str] = []
+    params: list[object] = []
+
+    provider_values = tuple(providers or ())
+    if provider_values:
+        filters.append(_in_clause("s.provider", provider_values, params))
+    if cwd:
+        filters.append("s.cwd LIKE ?")
+        params.append(f"%{cwd}%")
+    if not include_children:
+        filters.append(_root_session_filter("s"))
+    _append_model_filter(filters, params, models, session_column="s.session_key")
+
+    if not filters:
+        return "", params
+    return "WHERE " + " AND ".join(filters), params
+
+
+def _root_session_filter(alias: str) -> str:
+    return f"({alias}.parent_session_key IS NULL OR {alias}.parent_session_key = '')"
+
+
+def _append_model_filter(
+    filters: list[str],
+    params: list[object],
+    models: Iterable[str] | None,
+    *,
+    session_column: str,
+) -> None:
+    model_values = tuple(model for model in (models or ()) if model)
+    if not model_values:
+        return
+
+    model_params: list[object] = []
+    clause = _in_clause("sm_filter.model", model_values, model_params)
+    params.extend(model_params)
+    filters.append(
+        f"""
+        EXISTS (
+            SELECT 1
+            FROM session_models sm_filter
+            WHERE sm_filter.session_key = {session_column}
+              AND {clause}
+        )
+        """
+    )
+
+
+def _in_clause(column: str, values: Iterable[str], params: list[object]) -> str:
+    clean_values = tuple(value for value in values if value)
+    if not clean_values:
+        return "1 = 1"
+    params.extend(clean_values)
+    placeholders = ", ".join("?" for _ in clean_values)
+    return f"{column} IN ({placeholders})"