flowstatemcp 2.5.0__py3-none-any.whl

flowstate/ask.py

@@ -0,0 +1,107 @@
+"""ask: a plain question in, a short answer out, with the ids of the records it came from
+(v2 Phase D, E7).
+
+Local only: built on meaning.search (meaning + keywords when a local model is installed,
+keywords otherwise), plus the project's hard rules and open handoff notes. The answer is
+extractive: the best-matching sentence of each top record, quoted with its id. FlowState
+does not make anything up; if nothing matches, it says the memory has nothing on it.
+"""
+
+import re
+from pathlib import Path
+from typing import Optional
+
+from . import handoffs, links, meaning, provenance, rules
+
+# Question words that carry no topic ("what port does the server use" -> "port server use").
+_QWORDS = set("""what which who whom whose where when why how does do did is are was were can
+could should would will shall may might we our us i my me you your it its there their they
+about tell know any some have has had please the a an of to in on for with and or""".split())
+_SPLIT = re.compile(r"(?<=[.!?;])\s+|\n+")
+MAX_ANSWER_ITEMS = 3
+
+
+def _topic(question: str) -> str:
+    words = re.findall(r"[A-Za-z0-9_][A-Za-z0-9_.:/\\-]*", question or "")
+    kept = [w for w in words if w.lower() not in _QWORDS]
+    return " ".join(kept) or (question or "")
+
+
+def _best_sentence(text: str, topic: str, width: int = 220) -> str:
+    stems = {meaning._stem(w) for w in meaning._WORD.findall(topic.lower()) if w not in meaning._STOP}
+    best, score = "", -1
+    for s in _SPLIT.split(text or ""):
+        s = " ".join(s.split())
+        if not s:
+            continue
+        toks = {meaning._stem(w) for w in meaning._WORD.findall(s.lower())}
+        sc = sum(1 for w in stems if any(t.startswith(w) for t in toks))
+        if sc > score:
+            best, score = s, sc
+    return links._one_line(best, width)
+
+
+def _extras(conn, pid: Optional[int]) -> list[dict]:
+    """Hard rules and open handoff notes as searchable pseudo-records."""
+    if pid is None:
+        return []
+    out = [{"type": "rule", "id": r["id"], "project_id": pid, "title": r["rule"], "body": "",
+            "status": None} for r in rules.active(conn, pid)]
+    out += [{"type": "handoff", "id": n["id"], "project_id": pid, "title": n["where_i_was"],
+             "body": n.get("next_step") or "", "status": None} for n in handoffs.open_notes(conn, pid)]
+    return out
+
+
+def ask(db_path: Path, question: str, pid: Optional[int] = None, limit: int = 5) -> dict:
+    question = " ".join((question or "").split())
+    if not question:
+        return {"error": "question_required", "message": "Ask a question, e.g. "
+                "ask(question=\"which port does the LAN server use?\", project=\"FlowState\")."}
+    limit = max(1, min(int(limit or 5), 10))
+    topic = _topic(question)
+    found = meaning.search(db_path, topic, pid, None, limit * 2, "auto")
+    conn = links.connect(db_path)
+    try:
+        replaced = links.superseded_decisions(conn) if links.available(conn) else {}
+        hits = [r for r in found["results"]
+                if not (r["content_type"] == "decision" and r["content_id"] in replaced)]
+        extra = meaning.keyword_hits(_extras(conn, pid), topic, 3)
+        names = {pid: links.project_name(conn, pid)} if pid is not None else {}
+        sources = []
+        for _s, r in extra:
+            sources.append({"type": r["type"], "id": r["id"], "project": names.get(pid),
+                            "text": _best_sentence(f"{r['title']}. {r['body']}", topic)})
+        for r in hits[:limit]:
+            text = f"{r['title']}. {r.get('snippet') or ''}"
+            item = {"type": r["content_type"], "id": r["content_id"], "project": r["project"],
+                    "text": _best_sentence(text, topic), "matched_by": r["matched_by"]}
+            if r.get("status"):
+                item["status"] = r["status"]
+            sources.append(item)
+        metas: dict = {}
+        for t in {s["type"] for s in sources if s["type"] in provenance.TABLES}:
+            metas[t] = provenance.get(conn, t, [s["id"] for s in sources if s["type"] == t])
+        for s in sources:
+            m = metas.get(s["type"], {}).get(s["id"])
+            if m:
+                s.update(m)
+    finally:
+        conn.close()
+
+    if not sources:
+        return {"question": question, "answer": "FlowState has nothing on this"
+                + (" in this project" if pid is not None else "") + ". (Nothing matched; "
+                "it does not guess.)", "sources": [], "mode": found["mode"],
+                **({"note": found["note"]} if found.get("note") else {})}
+    lines = []
+    for s in sources[:MAX_ANSWER_ITEMS + len(extra)]:
+        label = {"rule": f"hard rule R{s['id']}", "handoff": f"handoff H{s['id']}"}.get(
+            s["type"], f"{s['type']} #{s['id']}")
+        where = f", {s['project']}" if s.get("project") and pid is None else ""
+        lines.append(f"- {s['text']} [{label}{where}{provenance.tag(s).replace(' (', ', ').rstrip(')')}]")
+    answer = ("From FlowState (best matches, quoted; check the records for detail):\n"
+              + "\n".join(lines))
+    out = {"question": question, "answer": answer, "sources": sources, "mode": found["mode"]}
+    if found.get("note"):
+        out["note"] = found["note"]
+    return out

flowstate/autosession.py

@@ -0,0 +1,480 @@
+"""Implicit sessions: the server opens a FlowState session on a client's first call
+for a project and closes it after an idle timeout, on shutdown, or when the agent ends
+it explicitly. Works the same for stdio and HTTP; state lives in SQLite so a session
+left behind by a crashed process is closed by the next reaper run of any process.
+
+Nothing in here may break a tool call: callers wrap every method in try/except.
+"""
+
+import json
+import os
+import sqlite3
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional
+
+from . import dbconn
+
+# Kept identical to the v2 block at the end of database/schema.sql (a test checks it).
+AUTO_SESSIONS_DDL = """CREATE TABLE IF NOT EXISTS auto_sessions (
+    session_id INTEGER PRIMARY KEY REFERENCES sessions(id) ON DELETE CASCADE,
+    project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+    client TEXT NOT NULL,
+    server_instance TEXT NOT NULL,
+    opened_at TEXT NOT NULL,      -- UTC, 'YYYY-MM-DD HH:MM:SS'
+    last_activity TEXT NOT NULL,  -- UTC
+    call_count INTEGER NOT NULL DEFAULT 0,
+    events TEXT NOT NULL DEFAULT '[]', -- JSON list of short event labels (capped)
+    closed_at TEXT,
+    close_reason TEXT             -- idle | shutdown | stale | explicit
+);
+CREATE INDEX IF NOT EXISTS idx_auto_sessions_open ON auto_sessions(closed_at, client, project_id);"""
+
+AUTO_TAG = "[auto-captured, needs review]"
+OFF_TAG = "[auto summary, review off]"
+SKIP_TAG = "[auto summary, housekeeping]"   # saved nothing new: not queued
+MAX_EVENTS = 60
+MAX_SUMMARY = 600
+TS_FMT = "%Y-%m-%d %H:%M:%S"
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc).replace(tzinfo=None)
+
+
+def _ts(dt: datetime) -> str:
+    return dt.strftime(TS_FMT)
+
+
+def _add(events: list, event: str) -> list:
+    """`events` plus `event`, at most MAX_EVENTS long: the oldest read goes first, so a long
+    session never loses what it saved to its reads (is_housekeeping, build_summary)."""
+    events = events + [event[:120]]
+    while len(events) > MAX_EVENTS:
+        del events[next((i for i, e in enumerate(events) if e.startswith("read:")), 0)]
+    return events
+
+
+def _parse(ts: str) -> datetime:
+    return datetime.strptime(ts[:19].replace("T", " "), TS_FMT)
+
+
+def idle_minutes_from_env() -> float:
+    try:
+        return float(os.environ.get("FLOWSTATE_IDLE_MINUTES", "120"))
+    except ValueError:
+        return 120.0
+
+
+def ensure_schema(db_path: Path) -> None:
+    """Additive migration: create auto_sessions if missing. Never alters existing data."""
+    conn = dbconn.connect(str(db_path), timeout=5.0)
+    try:
+        conn.execute("PRAGMA busy_timeout = 5000")
+        conn.executescript(AUTO_SESSIONS_DDL)
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def _has_runs(conn) -> bool:
+    return conn.execute("SELECT 1 FROM sqlite_master WHERE type='table' "
+                        "AND name='session_runs'").fetchone() is not None
+
+
+_OPEN = """SELECT a.* FROM auto_sessions a WHERE a.closed_at IS NULL AND a.client = ?
+           AND a.project_id = ?"""
+# 2.4.0 (migration 015): one session per connection; conn_key None = the old matching
+_BY_CONN = " AND a.session_id IN (SELECT session_id FROM session_runs WHERE conn_key = ?)"
+_LATEST = " ORDER BY a.session_id DESC LIMIT 1"
+
+
+class AutoSessions:
+    """Tracks implicit sessions keyed by (client, project, connection). The connection
+    (`conn_key`: identity.Identity.session, i.e. the stdio server process or the HTTP MCP
+    session) keeps two windows of one app apart; without one (or on a database before
+    migration 015) sessions are keyed by (client, project) as before."""
+
+    def __init__(self, db_path: Path, idle_minutes: Optional[float] = None,
+                 instance: Optional[str] = None):
+        self.db_path = Path(db_path)
+        self.idle = timedelta(minutes=idle_minutes if idle_minutes is not None
+                              else idle_minutes_from_env())
+        self.instance = instance or uuid.uuid4().hex[:12]
+        self._last: dict = {}   # conn_key -> the session it touched last (this process)
+
+    def _conn(self) -> sqlite3.Connection:
+        conn = dbconn.connect(str(self.db_path), timeout=5.0)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA busy_timeout = 5000")
+        conn.execute("PRAGMA foreign_keys = ON")
+        return conn
+
+    # ---------------------------------------------------------------- touch
+    def _find(self, conn, client: str, project_id: int, conn_key: Optional[str]):
+        if conn_key and _has_runs(conn):
+            return conn.execute(_OPEN + _BY_CONN + _LATEST,
+                                (client, project_id, conn_key)).fetchone()
+        return conn.execute(_OPEN + _LATEST, (client, project_id)).fetchone()
+
+    def touch(self, client: str, project_id: int, event: Optional[str] = None,
+              conn_key: Optional[str] = None, ident=None) -> int:
+        """Record activity; open a session if none is open for this connection. Returns
+        sessions.id. `ident` (identity.Identity) is recorded with a new session."""
+        client = (client or "unknown")[:80]
+        conn_key = (conn_key or "")[:80] or None
+        now = _utcnow()
+        conn = self._conn()
+        try:
+            conn.execute("BEGIN IMMEDIATE")
+            row = self._find(conn, client, project_id, conn_key)
+            if row is not None and now - _parse(row["last_activity"]) > self.idle:
+                self._close_row(conn, row, "stale")
+                row = None
+            if row is None:
+                cur = conn.execute(
+                    "INSERT INTO sessions (project_id, started_at) VALUES (?, ?)",
+                    (project_id, _ts(now)))
+                sid = cur.lastrowid
+                conn.execute(
+                    """INSERT INTO auto_sessions (session_id, project_id, client,
+                       server_instance, opened_at, last_activity, call_count, events)
+                       VALUES (?, ?, ?, ?, ?, ?, 0, '[]')""",
+                    (sid, project_id, client, self.instance, _ts(now), _ts(now)))
+                if conn_key and _has_runs(conn):
+                    who = ident.as_dict() if ident is not None else {}
+                    conn.execute(
+                        """INSERT INTO session_runs (session_id, conn_key, app, model, machine,
+                           identity_source) VALUES (?, ?, ?, ?, ?, ?)""",
+                        (sid, conn_key, who.get("app") or client, who.get("model"),
+                         who.get("machine"), who.get("identity_source")))
+                events: list = []
+                count = 0
+            else:
+                sid = row["session_id"]
+                events = json.loads(row["events"] or "[]")
+                count = row["call_count"]
+            if event:
+                events = _add(events, event)
+            conn.execute(
+                """UPDATE auto_sessions SET last_activity = ?, call_count = ?, events = ?,
+                   server_instance = ? WHERE session_id = ?""",
+                (_ts(now), count + 1, json.dumps(events), self.instance, sid))
+            conn.commit()
+            if conn_key:
+                dbconn.after(self.db_path, lambda ok: ok and self._last.__setitem__(conn_key, sid))
+            return sid
+        except Exception:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+    def note(self, session_id: int, event: str) -> None:
+        """Append an event label to an open session (used after a call succeeds)."""
+        conn = self._conn()
+        try:
+            conn.execute("BEGIN IMMEDIATE")
+            row = conn.execute("SELECT events FROM auto_sessions WHERE session_id = ? "
+                               "AND closed_at IS NULL", (session_id,)).fetchone()
+            if row is not None:
+                events = _add(json.loads(row["events"] or "[]"), event)
+                conn.execute("UPDATE auto_sessions SET events = ? WHERE session_id = ?",
+                             (json.dumps(events), session_id))
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+    def current(self, client: str, project_id: int,
+                conn_key: Optional[str] = None) -> Optional[dict]:
+        conn = self._conn()
+        try:
+            row = self._find(conn, (client or "unknown")[:80], project_id,
+                             (conn_key or "")[:80] or None)
+            return dict(row) if row else None
+        finally:
+            conn.close()
+
+    def own(self, client: str, project_id: Optional[int], conn_key: Optional[str]) -> Optional[dict]:
+        """This connection's open automatic session (in `project_id`, else the one it used
+        last). Never another connection's: two windows of one app each get their own."""
+        if not conn_key:
+            return self.current(client, project_id) if project_id else None
+        conn = self._conn()
+        try:
+            if not _has_runs(conn):
+                return None
+            last = self._last.get(conn_key[:80]) if not project_id else None
+            if last is not None:   # exact: the session this connection's last call touched
+                row = conn.execute("SELECT * FROM auto_sessions WHERE session_id = ? AND "
+                                   "closed_at IS NULL", (last,)).fetchone()
+                if row is not None:
+                    return dict(row)
+            sql = ("SELECT a.* FROM auto_sessions a WHERE a.closed_at IS NULL AND a.client = ?"
+                   + (" AND a.project_id = ?" if project_id else "") + _BY_CONN
+                   + " ORDER BY a.last_activity DESC, a.session_id DESC LIMIT 1")
+            args = (client[:80] if client else "unknown",) + ((project_id,) if project_id else ()) \
+                + (conn_key[:80],)
+            row = conn.execute(sql, args).fetchone()
+            return dict(row) if row else None
+        finally:
+            conn.close()
+
+    def is_auto(self, session_id: int) -> bool:
+        conn = self._conn()
+        try:
+            return conn.execute("SELECT 1 FROM auto_sessions WHERE session_id = ?",
+                                (session_id,)).fetchone() is not None
+        finally:
+            conn.close()
+
+    # ---------------------------------------------------------------- closing
+    def close_idle(self) -> list[int]:
+        """Close every open auto session idle longer than the timeout (any process)."""
+        cutoff = _ts(_utcnow() - self.idle)
+        return self._close_where("last_activity < ?", (cutoff,), "idle")
+
+    def close_instance(self, reason: str = "shutdown") -> list[int]:
+        """Close sessions this process owns (client disconnected / server stopping)."""
+        return self._close_where("server_instance = ?", (self.instance,), reason)
+
+    def mark_explicit_end(self, session_id: int) -> None:
+        """Agent ended the session itself: keep its summary, just stop tracking."""
+        conn = self._conn()
+        try:
+            cur = conn.execute(
+                """UPDATE auto_sessions SET closed_at = ?, close_reason = 'explicit'
+                   WHERE session_id = ? AND closed_at IS NULL""",
+                (_ts(_utcnow()), session_id))
+            if cur.rowcount:
+                pid = conn.execute("SELECT project_id FROM auto_sessions WHERE session_id = ?",
+                                   (session_id,)).fetchone()
+                self._release_claims(conn, session_id, pid["project_id"], "explicit")
+            conn.commit()
+        finally:
+            conn.close()
+
+    def _close_where(self, where: str, params: tuple, reason: str) -> list[int]:
+        conn = self._conn()
+        closed = []
+        try:
+            conn.execute("BEGIN IMMEDIATE")
+            rows = conn.execute(
+                f"SELECT * FROM auto_sessions WHERE closed_at IS NULL AND {where}",
+                params).fetchall()
+            for row in rows:
+                self._close_row(conn, row, reason)
+                closed.append(row["session_id"])
+            conn.commit()
+            return closed
+        except Exception:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+    def _close_row(self, conn: sqlite3.Connection, row: sqlite3.Row, reason: str) -> None:
+        opened, last = _parse(row["opened_at"]), _parse(row["last_activity"])
+        minutes = max(0, int((last - opened).total_seconds() // 60))
+        events = json.loads(row["events"] or "[]")
+        # Reads go first when the list is full (_add); a full list without one may have lost
+        # saves, so it counts as work.
+        trimmed = (len(events) >= MAX_EVENTS and row["call_count"] > len(events)
+                   and not any(e.startswith("read:") for e in events))
+        name = conn.execute("SELECT name FROM projects WHERE id = ?",
+                            (row["project_id"],)).fetchone()
+        project = name[0] if name else f"project #{row['project_id']}"
+        # The records it saved, by id (run ledger): stored with the review item so every page
+        # shows them next to the short summary line (session_contents.py). The line itself
+        # stays short: it is what Keep saves as the session's record.
+        from . import session_contents
+        try:
+            recs = session_contents.refs(conn, row["session_id"])
+        except sqlite3.Error:
+            recs = None
+        summary = build_summary(row["client"], project, events, trimmed,
+                                _taken_back(conn, recs))
+        outcomes = {"auto_captured": True, "needs_review": True, "close_reason": reason,
+                    "client": row["client"], "calls": row["call_count"]}
+        if recs:
+            outcomes["records"] = len(recs)
+        from .review_mode import get_with
+        if not trimmed and is_housekeeping(events):
+            # Nothing new was saved (reads, undo, review decisions...): a plain record for
+            # the session's history, but nothing for the user to judge in the queue.
+            summary = SKIP_TAG + summary[len(AUTO_TAG):]
+            outcomes.update({"needs_review": False, "review": "skipped_housekeeping"})
+        elif get_with(conn, row["project_id"])["mode"] == "off":
+            # The user turned review off: keep the summary as a normal one, queue nothing.
+            summary = OFF_TAG + summary[len(AUTO_TAG):]
+            outcomes.update({"needs_review": False, "review": "off"})
+        # Only fill the session if the agent hasn't ended it with its own summary. The
+        # summary stays flagged as provisional and waits in the review queue for the
+        # user's OK (approve replaces it with the reviewed text).
+        cur = conn.execute(
+            """UPDATE sessions SET ended_at = ?, summary = ?, outcomes = ?,
+               duration_minutes = ? WHERE id = ? AND ended_at IS NULL""",
+            (row["last_activity"], summary, json.dumps(outcomes), minutes,
+             row["session_id"]))
+        if cur.rowcount and outcomes["needs_review"]:
+            from .review import add_item
+            from .identity import on_behalf_of
+            run = conn.execute(
+                "SELECT app, model, machine, identity_source FROM session_runs "
+                "WHERE session_id = ? ORDER BY rowid LIMIT 1",
+                (row["session_id"],)).fetchone() if _has_runs(conn) else None
+            # the app its session recorded (with the sign-in it came in on), else the client
+            who = (on_behalf_of(run["app"] or row["client"], run["machine"],
+                                run["identity_source"], run["model"]) if run is not None
+                   else on_behalf_of(row["client"]))
+            item = add_item(self.db_path, row["project_id"], "session_summary", summary,
+                            payload={"close_reason": reason, "calls": row["call_count"],
+                                     **({"records": recs} if recs else {})},
+                            source=row["client"], session_id=row["session_id"], conn=conn,
+                            ident=who)
+            if item is not None:
+                outcomes["review_item_id"] = item
+                conn.execute("UPDATE sessions SET outcomes = ? WHERE id = ?",
+                             (json.dumps(outcomes), row["session_id"]))
+        conn.execute(
+            "UPDATE auto_sessions SET closed_at = ?, close_reason = ? WHERE session_id = ?",
+            (_ts(_utcnow()), reason, row["session_id"]))
+        self._release_claims(conn, row["session_id"], row["project_id"], reason)
+
+    @staticmethod
+    def _release_claims(conn, session_id: int, project_id: int, reason: str) -> None:
+        """A claim ends with its session (claims.py): drop what this connection held here."""
+        if not _has_runs(conn):
+            return
+        key = conn.execute("SELECT conn_key, app FROM session_runs WHERE session_id = ?",
+                           (session_id,)).fetchone()
+        if key and key["conn_key"]:
+            from . import claims
+            claims.release_for_session(conn, key["conn_key"], key["app"], project_id, reason)
+
+
+# Event labels (server._label: "<kind or tool/action>[: text]", reads "read:<tool>") of
+# calls that save no new work: taking something back, deciding the review queue, picking up
+# a handoff note, adopting the session FlowState opened, holding a todo while working on it
+# (a claim ends with its session). Reads are housekeeping too. Any other write label is
+# real work, so its session keeps its summary (fail safe). Value: the word for the summary.
+HOUSEKEEPING = {
+    "history/undo": "undo",
+    "review_approve": "review decision",
+    "review_reject": "review decision",
+    "resolve_review_card": "review decision",     # a tap on a review card (re-audit N-F15)
+    "resolve_conflict_card": "review decision",   # a tap on a disagreement card
+    "handoff/pickup": "handoff picked up",
+    "session/start": None,
+    "todo/claim": "todo claim",
+    "todo/renew": "todo claim",
+    "todo/release": "todo claim",
+}
+
+# Saved records, by the kind their label starts with (log_work kinds and the older tools).
+_SAVED = {"learning": "learning", "log_learning": "learning", "decision": "decision",
+          "session/log_conversation": "decision", "change": "change", "log_change": "change",
+          "problem": "problem", "problem/log": "problem", "todo": "todo", "todo/add": "todo"}
+_KINDS = ("learning", "decision", "change", "problem", "todo")
+# Plain words for the other writes (anything else: its label with spaces).
+_WORDS = {"todo/update": "todo update", "todo/block": "todo blocked",
+          "todo/unblock": "todo unblocked", "todo/handoff": "todo handed off",
+          "problem/solve": "problem solved", "attempt/log": "fix attempt",
+          "attempt/outcome": "fix attempt result", "link/add": "new link",
+          "link/remove": "link removed", "rules/add": "hard rule request", "rules/remove": "rule removal request",
+          "handoff/leave": "handoff note", "verify/mark": "fact checked",
+          "verify/source": "source changed", "review_mode/set": "review mode change",
+          "delete_request/record": "delete", "delete_request/project": "project delete",
+          "delete_request/component": "component delete", "cleanup_suggest": "clean-up ideas",
+          "import_memory": "memory import", "update_project": "project update",
+          "create_component": "new component", "update_component": "component update"}
+
+
+def _what(event: str) -> str:
+    """The label's kind or tool/action part (before ": <text>")."""
+    return event.split(": ", 1)[0].strip()
+
+
+def is_housekeeping(events: list) -> bool:
+    """True when a session saved nothing new: no events, or only reads and HOUSEKEEPING
+    labels. Such a session files no session_summary review item."""
+    return all(e.startswith("read:") or _what(e) in HOUSEKEEPING for e in events)
+
+
+def _n(count: int, word: str) -> str:
+    return f"{count} {word}{'' if count == 1 else 's'}"
+
+
+def _and(parts: list) -> str:
+    return parts[0] if len(parts) == 1 else ", ".join(parts[:-1]) + " and " + parts[-1]
+
+
+def _taken_back(conn, recs) -> dict:
+    """kind -> how many records the session saved that are no longer there when it closes
+    (an undo took one back, or the session deleted it): the summary counts what is still
+    there (audit 53, N-F39). From the run ledger's records; empty without one."""
+    from .history import TABLES
+    out: dict = {}
+    for rtype, rid, verb in recs or []:
+        if rtype not in _KINDS or str(verb).split(", ")[0] != "saved":
+            continue
+        try:
+            there = conn.execute(f'SELECT 1 FROM "{TABLES[rtype]}" WHERE id = ?',
+                                 (int(rid),)).fetchone()
+        except (sqlite3.Error, KeyError, ValueError, TypeError):
+            continue
+        if there is None:
+            out[rtype] = out.get(rtype, 0) + 1
+    return out
+
+
+def build_summary(client: str, project: str, events: list, trimmed: bool = False,
+                  taken_back: Optional[dict] = None) -> str:
+    """Short, plain summary from the event log: what the session saved, counted by kind.
+    Starts with AUTO_TAG (the caller swaps it for OFF_TAG / SKIP_TAG). Which records they
+    are is shown beside it (session_contents.py), not in it. `taken_back`: kind -> saved
+    records no longer there (_taken_back), not counted as saved."""
+    saved, suggested, other, chores = {}, {}, {}, {}
+    for e in events:
+        if e.startswith("read:"):
+            continue
+        what = _what(e)
+        if what.startswith("suggested "):
+            kind = _SAVED.get(what[10:])
+            if kind:
+                suggested[kind] = suggested.get(kind, 0) + 1
+                continue
+        if what in _SAVED:
+            saved[_SAVED[what]] = saved.get(_SAVED[what], 0) + 1
+        elif what in HOUSEKEEPING:
+            if HOUSEKEEPING[what]:
+                chores[HOUSEKEEPING[what]] = chores.get(HOUSEKEEPING[what], 0) + 1
+        else:
+            words = _WORDS.get(what) or what.replace("/", " ").replace("_", " ")
+            other[words] = other.get(words, 0) + 1
+    for k, n in (taken_back or {}).items():
+        if k in saved:
+            saved[k] -= n
+            if saved[k] <= 0:
+                del saved[k]
+    parts = []
+    if saved:
+        parts.append("saved " + _and([_n(saved[k], k) for k in _KINDS if k in saved]))
+    if suggested:
+        parts.append("suggested " + _and([_n(suggested[k], k) for k in _KINDS if k in suggested])
+                     + " for review")
+    if other:
+        parts.append("also " + ", ".join(f"{k} (x{v})" if v > 1 else k for k, v in other.items()))
+    if not parts:
+        parts.append("nothing new saved" + (f" ({_and([_n(v, k) for k, v in chores.items()])})"
+                                            if chores else ""))
+    text = f"{AUTO_TAG} {client} session in {project}: " + "; ".join(parts) + "."
+    if trimmed:
+        text += f" Only its last {MAX_EVENTS} saves were counted."
+    if len(text) > MAX_SUMMARY:
+        text = text[:MAX_SUMMARY - 3] + "..."
+    return text