zeno-cli 0.3.4__py3-none-any.whl

zeno_session_intel/prices.py

@@ -0,0 +1,281 @@
+"""Local, cache-aware model pricing: a bundled rate table + cost math + a name matcher.
+
+Local-first by doctrine: the rate table ships in-repo, no network fetch at runtime. The
+cost formula is ported from agentsview ``cmd/agentsview/usage.go:738-771`` (MIT, see
+THIRD_PARTY_LICENSES.md). Anthropic rates are the authoritative current rates (verified
+against the bundled ``claude-api`` skill on 2026-06-17); OpenAI/Codex rates are from
+agentsview ``internal/pricing/fallback.go``. Cache rates follow Anthropic's standard
+multipliers: cache-creation = 1.25x input, cache-read = 0.10x input.
+
+Rates are USD per million tokens (per-MTok). ``cost_for`` returns USD for one usage row.
+``resolve_model`` ports agentsview's 4-stage matcher (``internal/pricing/normalize.go``):
+resolve a logged model id to a table key ONCE at ingest, store the resolved key, so the
+analytics SQL stays a plain equijoin against ``model_pricing``.
+
+Stdlib-only (Python 3.12, never raises into hot paths).
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+
+# Bump when the rates below change so a re-seed re-upserts (mirrors agentsview's
+# FallbackVersion discipline). zeno's own reconciliation date.
+PRICING_VERSION = "2026-06-17"
+
+# 1M / 200K context windows are powered into the peak-context-pct lens (zeno addition).
+_M = 1_000_000
+
+# model_pattern -> rate row. cache_* default to 0 (graceful: 0 contribution, never a
+# silent partial). context_window is None where not authoritative (OpenAI/Codex).
+FALLBACK_PRICING: tuple[dict[str, object], ...] = (
+    # --- Anthropic (authoritative current rates; cache = 1.25x / 0.10x of input) ---
+    {
+        "model_pattern": "claude-opus-4-8",
+        "input_per_mtok": 5.0,
+        "output_per_mtok": 25.0,
+        "cache_creation_per_mtok": 6.25,
+        "cache_read_per_mtok": 0.50,
+        "context_window": _M,
+    },
+    {
+        "model_pattern": "claude-opus-4-7",
+        "input_per_mtok": 5.0,
+        "output_per_mtok": 25.0,
+        "cache_creation_per_mtok": 6.25,
+        "cache_read_per_mtok": 0.50,
+        "context_window": _M,
+    },
+    {
+        "model_pattern": "claude-opus-4-6",
+        "input_per_mtok": 5.0,
+        "output_per_mtok": 25.0,
+        "cache_creation_per_mtok": 6.25,
+        "cache_read_per_mtok": 0.50,
+        "context_window": _M,
+    },
+    {
+        "model_pattern": "claude-opus-4-5",
+        "input_per_mtok": 5.0,
+        "output_per_mtok": 25.0,
+        "cache_creation_per_mtok": 6.25,
+        "cache_read_per_mtok": 0.50,
+        "context_window": _M,
+    },
+    {
+        "model_pattern": "claude-sonnet-4-6",
+        "input_per_mtok": 3.0,
+        "output_per_mtok": 15.0,
+        "cache_creation_per_mtok": 3.75,
+        "cache_read_per_mtok": 0.30,
+        "context_window": _M,
+    },
+    {
+        "model_pattern": "claude-sonnet-4-5",
+        "input_per_mtok": 3.0,
+        "output_per_mtok": 15.0,
+        "cache_creation_per_mtok": 3.75,
+        "cache_read_per_mtok": 0.30,
+        "context_window": _M,
+    },
+    {
+        "model_pattern": "claude-haiku-4-5",
+        "input_per_mtok": 1.0,
+        "output_per_mtok": 5.0,
+        "cache_creation_per_mtok": 1.25,
+        "cache_read_per_mtok": 0.10,
+        "context_window": 200_000,
+    },
+    {
+        "model_pattern": "claude-fable-5",
+        "input_per_mtok": 10.0,
+        "output_per_mtok": 50.0,
+        "cache_creation_per_mtok": 12.50,
+        "cache_read_per_mtok": 1.0,
+        "context_window": _M,
+    },
+    # --- OpenAI / Codex (from agentsview fallback.go) ---
+    {
+        "model_pattern": "gpt-5.5",
+        "input_per_mtok": 5.0,
+        "output_per_mtok": 30.0,
+        "cache_creation_per_mtok": 0.0,
+        "cache_read_per_mtok": 0.50,
+        "context_window": None,
+    },
+    {
+        "model_pattern": "gpt-5.4",
+        "input_per_mtok": 2.50,
+        "output_per_mtok": 15.0,
+        "cache_creation_per_mtok": 0.0,
+        "cache_read_per_mtok": 0.0,
+        "context_window": None,
+    },
+    {
+        "model_pattern": "gpt-5.4-mini",
+        "input_per_mtok": 0.75,
+        "output_per_mtok": 4.50,
+        "cache_creation_per_mtok": 0.0,
+        "cache_read_per_mtok": 0.0,
+        "context_window": None,
+    },
+    {
+        "model_pattern": "gpt-5.4-nano",
+        "input_per_mtok": 0.20,
+        "output_per_mtok": 1.25,
+        "cache_creation_per_mtok": 0.0,
+        "cache_read_per_mtok": 0.0,
+        "context_window": None,
+    },
+    {
+        "model_pattern": "gpt-5.3-codex",
+        "input_per_mtok": 1.75,
+        "output_per_mtok": 14.0,
+        "cache_creation_per_mtok": 0.0,
+        "cache_read_per_mtok": 0.0,
+        "context_window": None,
+    },
+    {
+        "model_pattern": "gpt-5.2-codex",
+        "input_per_mtok": 1.75,
+        "output_per_mtok": 14.0,
+        "cache_creation_per_mtok": 0.0,
+        "cache_read_per_mtok": 0.0,
+        "context_window": None,
+    },
+    {
+        "model_pattern": "gpt-5.1-codex-max",
+        "input_per_mtok": 1.25,
+        "output_per_mtok": 10.0,
+        "cache_creation_per_mtok": 0.0,
+        "cache_read_per_mtok": 0.0,
+        "context_window": None,
+    },
+)
+
+_RATE_FIELDS = (
+    "input_per_mtok",
+    "output_per_mtok",
+    "cache_creation_per_mtok",
+    "cache_read_per_mtok",
+)
+
+
+def seed_pricing(con: sqlite3.Connection) -> int:
+    """Insert the bundled rate table into model_pricing without clobbering richer rows.
+
+    ``INSERT ... ON CONFLICT DO NOTHING`` so an operator who later refreshes a row from
+    LiteLLM keeps it. Returns the number of rows inserted. Assumes the table exists.
+    """
+    n = 0
+    for row in FALLBACK_PRICING:
+        cur = con.execute(
+            "INSERT INTO model_pricing "
+            "(model_pattern, input_per_mtok, output_per_mtok, "
+            " cache_creation_per_mtok, cache_read_per_mtok, context_window) "
+            "VALUES (?,?,?,?,?,?) ON CONFLICT(model_pattern) DO NOTHING",
+            (
+                row["model_pattern"],
+                row["input_per_mtok"],
+                row["output_per_mtok"],
+                row["cache_creation_per_mtok"],
+                row["cache_read_per_mtok"],
+                row["context_window"],
+            ),
+        )
+        n += cur.rowcount or 0
+    return n
+
+
+def cost_for(tokens: dict[str, float], rate: dict[str, float] | None) -> float | None:
+    """USD for one usage row given a rate row. None when unpriced (no matching rate).
+
+    cost = (input*in + output*out + cache_creation*cc + cache_read*cr) / 1e6
+    Missing token fields count as 0; a missing rate returns None (never a silent 0 total).
+    """
+    if not rate:
+        return None
+    try:
+        return (
+            float(tokens.get("input_tokens", 0) or 0) * float(rate.get("input_per_mtok", 0) or 0)
+            + float(tokens.get("output_tokens", 0) or 0)
+            * float(rate.get("output_per_mtok", 0) or 0)
+            + float(tokens.get("cache_creation_input_tokens", 0) or 0)
+            * float(rate.get("cache_creation_per_mtok", 0) or 0)
+            + float(tokens.get("cache_read_input_tokens", 0) or 0)
+            * float(rate.get("cache_read_per_mtok", 0) or 0)
+        ) / 1_000_000.0
+    except Exception:
+        return None
+
+
+def cache_savings(tokens: dict[str, float], rate: dict[str, float] | None) -> float | None:
+    """USD saved by caching vs paying full input rate (ccusage-class). May be negative
+    on write-heavy sessions (cache creation can cost more than the input it replaced) -
+    do NOT clamp; a negative value is itself the finding. None when unpriced."""
+    if not rate:
+        return None
+    try:
+        in_rate = float(rate.get("input_per_mtok", 0) or 0)
+        read = float(tokens.get("cache_read_input_tokens", 0) or 0) * (
+            in_rate - float(rate.get("cache_read_per_mtok", 0) or 0)
+        )
+        cr = float(tokens.get("cache_creation_input_tokens", 0) or 0) * (
+            in_rate - float(rate.get("cache_creation_per_mtok", 0) or 0)
+        )
+        return (read + cr) / 1_000_000.0
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# model-name resolution (agentsview normalize.go 4-stage matcher)
+# ---------------------------------------------------------------------------
+_PROVIDER_PREFIX = re.compile(r"^[a-z0-9_]+/")
+_TRAILING_DATE = re.compile(r"-\d{8}$")
+_TRAILING_GROUP = re.compile(r"[(\[][^)\]]*[)\]]$")
+_NON_ALNUM = re.compile(r"[^a-z0-9]")
+
+
+def _canonical(name: str) -> str:
+    """Stage-4 canonical form: lowercase, strip one provider prefix, strip one trailing
+    (...)/[...] group, strip one trailing -YYYYMMDD, drop all non-alphanumerics."""
+    s = name.strip().lower()
+    s = _PROVIDER_PREFIX.sub("", s, count=1)
+    s = _TRAILING_GROUP.sub("", s).strip()
+    s = _TRAILING_DATE.sub("", s)
+    return _NON_ALNUM.sub("", s)
+
+
+def resolve_model(name: str, patterns: tuple[str, ...] | list[str]) -> str | None:
+    """Resolve a logged model id to a known pricing pattern, or None if unresolved.
+
+    Four stages, no arbitrary substring match (so ``gpt-5.5`` never silently matches
+    ``gpt-5.5-codex``); an ambiguous canonical tie stays unresolved. Resolve once at
+    ingest and store the result so SQL stays a plain equijoin.
+    """
+    if not name:
+        return None
+    pats = list(patterns)
+    # 1. exact
+    if name in pats:
+        return name
+    # 2. dots -> dashes
+    dashed = name.replace(".", "-")
+    for p in pats:
+        if p == dashed or p.replace(".", "-") == dashed:
+            return p
+    # 3. case-insensitive
+    low = name.lower()
+    for p in pats:
+        if p.lower() == low:
+            return p
+    # 4. canonical, with ambiguity guard
+    target = _canonical(name)
+    if not target:
+        return None
+    matches = [p for p in pats if _canonical(p) == target]
+    if len(matches) == 1:
+        return matches[0]
+    return None  # 0 matches, or ambiguous tie -> unresolved

zeno_session_intel/schema.py

@@ -0,0 +1,277 @@
+"""Canonical SQLite schema for the session-intelligence tables (single source of truth).
+
+These tables are an ADDITIVE, derived cache of coding-agent transcripts. They sit
+ALONGSIDE zeno's primary capture (``sessions``/``agent_runs``/``cognition_samples``)
+and never replace it: agentsview-derived tables score *agent* behavior (token/cost,
+tool health, outcomes), while ``cognition_samples`` scores *human* cognition. The two
+are orthogonal and complementary.
+
+Schema + analytics design is adapted from agentsview (MIT, (c) 2026 Kenn Software LLC).
+The FTS5 virtual table + triggers are ported verbatim (``internal/db/db.go:261-277``);
+the table/column shapes map from ``internal/db/schema.sql``. See THIRD_PARTY_LICENSES.md.
+
+Naming: agentsview's ``sessions``/``messages`` collide with zeno's existing tables, so
+they are namespaced ``transcript_*``. ``token_usage_events`` is the cache-aware billing
+ledger (deduped); ``model_pricing`` is the per-MTok rate table.
+
+This module is stdlib-only (Python 3.12, never raises into the caller) so the ingester
+(a stdlib ``sqlite3`` writer) and the dashboard export scripts can both create + read the
+tables without importing the heavy SDK. The alembic migration
+``packages/sdk-python/alembic/versions/0004_transcript_intelligence.py`` mirrors this
+schema for the SDK-managed DB; the schema-drift test
+(``tests/test_session_intel_schema.py``) guards the two from diverging.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+# ---------------------------------------------------------------------------
+# column definitions: (name, sqlite_decl). Order is the literal CREATE order.
+# ---------------------------------------------------------------------------
+
+TRANSCRIPT_SESSIONS_COLUMNS: tuple[tuple[str, str], ...] = (
+    ("id", "TEXT PRIMARY KEY"),  # CC/Cursor/Codex session id
+    ("zeno_session_id", "TEXT"),  # soft bridge -> sessions.id (lifecycles differ; no hard FK)
+    ("agent", "TEXT NOT NULL DEFAULT 'claude'"),  # claude|codex|cursor
+    ("project", "TEXT NOT NULL DEFAULT ''"),
+    ("machine", "TEXT NOT NULL DEFAULT 'local'"),
+    ("first_message", "TEXT"),
+    ("display_name", "TEXT"),
+    ("started_at", "TEXT"),
+    ("ended_at", "TEXT"),
+    ("message_count", "INTEGER NOT NULL DEFAULT 0"),
+    ("user_message_count", "INTEGER NOT NULL DEFAULT 0"),
+    # token rollups (cache-aware) -- schema.sql:23-26
+    ("total_output_tokens", "INTEGER NOT NULL DEFAULT 0"),
+    ("peak_context_tokens", "INTEGER NOT NULL DEFAULT 0"),
+    # behavioral health signals -- schema.sql:27-41 / signals/score.go inputs
+    ("is_automated", "INTEGER NOT NULL DEFAULT 0"),
+    ("tool_failure_signal_count", "INTEGER NOT NULL DEFAULT 0"),
+    ("tool_retry_count", "INTEGER NOT NULL DEFAULT 0"),
+    ("edit_churn_count", "INTEGER NOT NULL DEFAULT 0"),
+    ("consecutive_failure_max", "INTEGER NOT NULL DEFAULT 0"),
+    ("outcome", "TEXT NOT NULL DEFAULT 'unknown'"),
+    ("outcome_confidence", "TEXT NOT NULL DEFAULT 'low'"),
+    ("ended_with_role", "TEXT NOT NULL DEFAULT ''"),
+    ("final_failure_streak", "INTEGER NOT NULL DEFAULT 0"),
+    ("compaction_count", "INTEGER NOT NULL DEFAULT 0"),
+    ("mid_task_compaction_count", "INTEGER NOT NULL DEFAULT 0"),
+    ("context_pressure_max", "REAL"),
+    ("health_score", "INTEGER"),
+    ("health_grade", "TEXT"),
+    # capability flags / env
+    ("has_tool_calls", "INTEGER NOT NULL DEFAULT 0"),
+    ("has_context_data", "INTEGER NOT NULL DEFAULT 0"),
+    ("cwd", "TEXT NOT NULL DEFAULT ''"),
+    ("git_branch", "TEXT NOT NULL DEFAULT ''"),
+    # ingest identity (idempotency -- zeno additions)
+    ("file_path", "TEXT"),
+    ("file_mtime", "INTEGER"),
+    ("content_hash", "TEXT"),
+    ("created_at", "TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))"),
+)
+
+TRANSCRIPT_MESSAGES_COLUMNS: tuple[tuple[str, str], ...] = (
+    ("id", "INTEGER PRIMARY KEY"),  # rowid alias == FTS5 content_rowid (do NOT make composite)
+    ("session_id", "TEXT NOT NULL REFERENCES transcript_sessions(id) ON DELETE CASCADE"),
+    ("ordinal", "INTEGER NOT NULL"),
+    ("role", "TEXT NOT NULL"),
+    ("content", "TEXT NOT NULL"),
+    ("thinking_text", "TEXT NOT NULL DEFAULT ''"),
+    ("timestamp", "TEXT"),
+    ("has_thinking", "INTEGER NOT NULL DEFAULT 0"),
+    ("has_tool_use", "INTEGER NOT NULL DEFAULT 0"),
+    ("content_length", "INTEGER NOT NULL DEFAULT 0"),
+    ("model", "TEXT NOT NULL DEFAULT ''"),
+    ("token_usage", "TEXT NOT NULL DEFAULT ''"),  # raw usage JSON (provenance)
+    ("context_tokens", "INTEGER NOT NULL DEFAULT 0"),
+    ("output_tokens", "INTEGER NOT NULL DEFAULT 0"),
+    ("source_uuid", "TEXT NOT NULL DEFAULT ''"),
+    ("source_parent_uuid", "TEXT NOT NULL DEFAULT ''"),  # threading DAG
+    ("is_sidechain", "INTEGER NOT NULL DEFAULT 0"),  # subagent branch
+    ("is_compact_boundary", "INTEGER NOT NULL DEFAULT 0"),
+)
+
+TOKEN_USAGE_EVENTS_COLUMNS: tuple[tuple[str, str], ...] = (
+    ("id", "INTEGER PRIMARY KEY"),
+    ("session_id", "TEXT NOT NULL REFERENCES transcript_sessions(id) ON DELETE CASCADE"),
+    ("message_ordinal", "INTEGER"),  # NULL = session-level event
+    ("source", "TEXT NOT NULL"),  # claude|codex|cursor
+    ("model", "TEXT NOT NULL"),  # resolved model_pattern (so cost is a plain equijoin)
+    ("input_tokens", "INTEGER NOT NULL DEFAULT 0"),
+    ("output_tokens", "INTEGER NOT NULL DEFAULT 0"),
+    ("cache_creation_input_tokens", "INTEGER NOT NULL DEFAULT 0"),
+    ("cache_read_input_tokens", "INTEGER NOT NULL DEFAULT 0"),
+    ("reasoning_tokens", "INTEGER NOT NULL DEFAULT 0"),
+    ("cost_usd", "REAL"),  # NULL = unpriced
+    ("cost_status", "TEXT NOT NULL DEFAULT ''"),  # ''|computed|reported (zeno enum)
+    ("cost_source", "TEXT NOT NULL DEFAULT ''"),  # computed|reported
+    ("occurred_at", "TEXT"),
+    ("dedup_key", "TEXT NOT NULL DEFAULT ''"),  # stable per-event id (idempotency)
+)
+
+TRANSCRIPT_TOOL_CALLS_COLUMNS: tuple[tuple[str, str], ...] = (
+    ("id", "INTEGER PRIMARY KEY"),
+    ("session_id", "TEXT NOT NULL REFERENCES transcript_sessions(id) ON DELETE CASCADE"),
+    ("message_ordinal", "INTEGER NOT NULL DEFAULT 0"),
+    ("ordinal_in_message", "INTEGER NOT NULL DEFAULT 0"),
+    ("tool_name", "TEXT NOT NULL DEFAULT ''"),
+    ("category", "TEXT NOT NULL DEFAULT 'Other'"),  # one of taxonomy.CATEGORIES
+    ("is_error", "INTEGER NOT NULL DEFAULT 0"),  # matched tool_result failure
+    ("source", "TEXT NOT NULL DEFAULT ''"),  # claude|codex|cursor
+)
+
+MODEL_PRICING_COLUMNS: tuple[tuple[str, str], ...] = (
+    ("model_pattern", "TEXT PRIMARY KEY"),
+    ("input_per_mtok", "REAL NOT NULL DEFAULT 0"),
+    ("output_per_mtok", "REAL NOT NULL DEFAULT 0"),
+    ("cache_creation_per_mtok", "REAL NOT NULL DEFAULT 0"),
+    ("cache_read_per_mtok", "REAL NOT NULL DEFAULT 0"),
+    ("context_window", "INTEGER"),  # zeno addition: powers the peak-context-pct lens
+    ("updated_at", "TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))"),
+)
+
+# table_name -> column tuple (drives the drift test + the generic create path)
+TABLES: dict[str, tuple[tuple[str, str], ...]] = {
+    "transcript_sessions": TRANSCRIPT_SESSIONS_COLUMNS,
+    "transcript_messages": TRANSCRIPT_MESSAGES_COLUMNS,
+    "transcript_tool_calls": TRANSCRIPT_TOOL_CALLS_COLUMNS,
+    "token_usage_events": TOKEN_USAGE_EVENTS_COLUMNS,
+    "model_pricing": MODEL_PRICING_COLUMNS,
+}
+
+# non-FTS indexes (name, sql). Mirrored in the alembic migration.
+INDEXES: tuple[tuple[str, str], ...] = (
+    (
+        "idx_transcript_sessions_ended",
+        "CREATE INDEX IF NOT EXISTS idx_transcript_sessions_ended "
+        "ON transcript_sessions (ended_at DESC, id)",
+    ),
+    (
+        "idx_transcript_sessions_agent",
+        "CREATE INDEX IF NOT EXISTS idx_transcript_sessions_agent "
+        "ON transcript_sessions (agent)",
+    ),
+    (
+        "idx_transcript_sessions_project",
+        "CREATE INDEX IF NOT EXISTS idx_transcript_sessions_project "
+        "ON transcript_sessions (project)",
+    ),
+    (
+        "idx_transcript_sessions_zeno",
+        "CREATE INDEX IF NOT EXISTS idx_transcript_sessions_zeno "
+        "ON transcript_sessions (zeno_session_id)",
+    ),
+    (
+        "idx_transcript_messages_session_ordinal",
+        "CREATE UNIQUE INDEX IF NOT EXISTS idx_transcript_messages_session_ordinal "
+        "ON transcript_messages (session_id, ordinal)",
+    ),
+    (
+        "idx_transcript_messages_session_role",
+        "CREATE INDEX IF NOT EXISTS idx_transcript_messages_session_role "
+        "ON transcript_messages (session_id, role)",
+    ),
+    (
+        "idx_transcript_tool_calls_session",
+        "CREATE INDEX IF NOT EXISTS idx_transcript_tool_calls_session "
+        "ON transcript_tool_calls (session_id)",
+    ),
+    (
+        "idx_transcript_tool_calls_category",
+        "CREATE INDEX IF NOT EXISTS idx_transcript_tool_calls_category "
+        "ON transcript_tool_calls (category)",
+    ),
+    (
+        "idx_token_usage_events_dedup",
+        "CREATE UNIQUE INDEX IF NOT EXISTS idx_token_usage_events_dedup "
+        "ON token_usage_events (session_id, source, dedup_key) WHERE dedup_key != ''",
+    ),
+    (
+        "idx_token_usage_events_session",
+        "CREATE INDEX IF NOT EXISTS idx_token_usage_events_session "
+        "ON token_usage_events (session_id)",
+    ),
+    (
+        "idx_token_usage_events_occurred",
+        "CREATE INDEX IF NOT EXISTS idx_token_usage_events_occurred "
+        "ON token_usage_events (occurred_at)",
+    ),
+)
+
+# FTS5 over transcript_messages.content. Ported verbatim from agentsview db.go:261-277,
+# renamed messages -> transcript_messages. `porter unicode61` is the search-quality
+# contract; the content/content_rowid pairing makes it an external-content index synced
+# by the triggers below. Optional: skipped (logged) on SQLite builds without fts5.
+FTS_TABLE = "transcript_messages_fts"
+FTS_DDL = """
+CREATE VIRTUAL TABLE IF NOT EXISTS transcript_messages_fts USING fts5(
+    content,
+    content='transcript_messages',
+    content_rowid='id',
+    tokenize='porter unicode61'
+);
+CREATE TRIGGER IF NOT EXISTS transcript_messages_ai
+AFTER INSERT ON transcript_messages BEGIN
+    INSERT INTO transcript_messages_fts(rowid, content) VALUES (new.id, new.content);
+END;
+CREATE TRIGGER IF NOT EXISTS transcript_messages_ad
+AFTER DELETE ON transcript_messages BEGIN
+    INSERT INTO transcript_messages_fts(transcript_messages_fts, rowid, content)
+        VALUES ('delete', old.id, old.content);
+END;
+CREATE TRIGGER IF NOT EXISTS transcript_messages_au
+AFTER UPDATE ON transcript_messages BEGIN
+    INSERT INTO transcript_messages_fts(transcript_messages_fts, rowid, content)
+        VALUES ('delete', old.id, old.content);
+    INSERT INTO transcript_messages_fts(rowid, content) VALUES (new.id, new.content);
+END;
+"""
+
+
+def _create_table_sql(name: str, columns: tuple[tuple[str, str], ...]) -> str:
+    cols = ",\n  ".join(f"{n} {decl}" for n, decl in columns)
+    return f"CREATE TABLE IF NOT EXISTS {name} (\n  {cols}\n)"
+
+
+def fts5_available(con: sqlite3.Connection) -> bool:
+    """True when the SQLite build has the fts5 module compiled in. Never raises."""
+    try:
+        con.execute("CREATE VIRTUAL TABLE temp._zeno_fts5_probe USING fts5(x)")
+        con.execute("DROP TABLE temp._zeno_fts5_probe")
+        return True
+    except Exception:
+        return False
+
+
+def ensure_schema(con: sqlite3.Connection) -> bool:
+    """Create the session-intelligence tables + indexes + FTS5 if missing. Idempotent.
+
+    Returns True if FTS5 was set up, False if the SQLite build lacks the fts5 module
+    (search degrades but ingest still works). Never raises into the caller; works on a
+    fresh DB and is a no-op when everything already exists.
+    """
+    con.execute("PRAGMA foreign_keys = ON")
+    for name, columns in TABLES.items():
+        con.execute(_create_table_sql(name, columns))
+    for _name, sql in INDEXES:
+        con.execute(sql)
+    if fts5_available(con):
+        con.executescript(FTS_DDL)
+        return True
+    return False
+
+
+def rebuild_fts(con: sqlite3.Connection) -> None:
+    """Rebuild the external-content FTS index from transcript_messages.
+
+    Used after a bulk reload where triggers were bypassed. No-op without fts5.
+    """
+    if fts5_available(con):
+        try:
+            con.execute(
+                "INSERT INTO transcript_messages_fts(transcript_messages_fts) VALUES('rebuild')"
+            )
+        except Exception:
+            pass