zeno-cli 0.3.4__py3-none-any.whl

zeno_session_intel/compression.py

@@ -0,0 +1,123 @@
+"""Directional "tokens you could have saved" estimator over captured content.
+
+Measures how much of your captured agent content is SAFELY compressible, segmented
+by type. Code and tracebacks are never counted as compressible: lossy token-level
+compression corrupts them (near-0% exact-match on repo-level code completion; it
+drops a SWE-bench agent from 62% to 54%), so the savings come only from redundant
+JSON / logs / listings. See the zeno-compression-decision memo.
+
+This is a MEASURE, never an inline compressor: the agent request path is never
+touched. Heuristic + directional, stdlib-only, py3.9-safe.
+"""
+
+from __future__ import annotations
+
+import functools
+import re
+
+# Rough chars-per-token for mixed Claude/GPT-family content. Directional only.
+CHARS_PER_TOKEN = 4.0
+
+# Safely-compressible fraction by content type. Conservative + directional.
+# code / traceback = 0.0 ON PURPOSE: lossy compression destroys exact tokens
+# (file paths, line numbers, identifiers, syntax). Never claim savings there.
+COMPRESSIBLE_FRACTION: dict[str, float] = {
+    "json": 0.55,
+    "log": 0.45,
+    "code": 0.0,
+    "traceback": 0.0,
+    "prose": 0.10,
+}
+
+_JSON_RE = re.compile(r"^\s*[\[{]")
+_TRACEBACK_RE = re.compile(
+    r"Traceback \(most recent call last\)|^\s+File \".*\", line \d+",
+    re.MULTILINE,
+)
+# Unified / git diffs are exact-token (paths, hunk headers, line numbers); never compress.
+_DIFF_RE = re.compile(r"^(diff --git |@@ -|\+\+\+ |--- |[+-]\S)", re.MULTILINE)
+_LOG_RE = re.compile(
+    r"^\s*(\d{4}-\d\d-\d\d[ T]\d\d:\d\d|\[\d{2}:\d{2}|DEBUG|INFO|WARN|ERROR|TRACE)\b",
+    re.MULTILINE,
+)
+# Broad, multi-language/markup code shape: anything code-like must land in the
+# 0%-savable bucket (the cardinal sin is crediting code as compressible). Covers
+# keywords across Python/JS/Go/Rust/Java/C-likes, arrows, line-end semicolons,
+# HTML/XML tags, CSS selector blocks, and unquoted YAML/key: lines.
+_CODE_RE = re.compile(
+    r"\b(def|class|import|from|func|fn|function|const|let|var|return|public|private|package|struct|impl|fun)\b"
+    r"|=>|->|;\s*$|</?[a-zA-Z][\w-]*[\s/>]|^[.#]?[\w-]+\s*\{|^\s*[\w.-]+:\s",
+    re.MULTILINE,
+)
+
+
+@functools.lru_cache(maxsize=4096)
+def _classify_cached(text: str) -> str:
+    """Memoized classify over the exact content string.
+
+    The compression scan re-sees the same blob shapes thousands of times (tool
+    output, listings, repeated JSON), so caching on the content collapses the
+    per-chunk regex sweep from O(rows) to O(distinct-content). The label is a
+    pure function of ``text``, so the cache is BYTE-IDENTICAL to the uncached
+    path - this is a speed-only change. ``lru_cache`` is bounded so a large,
+    high-cardinality scan never grows memory without limit; on a cache miss past
+    the bound it just recomputes (still correct, just not cached)."""
+    return _classify_impl(text)
+
+
+def classify(text: str) -> str:
+    """Best-effort single content-type label for a chunk of captured content.
+
+    Order is deliberate: traceback -> diff -> CODE (before JSON, so a brace-opening
+    object literal / block lands as code, not json) -> json -> log -> prose. For a
+    large blob we run the regexes over a head + interior + tail sample, so a code or
+    traceback tail after a benign 2000-char head is not mislabeled. Anything not
+    confidently redundant (genuine json/log) ends up code (0) or prose (0.1); we
+    never over-credit code as compressible.
+
+    Content-memoized: identical text returns the identical label without re-running
+    the regexes. The label depends only on ``text``, so the memo is byte-identical
+    to recomputing every call."""
+    # Empty / whitespace-only is the cheap common case and not worth a cache slot.
+    if not text or not text.strip():
+        return "prose"
+    return _classify_cached(text)
+
+
+def _classify_impl(text: str) -> str:
+    """Pure classifier (the original body). Callers go through ``classify`` so the
+    content memo applies; kept separate so the memo wraps a single pure function."""
+    if not text or not text.strip():
+        return "prose"
+    n = len(text)
+    if n > 6000:
+        sample = text[:2000] + "\n" + text[n // 2 - 1000 : n // 2 + 1000] + "\n" + text[-2000:]
+    else:
+        sample = text
+    if _TRACEBACK_RE.search(sample):
+        return "traceback"
+    if _DIFF_RE.search(sample):
+        return "code"
+    if len(_CODE_RE.findall(sample)) >= 2:
+        return "code"
+    if _JSON_RE.match(text) and (sample.count("{") + sample.count("[")) >= 2:
+        return "json"
+    if len(_LOG_RE.findall(sample)) >= 3:
+        return "log"
+    return "prose"
+
+
+def est_tokens(text: str) -> int:
+    """Rough token count from character length. Directional only."""
+    return int(len(text) / CHARS_PER_TOKEN)
+
+
+def estimate(text: str) -> dict:
+    """Classify a chunk and estimate its safely-savable tokens."""
+    content_type = classify(text)
+    tokens = est_tokens(text)
+    return {
+        "type": content_type,
+        "tokens": tokens,
+        "savable_tokens": int(tokens * COMPRESSIBLE_FRACTION[content_type]),
+    }

zeno_session_intel/ingest.py

@@ -0,0 +1,376 @@
+"""Multi-tool session ingester: discover -> parse -> extract signals -> idempotent write.
+
+Passively reads coding-agent session files (Claude Code, Cursor, Codex) READ-ONLY and
+writes the agentsview-shaped session-intelligence tables into zeno's local SQLite.
+Idempotent at three layers (session content-hash skip, message ``(session_id, ordinal)``
+replace, usage ``dedup_key`` partial-unique). Stdlib-only; never writes to source files.
+
+Tool status (this build is Claude-Code-first - see docs/TOOLS_STATUS.md):
+  - PRIMARY: ``claude`` (Claude Code) - the first-class capture path, validated on real data.
+  - CAPTURE-ONLY: ``cursor`` - validated against real local data, no SDK adapter; LATER.
+  - EXPERIMENTAL: ``codex`` - fixture-verified only (no real Codex install was available),
+    so it is an explicit opt-in ``--tools`` value, never advertised as a default - pointing
+    it at a divergently shaped real rollout can drop a whole session silently. Promote it
+    once a real ``~/.codex/.../rollout-*.jsonl`` confirms the schema.
+
+CLI::
+
+    python -m zeno_session_intel.ingest --db /path/to/dev.db --tools claude,cursor
+    python -m zeno_session_intel.ingest --db dev.db --tools claude --root claude=~/.claude/projects
+
+The default DB is the SDK capture path (``ZENO_DB_PATH`` / ``ZENO_HOME`` / ~/.zeno/zeno.db).
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sqlite3
+import sys
+from pathlib import Path
+
+from . import prices, schema
+from .model import ParsedSession
+from .parsers import REGISTRY
+from .signals import extract_signals
+from .taxonomy import normalize_tool_category
+
+_SESSION_INSERT_COLS = tuple(name for name, _ in schema.TRANSCRIPT_SESSIONS_COLUMNS)
+
+
+def default_db_path() -> str:
+    base = os.environ.get("ZENO_HOME") or os.path.join(os.path.expanduser("~"), ".zeno")
+    return os.environ.get("ZENO_DB_PATH") or os.path.join(base, "zeno.db")
+
+
+def _content_hash(session: ParsedSession) -> str:
+    h = hashlib.sha256()
+    for m in session.messages:
+        h.update(
+            json.dumps(
+                [
+                    m.ordinal,
+                    m.role,
+                    m.content,
+                    [tu.name for tu in m.tool_uses],
+                    [tr.tool_use_id for tr in m.tool_results],
+                    m.usage_dedup_key,
+                    m.context_tokens,
+                    m.output_tokens,
+                ],
+                sort_keys=True,
+            ).encode()
+        )
+    return h.hexdigest()
+
+
+def _load_pricing(con: sqlite3.Connection) -> tuple[dict[str, dict], list[str]]:
+    rows = con.execute(
+        "SELECT model_pattern, input_per_mtok, output_per_mtok, cache_creation_per_mtok, "
+        "cache_read_per_mtok, context_window FROM model_pricing"
+    ).fetchall()
+    rate_by_pattern: dict[str, dict] = {}
+    for r in rows:
+        rate_by_pattern[r[0]] = {
+            "input_per_mtok": r[1],
+            "output_per_mtok": r[2],
+            "cache_creation_per_mtok": r[3],
+            "cache_read_per_mtok": r[4],
+            "context_window": r[5],
+        }
+    return rate_by_pattern, list(rate_by_pattern.keys())
+
+
+def _dominant_model(session: ParsedSession) -> str:
+    counts: dict[str, int] = {}
+    for m in session.messages:
+        if m.model:
+            counts[m.model] = counts.get(m.model, 0) + 1
+    if not counts:
+        return ""
+    return max(counts.items(), key=lambda kv: kv[1])[0]
+
+
+def ingest_session(
+    con: sqlite3.Connection,
+    session: ParsedSession,
+    rate_by_pattern: dict[str, dict],
+    patterns: list[str],
+) -> str:
+    """Write one parsed session idempotently. Returns 'inserted' | 'updated' | 'skipped'."""
+    chash = _content_hash(session)
+    existing = con.execute(
+        "SELECT content_hash FROM transcript_sessions WHERE id=?", (session.id,)
+    ).fetchone()
+    status = "inserted"
+    if existing is not None:
+        if existing[0] == chash:
+            return "skipped"
+        status = "updated"
+        # ReplaceSessionMessages: clear derived rows for this session, then re-insert.
+        con.execute("DELETE FROM transcript_messages WHERE session_id=?", (session.id,))
+        con.execute("DELETE FROM transcript_tool_calls WHERE session_id=?", (session.id,))
+        con.execute("DELETE FROM token_usage_events WHERE session_id=?", (session.id,))
+        con.execute("DELETE FROM transcript_sessions WHERE id=?", (session.id,))
+
+    # tool_use_id -> is_error, so each tool call carries its result's failure flag
+    result_error: dict[str, bool] = {}
+    for m in session.messages:
+        for tr in m.tool_results:
+            if tr.tool_use_id:
+                result_error[tr.tool_use_id] = tr.is_error
+
+    dom_model = _dominant_model(session)
+    resolved_dom = prices.resolve_model(dom_model, patterns) if dom_model else None
+    window = None
+    if resolved_dom:
+        window = (rate_by_pattern.get(resolved_dom) or {}).get("context_window")
+    sig = extract_signals(session, context_window=window)
+    boundary_ordinals = set(sig.compaction_boundaries)
+
+    row = {
+        "id": session.id,
+        "zeno_session_id": None,
+        "agent": session.agent,
+        "project": session.project or "",
+        "machine": session.machine or "local",
+        "first_message": session.first_message,
+        "display_name": session.display_name,
+        "started_at": session.started_at,
+        "ended_at": session.ended_at,
+        "message_count": sig.message_count,
+        "user_message_count": sig.user_message_count,
+        "total_output_tokens": sig.total_output_tokens,
+        "peak_context_tokens": sig.peak_context_tokens,
+        "is_automated": int(sig.is_automated),
+        "tool_failure_signal_count": sig.tool_failure_signal_count,
+        "tool_retry_count": sig.tool_retry_count,
+        "edit_churn_count": sig.edit_churn_count,
+        "consecutive_failure_max": sig.consecutive_failure_max,
+        "outcome": sig.outcome,
+        "outcome_confidence": sig.outcome_confidence,
+        "ended_with_role": sig.ended_with_role,
+        "final_failure_streak": sig.final_failure_streak,
+        "compaction_count": sig.compaction_count,
+        "mid_task_compaction_count": sig.mid_task_compaction_count,
+        "context_pressure_max": sig.context_pressure_max,
+        "health_score": sig.health_score,
+        "health_grade": sig.health_grade,
+        "has_tool_calls": int(sig.has_tool_calls),
+        "has_context_data": int(sig.has_context_data),
+        "cwd": session.cwd or "",
+        "git_branch": session.git_branch or "",
+        "file_path": session.file_path,
+        "file_mtime": session.file_mtime,
+        "content_hash": chash,
+    }
+    # let the column default stamp created_at
+    cols = [c for c in _SESSION_INSERT_COLS if c != "created_at"]
+    placeholders = ",".join("?" for _ in cols)
+    con.execute(
+        f"INSERT INTO transcript_sessions ({','.join(cols)}) VALUES ({placeholders})",
+        [row[c] for c in cols],
+    )
+
+    for m in session.messages:
+        con.execute(
+            "INSERT INTO transcript_messages "
+            "(session_id, ordinal, role, content, thinking_text, timestamp, has_thinking, "
+            " has_tool_use, content_length, model, token_usage, context_tokens, output_tokens, "
+            " source_uuid, source_parent_uuid, is_sidechain, is_compact_boundary) "
+            "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+            (
+                session.id,
+                m.ordinal,
+                m.role,
+                m.content,
+                m.thinking_text,
+                m.timestamp,
+                int(m.has_thinking),
+                int(m.has_tool_use),
+                len(m.content or ""),
+                m.model,
+                m.raw_usage,
+                m.context_tokens,
+                int(m.output_tokens or 0),
+                m.source_uuid,
+                m.source_parent_uuid,
+                int(m.is_sidechain),
+                int(m.ordinal in boundary_ordinals),
+            ),
+        )
+        for k, tu in enumerate(m.tool_uses):
+            con.execute(
+                "INSERT INTO transcript_tool_calls "
+                "(session_id, message_ordinal, ordinal_in_message, tool_name, category, "
+                " is_error, source) VALUES (?,?,?,?,?,?,?)",
+                (
+                    session.id,
+                    m.ordinal,
+                    k,
+                    tu.name,
+                    normalize_tool_category(tu.name),
+                    int(bool(result_error.get(tu.id, False))),
+                    session.agent,
+                ),
+            )
+        if m.has_usage:
+            resolved = prices.resolve_model(m.model, patterns) if m.model else None
+            rate = rate_by_pattern.get(resolved) if resolved else None
+            tokens = {
+                "input_tokens": m.input_tokens,
+                "output_tokens": m.output_tokens,
+                "cache_creation_input_tokens": m.cache_creation_input_tokens,
+                "cache_read_input_tokens": m.cache_read_input_tokens,
+            }
+            cost = prices.cost_for(tokens, rate)
+            priced = cost is not None
+            con.execute(
+                "INSERT INTO token_usage_events "
+                "(session_id, message_ordinal, source, model, input_tokens, output_tokens, "
+                " cache_creation_input_tokens, cache_read_input_tokens, reasoning_tokens, "
+                " cost_usd, cost_status, cost_source, occurred_at, dedup_key) "
+                "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?) "
+                # the conflict target must repeat the partial index's WHERE predicate
+                "ON CONFLICT(session_id, source, dedup_key) WHERE dedup_key != '' DO NOTHING",
+                (
+                    session.id,
+                    m.ordinal,
+                    session.agent,
+                    resolved or m.model,
+                    m.input_tokens,
+                    m.output_tokens,
+                    m.cache_creation_input_tokens,
+                    m.cache_read_input_tokens,
+                    m.reasoning_tokens,
+                    cost,
+                    "computed" if priced else "",
+                    "computed" if priced else "",
+                    m.timestamp,
+                    m.usage_dedup_key,
+                ),
+            )
+    return status
+
+
+def ingest_tool(
+    con: sqlite3.Connection,
+    tool: str,
+    root: Path | None = None,
+    limit: int | None = None,
+) -> dict[str, int]:
+    """Discover + parse + ingest every session for one tool. Returns a status tally."""
+    mod = REGISTRY[tool]
+    root = mod.default_root() if root is None else Path(root)
+    rate_by_pattern, patterns = _load_pricing(con)
+    # failed = the file/session RAISED; empty = parsed cleanly to zero sessions (a
+    # header-only Cursor vscdb is the common, healthy empty case - not a failure).
+    tally = {"files": 0, "inserted": 0, "updated": 0, "skipped": 0, "failed": 0, "empty": 0}
+    files = mod.discover(root)
+    if limit is not None:
+        files = files[:limit]
+    has_multi = hasattr(mod, "parse_sessions")
+    for path in files:
+        tally["files"] += 1
+        # file-level parse: a raise here loses only this file
+        try:
+            # one source file may hold many sessions (Cursor: a vscdb of composers)
+            if has_multi:
+                parsed = mod.parse_sessions(path)
+            else:
+                one = mod.parse_file(path)
+                parsed = [one] if one is not None else []
+        except Exception:
+            tally["failed"] += 1
+            continue
+        live = [s for s in parsed if s is not None and s.messages]
+        if not live:
+            tally["empty"] += 1  # valid file with nothing to ingest (e.g. header-only)
+            continue
+        # per-session: one bad composer must NOT abandon the rest of the file
+        for session in live:
+            try:
+                status = ingest_session(con, session, rate_by_pattern, patterns)
+                tally[status] += 1
+            except Exception:
+                tally["failed"] += 1
+    return tally
+
+
+def run(
+    db_path: str,
+    tools: list[str],
+    roots: dict[str, Path] | None = None,
+    limit: int | None = None,
+) -> dict[str, dict[str, int]]:
+    """Open the DB, ensure schema + pricing, ingest each tool. Returns per-tool tallies."""
+    roots = roots or {}
+    con = sqlite3.connect(db_path)
+    try:
+        con.execute("PRAGMA journal_mode=WAL")
+        con.execute("PRAGMA busy_timeout=5000")
+        schema.ensure_schema(con)
+        prices.seed_pricing(con)
+        con.commit()
+        results: dict[str, dict[str, int]] = {}
+        for tool in tools:
+            if tool not in REGISTRY:
+                results[tool] = {"error": 1}
+                continue
+            results[tool] = ingest_tool(con, tool, roots.get(tool), limit)
+            con.commit()
+        schema.rebuild_fts(con)
+        con.commit()
+        return results
+    finally:
+        con.close()
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="zeno-ingest", description="Multi-tool session ingester")
+    ap.add_argument("--db", default=default_db_path(), help="target SQLite DB (zeno capture)")
+    ap.add_argument("--tools", default="claude", help="comma-separated: " + ",".join(REGISTRY))
+    ap.add_argument(
+        "--root",
+        action="append",
+        default=[],
+        metavar="TOOL=PATH",
+        help="override a tool's source root, e.g. claude=/path",
+    )
+    ap.add_argument("--limit", type=int, default=None, help="max files per tool (debug)")
+    ap.add_argument(
+        "--write-live",
+        action="store_true",
+        help="confirm writing the live capture DB at ~/.zeno/zeno.db (refused otherwise)",
+    )
+    args = ap.parse_args(argv)
+
+    # Guard the foot-gun: a bare invocation resolves --db to the live ~/.zeno/zeno.db
+    # (the file that also holds the frozen SCED). Refuse to write it without explicit
+    # confirmation; schema there should come from the 0004 alembic migration, not the
+    # ingester's ensure_schema, to keep alembic_version consistent.
+    live_db = os.path.join(os.path.expanduser("~"), ".zeno", "zeno.db")
+    if os.path.abspath(args.db) == os.path.abspath(live_db) and not args.write_live:
+        sys.stderr.write(
+            f"zeno-ingest: refusing to write the live capture DB at {live_db}\n"
+            "  pass --write-live to confirm, or --db <path> for a throwaway DB.\n"
+        )
+        return 2
+
+    tools = [t.strip() for t in args.tools.split(",") if t.strip()]
+    roots: dict[str, Path] = {}
+    for spec in args.root:
+        if "=" in spec:
+            tool, _, path = spec.partition("=")
+            roots[tool.strip()] = Path(os.path.expanduser(path.strip()))
+
+    results = run(args.db, tools, roots, args.limit)
+    json.dump({"db": args.db, "results": results}, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

zeno_session_intel/model.py

@@ -0,0 +1,129 @@
+"""Normalized intermediate representation shared by every tool parser.
+
+A parser's only job is to turn a tool's on-disk session format (Claude Code JSONL,
+Codex rollout JSONL, Cursor vscdb) into a ``ParsedSession``. The signal extractor and
+the writer then operate on this one shape, so adding a tool never touches them.
+
+Stdlib-only dataclasses (Python 3.12).
+
+
+Note: no ``slots=True`` and no 3.10+ runtime constructs - this package must import under
+the system ``python3`` (3.9) the dashboard export scripts use, matching the cognition
+stdlib doctrine. Modern annotations are fine (lazy via ``from __future__``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+_INT64_MAX = 2**63 - 1  # SQLite INTEGER ceiling
+
+
+def to_int(v: object) -> int:
+    """Best-effort token-count coercion that NEVER raises, clamped to ``[0, 2**63-1]``.
+
+    Honors the parser contract ('never raises - a malformed line is skipped'): a corrupt
+    or locale-formatted value (``"1,234"``, ``"NaN"``, ``None``) zeroes that one field
+    instead of throwing and dropping the whole session. Token counts are non-negative and
+    must fit a SQLite INTEGER, so a negative value clamps to 0 (else it would silently net
+    against real cost in the ledger SUM) and an oversized value clamps to the INT64 ceiling
+    (else the sqlite3 bind would OverflowError and drop the session)."""
+    try:
+        if isinstance(v, bool):
+            n = int(v)
+        elif isinstance(v, (int, float)):
+            n = int(v)
+        elif isinstance(v, str) and v.strip():
+            n = int(float(v.replace(",", "")))
+        else:
+            return 0
+    except (ValueError, TypeError, OverflowError):
+        return 0
+    if n < 0:
+        return 0
+    return n if n <= _INT64_MAX else _INT64_MAX
+
+
+@dataclass
+class ToolUse:
+    name: str
+    input_json: str = ""  # canonical JSON of the tool input (for retry detection)
+    id: str = ""
+
+
+@dataclass
+class ToolResult:
+    tool_use_id: str = ""
+    content: str = ""
+    is_error: bool = False
+
+
+@dataclass
+class ParsedMessage:
+    ordinal: int
+    role: str  # user | assistant | system | tool
+    content: str = ""  # flattened text (FTS + content_length)
+    thinking_text: str = ""
+    timestamp: str | None = None
+    model: str = ""
+    # token usage (cache-aware); raw kept for provenance
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_creation_input_tokens: int = 0
+    cache_read_input_tokens: int = 0
+    reasoning_tokens: int = 0
+    raw_usage: str = ""
+    # source threading + provenance
+    source_uuid: str = ""
+    source_parent_uuid: str = ""
+    is_sidechain: bool = False
+    # tool activity
+    tool_uses: list[ToolUse] = field(default_factory=list)
+    tool_results: list[ToolResult] = field(default_factory=list)
+    # idempotency: stable per-message id for the usage ledger dedup_key
+    usage_dedup_key: str = ""
+
+    @property
+    def has_thinking(self) -> bool:
+        return bool(self.thinking_text)
+
+    @property
+    def has_tool_use(self) -> bool:
+        return bool(self.tool_uses)
+
+    @property
+    def context_tokens(self) -> int:
+        """Live context-window size sent for this turn (the prompt), cache-inclusive."""
+        return (
+            int(self.input_tokens or 0)
+            + int(self.cache_read_input_tokens or 0)
+            + int(self.cache_creation_input_tokens or 0)
+        )
+
+    @property
+    def has_usage(self) -> bool:
+        return (
+            self.input_tokens
+            or self.output_tokens
+            or self.cache_creation_input_tokens
+            or self.cache_read_input_tokens
+            or self.reasoning_tokens
+        ) > 0
+
+
+@dataclass
+class ParsedSession:
+    id: str
+    agent: str  # claude (primary) | cursor (validated, capture-only) | codex (experimental)
+    messages: list[ParsedMessage] = field(default_factory=list)
+    project: str = ""
+    machine: str = "local"
+    cwd: str = ""
+    git_branch: str = ""
+    display_name: str | None = None
+    first_message: str | None = None
+    started_at: str | None = None
+    ended_at: str | None = None
+    # ingest identity (set by the loader, used for idempotency)
+    file_path: str | None = None
+    file_mtime: int | None = None

zeno_session_intel/parsers/__init__.py

@@ -0,0 +1,31 @@
+"""Per-tool session parsers. Each turns one tool's on-disk format into a ParsedSession.
+
+A parser module exposes:
+  - ``default_root() -> Path``           where this tool stores sessions locally
+  - ``discover(root) -> list[Path]``     session files under root (read-only)
+  - ``parse_file(path) -> ParsedSession | None``
+  - optionally ``parse_sessions(path) -> list[ParsedSession]`` when one source file holds
+    MANY sessions (Cursor: one vscdb == many composers). The ingester prefers it.
+
+The registry keeps the ingester tool-agnostic: adding a tool is adding a module + a row.
+
+Tool status (this build is Claude-Code-first - see docs/TOOLS_STATUS.md):
+  - ``claude`` (Claude Code): PRIMARY, the first-class capture path, validated on real data.
+  - ``cursor``: validated against real local data, capture-only (no SDK adapter); LATER.
+  - ``codex`` (OpenAI): EXPERIMENTAL, fixture-verified only (no real Codex install);
+    explicit ``--tools`` opt-in, never a default.
+"""
+
+from __future__ import annotations
+
+from . import claude_code, codex, cursor
+
+# tool name -> parser module.
+# claude = primary; cursor = validated (capture-only); codex = experimental (fixture-only).
+REGISTRY = {
+    "claude": claude_code,
+    "codex": codex,
+    "cursor": cursor,
+}
+
+__all__ = ["REGISTRY", "claude_code", "codex", "cursor"]