coding-agent-roi 0.1.0__py3-none-any.whl

agent_roi/collectors/__init__.py

@@ -0,0 +1,31 @@
+"""Collector registry.
+
+New collectors register here so the CLI and config can refer to them by name.
+"""
+
+from __future__ import annotations
+
+from agent_roi.collectors.base import Collector
+from agent_roi.collectors.claude_code import ClaudeCodeCollector
+from agent_roi.collectors.codex import CodexCollector
+from agent_roi.collectors.copilot import CopilotCollector
+from agent_roi.collectors.gemini import GeminiCollector
+
+_REGISTRY: dict[str, type[Collector]] = {
+    ClaudeCodeCollector.name: ClaudeCodeCollector,
+    CodexCollector.name: CodexCollector,
+    CopilotCollector.name: CopilotCollector,
+    GeminiCollector.name: GeminiCollector,
+}
+
+
+def get_collectors(names: list[str]) -> list[Collector]:
+    """Instantiate the named collectors, skipping unknown names."""
+    return [_REGISTRY[name]() for name in names if name in _REGISTRY]
+
+
+def all_collector_names() -> list[str]:
+    return list(_REGISTRY)
+
+
+__all__ = ["Collector", "get_collectors", "all_collector_names"]

agent_roi/collectors/base.py

@@ -0,0 +1,49 @@
+"""Collector interface.
+
+A collector knows how to find one tool's local logs and turn them into a stream
+of normalized :class:`Interaction` objects. Collectors must be read-only and
+idempotent: running ingest twice should not double-count, which is enforced
+upstream by the stable ``Interaction.id``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from pathlib import Path
+
+from agent_roi.core.models import Interaction, Tool
+
+
+class Collector(ABC):
+    """Base class for all tool log collectors."""
+
+    #: Which tool this collector produces interactions for.
+    tool: Tool
+
+    #: Stable name used in config's ``collectors.enabled`` list.
+    name: str
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Return True if this tool's logs exist on the current machine."""
+
+    @abstractmethod
+    def collect(self) -> Iterator[Interaction]:
+        """Yield normalized interactions parsed from local logs."""
+
+    def search_paths(self) -> list[Path]:
+        """Directories this collector looked in (for the diagnostics report).
+
+        Default is empty; collectors override to expose where they searched so
+        users can see why a tool was or wasn't detected.
+        """
+        return []
+
+    def count_files(self) -> int:
+        """Number of log files this collector can see (cheap; no parsing)."""
+        return 0
+
+    def note(self) -> str:
+        """Optional human-readable hint shown in diagnostics (e.g. why empty)."""
+        return ""

agent_roi/collectors/claude_code.py

@@ -0,0 +1,165 @@
+"""Collector for Claude Code.
+
+Claude Code stores one JSONL file per session under
+``~/.claude/projects/<encoded-project-path>/<session-id>.jsonl``. Each line is a
+JSON object; assistant turns carry a ``message.usage`` block with token counts.
+We read these files read-only and never modify them.
+
+We emit one :class:`Interaction` per assistant turn (those are the ones with
+token usage), but we build each interaction's ``summary`` from both the user's
+request and the assistant's reply. Many assistant turns are pure tool calls with
+no prose, so using assistant text alone leaves most summaries empty — which makes
+topic discovery impossible. Carrying the preceding user message keeps the topic
+signal intact.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from agent_roi.collectors.base import Collector
+from agent_roi.core.models import Interaction, Tool
+from agent_roi.core.platform import find_tool_dirs
+from agent_roi.core.project import project_for
+
+_SUMMARY_MAX = 600
+
+
+class ClaudeCodeCollector(Collector):
+    tool = Tool.CLAUDE_CODE
+    name = "claude_code"
+
+    def __init__(self, roots: list[Path] | None = None) -> None:
+        # Supports multiple roots so WSL can also read Windows-side logs.
+        self.roots = roots if roots is not None else find_tool_dirs(".claude", "projects")
+
+    def is_available(self) -> bool:
+        return bool(self.roots)
+
+    def search_paths(self) -> list[Path]:
+        return list(self.roots)
+
+    def count_files(self) -> int:
+        return sum(1 for root in self.roots for _ in root.rglob("*.jsonl"))
+
+    def collect(self) -> Iterator[Interaction]:
+        for root in self.roots:
+            for jsonl in root.rglob("*.jsonl"):
+                yield from self._parse_file(jsonl)
+
+    def _parse_file(self, path: Path) -> Iterator[Interaction]:
+        session_id = path.stem
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except OSError:
+            return
+
+        last_user_text = ""
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            message = record.get("message")
+            if not isinstance(message, dict):
+                continue
+
+            role = message.get("role") or record.get("type")
+            text = _text_from_content(message.get("content"))
+
+            if role == "user":
+                # Remember the latest user intent to attach to the next reply.
+                if text:
+                    last_user_text = text
+                continue
+
+            usage = message.get("usage")
+            if not isinstance(usage, dict):
+                continue
+
+            interaction = self._to_interaction(
+                record, message, usage, session_id, last_user_text, text
+            )
+            if interaction is not None:
+                yield interaction
+
+    def _to_interaction(
+        self,
+        record: dict[str, Any],
+        message: dict[str, Any],
+        usage: dict[str, Any],
+        session_id: str,
+        user_text: str,
+        assistant_text: str,
+    ) -> Interaction | None:
+        msg_id = message.get("id") or record.get("uuid")
+        if not msg_id:
+            return None
+
+        ts_raw = record.get("timestamp")
+        try:
+            timestamp = (
+                datetime.fromisoformat(ts_raw.replace("Z", "+00:00"))
+                if isinstance(ts_raw, str)
+                else datetime.now()
+            )
+        except ValueError:
+            timestamp = datetime.now()
+
+        cwd = str(record.get("cwd", ""))
+        return Interaction(
+            id=str(msg_id),
+            tool=self.tool,
+            session_id=session_id,
+            timestamp=timestamp,
+            model=message.get("model", "unknown"),
+            input_tokens=int(usage.get("input_tokens", 0)),
+            output_tokens=int(usage.get("output_tokens", 0)),
+            cache_read_tokens=int(usage.get("cache_read_input_tokens", 0)),
+            cache_write_tokens=int(usage.get("cache_creation_input_tokens", 0)),
+            cwd=cwd,
+            project=project_for(cwd),
+            summary=_combine_summary(user_text, assistant_text),
+        )
+
+
+def _combine_summary(user_text: str, assistant_text: str) -> str:
+    """Build a topic-bearing summary, preferring the user's request first."""
+    parts = [p for p in (user_text, assistant_text) if p]
+    return " ".join(parts)[:_SUMMARY_MAX]
+
+
+def _text_from_content(content: object) -> str:
+    """Extract human-readable text from a Claude message ``content`` field.
+
+    Content may be a plain string or a list of typed blocks. We keep prose
+    (``text``) and tool *names* (``tool_use``) as topic signal, but deliberately
+    skip ``tool_result`` bodies: those carry command output (e.g. ``ls -l``
+    listings, file dumps) that pollutes topic labels with noise like permission
+    bits and paths rather than describing the task.
+    """
+    if isinstance(content, str):
+        return content.strip()
+    if not isinstance(content, list):
+        return ""
+
+    pieces: list[str] = []
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        btype = block.get("type")
+        if btype == "text":
+            pieces.append(str(block.get("text", "")))
+        elif btype == "tool_use":
+            name = block.get("name")
+            if name:
+                pieces.append(str(name))
+    return " ".join(p for p in pieces if p).strip()

agent_roi/collectors/codex.py

@@ -0,0 +1,157 @@
+"""Collector for OpenAI Codex CLI.
+
+Codex CLI stores one rollout log per session as JSONL under
+``~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl``. Each line is a typed
+record. The shapes we care about:
+
+- ``session_meta``  — session id and start time.
+- ``turn_context``  — carries the active ``model`` for subsequent turns.
+- ``event_msg`` with ``payload.type == "token_count"`` — per-turn token usage in
+  ``info.last_token_usage`` (input/cached/output/reasoning tokens).
+- ``event_msg`` with ``payload.type in {"user_message","agent_message"}`` — text
+  we keep a short snippet of for the classifier.
+
+We emit one :class:`Interaction` per ``token_count`` event, using
+``last_token_usage`` (the delta for that turn) so usage isn't double-counted from
+the running ``total_token_usage``. The parser is defensive: unknown records are
+skipped rather than failing the whole ingest.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from agent_roi.collectors.base import Collector
+from agent_roi.core.models import Interaction, Tool
+from agent_roi.core.platform import find_tool_dirs
+from agent_roi.core.project import project_for
+
+
+class CodexCollector(Collector):
+    tool = Tool.CODEX
+    name = "codex"
+
+    def __init__(self, roots: list[Path] | None = None) -> None:
+        self.roots = roots if roots is not None else find_tool_dirs(".codex", "sessions")
+
+    def is_available(self) -> bool:
+        return bool(self.roots)
+
+    def search_paths(self) -> list[Path]:
+        return list(self.roots)
+
+    def count_files(self) -> int:
+        return sum(1 for root in self.roots for _ in root.rglob("rollout-*.jsonl"))
+
+    def collect(self) -> Iterator[Interaction]:
+        for root in self.roots:
+            for jsonl in root.rglob("*.jsonl"):
+                yield from self._parse_file(jsonl)
+
+    def _parse_file(self, path: Path) -> Iterator[Interaction]:
+        # Session id is the uuid at the end of the filename if present, else stem.
+        session_id = path.stem.split("-")[-1] if "-" in path.stem else path.stem
+
+        model = "unknown"
+        cwd = ""
+        last_user = ""
+        last_agent = ""
+        seq = 0
+
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except OSError:
+            return
+
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            rtype = record.get("type")
+            payload = record.get("payload")
+            payload = payload if isinstance(payload, dict) else {}
+
+            if rtype == "turn_context":
+                model = str(payload.get("model") or model)
+                cwd = str(payload.get("cwd") or cwd)
+                continue
+
+            if rtype == "session_meta":
+                cwd = str(payload.get("cwd") or cwd)
+                continue
+
+            if rtype != "event_msg":
+                continue
+
+            ptype = payload.get("type")
+            if ptype == "user_message":
+                text = _event_text(payload)
+                if text:
+                    last_user = text
+            elif ptype == "agent_message":
+                text = _event_text(payload)
+                if text:
+                    last_agent = text
+            elif ptype == "token_count":
+                usage = _last_usage(payload)
+                if usage is None:
+                    continue
+                seq += 1
+                yield Interaction(
+                    id=f"codex:{session_id}:{seq}",
+                    tool=self.tool,
+                    session_id=session_id,
+                    timestamp=_parse_ts(record.get("timestamp")),
+                    model=_normalize_model(model),
+                    input_tokens=int(usage.get("input_tokens", 0)),
+                    output_tokens=(
+                        int(usage.get("output_tokens", 0))
+                        + int(usage.get("reasoning_output_tokens", 0))
+                    ),
+                    cache_read_tokens=int(usage.get("cached_input_tokens", 0)),
+                    cwd=cwd,
+                    project=project_for(cwd),
+                    summary=_combine(last_user, last_agent),
+                )
+
+
+def _event_text(payload: dict[str, Any]) -> str:
+    text = payload.get("message") or payload.get("text") or ""
+    return text.strip() if isinstance(text, str) else ""
+
+
+def _combine(user_text: str, agent_text: str) -> str:
+    parts = [p for p in (user_text, agent_text) if p]
+    return " ".join(parts)[:600]
+
+
+def _last_usage(payload: dict[str, Any]) -> dict[str, Any] | None:
+    """Pull the per-turn token usage from a token_count event payload."""
+    info = payload.get("info")
+    if not isinstance(info, dict):
+        return None
+    usage = info.get("last_token_usage") or info.get("total_token_usage")
+    return usage if isinstance(usage, dict) else None
+
+
+def _normalize_model(model: str) -> str:
+    # Codex reports e.g. "gpt-5.5"; normalize dots to dashes for pricing lookup.
+    return model.replace(".", "-")
+
+
+def _parse_ts(raw: object) -> datetime:
+    if isinstance(raw, str):
+        try:
+            return datetime.fromisoformat(raw.replace("Z", "+00:00"))
+        except ValueError:
+            pass
+    return datetime.now()

agent_roi/collectors/copilot.py

@@ -0,0 +1,210 @@
+"""Collector for GitHub Copilot Chat in VS Code.
+
+Copilot stores chat sessions under each VS Code workspace's
+``workspaceStorage/<id>/chatSessions/*.json(l)``. Crucially, these logs record
+the conversation text and the model id, but **not** real token usage (Copilot is
+subscription-billed, so GitHub doesn't write token counts). We therefore
+*estimate* token counts from the message text with a tokenizer and flag the
+interactions as ``estimated`` so reports never present them as exact.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from agent_roi.collectors.base import Collector
+from agent_roi.core.models import Interaction, Tool
+from agent_roi.core.platform import vscode_user_dirs
+from agent_roi.core.project import project_for
+from agent_roi.core.tokens import estimate_tokens
+
+
+class CopilotCollector(Collector):
+    tool = Tool.COPILOT
+    name = "copilot"
+
+    def __init__(self, roots: list[Path] | None = None) -> None:
+        # Each root is a VS Code "User" dir; chat sessions live under its
+        # workspaceStorage subtree.
+        self.roots = roots if roots is not None else vscode_user_dirs()
+
+    def is_available(self) -> bool:
+        return any((r / "workspaceStorage").is_dir() for r in self.roots)
+
+    def search_paths(self) -> list[Path]:
+        return list(self.roots)
+
+    def count_files(self) -> int:
+        total = 0
+        for root in self.roots:
+            ws = root / "workspaceStorage"
+            if ws.is_dir():
+                total += sum(1 for _ in ws.glob("*/chatSessions/*.json*"))
+        return total
+
+    def collect(self) -> Iterator[Interaction]:
+        for root in self.roots:
+            ws = root / "workspaceStorage"
+            if not ws.is_dir():
+                continue
+            for ws_dir in ws.iterdir():
+                if not ws_dir.is_dir():
+                    continue
+                cwd = _workspace_cwd(ws_dir)
+                chat_dir = ws_dir / "chatSessions"
+                if not chat_dir.is_dir():
+                    continue
+                for session_file in chat_dir.glob("*.json*"):
+                    yield from self._parse_file(session_file, cwd)
+
+    def _parse_file(self, path: Path, cwd: str) -> Iterator[Interaction]:
+        session_id = path.stem
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except OSError:
+            return
+        for obj in _load_objects(raw):
+            yield from self._requests_in(obj, session_id, cwd)
+
+    def _requests_in(self, obj: Any, session_id: str, cwd: str) -> Iterator[Interaction]:
+        """Walk an arbitrary JSON structure, yielding an Interaction per Copilot
+        chat request found."""
+        if isinstance(obj, dict):
+            if obj.get("requestId") and "modelId" in obj:
+                itx = self._to_interaction(obj, session_id, cwd)
+                if itx is not None:
+                    yield itx
+            for value in obj.values():
+                yield from self._requests_in(value, session_id, cwd)
+        elif isinstance(obj, list):
+            for value in obj:
+                yield from self._requests_in(value, session_id, cwd)
+
+    def _to_interaction(self, req: dict[str, Any], session_id: str, cwd: str) -> Interaction | None:
+        request_id = req.get("requestId")
+        if not request_id:
+            return None
+
+        user_text = _message_text(req.get("message"))
+        response_text = _response_text(req.get("response"))
+
+        model = str(req.get("modelId") or "unknown")
+        summary = " ".join(p for p in (user_text, response_text) if p)[:600]
+        return Interaction(
+            id=f"copilot:{request_id}",
+            tool=self.tool,
+            session_id=session_id,
+            timestamp=_parse_ts(req.get("timestamp")),
+            model=_normalize_model(model),
+            input_tokens=estimate_tokens(user_text),
+            output_tokens=estimate_tokens(response_text),
+            cwd=cwd,
+            project=project_for(cwd),
+            summary=summary,
+            estimated=True,
+        )
+
+
+def _workspace_cwd(ws_dir: Path) -> str:
+    """Read the workspace folder from VS Code's ``workspace.json``.
+
+    VS Code writes ``workspaceStorage/<hash>/workspace.json`` with a ``folder``
+    key that is a URI such as:
+    - ``file:///Users/yen/repo``  → local path (most common)
+    - ``vscode-remote://ssh-remote%2B<host>/home/yen/repo``  → SSH remote
+
+    We convert both to the plain path portion so ``project_for`` can derive a
+    project name. For remote workspaces we keep a ``ssh:<host>:`` prefix so the
+    project name stays meaningful (e.g. ``repo`` on host ``100.120.0.60``).
+    """
+    from urllib.parse import unquote
+
+    wj = ws_dir / "workspace.json"
+    try:
+        data = json.loads(wj.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return ""
+    folder = str(data.get("folder", ""))
+
+    if folder.startswith("file:///"):
+        # file:///Users/yen/repo -> /Users/yen/repo
+        return unquote(folder[len("file://"):])
+
+    if folder.startswith("vscode-remote://"):
+        # vscode-remote://ssh-remote%2B<host>/path/to/repo
+        rest = folder[len("vscode-remote://"):]
+        slash = rest.find("/")
+        if slash != -1:
+            path = unquote(rest[slash:])
+            return path  # project_for will pick up the last meaningful segment
+        return unquote(rest)
+
+    return folder
+
+
+def _load_objects(raw: str) -> list[Any]:
+    """Parse a session file that may be a single JSON object or JSONL."""
+    try:
+        return [json.loads(raw)]
+    except json.JSONDecodeError:
+        objects: list[Any] = []
+        for line in raw.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                objects.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        return objects
+
+
+def _message_text(message: Any) -> str:
+    if isinstance(message, dict):
+        return str(message.get("text", ""))
+    if isinstance(message, str):
+        return message
+    return ""
+
+
+def _response_text(response: Any) -> str:
+    """Copilot responses are usually a list of parts with a ``value``/``text``."""
+    if isinstance(response, str):
+        return response
+    if isinstance(response, dict):
+        return str(response.get("value") or response.get("text") or "")
+    if isinstance(response, list):
+        parts = []
+        for part in response:
+            if isinstance(part, dict):
+                parts.append(str(part.get("value") or part.get("text") or ""))
+            elif isinstance(part, str):
+                parts.append(part)
+        return "".join(parts)
+    return ""
+
+
+def _normalize_model(model: str) -> str:
+    # Copilot reports e.g. "copilot/claude-opus-4.6"; strip the vendor prefix and
+    # map dots to dashes so it matches the pricing table where possible.
+    name = model.split("/", 1)[-1]
+    return name.replace(".", "-")
+
+
+def _parse_ts(raw: Any) -> datetime:
+    # Copilot timestamps are epoch milliseconds.
+    if isinstance(raw, (int, float)):
+        try:
+            return datetime.fromtimestamp(raw / 1000, tz=timezone.utc)
+        except (ValueError, OSError):
+            pass
+    if isinstance(raw, str):
+        try:
+            return datetime.fromisoformat(raw.replace("Z", "+00:00"))
+        except ValueError:
+            pass
+    return datetime.now(tz=timezone.utc)