octarin-cli 0.2.0

package/assets/backfill.py

@@ -0,0 +1,1113 @@
+#!/usr/bin/env python3
+# ruff: noqa: BLE001, S110, S112, S310
+#
+# This is a fail-open one-shot importer: every error path is intentionally a
+# bare ``except Exception: continue`` (S112) / ``pass`` (S110) so a single
+# malformed line, parse failure, or network blip never aborts the run. The
+# ingest URL comes from ``OCTARIN_INGEST_URL`` env (controlled), not user
+# input, so S310 (urlopen with permitted schemes) doesn't apply here.
+"""Octarin history backfill (https://octarin.ai) — team AI-usage analytics tool.
+
+Octarin is a team AI-usage analytics tool for AI-assisted coding (the same
+pattern as Langfuse / OpenTelemetry session logging). This one-shot importer
+reads the AI-coding session logs your tools already keep on THIS machine and
+POSTs them, as canonical Octarin ``IngestEvent``s, to your team's shared Octarin
+workspace so your past usage + cost shows up alongside new sessions. It reads
+only local agent-session transcripts you produced and sends them to the ingest
+URL baked into your install.
+
+What it scans (read-only):
+  * ~/.claude/projects/**/*.jsonl        (Claude Code transcripts)
+  * ~/.codex/sessions/**/rollout-*.jsonl (Codex rollout logs)
+  * Cursor workspaceStorage             (best-effort; state.vscdb chat history)
+
+Excludes ``_*`` files and any ``subagents/`` directory (sidecar/internal logs).
+
+Pure stdlib. Fail-open: a single bad file or failed POST never aborts the run.
+Idempotent: each session maps to a deterministic trace id server-side (derived
+from project + source + session id), so re-running dedupes instead of double
+-counting. Use ``--since`` to limit how far back to import.
+
+Usage:
+  OCTARIN_API_KEY=<key> python3 backfill.py [--since 7d] [--dry-run] [--verbose]
+
+Env:
+  OCTARIN_API_KEY     (required) the project key, same one the hooks use.
+  OCTARIN_INGEST_URL  (optional) defaults to https://api.octarin.ai/v1/ingest.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import getpass
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+INGEST_URL_DEFAULT = "https://api.octarin.ai/v1/ingest"
+
+# Truncation budgets mirror the live hooks so backfilled spans look identical to
+# streamed ones.
+_INPUT_CAP = 8000
+_OUTPUT_CAP = 16000
+_NAME_CAP = 80
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _eprint(*args: object) -> None:
+    print(*args, file=sys.stderr, flush=True)
+
+
+# ── argument / config plumbing ───────────────────────────────────────────────
+
+
+def parse_since(spec: str | None) -> datetime | None:
+    """Parse a ``--since`` value into a UTC cutoff datetime (or None for 'all').
+
+    Accepts a relative span (``30m``, ``12h``, ``7d``, ``2w``) or an absolute
+    ISO date/datetime (``2026-01-01`` / ``2026-01-01T00:00:00``). Returns None on
+    an empty/unparseable value so the run simply imports everything.
+    """
+    if not spec:
+        return None
+    spec = spec.strip()
+    m = re.fullmatch(r"(\d+)\s*([smhdw])", spec.lower())
+    if m:
+        n = int(m.group(1))
+        unit = m.group(2)
+        seconds = {"s": 1, "m": 60, "h": 3600, "d": 86400, "w": 604800}[unit] * n
+        return datetime.now(timezone.utc) - timedelta(seconds=seconds)
+    for fmt in ("%Y-%m-%dT%H:%M:%S", "%Y-%m-%d"):
+        try:
+            return datetime.strptime(spec, fmt).replace(tzinfo=timezone.utc)
+        except ValueError:
+            continue
+    _eprint(
+        f"[octarin] warning: could not parse --since {spec!r}; importing all history"
+    )
+    return None
+
+
+def _parse_ts(value: object) -> datetime | None:
+    """Best-effort parse of a timestamp string into an aware UTC datetime."""
+    if not isinstance(value, str) or not value:
+        return None
+    v = value.strip()
+    if v.endswith("Z"):
+        v = v[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(v)
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+def _default_user(cwd: str | None = None) -> str:
+    """Resolve a stable, pseudonymous user_ref (git email, then OS user)."""
+    user = os.environ.get("OCTARIN_USER")
+    if user:
+        return user
+    try:
+        out = subprocess.check_output(
+            ["git", "config", "user.email"],
+            cwd=cwd or os.getcwd(),
+            stderr=subprocess.DEVNULL,
+        )
+        email = out.decode().strip()
+        if email:
+            return email
+    except Exception:
+        pass
+    try:
+        return getpass.getuser()
+    except Exception:
+        return "unknown"
+
+
+def _repo_of(cwd: str | None) -> str | None:
+    """Derive a repo label from a working directory path."""
+    if not cwd:
+        return None
+    base = os.path.basename(cwd.rstrip("/"))
+    return base or None
+
+
+# ── Claude Code transcript parser (ported from the install Stop hook) ─────────
+
+
+def parse_claude_transcript(  # noqa: PLR0915 - top-down jsonl parser; splitting
+    path: str,  # would scatter the local span-id/state bookkeeping.
+    default_user: str,
+) -> dict | None:
+    """Map a Claude Code ``*.jsonl`` transcript to a canonical IngestEvent dict.
+
+    This mirrors the streaming Stop hook (install/router.py ``HOOK_PY``) so
+    backfilled traces are identical to live ones: deterministic session id,
+    smart session_name, multi-hop parent_span_id tree (tool/subagent nested
+    under their assistant turn), real tool/file content, and span_type
+    classification (subagents→agent, search/read→retrieval, else→tool).
+
+    Returns None when the file has no usable spans.
+    """
+    msgs: list[dict] = []
+    cwd: str | None = None
+    try:
+        with Path(path).open(encoding="utf-8", errors="replace") as f:
+            for raw_line in f:
+                line = raw_line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except Exception:
+                    continue
+                if isinstance(obj, dict):
+                    msgs.append(obj)
+                    if cwd is None and isinstance(obj.get("cwd"), str):
+                        cwd = obj.get("cwd")
+    except Exception:
+        return None
+
+    # session id: prefer an embedded sessionId, else the file stem.
+    sid = None
+    for m in msgs:
+        sid = m.get("sessionId") or m.get("session_id")
+        if sid:
+            break
+    if not sid:
+        sid = os.path.splitext(os.path.basename(path))[0] or "unknown"
+
+    repo = _repo_of(cwd)
+
+    # First pass: collect tool_result content (and its ts) keyed by tool_use_id.
+    results: dict[str, str] = {}
+    result_ts: dict[str, str] = {}
+    for m in msgs:
+        msg = m.get("message", m)
+        if not isinstance(msg, dict):
+            continue
+        mts = m.get("timestamp")
+        content = msg.get("content")
+        if isinstance(content, list):
+            for b in content:
+                if isinstance(b, dict) and b.get("type") == "tool_result":
+                    txt = b.get("content")
+                    if isinstance(txt, list):
+                        txt = "\n".join(
+                            x.get("text", "") for x in txt if isinstance(x, dict)
+                        )
+                    tid = b.get("tool_use_id")
+                    results[tid] = (
+                        txt if isinstance(txt, str) else json.dumps(txt)
+                    )
+                    if mts:
+                        result_ts[tid] = mts
+
+    # Second pass: build spans.
+    spans: list[dict] = []
+    session_name: str | None = None
+    model: str | None = None
+    gen = 0
+    prev_ts: str | None = None  # for assistant-span start = prior message ts
+    for m in msgs:
+        msg = m.get("message", m)
+        if not isinstance(msg, dict):
+            continue
+        role = msg.get("role") or m.get("type")
+        ts = m.get("timestamp") or _now_iso()
+        content = msg.get("content")
+        if session_name is None and role == "user":
+            t = content if isinstance(content, str) else None
+            if isinstance(content, list):
+                t = " ".join(
+                    b.get("text", "")
+                    for b in content
+                    if isinstance(b, dict) and b.get("type") == "text"
+                )
+            if t and t.strip():
+                session_name = t.strip().replace("\n", " ")[:_NAME_CAP]
+        if role == "assistant":
+            model = msg.get("model") or model
+            usage = msg.get("usage") or {}
+            out = content if isinstance(content, str) else ""
+            if isinstance(content, list):
+                out = "\n".join(
+                    b.get("text", "")
+                    for b in content
+                    if isinstance(b, dict) and b.get("type") == "text"
+                )
+            gen += 1
+            spans.append(
+                {
+                    "span_id": f"{sid}-gen{gen}",
+                    "name": "assistant",
+                    "span_type": "llm",
+                    "start_time": prev_ts or ts,
+                    "end_time": ts,
+                    "model": model,
+                    "output": out,
+                    "input_tokens": usage.get("input_tokens", 0),
+                    "output_tokens": usage.get("output_tokens", 0),
+                    "cache_read_tokens": usage.get("cache_read_input_tokens", 0),
+                    "cache_write_tokens": usage.get("cache_creation_input_tokens", 0),
+                    "status": "ok",
+                }
+            )
+            if isinstance(content, list):
+                for b in content:
+                    if isinstance(b, dict) and b.get("type") == "tool_use":
+                        tname = b.get("name", "")
+                        if tname in ("Task", "Agent"):
+                            stype, label = "agent", f"subagent:{tname}"
+                        elif tname in ("Read", "Grep", "Glob", "WebFetch", "WebSearch"):
+                            stype, label = "retrieval", f"tool:{tname}"
+                        else:
+                            stype, label = "tool", f"tool:{tname}"
+                        tid = b.get("id")
+                        spans.append(
+                            {
+                                "span_id": f"{sid}-{tid or 'tool'}",
+                                "parent_span_id": f"{sid}-gen{gen}",
+                                "name": label,
+                                "span_type": stype,
+                                "start_time": ts,
+                                "end_time": result_ts.get(tid, ts),
+                                "input": json.dumps(b.get("input", {}))[:_INPUT_CAP],
+                                "output": (results.get(tid) or "")[
+                                    :_OUTPUT_CAP
+                                ],
+                                "status": "ok",
+                            }
+                        )
+        prev_ts = ts
+    if not spans:
+        return None
+    if not session_name:
+        session_name = f"Claude Code: {repo or sid}"
+    return {
+        "source": "claude-code",
+        "session_id": sid,
+        "session_name": session_name,
+        "user_ref": default_user,
+        "repo": repo,
+        "model": model,
+        "spans": spans,
+    }
+
+
+# ── Codex rollout parser ──────────────────────────────────────────────────────
+
+
+def _codex_text(content: object) -> str:
+    """Flatten a Codex content value (string or list of typed blocks) to text."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        out = []
+        for b in content:
+            if isinstance(b, dict):
+                out.append(b.get("text") or b.get("content") or "")
+            elif isinstance(b, str):
+                out.append(b)
+        return "\n".join(x for x in out if x)
+    return ""
+
+
+def parse_codex_rollout(  # noqa: PLR0915 - top-down jsonl parser; same shape
+    path: str,  # as parse_claude_transcript, kept linear for clarity.
+    default_user: str,
+) -> dict | None:
+    """Map a Codex ``rollout-*.jsonl`` session to a canonical IngestEvent dict.
+
+    Codex wraps each record in ``{type, payload}``. ``response_item`` /
+    ``event_msg`` payloads carry ``message`` (role user/assistant), ``reasoning``,
+    and ``function_call`` / ``function_call_output`` items. We build an
+    assistant ``llm`` span per assistant message and nest tool (function-call)
+    spans under the most recent assistant turn for the multi-hop tree.
+
+    Returns None when the file has no usable spans (e.g. a pure SDK exec call).
+    """
+    items: list[dict] = []
+    sid: str | None = None
+    cwd: str | None = None
+    model: str | None = None
+    try:
+        with Path(path).open(encoding="utf-8", errors="replace") as f:
+            for raw_line in f:
+                line = raw_line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except Exception:
+                    continue
+                if not isinstance(obj, dict):
+                    continue
+                payload = obj.get("payload")
+                if obj.get("type") == "session_meta" and isinstance(payload, dict):
+                    sid = payload.get("id") or sid
+                    cwd = payload.get("cwd") or cwd
+                    model = payload.get("model") or model
+                    continue
+                if isinstance(payload, dict):
+                    payload.setdefault("_ts", obj.get("timestamp"))
+                    items.append(payload)
+    except Exception:
+        return None
+
+    if not sid:
+        # rollout-<iso>-<uuid>.jsonl → take the trailing uuid-ish segment.
+        stem = os.path.splitext(os.path.basename(path))[0]
+        sid = stem
+        m = re.search(r"([0-9a-fA-F-]{8,})$", stem)
+        if m:
+            sid = m.group(1)
+
+    repo = _repo_of(cwd)
+    spans: list[dict] = []
+    session_name: str | None = None
+    gen = 0
+    last_gen_id: str | None = None
+    # Map function_call call_id → its emitted span so outputs can attach.
+    call_index: dict[str, dict] = {}
+    prev_ts: str | None = None  # LLM start ts; tool spans also extend to result ts
+
+    for it in items:
+        ts = it.get("_ts") or _now_iso()
+        ptype = it.get("type")
+        role = it.get("role") or ""
+        model = it.get("model") or model
+
+        if ptype == "message":
+            text = _codex_text(it.get("content"))
+            if role == "user":
+                # Skip the giant injected developer/instruction preamble for the
+                # session name; user prompts are inputs, not billable turns.
+                if session_name is None and text and not text.lstrip().startswith("#"):
+                    session_name = text.strip().replace("\n", " ")[:_NAME_CAP]
+            elif role == "assistant":
+                gen += 1
+                last_gen_id = f"{sid}-gen{gen}"
+                spans.append(
+                    {
+                        "span_id": last_gen_id,
+                        "name": "assistant",
+                        "span_type": "llm",
+                        "start_time": prev_ts or ts,
+                        "end_time": ts,
+                        "model": model,
+                        "output": text[:_OUTPUT_CAP],
+                        "status": "ok",
+                    }
+                )
+        elif ptype == "function_call":
+            name = it.get("name") or "tool"
+            call_id = it.get("call_id") or it.get("id") or f"call{len(spans)}"
+            if name in ("read_file", "grep", "search", "web_search", "find"):
+                stype = "retrieval"
+            else:
+                stype = "tool"
+            arguments = it.get("arguments")
+            span = {
+                "span_id": f"{sid}-{call_id}",
+                "name": f"tool:{name}",
+                "span_type": stype,
+                "start_time": ts,
+                "end_time": ts,
+                "input": (
+                    arguments[:_INPUT_CAP]
+                    if isinstance(arguments, str)
+                    else json.dumps(arguments or {})[:_INPUT_CAP]
+                ),
+                "output": "",
+                "status": "ok",
+            }
+            if last_gen_id:
+                span["parent_span_id"] = last_gen_id
+            spans.append(span)
+            call_index[call_id] = span
+        elif ptype == "function_call_output":
+            call_id = it.get("call_id") or it.get("id")
+            target = call_index.get(call_id)
+            if target is not None:
+                out = it.get("output")
+                if isinstance(out, dict):
+                    out = out.get("content") or json.dumps(out)
+                target["output"] = out[:_OUTPUT_CAP] if isinstance(out, str) else ""
+                target["end_time"] = ts
+        prev_ts = ts
+
+    if not spans:
+        return None
+    if not session_name:
+        session_name = f"Codex: {repo or sid}"
+    return {
+        "source": "codex",
+        "session_id": sid,
+        "session_name": session_name,
+        "user_ref": default_user,
+        "repo": repo,
+        "model": model,
+        "spans": spans,
+    }
+
+
+# ── Cursor (best-effort) ──────────────────────────────────────────────────────
+
+
+def _cursor_storage_root() -> str | None:
+    """Locate the Cursor workspaceStorage dir for the host OS, if present."""
+    home = os.path.expanduser("~")
+    candidates = [
+        os.path.join(
+            home, "Library", "Application Support", "Cursor", "User", "workspaceStorage"
+        ),
+        os.path.join(home, ".config", "Cursor", "User", "workspaceStorage"),
+        os.path.join(home, "AppData", "Roaming", "Cursor", "User", "workspaceStorage"),
+    ]
+    for c in candidates:
+        if os.path.isdir(c):
+            return c
+    return None
+
+
+def parse_cursor_sessions(
+    default_user: str, cutoff: datetime | None, verbose: bool
+) -> list[dict]:
+    """Best-effort import of Cursor chat history from workspaceStorage.
+
+    Two parsers run per workspace in priority order:
+
+    * **aiService** (current Cursor) — reads ``aiService.generations`` and
+      ``aiService.prompts`` from ``ItemTable``. Generations carry a ``unixMs``
+      timestamp and a ``generationUUID``, so we can split a workspace into
+      proper time-bounded sessions (one session per >30-min gap) with
+      deterministic ``trace_id``/``span_id`` for idempotent re-runs.
+    * **bubbles** (older Cursor) — legacy fallback that walks ``cursorDiskKV``
+      and ``ItemTable`` for keys containing ``bubble``/``chat``. Used only when
+      the aiService keys are absent.
+
+    Inherently schema-fragile across Cursor versions, so still fail-open: any
+    error on any workspace is skipped (logged under --verbose). Live capture
+    via the Cursor hook is the authoritative path; this just backfills the
+    history sitting on disk.
+    """
+    root = _cursor_storage_root()
+    if not root:
+        if verbose:
+            _eprint("[octarin] cursor: no workspaceStorage found; skipping")
+        return []
+    try:
+        import sqlite3
+    except Exception:
+        return []
+
+    events: list[dict] = []
+    workspaces_seen = 0
+    for ws in sorted(os.listdir(root)):
+        db = os.path.join(root, ws, "state.vscdb")
+        if not os.path.isfile(db):
+            continue
+        workspaces_seen += 1
+        if cutoff is not None:
+            try:
+                mtime = datetime.fromtimestamp(os.path.getmtime(db), tz=timezone.utc)
+                if mtime < cutoff:
+                    continue
+            except Exception:
+                pass
+        try:
+            ws_events = _parse_cursor_workspace(sqlite3, db, ws, default_user, cutoff)
+        except Exception as exc:  # fail-open per workspace
+            if verbose:
+                _eprint(f"[octarin] cursor: skipped {ws}: {exc}")
+            continue
+        if verbose and ws_events:
+            _eprint(f"[octarin] cursor:   {ws}: {len(ws_events)} session(s)")
+        events.extend(ws_events)
+    if verbose:
+        _eprint(
+            f"[octarin] cursor: scanned {workspaces_seen} workspace(s), "
+            f"recovered {len(events)} session(s)"
+        )
+    return events
+
+
+# Generations more than this many seconds apart land in distinct sessions. 30
+# minutes is a pragmatic boundary that matches how people use Cursor (start a
+# task, walk away, come back later → that's two sessions).
+_CURSOR_SESSION_GAP_SECONDS = 30 * 60
+
+
+def _parse_cursor_workspace(
+    sqlite3, db_path: str, ws_id: str, default_user: str, cutoff: datetime | None
+) -> list[dict]:
+    """Read one workspace's state.vscdb → list of IngestEvents (one per session).
+
+    Reads aiService.generations + aiService.prompts (current Cursor schema). If
+    those are absent or empty, falls back to the legacy bubble path so we don't
+    regress on older installs.
+    """
+    # Open read-only so we never disturb a running Cursor.
+    uri = f"file:{db_path}?mode=ro&immutable=1"
+    conn = sqlite3.connect(uri, uri=True, timeout=2.0)
+    try:
+        cur = conn.cursor()
+        try:
+            cur.execute(
+                "SELECT key, value FROM ItemTable "
+                "WHERE key IN ('aiService.generations', 'aiService.prompts')"
+            )
+            ai_rows = dict(cur.fetchall())
+        except Exception:
+            ai_rows = {}
+
+        # Fallback: legacy bubble/chat rows (older Cursor versions only — the
+        # current schema lives in aiService.* above).
+        legacy_rows: list[tuple] = []
+        if not ai_rows.get("aiService.generations"):
+            for table in ("cursorDiskKV", "ItemTable"):
+                try:
+                    # Fixed table names from a literal tuple — not user input.
+                    cur.execute(f"SELECT key, value FROM {table}")
+                    legacy_rows.extend(cur.fetchall())
+                except Exception:
+                    continue
+    finally:
+        conn.close()
+
+    # Path 1: the aiService schema (every modern Cursor).
+    events = _parse_cursor_aiservice(ai_rows, ws_id, default_user, cutoff)
+    if events:
+        return events
+
+    # Path 2: legacy bubbles (no time grouping, one event per workspace).
+    legacy = _parse_cursor_bubbles(legacy_rows, ws_id, default_user)
+    return [legacy] if legacy else []
+
+
+def _parse_cursor_aiservice(  # noqa: PLR0915 - per-session bookkeeping inline
+    rows: dict, ws_id: str, default_user: str, cutoff: datetime | None
+) -> list[dict]:
+    """Build per-session IngestEvents from ``aiService.generations`` (+ ``prompts``).
+
+    Generations are the authoritative records (they carry ``unixMs`` +
+    ``generationUUID``). We sort by timestamp, split on ``_CURSOR_SESSION_GAP_SECONDS``
+    gaps, and emit one event per resulting session — each with a deterministic
+    ``session_id`` derived from workspace + session start so re-runs dedupe via
+    the backend's trace-id derivation. User prompts get joined into the
+    session-level ``input`` (Cursor doesn't timestamp them so per-turn
+    correlation isn't safe).
+    """
+    raw_gens = rows.get("aiService.generations")
+    raw_prompts = rows.get("aiService.prompts")
+    if not raw_gens:
+        return []
+    try:
+        gens = json.loads(raw_gens) or []
+    except Exception:
+        return []
+    if not isinstance(gens, list) or not gens:
+        return []
+
+    # Sort generations chronologically. Defensive about missing/non-int unixMs.
+    def _ts(g: object) -> int:
+        if isinstance(g, dict):
+            v = g.get("unixMs")
+            if isinstance(v, (int, float)):
+                return int(v)
+        return 0
+
+    gens = sorted([g for g in gens if isinstance(g, dict) and _ts(g) > 0], key=_ts)
+    if not gens:
+        return []
+
+    # Apply --since cutoff at the generation level (mtime on the file is too
+    # coarse — a workspace touched yesterday may have months of older history).
+    if cutoff is not None:
+        cutoff_ms = int(cutoff.timestamp() * 1000)
+        gens = [g for g in gens if _ts(g) >= cutoff_ms]
+        if not gens:
+            return []
+
+    # User prompts (no timestamps in Cursor's schema) — we attach the full text
+    # as the session-level input. Best-effort join; if the JSON is malformed we
+    # quietly proceed without prompts.
+    prompt_texts: list[str] = []
+    if raw_prompts:
+        try:
+            prompts = json.loads(raw_prompts) or []
+            for p in prompts if isinstance(prompts, list) else []:
+                if isinstance(p, dict):
+                    t = p.get("text")
+                    if isinstance(t, str) and t.strip():
+                        prompt_texts.append(t.strip())
+        except Exception:
+            pass
+
+    # Split into sessions on the gap boundary.
+    sessions: list[list[dict]] = []
+    for g in gens:
+        if (
+            not sessions
+            or _ts(g) - _ts(sessions[-1][-1]) > _CURSOR_SESSION_GAP_SECONDS * 1000
+        ):
+            sessions.append([g])
+        else:
+            sessions[-1].append(g)
+
+    events: list[dict] = []
+    # Distribute prompts proportionally across sessions (best-effort: split
+    # evenly by session count — better than dumping all of them onto session
+    # one and worse than impossible without timestamps).
+    prompts_per_session = (
+        [prompt_texts[i :: len(sessions)] for i in range(len(sessions))]
+        if prompt_texts and sessions
+        else [[] for _ in sessions]
+    )
+
+    for idx, gen_list in enumerate(sessions):
+        start_ms = _ts(gen_list[0])
+        end_ms = _ts(gen_list[-1])
+        # Session-level input from the prompt slice (may be empty).
+        my_prompts = prompts_per_session[idx]
+        session_input = "\n\n".join(my_prompts)[:_INPUT_CAP] if my_prompts else None
+        # Session name = first prompt (truncated), or first generation snippet.
+        first_text = (
+            my_prompts[0]
+            if my_prompts
+            else str(gen_list[0].get("textDescription") or "")
+        )
+        session_name = (
+            first_text.strip().replace("\n", " ")[:_NAME_CAP] or f"Cursor: {ws_id}"
+        )
+
+        # Estimated session-level input tokens — the total length of every
+        # prompt that landed in this session bucket (the prompts have no
+        # timestamps so we attribute their tokens at the session, not span).
+        # We surface this on the FIRST span so the trace-level rollup picks it
+        # up exactly once without double-counting.
+        session_input_tokens = sum(_est_tokens(p) for p in my_prompts)
+
+        spans: list[dict] = []
+        for span_idx, g in enumerate(gen_list):
+            gen_uuid = g.get("generationUUID") or g.get("uuid") or ""
+            text = g.get("textDescription") or ""
+            if isinstance(text, dict):
+                text = json.dumps(text)
+            if not isinstance(text, str):
+                text = ""
+            gen_ms = _ts(g)
+            gen_type = g.get("type") or "composer"
+            out_tokens = _est_tokens(text)
+            # First span carries the session's input-token estimate (sum of
+            # prompt text lengths). Subsequent spans only have output tokens.
+            input_tokens = session_input_tokens if span_idx == 0 else 0
+            spans.append(
+                {
+                    "span_id": f"cursor-{ws_id}-{gen_uuid or str(gen_ms)}",
+                    "name": gen_type,
+                    "span_type": "llm",
+                    # We don't have separate start/end timestamps; Cursor only
+                    # records a single time per generation. Use it for both so
+                    # duration is 0 — fair: this is post-hoc, not live timing.
+                    "start_time": _ms_to_iso(gen_ms),
+                    "end_time": _ms_to_iso(gen_ms),
+                    # Cursor doesn't expose its underlying model id in this
+                    # storage path; ``cursor:composer`` (or whatever ``type``
+                    # the generation declared) flags this as Cursor's own
+                    # composer flow. The backend pricing layer doesn't know
+                    # this model, so cost stays $0 (correct: Cursor cost is
+                    # tier-based, not per-token).
+                    "model": f"cursor:{gen_type}",
+                    "output": text[:_OUTPUT_CAP],
+                    "input_tokens": input_tokens,
+                    "output_tokens": out_tokens,
+                    "total_tokens": input_tokens + out_tokens,
+                    "status": "ok",
+                }
+            )
+
+        events.append(
+            {
+                "source": "cursor",
+                # Deterministic per session so re-runs dedupe via backend
+                # trace_id derivation (uuid5(project, source, session_id)).
+                "session_id": f"cursor-{ws_id}-{start_ms}",
+                "session_name": session_name,
+                "user_ref": default_user,
+                "model": f"cursor:{gen_list[0].get('type') or 'composer'}",
+                "input": session_input,
+                "start_time": _ms_to_iso(start_ms),
+                "end_time": _ms_to_iso(end_ms),
+                "spans": spans,
+            }
+        )
+    return events
+
+
+def _est_tokens(text: str) -> int:
+    """Char-based token estimate (~4 chars/token).
+
+    Cursor's ``aiService.generations`` records the rendered text of a model
+    reply but NOT a token count — Cursor charges per-request on its own tier,
+    not per-token, so it doesn't bother. To make tokens-per-day / tokens-per-
+    session analytics meaningful for imported Cursor history we estimate from
+    text length using the standard ~4-char-per-token English ratio. Spans
+    minted this way get a ``cursor:composer`` model name which the backend's
+    pricing layer doesn't know — so $ stays $0 (correct: Cursor cost is opaque
+    on a tier plan) but token counts roll up.
+    """
+    if not text:
+        return 0
+    return max(0, (len(text) + 3) // 4)
+
+
+def _ms_to_iso(unix_ms: int) -> str:
+    """Convert a unix millisecond timestamp to a UTC ISO 8601 string."""
+    try:
+        return datetime.fromtimestamp(unix_ms / 1000, tz=timezone.utc).isoformat()
+    except Exception:
+        return _now_iso()
+
+
+def _parse_cursor_bubbles(
+    rows: list[tuple], ws_id: str, default_user: str
+) -> dict | None:
+    """Legacy fallback: walk bubble/chat rows from older Cursor versions.
+
+    Same shape as the original parser this file shipped with — kept untouched
+    so any pre-aiService Cursor install still gets best-effort backfill.
+    """
+    spans: list[dict] = []
+    session_name: str | None = None
+    model: str | None = None
+    gen = 0
+    for key, value in rows:
+        if not isinstance(key, str) or not isinstance(value, (str, bytes)):
+            continue
+        if "bubble" not in key and "chat" not in key.lower():
+            continue
+        try:
+            data = json.loads(value)
+        except Exception:
+            continue
+        for b in _cursor_bubbles(data):
+            text = b.get("text") or b.get("richText") or ""
+            if isinstance(text, dict):
+                text = json.dumps(text)
+            if not isinstance(text, str) or not text.strip():
+                continue
+            btype = b.get("type")
+            # Cursor's legacy bubble schema: 1 == user turn, 2 == assistant turn.
+            _BUBBLE_USER = 1
+            _BUBBLE_ASSISTANT = 2
+            is_user = btype == _BUBBLE_USER or b.get("role") == "user"
+            is_asst = btype == _BUBBLE_ASSISTANT or b.get("role") == "assistant"
+            model = b.get("model") or model
+            if is_user and session_name is None:
+                session_name = text.strip().replace("\n", " ")[:_NAME_CAP]
+            if is_asst:
+                gen += 1
+                out_tokens = _est_tokens(text)
+                spans.append(
+                    {
+                        "span_id": f"cursor-{ws_id}-gen{gen}",
+                        "name": "assistant",
+                        "span_type": "llm",
+                        "start_time": _now_iso(),
+                        "end_time": _now_iso(),
+                        "model": model,
+                        "output": text[:_OUTPUT_CAP],
+                        "output_tokens": out_tokens,
+                        "total_tokens": out_tokens,
+                        "status": "ok",
+                    }
+                )
+    if not spans:
+        return None
+    return {
+        "source": "cursor",
+        "session_id": f"cursor-{ws_id}",
+        "session_name": session_name or f"Cursor: {ws_id}",
+        "user_ref": default_user,
+        "model": model,
+        "spans": spans,
+    }
+
+
+def _cursor_bubbles(data: object) -> list[dict]:
+    """Extract a flat list of chat-bubble dicts from a decoded Cursor value."""
+    if isinstance(data, dict):
+        if "type" in data and ("text" in data or "richText" in data):
+            return [data]
+        for k in ("bubbles", "messages", "conversation"):
+            v = data.get(k)
+            if isinstance(v, list):
+                return [x for x in v if isinstance(x, dict)]
+        return []
+    if isinstance(data, list):
+        return [x for x in data if isinstance(x, dict)]
+    return []
+
+
+# ── file discovery ────────────────────────────────────────────────────────────
+
+
+def _excluded(path: str) -> bool:
+    """True for sidecar/internal files we must skip (``_*`` files, subagents/)."""
+    parts = path.split(os.sep)
+    if any(p == "subagents" for p in parts):
+        return True
+    return os.path.basename(path).startswith("_")
+
+
+def discover_claude(cutoff: datetime | None) -> list[str]:
+    """All Claude transcript jsonl files newer than ``cutoff`` (excluding sidecars)."""
+    root = os.path.expanduser("~/.claude/projects")
+    return _walk(root, lambda n: n.endswith(".jsonl"), cutoff)
+
+
+def discover_codex(cutoff: datetime | None) -> list[str]:
+    """All Codex rollout jsonl files newer than ``cutoff`` (excluding sidecars)."""
+    root = os.path.expanduser("~/.codex/sessions")
+    return _walk(
+        root, lambda n: n.startswith("rollout-") and n.endswith(".jsonl"), cutoff
+    )
+
+
+def _walk(root: str, name_ok, cutoff: datetime | None) -> list[str]:
+    """Return matching files under ``root``, excluding sidecars + stale-by-mtime."""
+    out: list[str] = []
+    if not os.path.isdir(root):
+        return out
+    for dirpath, dirnames, filenames in os.walk(root):
+        # prune subagents dirs so we never descend into them.
+        dirnames[:] = [d for d in dirnames if d != "subagents"]
+        for name in filenames:
+            if not name_ok(name) or name.startswith("_"):
+                continue
+            path = os.path.join(dirpath, name)
+            if _excluded(path):
+                continue
+            if cutoff is not None:
+                try:
+                    mtime = datetime.fromtimestamp(
+                        os.path.getmtime(path), tz=timezone.utc
+                    )
+                    if mtime < cutoff:
+                        continue
+                except Exception:
+                    pass
+            out.append(path)
+    return out
+
+
+# ── posting ───────────────────────────────────────────────────────────────────
+
+
+def _filter_spans_by_cutoff(event: dict, cutoff: datetime | None) -> dict | None:
+    """Drop spans older than the cutoff; return None if nothing survives.
+
+    File-level mtime already prunes most stale files; this trims partial files so
+    a long-running session that started before the cutoff still imports only its
+    recent turns. Spans with no/unparseable timestamp are always kept.
+    """
+    if cutoff is None:
+        return event
+    spans = event.get("spans") or []
+    kept = []
+    for s in spans:
+        ts = _parse_ts(s.get("start_time"))
+        if ts is None or ts >= cutoff:
+            kept.append(s)
+    if not kept:
+        return None
+    event = dict(event)
+    event["spans"] = kept
+    return event
+
+
+def post_event(
+    url: str, key: str, event: dict, timeout: float = 20.0
+) -> tuple[bool, str]:
+    """POST one IngestEvent. Returns ``(ok, detail)``; never raises."""
+    body = json.dumps(event).encode()
+    req = urllib.request.Request(
+        url,
+        data=body,
+        headers={
+            "Authorization": f"Bearer {key}",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8", "replace")
+            try:
+                n = json.loads(raw).get("span_count")
+                return True, f"span_count={n}" if n is not None else "ok"
+            except Exception:
+                return True, "ok"
+    except urllib.error.HTTPError as exc:
+        detail = ""
+        with contextlib.suppress(Exception):
+            detail = exc.read().decode("utf-8", "replace")[:300]
+        return False, f"HTTP {exc.code} {detail}".strip()
+    except Exception as exc:  # network / timeout — fail-open
+        return False, str(exc)
+
+
+# ── orchestration ─────────────────────────────────────────────────────────────
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="backfill.py",
+        description="Import past Claude Code / Codex / Cursor sessions into Octarin.",
+    )
+    p.add_argument(
+        "--since",
+        default=None,
+        help="Only import sessions newer than this (e.g. 7d, 12h, 2w, or 2026-01-01).",
+    )
+    p.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Parse and count, but do not POST anything.",
+    )
+    p.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Log every file parsed/posted.",
+    )
+    return p
+
+
+def _handle_event(event, cutoff, args, url, key, label, totals) -> None:
+    """Filter by cutoff, account it, and (unless dry-run) POST one event."""
+    event = _filter_spans_by_cutoff(event, cutoff)
+    if not event:
+        totals["skipped"] += 1
+        return
+    n_spans = len(event.get("spans") or [])
+    totals["events"] += 1
+    totals["spans"] += n_spans
+    if args.dry_run:
+        if args.verbose:
+            _eprint(
+                f"[octarin]   [dry-run] {label} {event['session_id']} "
+                f"({n_spans} spans) {event.get('session_name', '')[:50]}"
+            )
+        return
+    ok, detail = post_event(url, key, event)
+    if ok:
+        totals["posted"] += 1
+        if args.verbose:
+            _eprint(f"[octarin]   posted {event['session_id']} ({detail})")
+    else:
+        totals["failed"] += 1
+        _eprint(f"[octarin]   FAILED {event['session_id']}: {detail}")
+
+
+def run(argv: list[str] | None = None) -> int:
+    args = build_arg_parser().parse_args(argv)
+    cutoff = parse_since(args.since)
+
+    key = os.environ.get("OCTARIN_API_KEY", "").strip()
+    url = os.environ.get("OCTARIN_INGEST_URL", "").strip() or INGEST_URL_DEFAULT
+
+    if not args.dry_run and not key:
+        _eprint(
+            "[octarin] OCTARIN_API_KEY is not set; cannot upload.\n"
+            "          Run: OCTARIN_API_KEY=<your key> python3 backfill.py"
+        )
+        return 1
+
+    default_user = _default_user()
+    since_label = args.since or "all history"
+    _eprint(f"[octarin] backfill starting (since: {since_label}) → {url}")
+
+    totals = {
+        "files": 0,
+        "events": 0,
+        "spans": 0,
+        "posted": 0,
+        "failed": 0,
+        "skipped": 0,
+    }
+
+    # (label, discover_fn, parse_fn) for the file-based sources.
+    sources = [
+        ("Claude Code", discover_claude, parse_claude_transcript),
+        ("Codex", discover_codex, parse_codex_rollout),
+    ]
+    for label, discover, parse in sources:
+        files = discover(cutoff)
+        _eprint(f"[octarin] {label}: {len(files)} session file(s) to scan")
+        for path in files:
+            totals["files"] += 1
+            event = None
+            try:
+                event = parse(path, default_user)
+            except Exception as exc:  # fail-open per file
+                if args.verbose:
+                    _eprint(f"[octarin]   parse error {os.path.basename(path)}: {exc}")
+            if not event:
+                totals["skipped"] += 1
+                continue
+            _handle_event(event, cutoff, args, url, key, label, totals)
+
+    # Cursor (best-effort, separate path: parses straight to events).
+    cursor_events = parse_cursor_sessions(default_user, cutoff, args.verbose)
+    if cursor_events:
+        _eprint(
+            f"[octarin] Cursor: {len(cursor_events)} chat session(s) recovered "
+            "(best-effort)"
+        )
+    for event in cursor_events:
+        _handle_event(event, cutoff, args, url, key, "Cursor", totals)
+
+    _eprint("")
+    _eprint("[octarin] backfill complete:")
+    _eprint(f"           files scanned : {totals['files']}")
+    _eprint(f"           sessions found: {totals['events']}  ({totals['spans']} spans)")
+    if args.dry_run:
+        _eprint("           dry-run       : nothing uploaded")
+    else:
+        _eprint(f"           uploaded      : {totals['posted']}")
+        if totals["failed"]:
+            _eprint(
+                f"           failed        : {totals['failed']} "
+                "(fail-open; safe to re-run)"
+            )
+    _eprint("           Re-running is safe — sessions dedupe by trace id.")
+    # Fail-open: a backfill with some failed POSTs still exits 0 so it never
+    # breaks an install pipeline. Only a hard config error (missing key) is
+    # nonzero.
+    return 0
+
+
+def main() -> None:
+    try:
+        sys.exit(run())
+    except KeyboardInterrupt:
+        _eprint("\n[octarin] interrupted")
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()