argus-code 0.2.0__py3-none-any.whl

argus/__init__.py

@@ -0,0 +1,3 @@
+"""Argus — local-first analytics for Claude Code and other coding agents."""
+
+__version__ = "0.2.0"

argus/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Adapters — one subpackage per coding-agent data source.
+
+Importing this module auto-imports every known adapter so their
+``@register`` decorators run and the registry is populated.
+"""
+# Side-effect imports — each adapter's package self-registers via @register.
+from . import claude_code  # noqa: F401

argus/adapters/base.py

@@ -0,0 +1,108 @@
+"""Adapter contract.
+
+Adapters know how to find and parse one coding-agent's session logs. The
+pipeline, watcher, and server are agent-agnostic — they only see this
+protocol. Anything agent-specific (e.g., Claude Code's ``history.jsonl``
+sidecar, sub-agent rollup) is expressed through the optional extension
+points below; defaults are no-ops so simple adapters stay simple.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from ..schema.types import RawSessionHeader, RawTurnEvent
+
+if TYPE_CHECKING:
+    from ..store.repository import Repository
+
+
+class ParseError(BaseModel):
+    """One JSONL line (or whole-file failure) that couldn't be parsed."""
+
+    file: str
+    byte_offset: int
+    reason: str
+    raw_line_truncated: str
+
+
+class RawToolCall(BaseModel):
+    """Adapter-local tool_call shape. Pipeline stamps session_id + composite id."""
+
+    native_turn_id: str
+    turn_index: int
+    block_index: int
+    tool_name: str
+    tool_use_id: str
+    is_error: int  # 0 | 1
+    input_size: int
+    subagent_type: str | None
+    timestamp: str
+
+
+class RawSegment(BaseModel):
+    """Adapter-local transcript segment. uid_suffix = '{line_uuid}:{block_index}'."""
+
+    uid_suffix: str
+    timestamp: str
+    role: str  # 'user' | 'assistant' | 'thinking' | 'tool_result'
+    text: str
+
+
+class AdapterIngestResult(BaseModel):
+    """What an adapter returns from ingesting one file."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    header: RawSessionHeader
+    turns: list[RawTurnEvent]
+    parse_errors: list[ParseError] = []
+    # Optional — adapters that don't populate these leave them empty. The
+    # pipeline treats empty as "no data", not "delete existing rows".
+    tool_calls: list[RawToolCall] = []
+    segments: list[RawSegment] = []
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """The pluggable contract every agent integration implements."""
+
+    agent: str  # e.g., "claude_code", "codex", "openclaw", "hermes"
+
+    def root_path(self) -> Path: ...
+
+    def is_present(self) -> bool:
+        """True if this agent's data exists on the current machine."""
+        ...
+
+    def discover_session_files(self) -> list[Path]: ...
+
+    def ingest_file(
+        self, path: Path, from_offset: int = 0
+    ) -> tuple[AdapterIngestResult, int]:
+        """Read from ``from_offset``; return (result, new_offset)."""
+        ...
+
+    # ─── Optional extension points (default no-op) ─────────────────────
+
+    def extra_watch_paths(self) -> list[Path]:
+        """Side-channel files this adapter wants tailed (e.g., history.jsonl)."""
+        return []
+
+    def ingest_extra(self, path: Path, repo: "Repository") -> None:
+        """Handle an event on one of ``extra_watch_paths()``."""
+        return None
+
+    def sub_session_files_for(self, session_file: Path) -> list[Path]:
+        """Files that roll up into ``session_file`` (e.g., sub-agent JSONLs)."""
+        return []
+
+    def should_skip(self, path: Path) -> bool:
+        """Watcher predicate — true to silently ignore events on this path."""
+        return False
+
+    def normalize_model_name(self, raw: str) -> str:
+        """Map raw model identifier to the form the pricing table keys on."""
+        return raw

argus/adapters/claude_code/__init__.py

@@ -0,0 +1,5 @@
+"""Claude Code adapter package.
+
+Importing triggers the @register side effect on ClaudeCodeAdapter.
+"""
+from .adapter import ClaudeCodeAdapter  # noqa: F401

argus/adapters/claude_code/adapter.py

@@ -0,0 +1,63 @@
+"""The Claude Code adapter — façade that wires the package together."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ..base import AdapterIngestResult
+from ..registry import register
+from .discover import discover_session_files, sub_agent_files_for
+from .history_jsonl import ingest_history_file
+from .ingest_file import ingest_claude_code_file
+from .model import canonicalize_claude_model
+
+if TYPE_CHECKING:
+    from ...store.repository import Repository
+
+
+def _default_root() -> Path:
+    return Path.home() / ".claude"
+
+
+@register
+class ClaudeCodeAdapter:
+    agent = "claude_code"
+
+    def __init__(self, root: Path | None = None) -> None:
+        self._root = (root or _default_root()).resolve(strict=False)
+
+    def root_path(self) -> Path:
+        return self._root
+
+    def is_present(self) -> bool:
+        return self._root.exists()
+
+    def discover_session_files(self) -> list[Path]:
+        return discover_session_files(self._root)
+
+    def ingest_file(
+        self, path: Path, from_offset: int = 0
+    ) -> tuple[AdapterIngestResult, int]:
+        return ingest_claude_code_file(path, from_offset)
+
+    # ─── Extension-point overrides ─────────────────────────────────────
+
+    def extra_watch_paths(self) -> list[Path]:
+        history = self._root / "history.jsonl"
+        return [history] if history.exists() else []
+
+    def ingest_extra(self, path: Path, repo: "Repository") -> None:
+        # Only the history file is interesting for this adapter.
+        if path.name == "history.jsonl":
+            ingest_history_file(path, repo)
+
+    def sub_session_files_for(self, session_file: Path) -> list[Path]:
+        return sub_agent_files_for(session_file)
+
+    def should_skip(self, path: Path) -> bool:
+        # The subagents/ tree is walked as part of the parent's ingest,
+        # never as standalone sessions.
+        return "subagents" in path.parts
+
+    def normalize_model_name(self, raw: str) -> str:
+        return canonicalize_claude_model(raw)

argus/adapters/claude_code/discover.py

@@ -0,0 +1,72 @@
+"""Discover Claude Code session JSONL files under ``~/.claude/``.
+
+Path-safety rules:
+
+- Realpath every candidate; reject anything that doesn't canonicalize
+  under the claude root (defends against a hostile symlink pointing at
+  ``/etc/passwd``).
+- On Windows, lowercase the comparison since the filesystem is
+  case-insensitive but Python string equality isn't.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+_IS_WIN = sys.platform == "win32"
+
+
+def _norm(p: str) -> str:
+    return p.lower() if _IS_WIN else p
+
+
+def _safe_realpath_under(candidate: Path, canonical_root: Path) -> Path | None:
+    """Return resolved path if it's the root or a descendant, else None."""
+    try:
+        resolved = candidate.resolve(strict=True)
+    except (OSError, RuntimeError):
+        return None
+    a = _norm(str(resolved))
+    b = _norm(str(canonical_root))
+    if a == b:
+        return resolved
+    if a.startswith(b + os.sep):
+        return resolved
+    return None
+
+
+def discover_session_files(claude_root: Path) -> list[Path]:
+    """Find every top-level session JSONL under ``~/.claude/projects/*/``.
+
+    Sub-agent files inside ``<sid>/subagents/`` are intentionally excluded;
+    they're rolled up under their parent session by the pipeline.
+    """
+    projects_dir = claude_root / "projects"
+    if not projects_dir.exists():
+        return []
+    try:
+        canonical_root = claude_root.resolve(strict=True)
+    except (OSError, RuntimeError):
+        return []
+
+    out: list[Path] = []
+    for proj in projects_dir.iterdir():
+        if not proj.is_dir():
+            continue
+        for f in proj.iterdir():
+            if f.suffix != ".jsonl":
+                continue
+            safe = _safe_realpath_under(f, canonical_root)
+            if safe is not None:
+                out.append(f)
+    return out
+
+
+def sub_agent_files_for(session_file: Path) -> list[Path]:
+    """Return ``<session_dir>/<sid>/subagents/*.jsonl`` if it exists."""
+    sid = session_file.stem  # filename without .jsonl
+    sub = session_file.parent / sid / "subagents"
+    if not sub.exists():
+        return []
+    return sorted(f for f in sub.iterdir() if f.suffix == ".jsonl")

argus/adapters/claude_code/extract_tool_calls.py

@@ -0,0 +1,86 @@
+"""Extract one RawToolCall per tool_use block."""
+from __future__ import annotations
+
+import json
+
+from ..base import RawToolCall
+from .schemas import AssistantLine, UserLine
+
+
+def _safe_json_length(v: object) -> int:
+    """Length of JSON-stringified ``v``, matching JS ``JSON.stringify`` byte count."""
+    try:
+        # Compact separators reproduce JS default JSON.stringify output
+        # (no whitespace), so input_size stays consistent with the TS impl.
+        return len(json.dumps(v, separators=(",", ":")))
+    except (TypeError, ValueError):
+        return 0
+
+
+def extract_tool_calls(
+    assistant_lines: list[AssistantLine],
+    user_lines: list[UserLine],
+) -> list[RawToolCall]:
+    """Emit one RawToolCall per tool_use block; attribute is_error from results."""
+    # 1) Build tool_use_id → is_error from tool_result blocks in user messages.
+    error_map: dict[str, bool] = {}
+    for u in user_lines:
+        content = u.message.content
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") != "tool_result":
+                continue
+            tool_use_id = block.get("tool_use_id")
+            if not isinstance(tool_use_id, str):
+                continue
+            is_err_raw = block.get("is_error", False)
+            flag = is_err_raw is True or is_err_raw == "true"
+            error_map[tool_use_id] = flag
+
+    # 2) Group assistant lines by message.id, preserve order.
+    by_id: dict[str, list[AssistantLine]] = {}
+    order: list[str] = []
+    for line in assistant_lines:
+        mid = line.message.id
+        if mid not in by_id:
+            by_id[mid] = []
+            order.append(mid)
+        by_id[mid].append(line)
+
+    # 3) Emit one RawToolCall per tool_use block.
+    out: list[RawToolCall] = []
+    turn_index = 0
+    for mid in order:
+        group = by_id[mid]
+        block_index = 0
+        for line in group:
+            for block in line.message.content:
+                if block.get("type") != "tool_use":
+                    continue
+                inp = block.get("input") or {}
+                name = block.get("name") or ""
+                use_id = block.get("id") or ""
+                subagent = (
+                    inp.get("subagent_type")
+                    if name == "Task" and isinstance(inp, dict) and isinstance(inp.get("subagent_type"), str)
+                    else None
+                )
+                out.append(
+                    RawToolCall(
+                        native_turn_id=mid,
+                        turn_index=turn_index,
+                        block_index=block_index,
+                        tool_name=name,
+                        tool_use_id=use_id,
+                        is_error=1 if error_map.get(use_id) else 0,
+                        input_size=_safe_json_length(inp),
+                        subagent_type=subagent,
+                        timestamp=line.timestamp,
+                    )
+                )
+                block_index += 1
+        turn_index += 1
+    return out

argus/adapters/claude_code/extract_transcript.py

@@ -0,0 +1,111 @@
+"""Extract searchable transcript segments from a session's lines."""
+from __future__ import annotations
+
+from ..base import RawSegment
+from .schemas import AssistantLine, UserLine
+
+# Per-segment byte cap. Tool_result content (a Read of a file, a Bash of a
+# build log) can be enormous; indexing the entire body bloats FTS5 for
+# very little search value.
+SEGMENT_CAP_BYTES = 16 * 1024
+
+
+def _cap_text(s: str) -> str:
+    """Truncate ``s`` to ``SEGMENT_CAP_BYTES`` UTF-8 bytes with an ellipsis."""
+    encoded = s.encode("utf-8")
+    if len(encoded) <= SEGMENT_CAP_BYTES:
+        return s
+    # Walk back to a unicode-safe boundary by decoding with errors='ignore'.
+    truncated = encoded[:SEGMENT_CAP_BYTES].decode("utf-8", errors="ignore")
+    return truncated + "…"
+
+
+def extract_transcript_segments(
+    assistant_lines: list[AssistantLine],
+    user_lines: list[UserLine],
+) -> list[RawSegment]:
+    out: list[RawSegment] = []
+
+    for line in assistant_lines:
+        block_idx = 0
+        for block in line.message.content:
+            btype = block.get("type")
+            if btype == "text":
+                text = block.get("text")
+                if isinstance(text, str) and text.strip():
+                    out.append(
+                        RawSegment(
+                            uid_suffix=f"{line.uuid}:{block_idx}",
+                            timestamp=line.timestamp,
+                            role="assistant",
+                            text=_cap_text(text),
+                        )
+                    )
+            elif btype == "thinking":
+                text = block.get("thinking")
+                if isinstance(text, str) and text.strip():
+                    out.append(
+                        RawSegment(
+                            uid_suffix=f"{line.uuid}:{block_idx}",
+                            timestamp=line.timestamp,
+                            role="thinking",
+                            text=_cap_text(text),
+                        )
+                    )
+            block_idx += 1
+
+    for line in user_lines:
+        c = line.message.content
+        if isinstance(c, str):
+            if c.strip():
+                out.append(
+                    RawSegment(
+                        uid_suffix=f"{line.uuid}:0",
+                        timestamp=line.timestamp,
+                        role="user",
+                        text=_cap_text(c),
+                    )
+                )
+            continue
+        if not isinstance(c, list):
+            continue
+        block_idx = 0
+        for block in c:
+            if not isinstance(block, dict):
+                block_idx += 1
+                continue
+            btype = block.get("type")
+            if btype == "text" and isinstance(block.get("text"), str) and block["text"].strip():
+                out.append(
+                    RawSegment(
+                        uid_suffix=f"{line.uuid}:{block_idx}",
+                        timestamp=line.timestamp,
+                        role="user",
+                        text=_cap_text(block["text"]),
+                    )
+                )
+            elif btype == "tool_result":
+                content = block.get("content")
+                combined = ""
+                if isinstance(content, str):
+                    combined = content
+                elif isinstance(content, list):
+                    parts = []
+                    for sub in content:
+                        if isinstance(sub, dict):
+                            t = sub.get("text")
+                            if isinstance(t, str):
+                                parts.append(t)
+                    combined = "\n".join(p for p in parts if p)
+                if combined.strip():
+                    out.append(
+                        RawSegment(
+                            uid_suffix=f"{line.uuid}:{block_idx}",
+                            timestamp=line.timestamp,
+                            role="tool_result",
+                            text=_cap_text(combined),
+                        )
+                    )
+            block_idx += 1
+
+    return out

argus/adapters/claude_code/extract_turns.py

@@ -0,0 +1,69 @@
+"""Build per-turn records from a session's assistant lines."""
+from __future__ import annotations
+
+from ...schema.types import RawTurnEvent
+from .model import canonicalize_claude_model
+from .schemas import AssistantLine
+
+
+def extract_turns(lines: list[AssistantLine]) -> list[RawTurnEvent]:
+    """Group assistant lines by message.id, emit one RawTurnEvent per group.
+
+    A single message can be split across multiple JSONL lines (one per
+    content block in some Claude Code versions) — all sharing message.id.
+    We preserve first-seen order and walk every line in the group.
+    """
+    by_id: dict[str, list[AssistantLine]] = {}
+    order: list[str] = []
+    for line in lines:
+        mid = line.message.id
+        if mid not in by_id:
+            by_id[mid] = []
+            order.append(mid)
+        by_id[mid].append(line)
+
+    turns: list[RawTurnEvent] = []
+    seq = 0
+    for mid in order:
+        group = by_id[mid]
+        first = group[0]
+        usage = first.message.usage
+        cache_5m = (
+            usage.cache_creation.ephemeral_5m_input_tokens
+            if usage.cache_creation is not None
+            else None
+        )
+        cache_1h = (
+            usage.cache_creation.ephemeral_1h_input_tokens
+            if usage.cache_creation is not None
+            else None
+        )
+        tool_calls = sum(
+            sum(1 for b in line.message.content if b.get("type") == "tool_use")
+            for line in group
+        )
+
+        turns.append(
+            RawTurnEvent(
+                native_turn_id=mid,
+                sequence=seq,
+                timestamp=first.timestamp,
+                model=canonicalize_claude_model(first.message.model),
+                model_raw=first.message.model,
+                fresh_input_tokens=usage.input_tokens,
+                output_tokens=usage.output_tokens,
+                cache_read_tokens=usage.cache_read_input_tokens,
+                cache_write_tokens=usage.cache_creation_input_tokens,
+                cache_write_5m_tokens=cache_5m,
+                cache_write_1h_tokens=cache_1h,
+                tool_calls_count=tool_calls,
+                metadata={
+                    "service_tier": usage.service_tier,
+                    "agentId": first.agentId,
+                    "attribution_agent": first.attribution_agent,
+                    "isSidechain": first.isSidechain if first.isSidechain is not None else False,
+                },
+            )
+        )
+        seq += 1
+    return turns

argus/adapters/claude_code/history_jsonl.py

@@ -0,0 +1,138 @@
+"""Ingest ``~/.claude/history.jsonl`` — the global prompt history file.
+
+Byte-offset tail like sessions. Partial last line is held back until
+newline. If the file shrinks below the recorded offset (rotation /
+truncation), we reset to 0 and re-ingest.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from ...schema.types import Prompt
+from ...store.repository import normalize_project_path
+
+if TYPE_CHECKING:
+    from ...store.repository import Repository
+
+# Hard cap on the indexed body. 8 KB is past any realistic hand-typed
+# prompt; longer values are almost always a paste-by-mistake.
+DISPLAY_CAP_BYTES = 8 * 1024
+MAX_TICK_BYTES = 64 * 1024 * 1024
+
+
+class HistoryLine(BaseModel):
+    """One line of ~/.claude/history.jsonl."""
+
+    model_config = ConfigDict(extra="allow")
+
+    display: str
+    pastedContents: dict[str, Any] = Field(default_factory=dict)
+    timestamp: int
+    project: str
+
+
+class HistoryIngestStats(BaseModel):
+    inserted: int
+    skipped_empty: int
+    parse_errors: int
+    new_offset: int
+
+
+def line_to_prompt(line: HistoryLine) -> Prompt | None:
+    """Pure transformation: history line → Prompt row, or None if skipped."""
+    trimmed = line.display.strip()
+    if trimmed == "":
+        return None
+
+    display = line.display
+    if len(display.encode("utf-8")) > DISPLAY_CAP_BYTES:
+        # Walk back to a unicode-safe boundary by decoding with errors='ignore'.
+        truncated = display.encode("utf-8")[: DISPLAY_CAP_BYTES - 1].decode(
+            "utf-8", errors="ignore"
+        )
+        display = truncated + "…"
+
+    try:
+        # Compact separators match JS ``JSON.stringify`` byte count, so
+        # the pasted_chars upper bound is identical across stacks.
+        pasted_chars = len(json.dumps(line.pastedContents or {}, separators=(",", ":")))
+        if pasted_chars <= 2:  # "{}"
+            pasted_chars = 0
+    except (TypeError, ValueError):
+        pasted_chars = 0
+
+    return Prompt(
+        timestamp_ms=line.timestamp,
+        project_path=normalize_project_path(line.project),
+        display=display,
+        pasted_chars=pasted_chars,
+        is_slash=1 if trimmed.startswith("/") else 0,
+    )
+
+
+def ingest_history_file(
+    file_path: Path, repo: "Repository"
+) -> HistoryIngestStats:
+    """Read ``file_path`` from the stored offset, append new prompts."""
+    offset_key = f"history:{file_path}"
+    from_offset = repo.get_file_offset(offset_key)
+
+    with open(file_path, "rb") as fh:
+        fh.seek(0, 2)
+        size = fh.tell()
+
+        # Rotation / truncation: file smaller than the offset → re-ingest.
+        if size < from_offset:
+            from_offset = 0
+
+        if size <= from_offset:
+            return HistoryIngestStats(
+                inserted=0, skipped_empty=0, parse_errors=0, new_offset=from_offset
+            )
+
+        read_len = min(size - from_offset, MAX_TICK_BYTES)
+        fh.seek(from_offset)
+        raw = fh.read(read_len)
+
+    text = raw.decode("utf-8", errors="replace")
+    last_nl = text.rfind("\n")
+    consumable = text[: last_nl + 1] if last_nl != -1 else ""
+    consumed_bytes = len(consumable.encode("utf-8"))
+    new_offset = from_offset + consumed_bytes
+
+    rows: list[Prompt] = []
+    parse_errors = 0
+    skipped_empty = 0
+
+    for line in consumable.split("\n"):
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            parse_errors += 1
+            continue
+        try:
+            parsed = HistoryLine.model_validate(obj)
+        except ValidationError:
+            parse_errors += 1
+            continue
+        row = line_to_prompt(parsed)
+        if row is None:
+            skipped_empty += 1
+            continue
+        rows.append(row)
+
+    repo.insert_prompts(rows)
+    repo.set_file_offset(offset_key, new_offset)
+
+    return HistoryIngestStats(
+        inserted=len(rows),
+        skipped_empty=skipped_empty,
+        parse_errors=parse_errors,
+        new_offset=new_offset,
+    )