agentprof 0.1.0__py3-none-any.whl

agentprof/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""agentprof: analyse AI coding agent sessions."""
+
+from importlib.metadata import version
+
+__version__ = version("agentprof")

agentprof/adapters/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Agent adapters: turn agent-specific session files into the neutral model."""
+
+from importlib.metadata import entry_points
+
+from agentprof.adapters.base import AdapterConfig, AgentAdapter
+
+ENTRY_POINT_GROUP = "agentprof.adapters"
+
+
+def load_adapters(config: AdapterConfig) -> list[AgentAdapter]:
+    """Instantiate every adapter registered under the `agentprof.adapters` entry point group."""
+    registered = sorted(entry_points(group=ENTRY_POINT_GROUP), key=lambda entry_point: entry_point.name)
+    return [entry_point.load()(config) for entry_point in registered]

agentprof/adapters/base.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""The adapter protocol and the lightweight types the registry works with."""
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from agentprof.model import CostMetric, Session
+
+
+def latest_mtime(paths: Iterable[Path]) -> float:
+    """The newest modification time among `paths`; paths that vanished meanwhile are ignored."""
+    times: list[float] = []
+    for path in paths:
+        try:
+            times.append(path.stat().st_mtime)
+        except OSError:
+            continue
+    return max(times, default=0.0)
+
+
+@dataclass(frozen=True)
+class AdapterConfig:
+    """User configuration shared by all adapters.
+
+    `roots` maps an adapter name to an overriding data root; `pricing_file` replaces the bundled price table.
+    """
+
+    roots: dict[str, Path] = field(default_factory=dict)
+    pricing_file: Path | None = None
+
+
+@dataclass(frozen=True)
+class SessionRef:
+    """A cheap handle to one session file."""
+
+    agent: str
+    native_id: str
+    path: Path
+    mtime: float
+
+    @property
+    def id(self) -> str:
+        return f"{self.agent}:{self.native_id}"
+
+
+@dataclass
+class SessionSummary:
+    """One row of the session list: only what an adapter can read without building the tree."""
+
+    id: str
+    agent: str
+    title: str
+    workspace: str | None
+    start_ms: float | None
+    end_ms: float | None
+    file_size: int
+    last_activity_ms: float | None = None
+    cost_total: CostMetric = field(default_factory=CostMetric.not_available)
+
+
+class AgentAdapter(Protocol):
+    """Turns one agent's session files into the neutral model.
+
+    Implementations are constructed with an `AdapterConfig` and registered under the entry point group
+    `agentprof.adapters`. `summarize` and `analyze` raise on sessions they cannot read.
+    """
+
+    name: str
+
+    def discover(self) -> Iterable[SessionRef]: ...
+
+    def open_path(self, path: Path) -> SessionRef | None: ...
+
+    def summarize(self, ref: SessionRef) -> SessionSummary: ...
+
+    def analyze(self, ref: SessionRef) -> Session: ...

agentprof/adapters/claude_code/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Claude Code adapter."""

agentprof/adapters/claude_code/adapter.py

@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""The Claude Code adapter."""
+
+import json
+import os
+from collections import Counter
+from collections.abc import Iterator
+from pathlib import Path
+
+from agentprof.adapters.base import AdapterConfig, SessionRef, SessionSummary, latest_mtime
+from agentprof.adapters.claude_code.discovery import (
+    default_projects_root,
+    load_subagents,
+    session_files,
+    subagent_dir,
+)
+from agentprof.adapters.claude_code.prompts import NO_PROMPT, prompt_topic
+from agentprof.adapters.claude_code.tools import is_known_tool_id
+from agentprof.adapters.claude_code.transcript import Transcript, load_transcript
+from agentprof.adapters.claude_code.tree import build_root, message_cost
+from agentprof.model import Diagnostics, Session, sum_costs
+from agentprof.pricing import PriceTable
+
+_TITLE_LENGTH = 80
+_SNIFF_LINES = 20
+_SUBAGENT_DIR = "subagents"
+
+
+def _title(main: Transcript, fallback: str) -> str:
+    if main.title:
+        return main.title
+    for prompt in main.prompts:
+        topic = prompt_topic(prompt.text)
+        if topic != NO_PROMPT:
+            return topic[:_TITLE_LENGTH]
+    return fallback
+
+
+def _looks_like_session(path: Path) -> bool:
+    """Whether one of the first lines is a Claude Code entry carrying a `sessionId`."""
+    try:
+        with path.open(encoding="utf-8") as lines:
+            for _, line in zip(range(_SNIFF_LINES), lines, strict=False):
+                try:
+                    entry = json.loads(line)
+                except ValueError:
+                    continue
+                if isinstance(entry, dict) and isinstance(entry.get("sessionId"), str):
+                    return True
+    except (OSError, UnicodeDecodeError):
+        return False
+    return False
+
+
+class ClaudeCodeAdapter:
+    """Reads Claude Code sessions from `~/.claude/projects`."""
+
+    name = "claude-code"
+
+    def __init__(self, config: AdapterConfig) -> None:
+        override = config.roots.get(self.name)
+        self._root = override if override is not None else default_projects_root(os.environ, Path.home())
+        self._prices = PriceTable.load(config.pricing_file)
+
+    def _ref(self, path: Path) -> SessionRef:
+        files = [path, *subagent_dir(path).glob("agent-*")]
+        return SessionRef(agent=self.name, native_id=path.stem, path=path, mtime=latest_mtime(files))
+
+    def discover(self) -> Iterator[SessionRef]:
+        for path in session_files(self._root):
+            yield self._ref(path)
+
+    def open_path(self, path: Path) -> SessionRef | None:
+        if path.suffix != ".jsonl" or path.parent.name == _SUBAGENT_DIR or not path.is_file():
+            return None
+        return self._ref(path) if _looks_like_session(path) else None
+
+    def summarize(self, ref: SessionRef) -> SessionSummary:
+        main = load_transcript(ref.path)
+        transcripts = [main, *(subagent.transcript for subagent in load_subagents(ref.path))]
+        return SessionSummary(
+            id=ref.id,
+            agent=self.name,
+            title=_title(main, ref.native_id),
+            workspace=main.cwd,
+            start_ms=main.first_timestamp_ms if main.first_timestamp_ms is not None else ref.mtime * 1000,
+            end_ms=ref.mtime * 1000,
+            file_size=ref.path.stat().st_size,
+            last_activity_ms=max(
+                (timestamp for transcript in transcripts if (timestamp := transcript.last_message_ms) is not None),
+                default=None,
+            ),
+            cost_total=sum_costs(
+                [message_cost(message, self._prices) for transcript in transcripts for message in transcript.messages]
+            ),
+        )
+
+    def analyze(self, ref: SessionRef) -> Session:
+        main = load_transcript(ref.path)
+        subagents = load_subagents(ref.path)
+        transcripts = [main, *(subagent.transcript for subagent in subagents)]
+        diagnostics = Diagnostics(malformed_lines=sum(transcript.malformed_lines for transcript in transcripts))
+        diagnostics.malformed_line_details = [
+            detail for transcript in transcripts for detail in transcript.malformed_line_details
+        ][:20]
+        diagnostics.unknown_tool_ids = dict(
+            Counter(
+                tool_use.name
+                for transcript in transcripts
+                for tool_use in transcript.tool_uses
+                if not is_known_tool_id(tool_use.name)
+            )
+        )
+        unpriced = sorted(
+            {
+                message.model
+                for transcript in transcripts
+                for message in transcript.messages
+                if message.model and self._prices.price_for(message.model) is None
+            }
+        )
+        diagnostics.warnings.extend(f"No price for model {model!r}: its cost is unavailable." for model in unpriced)
+        title = _title(main, ref.native_id)
+        return Session(
+            id=ref.id,
+            agent=self.name,
+            title=title,
+            workspace=main.cwd,
+            root=build_root(main, subagents, self._prices, title),
+            sources=["transcript", *(["subagents"] if subagents else [])],
+            diagnostics=diagnostics,
+        )

agentprof/adapters/claude_code/discovery.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Locate Claude Code session files and their subagent transcripts."""
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from agentprof.adapters.claude_code.transcript import Transcript, load_transcript
+
+_AGENT_PREFIX = "agent-"
+
+
+@dataclass(frozen=True)
+class SubagentMeta:
+    """Contents of `agent-<id>.meta.json`; `tool_use_id` names the `Agent` call that spawned the subagent."""
+
+    agent_id: str
+    tool_use_id: str | None
+    agent_type: str | None
+    description: str | None
+    model: str | None
+
+
+@dataclass
+class Subagent:
+    meta: SubagentMeta
+    transcript: Transcript
+
+
+def default_projects_root(env: Mapping[str, str], home: Path) -> Path:
+    """`$CLAUDE_CONFIG_DIR/projects` if set, else `~/.claude/projects`."""
+    config_dir = env.get("CLAUDE_CONFIG_DIR")
+    return (Path(config_dir) if config_dir else home / ".claude") / "projects"
+
+
+def session_files(root: Path) -> list[Path]:
+    """Main transcripts: `<root>/<project-dir>/<session-id>.jsonl` (subagent files sit deeper)."""
+    return sorted(root.glob("*/*.jsonl"))
+
+
+def subagent_dir(session_file: Path) -> Path:
+    """`<project-dir>/<session-id>/subagents/`, next to the main transcript."""
+    return session_file.parent / session_file.stem / "subagents"
+
+
+def read_meta(agent_id: str, meta_file: Path) -> SubagentMeta:
+    """Read a subagent's meta file; missing or invalid files yield a meta without spawning call."""
+    try:
+        data = json.loads(meta_file.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        data = {}
+    if not isinstance(data, dict):
+        data = {}
+
+    def text(key: str) -> str | None:
+        value = data.get(key)
+        return value if isinstance(value, str) and value else None
+
+    return SubagentMeta(
+        agent_id=agent_id,
+        tool_use_id=text("toolUseId"),
+        agent_type=text("agentType"),
+        description=text("description"),
+        model=text("model"),
+    )
+
+
+def load_subagents(session_file: Path) -> list[Subagent]:
+    """Parse every subagent transcript of a session, flat regardless of nesting depth."""
+    directory = subagent_dir(session_file)
+    subagents: list[Subagent] = []
+    for path in sorted(directory.glob(f"{_AGENT_PREFIX}*.jsonl")):
+        agent_id = path.stem.removeprefix(_AGENT_PREFIX)
+        subagents.append(
+            Subagent(meta=read_meta(agent_id, path.with_suffix(".meta.json")), transcript=load_transcript(path))
+        )
+    return subagents

agentprof/adapters/claude_code/prompts.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Derive a short, human-readable topic from a Claude Code turn prompt."""
+
+import re
+
+NO_PROMPT = "(no prompt)"
+_TOPIC_LENGTH = 200
+_BLOCK_TAGS = ("ide_opened_file", "ide_selection", "system-reminder", "local-command-caveat")
+_BLOCK_RE = re.compile("|".join(rf"<{tag}>.*?</{tag}>" for tag in _BLOCK_TAGS), re.DOTALL)
+_COMMAND_RE = re.compile(r"<command-name>(.*?)</command-name>(?:<command-args>(.*?)</command-args>)?", re.DOTALL)
+_LOCAL_COMMAND_STDOUT_RE = re.compile(r"<local-command-stdout>.*?</local-command-stdout>", re.DOTALL)
+_TASK_NOTIFICATION_RE = re.compile(r"<task-notification>(.*?)</task-notification>", re.DOTALL)
+_SUMMARY_RE = re.compile(r"<summary>(.*?)</summary>", re.DOTALL)
+
+
+def first_line(text: str, limit: int) -> str:
+    """The first non-blank line of `text`, stripped and cut to `limit` characters."""
+    return next((line.strip()[:limit] for line in text.splitlines() if line.strip()), "")
+
+
+def prompt_topic(text: str) -> str:
+    """A short topic for a turn prompt, stripping IDE/harness context and special markup."""
+    stripped = _BLOCK_RE.sub("", text)
+
+    command_match = _COMMAND_RE.search(stripped)
+    if command_match is not None:
+        name = command_match.group(1).strip()
+        args = (command_match.group(2) or "").strip()
+        return f"{name} {args}" if args else name
+
+    without_stdout = _LOCAL_COMMAND_STDOUT_RE.sub("", stripped)
+    if without_stdout != stripped and not without_stdout.strip():
+        return "(command output)"
+    stripped = without_stdout
+
+    notification_match = _TASK_NOTIFICATION_RE.search(stripped)
+    if notification_match is not None:
+        summary_match = _SUMMARY_RE.search(notification_match.group(1))
+        if summary_match is not None:
+            return f"Task notification: {summary_match.group(1).strip()}"
+        return "Task notification"
+
+    return first_line(stripped, _TOPIC_LENGTH) or NO_PROMPT

agentprof/adapters/claude_code/tools.py

@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Map Claude Code tool names to neutral tool categories and normalised arguments."""
+
+from agentprof.model import ToolCategory, ToolInfo
+
+_CATEGORIES: dict[str, ToolCategory] = {
+    "Read": ToolCategory.READ,
+    "Edit": ToolCategory.EDIT,
+    "Write": ToolCategory.EDIT,
+    "NotebookEdit": ToolCategory.EDIT,
+    "Grep": ToolCategory.SEARCH,
+    "Glob": ToolCategory.SEARCH,
+    "Bash": ToolCategory.SHELL,
+    "BashOutput": ToolCategory.SHELL_POLL,
+    "TaskOutput": ToolCategory.SHELL_POLL,
+    "Monitor": ToolCategory.SHELL_POLL,
+    "WebFetch": ToolCategory.WEB,
+    "WebSearch": ToolCategory.WEB,
+    "Agent": ToolCategory.SUBAGENT,
+    "Task": ToolCategory.SUBAGENT,
+}
+
+# Built-in harness tools without a dedicated category; they map to `other` but are not reported as unknown.
+_KNOWN_OTHER_TOOL_IDS = {
+    "AskUserQuestion",
+    "ToolSearch",
+    "Skill",
+    "SendMessage",
+    "ListAgents",
+    "TaskCreate",
+    "TaskUpdate",
+    "TaskList",
+    "TaskGet",
+    "TaskStop",
+    "KillShell",
+    "TodoWrite",
+    "EnterPlanMode",
+    "ExitPlanMode",
+    "EnterWorktree",
+    "ExitWorktree",
+    "ScheduleWakeup",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
+    "PushNotification",
+    "RemoteTrigger",
+    "ReadNotifications",
+    "SendUserFile",
+    "SlashCommand",
+    "LSP",
+    "Artifact",
+    "ArtifactComments",
+    "ArtifactData",
+    "ReportFindings",
+    "SendFeedback",
+}
+_CATEGORIES_CASEFOLDED = {name.casefold(): category for name, category in _CATEGORIES.items()}
+_KNOWN_OTHER_TOOL_IDS_CASEFOLDED = {name.casefold() for name in _KNOWN_OTHER_TOOL_IDS}
+_MCP_PREFIX = "mcp__"
+_FILE_CATEGORIES = (ToolCategory.READ, ToolCategory.EDIT)
+_WHOLE_FILE_WRITERS = {"write"}
+
+
+def is_known_tool_id(name: str) -> bool:
+    """Whether `name` is expected; unknown names are counted in the session diagnostics."""
+    normalized = name.casefold()
+    return (
+        normalized in _CATEGORIES_CASEFOLDED
+        or normalized in _KNOWN_OTHER_TOOL_IDS_CASEFOLDED
+        or normalized.startswith(_MCP_PREFIX)
+    )
+
+
+def _positive_int(value: object) -> int | None:
+    return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else None
+
+
+def _line_range(arguments: dict[str, object]) -> tuple[int, int] | None:
+    """`Read` takes a 1-based start line `offset` and a line count `limit`; without both it may read the whole file."""
+    offset = _positive_int(arguments.get("offset"))
+    limit = _positive_int(arguments.get("limit"))
+    if limit is None:
+        return None
+    start = offset or 1
+    return (start, start + limit - 1)
+
+
+def tool_info(name: str, arguments: dict[str, object]) -> ToolInfo:
+    """Build the neutral `ToolInfo` for one Claude Code tool call."""
+    category = _CATEGORIES_CASEFOLDED.get(name.casefold(), ToolCategory.OTHER)
+    path = arguments.get("file_path") or arguments.get("notebook_path")
+    command = arguments.get("command")
+    return ToolInfo(
+        native_id=name,
+        category=category,
+        path=str(path) if path and category in _FILE_CATEGORIES else None,
+        line_range=_line_range(arguments) if category is ToolCategory.READ else None,
+        command=str(command) if command and category is ToolCategory.SHELL else None,
+        writes_file=name.casefold() in _WHOLE_FILE_WRITERS,
+        arguments=arguments,
+    )