lcode-agent 0.1.0__py3-none-any.whl

lcode/store.py

@@ -0,0 +1,889 @@
+"""SQLite 会话存储:多轮上下文的真相来源。
+
+库文件默认在 ~/.lcode/lcode.db,不进仓库。
+思考只给界面看。发给模型的是摘要 + 近文,含工具调用和结果。
+改文件前打快照,/history 可回退项目。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import time
+import uuid
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+DB_PATH = Path.home() / ".lcode" / "lcode.db"
+
+# 模型窗口未知时的回退;真正阈值 = 窗口 * auto_compact 百分比
+DEFAULT_MODEL_WINDOW = 128_000
+DEFAULT_COMPACT_PERCENT = 85
+SUMMARY_BUDGET = 8_000
+
+
+def current_project_path() -> str:
+    """当前工作目录,用来按项目拆开上下文。"""
+    return str(Path.cwd().resolve())
+
+
+def _est_tokens(text: str) -> int:
+    if not text:
+        return 0
+    cjk = 0
+    other = 0
+    for ch in text:
+        if ord(ch) >= 0x2E80:
+            cjk += 1
+        else:
+            other += 1
+    return cjk + (other + 3) // 4
+
+
+CHECKPOINT_KEEP = 100
+SNAPSHOT_MAX_BYTES = 2_000_000
+
+
+@dataclass(frozen=True)
+class Message:
+    id: int
+    session_id: str
+    role: str
+    content: str
+    thinking: str
+    created_at: int
+    project_path: str = ""
+    meta: str = ""
+
+
+class Store:
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = path or DB_PATH
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(self.path, timeout=5)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("PRAGMA foreign_keys=ON")
+        self._init()
+        # 当前会话的内存副本:启动从库载入,之后只追加,请求走这份
+        self._session_id: str | None = None
+        self._messages: list[Message] = []
+        self._summary = ""
+        self._summarized_until = 0
+        self._project_path = ""
+        self.model_window = DEFAULT_MODEL_WINDOW
+        self.compact_percent = DEFAULT_COMPACT_PERCENT
+        self.compact_at = DEFAULT_MODEL_WINDOW * DEFAULT_COMPACT_PERCENT // 100
+        self.context_limit = self.compact_at
+
+    def set_context_limit(self, tokens: int) -> None:
+        self.apply_window(tokens, self.compact_percent)
+
+    def apply_window(self, context_length: int, percent: int = DEFAULT_COMPACT_PERCENT) -> None:
+        """和 Grok 一样:按模型窗口的百分比自动 compact,磁盘全文仍留着。"""
+        self.model_window = max(1024, int(context_length))
+        self.compact_percent = min(95, max(50, int(percent)))
+        self.compact_at = max(1024, self.model_window * self.compact_percent // 100)
+        self.context_limit = self.compact_at
+
+    def summary_budget(self) -> int:
+        cap = max(32, self.compact_at // 8)
+        return max(32, min(SUMMARY_BUDGET, cap))
+
+    def _init(self) -> None:
+        self._conn.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS session (
+              id         TEXT PRIMARY KEY,
+              created_at INTEGER NOT NULL,
+              updated_at INTEGER NOT NULL,
+              title      TEXT NOT NULL DEFAULT '',
+              summary    TEXT NOT NULL DEFAULT '',
+              summarized_until INTEGER NOT NULL DEFAULT 0,
+              project_path TEXT NOT NULL DEFAULT ''
+            );
+            CREATE TABLE IF NOT EXISTS message (
+              id         INTEGER PRIMARY KEY AUTOINCREMENT,
+              session_id TEXT NOT NULL,
+              role       TEXT NOT NULL,
+              content    TEXT NOT NULL,
+              thinking   TEXT NOT NULL DEFAULT '',
+              created_at INTEGER NOT NULL,
+              project_path TEXT NOT NULL DEFAULT '',
+              FOREIGN KEY (session_id) REFERENCES session(id)
+            );
+            CREATE INDEX IF NOT EXISTS idx_message_session
+              ON message(session_id, id);
+            CREATE TABLE IF NOT EXISTS checkpoint (
+              id         TEXT PRIMARY KEY,
+              session_id TEXT NOT NULL,
+              message_id INTEGER NOT NULL,
+              created_at INTEGER NOT NULL,
+              title      TEXT NOT NULL DEFAULT '',
+              FOREIGN KEY (session_id) REFERENCES session(id)
+            );
+            CREATE INDEX IF NOT EXISTS idx_checkpoint_session
+              ON checkpoint(session_id, message_id);
+            CREATE TABLE IF NOT EXISTS snapshot_file (
+              checkpoint_id TEXT NOT NULL,
+              relpath       TEXT NOT NULL,
+              existed       INTEGER NOT NULL,
+              blob_id       TEXT,
+              PRIMARY KEY (checkpoint_id, relpath)
+            );
+            CREATE TABLE IF NOT EXISTS snapshot_blob (
+              id      TEXT PRIMARY KEY,
+              content BLOB NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS todo (
+              project_path TEXT PRIMARY KEY,
+              data         TEXT NOT NULL DEFAULT '[]'
+            );
+            """
+        )
+        cols = {
+            str(row[1])
+            for row in self._conn.execute("PRAGMA table_info(session)").fetchall()
+        }
+        if "summary" not in cols:
+            self._conn.execute(
+                "ALTER TABLE session ADD COLUMN summary TEXT NOT NULL DEFAULT ''"
+            )
+        if "summarized_until" not in cols:
+            self._conn.execute(
+                "ALTER TABLE session ADD COLUMN summarized_until INTEGER NOT NULL DEFAULT 0"
+            )
+        if "project_path" not in cols:
+            self._conn.execute(
+                "ALTER TABLE session ADD COLUMN project_path TEXT NOT NULL DEFAULT ''"
+            )
+        # 每个 session 的 token 记账:重启后底部 ↑↓/cache 接着算,不再归零
+        for col in ("tokens_in", "tokens_out", "tokens_cache"):
+            if col not in cols:
+                self._conn.execute(
+                    f"ALTER TABLE session ADD COLUMN {col} INTEGER NOT NULL DEFAULT 0"
+                )
+        msg_cols = {
+            str(row[1])
+            for row in self._conn.execute("PRAGMA table_info(message)").fetchall()
+        }
+        if "project_path" not in msg_cols:
+            self._conn.execute(
+                "ALTER TABLE message ADD COLUMN project_path TEXT NOT NULL DEFAULT ''"
+            )
+        if "meta" not in msg_cols:
+            self._conn.execute(
+                "ALTER TABLE message ADD COLUMN meta TEXT NOT NULL DEFAULT ''"
+            )
+        self._conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_session_project ON session(project_path, updated_at)"
+        )
+        self._conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_message_project ON message(project_path, id)"
+        )
+        self._conn.commit()
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def create_session(self, project_path: str | None = None) -> str:
+        sid = uuid.uuid4().hex
+        now = int(time.time())
+        path = project_path or current_project_path()
+        self._conn.execute(
+            """
+            INSERT INTO session (id, created_at, updated_at, title, project_path)
+            VALUES (?, ?, ?, '', ?)
+            """,
+            (sid, now, now, path),
+        )
+        self._conn.commit()
+        self._project_path = path
+        self._attach(sid, [])
+        return sid
+
+    def latest_session(self) -> str | None:
+        row = self._conn.execute(
+            "SELECT id FROM session ORDER BY updated_at DESC, created_at DESC LIMIT 1"
+        ).fetchone()
+        return str(row["id"]) if row else None
+
+    def latest_for_project(self, project_path: str) -> str | None:
+        row = self._conn.execute(
+            """
+            SELECT id FROM session
+            WHERE project_path=?
+            ORDER BY updated_at DESC, created_at DESC
+            LIMIT 1
+            """,
+            (project_path,),
+        ).fetchone()
+        return str(row["id"]) if row else None
+
+    def open_or_create(self, project_path: str | None = None) -> str:
+        path = project_path or current_project_path()
+        sid = self.latest_for_project(path)
+        if not sid:
+            # 旧库没有项目路径时,把最近一次空路径会话认领到当前项目
+            row = self._conn.execute(
+                """
+                SELECT id FROM session
+                WHERE project_path='' OR project_path IS NULL
+                ORDER BY updated_at DESC, created_at DESC
+                LIMIT 1
+                """
+            ).fetchone()
+            if row:
+                sid = str(row["id"])
+                self._conn.execute(
+                    "UPDATE session SET project_path=? WHERE id=?",
+                    (path, sid),
+                )
+                self._conn.execute(
+                    """
+                    UPDATE message SET project_path=?
+                    WHERE session_id=? AND (project_path='' OR project_path IS NULL)
+                    """,
+                    (path, sid),
+                )
+                self._conn.commit()
+        if sid:
+            self._project_path = path
+            self._attach(sid, self._fetch_messages(sid))
+            return sid
+        return self.create_session(path)
+
+    def list_sessions_for_project(self, project_path: str | None = None) -> list[dict]:
+        path = project_path or self._project_path or current_project_path()
+        rows = self._conn.execute(
+            """
+            SELECT s.id, s.title, s.updated_at,
+                   (SELECT COUNT(*) FROM message m WHERE m.session_id=s.id) AS n
+            FROM session s
+            WHERE s.project_path=?
+            ORDER BY s.updated_at DESC, s.created_at DESC
+            """,
+            (path,),
+        ).fetchall()
+        return [
+            {
+                "id": str(r["id"]),
+                "title": str(r["title"] or ""),
+                "updated_at": int(r["updated_at"] or 0),
+                "n": int(r["n"] or 0),
+            }
+            for r in rows
+        ]
+
+    def switch_session(self, session_id: str) -> str:
+        row = self._conn.execute(
+            "SELECT id FROM session WHERE id=?", (session_id,)
+        ).fetchone()
+        if not row:
+            raise ValueError("窗口不存在")
+        self._attach(session_id, self._fetch_messages(session_id))
+        return session_id
+
+    def _attach(self, session_id: str, messages: list[Message]) -> None:
+        self._session_id = session_id
+        self._messages = list(messages)
+        self._summary = ""
+        self._summarized_until = 0
+        row = self._conn.execute(
+            "SELECT summary, summarized_until, project_path FROM session WHERE id=?",
+            (session_id,),
+        ).fetchone()
+        if row:
+            self._summary = str(row["summary"] or "")
+            self._summarized_until = int(row["summarized_until"] or 0)
+            path = str(row["project_path"] or "")
+            if path:
+                self._project_path = path
+
+    def add_usage(
+        self, session_id: str, tokens_in: int, tokens_out: int, tokens_cache: int
+    ) -> None:
+        """把这一轮的官方用量记到 session 上,重启后还在。"""
+        if not session_id or not (tokens_in or tokens_out or tokens_cache):
+            return
+        self._conn.execute(
+            """
+            UPDATE session
+            SET tokens_in=tokens_in+?, tokens_out=tokens_out+?,
+                tokens_cache=tokens_cache+?
+            WHERE id=?
+            """,
+            (
+                max(0, int(tokens_in)),
+                max(0, int(tokens_out)),
+                max(0, int(tokens_cache)),
+                session_id,
+            ),
+        )
+        self._conn.commit()
+
+    def usage_of(self, session_id: str) -> tuple[int, int, int]:
+        """(tokens_in, tokens_out, tokens_cache),没有就全 0。"""
+        if not session_id:
+            return 0, 0, 0
+        row = self._conn.execute(
+            "SELECT tokens_in, tokens_out, tokens_cache FROM session WHERE id=?",
+            (session_id,),
+        ).fetchone()
+        if not row:
+            return 0, 0, 0
+        return (
+            int(row["tokens_in"] or 0),
+            int(row["tokens_out"] or 0),
+            int(row["tokens_cache"] or 0),
+        )
+
+    def rename_session(self, session_id: str, title: str) -> None:
+        title = " ".join((title or "").strip().split())[:40]
+        if not title:
+            return
+        self._conn.execute(
+            "UPDATE session SET title=?, updated_at=? WHERE id=?",
+            (title, int(time.time()), session_id),
+        )
+        self._conn.commit()
+
+    def delete_session(self, session_id: str) -> None:
+        """删掉整个窗口:消息、检查点、快照文件一起清,blob 引用计数回收。"""
+        rows = self._conn.execute(
+            "SELECT id FROM checkpoint WHERE session_id=?", (session_id,)
+        ).fetchall()
+        for row in rows:
+            self._conn.execute(
+                "DELETE FROM snapshot_file WHERE checkpoint_id=?", (str(row["id"]),)
+            )
+        self._conn.execute("DELETE FROM checkpoint WHERE session_id=?", (session_id,))
+        self._conn.execute("DELETE FROM message WHERE session_id=?", (session_id,))
+        self._conn.execute("DELETE FROM session WHERE id=?", (session_id,))
+        self._gc_blobs()
+        self._conn.commit()
+        if session_id == self._session_id:
+            self._session_id = None
+            self._messages = []
+            self._summary = ""
+            self._summarized_until = 0
+
+    def save_todos(self, project_path: str, todos: list) -> None:
+        data = json.dumps(todos, ensure_ascii=False)
+        self._conn.execute(
+            "INSERT OR REPLACE INTO todo (project_path, data) VALUES (?, ?)",
+            (project_path, data),
+        )
+        self._conn.commit()
+
+    def load_todos(self, project_path: str) -> list:
+        row = self._conn.execute(
+            "SELECT data FROM todo WHERE project_path=?", (project_path,)
+        ).fetchone()
+        if not row:
+            return []
+        try:
+            data = json.loads(str(row["data"] or "[]"))
+        except (TypeError, json.JSONDecodeError):
+            return []
+        return data if isinstance(data, list) else []
+
+    def touch(self, session_id: str) -> None:
+        self._conn.execute(
+            "UPDATE session SET updated_at=? WHERE id=?",
+            (int(time.time()), session_id),
+        )
+        self._conn.commit()
+
+    def set_title_if_empty(self, session_id: str, text: str) -> None:
+        title = " ".join(text.strip().split())[:40]
+        if not title:
+            return
+        self._conn.execute(
+            "UPDATE session SET title=? WHERE id=? AND title=''",
+            (title, session_id),
+        )
+        self._conn.commit()
+
+    def add_message(
+        self,
+        session_id: str,
+        role: str,
+        content: str,
+        thinking: str = "",
+        meta: str | dict | None = "",
+    ) -> int:
+        now = int(time.time())
+        path = self._project_path or current_project_path()
+        if isinstance(meta, dict):
+            packed = json.dumps(meta, ensure_ascii=False)
+        else:
+            packed = str(meta or "")
+        cur = self._conn.execute(
+            """
+            INSERT INTO message
+              (session_id, role, content, thinking, created_at, project_path, meta)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+            (session_id, role, content, thinking, now, path, packed),
+        )
+        self._conn.execute(
+            "UPDATE session SET updated_at=? WHERE id=?",
+            (now, session_id),
+        )
+        self._conn.commit()
+        mid = int(cur.lastrowid)
+        msg = Message(
+            id=mid,
+            session_id=session_id,
+            role=role,
+            content=content,
+            thinking=thinking,
+            created_at=now,
+            project_path=path,
+            meta=packed,
+        )
+        if session_id == self._session_id:
+            self._messages.append(msg)
+        return mid
+
+    def _fetch_messages(self, session_id: str) -> list[Message]:
+        rows = self._conn.execute(
+            """
+            SELECT id, session_id, role, content, thinking, created_at, project_path, meta
+            FROM message
+            WHERE session_id=?
+            ORDER BY id
+            """,
+            (session_id,),
+        ).fetchall()
+        return [
+            Message(
+                id=int(r["id"]),
+                session_id=str(r["session_id"]),
+                role=str(r["role"]),
+                content=str(r["content"]),
+                thinking=str(r["thinking"]),
+                created_at=int(r["created_at"]),
+                project_path=str(r["project_path"] or ""),
+                meta=str(r["meta"] or ""),
+            )
+            for r in rows
+        ]
+
+    def merge_message_meta(self, session_id: str, message_id: int, patch: dict) -> None:
+        """往已有消息的 meta 里合并几个字段(如附加图片的文件名)。"""
+        row = self._conn.execute(
+            "SELECT meta FROM message WHERE id=? AND session_id=?",
+            (message_id, session_id),
+        ).fetchone()
+        if not row:
+            return
+        meta = _meta_dict(str(row["meta"] or ""))
+        meta.update(patch)
+        packed = json.dumps(meta, ensure_ascii=False)
+        self._conn.execute(
+            "UPDATE message SET meta=? WHERE id=?", (packed, message_id)
+        )
+        self._conn.commit()
+        if session_id == self._session_id:
+            for i, msg in enumerate(self._messages):
+                if msg.id == message_id:
+                    self._messages[i] = replace(msg, meta=packed)
+                    break
+
+    def list_messages(self, session_id: str) -> list[Message]:
+        if session_id == self._session_id:
+            return list(self._messages)
+        return self._fetch_messages(session_id)
+
+    def live_messages(self, session_id: str) -> list[Message]:
+        """还没折进摘要、按当前项目路径注入的原文。"""
+        until = self._summarized_until if session_id == self._session_id else self._until_of(session_id)
+        path = self._project_path
+        rows = self.list_messages(session_id)
+        if path:
+            rows = [
+                m
+                for m in rows
+                if m.project_path == path or not m.project_path
+            ]
+        return [
+            m
+            for m in rows
+            if m.id > until
+            and m.role in ("user", "assistant", "tool")
+            and (m.content.strip() or _meta_dict(m.meta).get("tool_calls"))
+        ]
+
+    def _until_of(self, session_id: str) -> int:
+        if session_id == self._session_id:
+            return self._summarized_until
+        row = self._conn.execute(
+            "SELECT summarized_until FROM session WHERE id=?",
+            (session_id,),
+        ).fetchone()
+        return int(row["summarized_until"] or 0) if row else 0
+
+    def _summary_of(self, session_id: str) -> str:
+        if session_id == self._session_id:
+            return self._summary
+        row = self._conn.execute(
+            "SELECT summary FROM session WHERE id=?",
+            (session_id,),
+        ).fetchone()
+        return str(row["summary"] or "") if row else ""
+
+    def summary_messages(self, session_id: str) -> list[dict[str, str]]:
+        text = self._summary_of(session_id).strip()
+        if not text:
+            return []
+        return [
+            {"role": "user", "content": "【此前对话摘要】\n" + text},
+            {"role": "assistant", "content": "已记住摘要，会在此基础上继续。"},
+        ]
+
+    def context_for_model(self, session_id: str) -> list[dict]:
+        """给接口用:摘要 + 未折进摘要的原文(含工具)。磁盘全文仍在,这里只组请求。"""
+        msgs: list[dict] = self.summary_messages(session_id)
+        for row in self.live_messages(session_id):
+            item = _message_to_payload(row)
+            if item:
+                msgs.append(item)
+        return msgs
+
+    def context_tokens(self, session_id: str) -> int:
+        return tokens_of(self.context_for_model(session_id))
+
+    def needs_compress(self, session_id: str) -> bool:
+        return self.context_tokens(session_id) > self.context_limit
+
+    def split_overflow(
+        self, session_id: str, *, force: bool = False
+    ) -> tuple[list[Message], list[Message]]:
+        """超窗时:前面折进摘要,尾巴尽量留到 compact 阈值。force 时至少压掉尾部以外的旧文。"""
+        live = self.live_messages(session_id)
+        if not live:
+            return [], []
+        if force and len(live) > 2:
+            prefix, tail = live[:-2], live[-2:]
+            return _align_tool_tail(live, prefix, tail)
+        tail_budget = self.context_limit - self.summary_budget()
+        if tail_budget < 32:
+            tail_budget = max(32, self.context_limit // 2)
+        tail: list[Message] = []
+        used = 0
+        for msg in reversed(live):
+            cost = _est_tokens(msg.content)
+            if tail and used + cost > tail_budget:
+                break
+            tail.append(msg)
+            used += cost
+        tail.reverse()
+        if not tail:
+            tail = live[-1:]
+        keep = {m.id for m in tail}
+        prefix = [m for m in live if m.id not in keep]
+        return _align_tool_tail(live, prefix, tail)
+
+    def apply_summary(self, session_id: str, summary: str, until_id: int) -> None:
+        now = int(time.time())
+        self._conn.execute(
+            """
+            UPDATE session
+            SET summary=?, summarized_until=?, updated_at=?
+            WHERE id=?
+            """,
+            (summary, until_id, now, session_id),
+        )
+        self._conn.commit()
+        if session_id == self._session_id:
+            self._summary = summary
+            self._summarized_until = until_id
+
+    def _root(self) -> Path:
+        return Path(self._project_path or current_project_path()).resolve()
+
+    def open_checkpoint(self, session_id: str, message_id: int, title: str) -> str:
+        cid = uuid.uuid4().hex
+        now = int(time.time())
+        label = " ".join((title or "").strip().split())[:40]
+        self._conn.execute(
+            """
+            INSERT INTO checkpoint (id, session_id, message_id, created_at, title)
+            VALUES (?, ?, ?, ?, ?)
+            """,
+            (cid, session_id, message_id, now, label),
+        )
+        self._conn.commit()
+        self._prune_checkpoints(session_id)
+        return cid
+
+    def snapshot_file(self, checkpoint_id: str, path: Path) -> None:
+        if not checkpoint_id:
+            return
+        root = self._root()
+        resolved = path.resolve()
+        try:
+            rel = str(resolved.relative_to(root)).replace("\\", "/")
+        except ValueError:
+            rel = str(resolved)
+        hit = self._conn.execute(
+            """
+            SELECT 1 FROM snapshot_file
+            WHERE checkpoint_id=? AND relpath=?
+            """,
+            (checkpoint_id, rel),
+        ).fetchone()
+        if hit:
+            return
+        existed = 1 if resolved.is_file() else 0
+        blob_id = None
+        if existed:
+            try:
+                data = resolved.read_bytes()
+            except OSError:
+                return
+            if len(data) > SNAPSHOT_MAX_BYTES:
+                return
+            blob_id = hashlib.sha256(data).hexdigest()
+            self._conn.execute(
+                "INSERT OR IGNORE INTO snapshot_blob (id, content) VALUES (?, ?)",
+                (blob_id, data),
+            )
+        self._conn.execute(
+            """
+            INSERT INTO snapshot_file (checkpoint_id, relpath, existed, blob_id)
+            VALUES (?, ?, ?, ?)
+            """,
+            (checkpoint_id, rel, existed, blob_id),
+        )
+        self._conn.commit()
+
+    def list_checkpoints(self, session_id: str) -> list[dict]:
+        rows = self._conn.execute(
+            """
+            SELECT c.id, c.message_id, c.created_at, c.title,
+                   (SELECT COUNT(*) FROM snapshot_file s WHERE s.checkpoint_id=c.id) AS n
+            FROM checkpoint c
+            WHERE c.session_id=?
+            ORDER BY c.message_id DESC, c.created_at DESC
+            """,
+            (session_id,),
+        ).fetchall()
+        out = []
+        later_files = 0
+        for r in rows:
+            n = int(r["n"] or 0)
+            item = {
+                "id": str(r["id"]),
+                "message_id": int(r["message_id"]),
+                "created_at": int(r["created_at"] or 0),
+                "title": str(r["title"] or ""),
+                "n": n,
+                "later_files": later_files + n,
+            }
+            later_files += n
+            out.append(item)
+        return out
+
+    def restore_files(self, session_id: str, checkpoint_id: str) -> list[str]:
+        target = self._conn.execute(
+            "SELECT id, message_id FROM checkpoint WHERE id=? AND session_id=?",
+            (checkpoint_id, session_id),
+        ).fetchone()
+        if not target:
+            raise ValueError("找不到这个快照")
+        cut = int(target["message_id"])
+        cps = self._conn.execute(
+            """
+            SELECT id FROM checkpoint
+            WHERE session_id=? AND message_id>=?
+            ORDER BY message_id DESC, created_at DESC
+            """,
+            (session_id, cut),
+        ).fetchall()
+        changed: list[str] = []
+        root = self._root()
+        for cp in cps:
+            files = self._conn.execute(
+                """
+                SELECT relpath, existed, blob_id FROM snapshot_file
+                WHERE checkpoint_id=?
+                """,
+                (str(cp["id"]),),
+            ).fetchall()
+            for f in files:
+                rel = str(f["relpath"])
+                raw = Path(rel)
+                dest = raw.resolve() if raw.is_absolute() else (root / rel).resolve()
+                if int(f["existed"] or 0) == 0:
+                    if dest.is_file():
+                        dest.unlink()
+                        changed.append(rel)
+                    continue
+                blob_id = f["blob_id"]
+                if not blob_id:
+                    continue
+                blob = self._conn.execute(
+                    "SELECT content FROM snapshot_blob WHERE id=?",
+                    (blob_id,),
+                ).fetchone()
+                if not blob:
+                    continue
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                dest.write_bytes(blob["content"])
+                changed.append(rel)
+        seen: list[str] = []
+        for rel in changed:
+            if rel not in seen:
+                seen.append(rel)
+        return seen
+
+    def drop_checkpoints_after(
+        self, session_id: str, message_id: int, *, include: bool = False
+    ) -> None:
+        if include:
+            rows = self._conn.execute(
+                "SELECT id FROM checkpoint WHERE session_id=? AND message_id>=?",
+                (session_id, message_id),
+            ).fetchall()
+        else:
+            rows = self._conn.execute(
+                "SELECT id FROM checkpoint WHERE session_id=? AND message_id>?",
+                (session_id, message_id),
+            ).fetchall()
+        ids = [str(r["id"]) for r in rows]
+        for cid in ids:
+            self._conn.execute(
+                "DELETE FROM snapshot_file WHERE checkpoint_id=?", (cid,)
+            )
+            self._conn.execute("DELETE FROM checkpoint WHERE id=?", (cid,))
+        self._gc_blobs()
+        self._conn.commit()
+
+    def truncate_from_message(self, session_id: str, message_id: int) -> None:
+        self._conn.execute(
+            "DELETE FROM message WHERE session_id=? AND id>=?",
+            (session_id, message_id),
+        )
+        until = self._until_of(session_id)
+        if until >= message_id:
+            self._conn.execute(
+                """
+                UPDATE session
+                SET summary='', summarized_until=0, updated_at=?
+                WHERE id=?
+                """,
+                (int(time.time()), session_id),
+            )
+            if session_id == self._session_id:
+                self._summary = ""
+                self._summarized_until = 0
+        self.drop_checkpoints_after(session_id, message_id, include=True)
+        if session_id == self._session_id:
+            self._messages = [m for m in self._messages if m.id < message_id]
+        self._conn.commit()
+
+    def _prune_checkpoints(self, session_id: str) -> None:
+        rows = self._conn.execute(
+            """
+            SELECT id FROM checkpoint
+            WHERE session_id=?
+            ORDER BY message_id DESC, created_at DESC
+            """,
+            (session_id,),
+        ).fetchall()
+        extra = [str(r["id"]) for r in rows[CHECKPOINT_KEEP:]]
+        for cid in extra:
+            self._conn.execute(
+                "DELETE FROM snapshot_file WHERE checkpoint_id=?", (cid,)
+            )
+            self._conn.execute("DELETE FROM checkpoint WHERE id=?", (cid,))
+        if extra:
+            self._gc_blobs()
+            self._conn.commit()
+
+    def _gc_blobs(self) -> None:
+        self._conn.execute(
+            """
+            DELETE FROM snapshot_blob
+            WHERE id NOT IN (
+              SELECT blob_id FROM snapshot_file WHERE blob_id IS NOT NULL
+            )
+            """
+        )
+
+
+def _align_tool_tail(
+    live: list[Message], prefix: list[Message], tail: list[Message]
+) -> tuple[list[Message], list[Message]]:
+    """尾巴不要从孤立的 tool 结果起头,把对应的 assistant tool_calls 拉回来。"""
+    if not tail:
+        return prefix, tail
+    by_id = {m.id: i for i, m in enumerate(live)}
+    keep = {m.id for m in tail}
+    while tail and tail[0].role == "tool":
+        idx = by_id.get(tail[0].id)
+        if idx is None or idx <= 0:
+            break
+        prev = live[idx - 1]
+        if prev.id in keep:
+            break
+        tail.insert(0, prev)
+        keep.add(prev.id)
+    prefix = [m for m in live if m.id not in keep]
+    return prefix, tail
+
+
+def _meta_dict(raw: str) -> dict:
+    if not raw:
+        return {}
+    try:
+        data = json.loads(raw)
+    except (TypeError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _message_to_payload(row: Message) -> dict | None:
+    meta = _meta_dict(row.meta)
+    if row.role == "tool":
+        item = {
+            "role": "tool",
+            "content": row.content or "",
+            "tool_call_id": str(meta.get("tool_call_id") or ""),
+        }
+        name = str(meta.get("name") or "")
+        if name:
+            item["name"] = name
+        return item
+    if row.role == "assistant":
+        item: dict = {"role": "assistant"}
+        text = (row.content or "").strip()
+        calls = meta.get("tool_calls")
+        if text:
+            item["content"] = text
+        if calls:
+            item["tool_calls"] = calls
+        if "content" not in item and not calls:
+            return None
+        return item
+    text = (row.content or "").strip()
+    if not text:
+        return None
+    return {"role": row.role, "content": text}
+
+
+def tokens_of(msgs: list[dict]) -> int:
+    total = 0
+    for msg in msgs:
+        total += _est_tokens(str(msg.get("content") or ""))
+        calls = msg.get("tool_calls")
+        if calls:
+            try:
+                total += _est_tokens(json.dumps(calls, ensure_ascii=False))
+            except (TypeError, ValueError):
+                pass
+    return total