agent-trace-cli 0.1.0__py3-none-any.whl

agent_trace/hooks/codex.py

@@ -0,0 +1,232 @@
+"""
+Codex CLI adapter — hooks injection, event translators, summary
+lifecycle.
+
+OpenAI's Codex CLI exposes a single hook surface called ``notify``: a
+program declared in ``~/.codex/config.toml`` which Codex spawns when an
+agent turn completes. The program receives a JSON payload as its last
+argv, e.g.::
+
+    {"type": "agent-turn-complete", "turn-id": "...",
+     "input-messages": [...], "last-assistant-message": "..."}
+
+Strategy:
+
+  - ``inject`` writes a ``notify`` entry that pipes Codex's JSON through
+    a tiny shell wrapper into ``agent-trace record``. The wrapper also
+    annotates the event with a canonical ``hook_event_name`` so the
+    record dispatcher knows which adapter owns it.
+  - The canonical event names this adapter emits:
+        * ``CodexTurnComplete`` — one trace per finished agent turn
+        * ``CodexSessionStart`` — set-up hook (optional, written when
+          Codex's config supports it; Codex doesn't currently expose
+          a session-start hook, so this event is here so tests and
+          future Codex versions can drive it via stdin).
+  - For tests / fixtures, simply pipe a JSON object with
+    ``"hook_event_name": "CodexTurnComplete"`` into ``agent-trace
+    record`` (mirrors the Cursor / Claude testing pattern).
+
+To add a new coding agent, copy this file, swap the config-path /
+shell-wrapper bits, declare your event names and translators, and
+register the adapter in ``hooks/__init__.py``. The CLI, doctor, status
+and rule surfaces will pick it up automatically.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .base import AGENT_TRACE_CMD, CodingAgentAdapter
+
+
+CODEX_DIR = Path.home() / ".codex"
+CODEX_CONFIG_FILE = CODEX_DIR / "config.toml"
+
+# Shell snippet Codex's ``notify`` will invoke. It takes Codex's JSON
+# payload (passed as the last argv), tags it with a ``hook_event_name``
+# keyed off the payload's ``type`` field, and pipes the result into
+# ``agent-trace record``.
+_NOTIFY_SHELL = (
+    "payload=\"$1\"; "
+    "case \"$payload\" in *agent-turn-complete*) ev=CodexTurnComplete;; "
+    "*) ev=CodexUnknown;; esac; "
+    'printf \'%s\' "$payload" | python3 -c '
+    "'import json,sys; "
+    'd=json.loads(sys.stdin.read() or "{}"); '
+    'd["hook_event_name"]=sys.argv[1]; '
+    "print(json.dumps(d))' "
+    "\"$ev\" | agent-trace record"
+)
+
+# Marker line written into config.toml when our notify entry is present.
+_AGENT_TRACE_NOTIFY_MARKER = "# agent-trace:notify"
+_NOTIFY_ARRAY_PREFIX = "notify = "
+
+
+# ---------------------------------------------------------------------
+# Event translators (hook payload → trace record)
+# ---------------------------------------------------------------------
+
+def _TurnComplete(d):
+    from ..record import transcript_path_from_hook
+    from ..trace import create_trace, resolve_file_project
+
+    anchor = d.get("cwd") or os.getcwd()
+    res = resolve_file_project(".sessions", anchor_path=anchor)
+    last_msg = d.get("last-assistant-message") or d.get("last_assistant_message")
+    metadata = {
+        "event": "turn_complete",
+        "turn_id": d.get("turn-id") or d.get("turn_id"),
+        "session_id": d.get("session_id") or d.get("session-id"),
+        "input_messages": d.get("input-messages") or d.get("input_messages"),
+        "last_assistant_message": last_msg,
+    }
+    return create_trace(
+        "ai", ".sessions",
+        model=d.get("model") or d.get("model_id"),
+        transcript=transcript_path_from_hook(d),
+        metadata=metadata,
+        anchor_path=anchor,
+        resolution=res,
+    ), "CodexTurnComplete"
+
+
+def _SessionStart(d):
+    from ..trace import create_trace, resolve_file_project
+
+    anchor = d.get("cwd") or os.getcwd()
+    res = resolve_file_project(".sessions", anchor_path=anchor)
+    return create_trace(
+        "ai", ".sessions",
+        model=d.get("model") or d.get("model_id"),
+        metadata={
+            "event": "session_start",
+            "session_id": d.get("session_id") or d.get("session-id"),
+            "source": d.get("source"),
+        },
+        anchor_path=anchor,
+        resolution=res,
+    ), "CodexSessionStart"
+
+
+# ---------------------------------------------------------------------
+# Adapter
+# ---------------------------------------------------------------------
+
+class CodexAdapter(CodingAgentAdapter):
+    name = "codex"
+    display_name = "Codex CLI"
+    rules_dir = ".codex/rules"
+    rule_extension = ".md"
+
+    EVENTS = {
+        "CodexTurnComplete": _TurnComplete,
+        "CodexSessionStart": _SessionStart,
+    }
+
+    def global_config_path(self) -> Path:
+        return CODEX_CONFIG_FILE
+
+    def project_config_paths(self) -> tuple[str, ...]:
+        # Codex has no project-scoped config, but we drop a marker so
+        # ``doctor`` can show "project notify hook installed via Codex".
+        return (".codex/agent-trace.installed",)
+
+    def detect_tool_info(self) -> dict | None:
+        ver = os.environ.get("CODEX_VERSION")
+        if ver:
+            return {"name": "codex", "version": ver}
+        if os.environ.get("CODEX_HOME"):
+            return {"name": "codex"}
+        return None
+
+    def inject(
+        self,
+        record_invocation: str,  # noqa: ARG002 — recorded inside _NOTIFY_SHELL
+        project_dir: str | None = None,
+        *,
+        global_install: bool = False,
+    ) -> bool:
+        if not global_install:
+            if project_dir is None:
+                project_dir = os.getcwd()
+            project_marker = Path(project_dir) / ".codex" / "agent-trace.installed"
+            project_marker.parent.mkdir(parents=True, exist_ok=True)
+            project_marker.write_text(
+                "Codex's notify hook is user-scoped (~/.codex/config.toml).\n"
+                "Run: agent-trace hooks setup-global --tool codex\n",
+            )
+            return True
+
+        CODEX_DIR.mkdir(parents=True, exist_ok=True)
+        existing = ""
+        if CODEX_CONFIG_FILE.exists():
+            try:
+                existing = CODEX_CONFIG_FILE.read_text()
+            except OSError:
+                existing = ""
+
+        if _AGENT_TRACE_NOTIFY_MARKER in existing and AGENT_TRACE_CMD in existing:
+            return True  # idempotent
+
+        cleaned_lines: list[str] = []
+        skip_next_notify = False
+        for line in existing.splitlines():
+            if line.strip() == _AGENT_TRACE_NOTIFY_MARKER:
+                skip_next_notify = True
+                continue
+            if skip_next_notify and line.lstrip().startswith(_NOTIFY_ARRAY_PREFIX):
+                skip_next_notify = False
+                continue
+            skip_next_notify = False
+            cleaned_lines.append(line)
+
+        block = (
+            f"{_AGENT_TRACE_NOTIFY_MARKER}\n"
+            f"notify = [\"bash\", \"-lc\", {_quote_toml(_NOTIFY_SHELL)}, \"--\"]\n"
+        )
+        if cleaned_lines and cleaned_lines[-1].strip():
+            cleaned_lines.append("")
+        cleaned_lines.append(block.rstrip())
+        CODEX_CONFIG_FILE.write_text("\n".join(cleaned_lines) + "\n")
+        return True
+
+    def remove(self) -> bool:
+        if not CODEX_CONFIG_FILE.is_file():
+            return False
+        try:
+            text = CODEX_CONFIG_FILE.read_text()
+        except OSError:
+            return False
+        if _AGENT_TRACE_NOTIFY_MARKER not in text:
+            return False
+        new_lines: list[str] = []
+        skip_next_notify = False
+        removed = False
+        for line in text.splitlines():
+            if line.strip() == _AGENT_TRACE_NOTIFY_MARKER:
+                skip_next_notify = True
+                removed = True
+                continue
+            if skip_next_notify and line.lstrip().startswith(_NOTIFY_ARRAY_PREFIX):
+                skip_next_notify = False
+                continue
+            skip_next_notify = False
+            new_lines.append(line)
+        if removed:
+            CODEX_CONFIG_FILE.write_text(("\n".join(new_lines).rstrip() + "\n") if new_lines else "")
+        return removed
+
+    def is_installed(self, *, global_only: bool = True) -> bool:
+        try:
+            raw = CODEX_CONFIG_FILE.read_text()
+        except (OSError, FileNotFoundError):
+            return False
+        return _AGENT_TRACE_NOTIFY_MARKER in raw and AGENT_TRACE_CMD in raw
+
+
+def _quote_toml(value: str) -> str:
+    """Quote a string for inclusion in a TOML array element."""
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'

agent_trace/hooks/cursor.py

@@ -0,0 +1,278 @@
+"""
+Cursor adapter — hooks injection, event translators, summary lifecycle.
+
+Everything Cursor-specific lives here:
+  - hook config writer / remover
+  - hook events Cursor emits (``afterFileEdit`` etc.) and their translators
+  - env vars Cursor sets (``CURSOR_TRANSCRIPT_PATH``, ``CURSOR_PROJECT_DIR``)
+  - which events trigger the summary command (``afterAgentResponse``,
+    ``sessionEnd``)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from .base import AGENT_TRACE_CMD, CodingAgentAdapter
+
+
+CURSOR_HOOKS_FILE = ".cursor/hooks.json"
+CURSOR_GLOBAL_HOOKS_FILE = Path.home() / ".cursor" / "hooks.json"
+
+
+# Hook events Cursor emits that we listen to (used by the inject step).
+_CURSOR_HOOK_EVENTS = (
+    "sessionStart",
+    "sessionEnd",
+    "afterFileEdit",
+    "afterTabFileEdit",
+    "afterShellExecution",
+    "afterAgentResponse",
+)
+
+
+# ---------------------------------------------------------------------
+# Event translators (hook payload → trace record)
+# ---------------------------------------------------------------------
+
+def _afterFileEdit(d):
+    from ..record import (
+        _get_next_sequence,
+        _try_read_file,
+        transcript_path_from_hook,
+    )
+    from ..trace import (
+        compute_range_positions,
+        create_trace,
+        resolve_file_project,
+    )
+
+    edits = d.get("edits", [])
+    fp = d.get("file_path", "")
+    fc = _try_read_file(fp) if fp else None
+    session_id = d.get("conversation_id") or ""
+    res = resolve_file_project(fp)
+    seq = _get_next_sequence(session_id, res.repo_root if res else None) if session_id else None
+    return create_trace(
+        "ai", fp,
+        model=d.get("model"),
+        range_positions=compute_range_positions(edits, fc),
+        range_contents=[e["new_string"] for e in edits if e.get("new_string")],
+        transcript=transcript_path_from_hook(d),
+        metadata={"conversation_id": d.get("conversation_id"), "generation_id": d.get("generation_id")},
+        edit_sequence=seq,
+        resolution=res,
+    ), "afterFileEdit"
+
+
+def _afterTabFileEdit(d):
+    from ..record import _get_next_sequence
+    from ..trace import (
+        compute_range_positions,
+        create_trace,
+        resolve_file_project,
+    )
+
+    edits = d.get("edits", [])
+    fp = d.get("file_path", "")
+    session_id = d.get("conversation_id") or ""
+    res = resolve_file_project(fp)
+    seq = _get_next_sequence(session_id, res.repo_root if res else None) if session_id else None
+    return create_trace(
+        "ai", fp,
+        model=d.get("model"),
+        range_positions=compute_range_positions(edits),
+        range_contents=[e["new_string"] for e in edits if e.get("new_string")],
+        metadata={"conversation_id": d.get("conversation_id"), "generation_id": d.get("generation_id")},
+        edit_sequence=seq,
+        resolution=res,
+    ), "afterTabFileEdit"
+
+
+def _afterShellExecution(d):
+    from ..record import project_dir_from_hook, transcript_path_from_hook
+    from ..trace import create_trace, resolve_file_project
+
+    anchor = project_dir_from_hook(d)
+    res = resolve_file_project(".shell-history", anchor_path=anchor)
+    return create_trace(
+        "ai", ".shell-history",
+        model=d.get("model"),
+        transcript=transcript_path_from_hook(d),
+        metadata={
+            "conversation_id": d.get("conversation_id"),
+            "generation_id": d.get("generation_id"),
+            "command": d.get("command"),
+            "duration_ms": d.get("duration"),
+        },
+        anchor_path=anchor,
+        resolution=res,
+    ), "afterShellExecution"
+
+
+def _sessionStart(d):
+    from ..record import project_dir_from_hook
+    from ..trace import create_trace, resolve_file_project
+
+    anchor = project_dir_from_hook(d)
+    res = resolve_file_project(".sessions", anchor_path=anchor)
+    return create_trace(
+        "ai", ".sessions",
+        model=d.get("model"),
+        metadata={
+            "event": "session_start",
+            "session_id": d.get("session_id"),
+            "conversation_id": d.get("conversation_id"),
+            "is_background_agent": d.get("is_background_agent"),
+            "composer_mode": d.get("composer_mode"),
+        },
+        anchor_path=anchor,
+        resolution=res,
+    ), "sessionStart"
+
+
+def _sessionEnd(d):
+    from ..record import project_dir_from_hook, transcript_path_from_hook
+    from ..trace import create_trace, resolve_file_project
+
+    anchor = project_dir_from_hook(d)
+    res = resolve_file_project(".sessions", anchor_path=anchor)
+    return create_trace(
+        "ai", ".sessions",
+        model=d.get("model"),
+        transcript=transcript_path_from_hook(d),
+        metadata={
+            "event": "session_end",
+            "session_id": d.get("session_id"),
+            "conversation_id": d.get("conversation_id"),
+            "reason": d.get("reason"),
+            "duration_ms": d.get("duration_ms"),
+        },
+        anchor_path=anchor,
+        resolution=res,
+    ), "sessionEnd"
+
+
+# ---------------------------------------------------------------------
+# Adapter
+# ---------------------------------------------------------------------
+
+class CursorAdapter(CodingAgentAdapter):
+    name = "cursor"
+    display_name = "Cursor"
+    rules_dir = ".cursor/rules"
+    rule_extension = ".mdc"
+
+    EVENTS = {
+        "afterFileEdit": _afterFileEdit,
+        "afterTabFileEdit": _afterTabFileEdit,
+        "afterShellExecution": _afterShellExecution,
+        "sessionStart": _sessionStart,
+        "sessionEnd": _sessionEnd,
+    }
+
+    # ``afterAgentResponse`` is "agent finished a turn" in Cursor; no
+    # trace record, but it should fire the summary command.
+    summary_only_events = ("afterAgentResponse",)
+    # ``sessionEnd`` *both* ends the session (-> summary) and gets
+    # routed to the trace handler so we record a session-end trace.
+    summary_then_trace_events = ("sessionEnd",)
+
+    transcript_env_vars = ("CURSOR_TRANSCRIPT_PATH",)
+    project_dir_env_vars = ("CURSOR_PROJECT_DIR",)
+
+    def global_config_path(self) -> Path:
+        return CURSOR_GLOBAL_HOOKS_FILE
+
+    def project_config_paths(self) -> tuple[str, ...]:
+        return (CURSOR_HOOKS_FILE,)
+
+    def detect_tool_info(self) -> dict | None:
+        ver = os.environ.get("CURSOR_VERSION")
+        if ver:
+            return {"name": "cursor", "version": ver}
+        return None
+
+    def inject(
+        self,
+        record_invocation: str,
+        project_dir: str | None = None,
+        *,
+        global_install: bool = False,
+    ) -> bool:
+        if global_install:
+            hooks_path = CURSOR_GLOBAL_HOOKS_FILE
+        else:
+            if project_dir is None:
+                project_dir = os.getcwd()
+            hooks_path = Path(project_dir) / CURSOR_HOOKS_FILE
+
+        hooks_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if hooks_path.exists():
+            try:
+                config = json.loads(hooks_path.read_text())
+            except (json.JSONDecodeError, OSError):
+                config = {}
+        else:
+            config = {}
+
+        config.setdefault("version", 1)
+        config.setdefault("hooks", {})
+
+        for event in _CURSOR_HOOK_EVENTS:
+            existing = config["hooks"].get(event, [])
+            already = any(
+                record_invocation in (h.get("command", "") if isinstance(h, dict) else "")
+                for h in existing
+            )
+            if not already:
+                existing.append({"command": record_invocation})
+                config["hooks"][event] = existing
+
+        hooks_path.write_text(json.dumps(config, indent=2) + "\n")
+        return True
+
+    def remove(self) -> bool:
+        return _remove_agent_trace_from_cursor(CURSOR_GLOBAL_HOOKS_FILE)
+
+    def is_installed(self, *, global_only: bool = True) -> bool:
+        try:
+            raw = CURSOR_GLOBAL_HOOKS_FILE.read_text()
+        except (OSError, FileNotFoundError):
+            return False
+        return AGENT_TRACE_CMD in raw
+
+
+def _remove_agent_trace_from_cursor(hooks_path: Path) -> bool:
+    if not hooks_path.is_file():
+        return False
+    try:
+        config = json.loads(hooks_path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return False
+
+    hooks = config.get("hooks")
+    if not isinstance(hooks, dict):
+        return False
+
+    changed = False
+    for event, entries in list(hooks.items()):
+        if not isinstance(entries, list):
+            continue
+        filtered = [
+            h for h in entries
+            if not (isinstance(h, dict) and AGENT_TRACE_CMD in h.get("command", ""))
+        ]
+        if len(filtered) != len(entries):
+            changed = True
+            if filtered:
+                hooks[event] = filtered
+            else:
+                del hooks[event]
+
+    if changed:
+        hooks_path.write_text(json.dumps(config, indent=2) + "\n")
+    return changed

agent_trace/hooks/git.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import os
+import stat
+import subprocess
+from pathlib import Path
+
+GIT_NOTES_REFSPEC = "+refs/notes/agent-trace:refs/notes/agent-trace"
+
+AGENT_TRACE_COMMIT_LINK_CMD = "agent-trace commit-link"
+
+GIT_HOOK_MARKER = AGENT_TRACE_COMMIT_LINK_CMD
+GIT_HOOK_SCRIPT = """\
+# agent-trace: link commit to AI traces
+agent-trace commit-link 2>/dev/null || true
+"""
+
+GIT_POST_REWRITE_MARKER = "agent-trace rewrite-ledger"
+GIT_POST_REWRITE_SCRIPT = """\
+# agent-trace: remap ledgers after rebase/amend
+agent-trace rewrite-ledger 2>/dev/null || true
+"""
+
+
+def configure_git_hooks(project_dir: str | None = None) -> bool:
+    if project_dir is None:
+        project_dir = os.getcwd()
+
+    git_dir = Path(project_dir) / ".git"
+    if not git_dir.is_dir():
+        return False
+
+    hooks_dir = git_dir / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    hook_path = hooks_dir / "post-commit"
+
+    if hook_path.exists():
+        try:
+            content = hook_path.read_text()
+        except OSError:
+            return False
+
+        if GIT_HOOK_MARKER in content:
+            return True
+
+        if not content.endswith("\n"):
+            content += "\n"
+        content += "\n" + GIT_HOOK_SCRIPT
+        hook_path.write_text(content)
+    else:
+        hook_path.write_text("#!/bin/sh\n" + GIT_HOOK_SCRIPT)
+
+    current = hook_path.stat().st_mode
+    hook_path.chmod(current | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    configure_git_post_rewrite_hook(project_dir)
+    return True
+
+
+def configure_git_post_rewrite_hook(project_dir: str | None = None) -> bool:
+    if project_dir is None:
+        project_dir = os.getcwd()
+
+    git_dir = Path(project_dir) / ".git"
+    if not git_dir.is_dir():
+        return False
+
+    hooks_dir = git_dir / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    hook_path = hooks_dir / "post-rewrite"
+
+    if hook_path.exists():
+        try:
+            content = hook_path.read_text()
+        except OSError:
+            return False
+
+        if GIT_POST_REWRITE_MARKER in content:
+            return True
+
+        if not content.endswith("\n"):
+            content += "\n"
+        content += "\n" + GIT_POST_REWRITE_SCRIPT
+        hook_path.write_text(content)
+    else:
+        hook_path.write_text("#!/bin/sh\n" + GIT_POST_REWRITE_SCRIPT)
+
+    current = hook_path.stat().st_mode
+    hook_path.chmod(current | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return True
+
+
+def configure_git_notes_refspecs(project_dir: str | None = None, remote_name: str = "origin") -> bool:
+    if project_dir is None:
+        project_dir = os.getcwd()
+
+    git_dir = Path(project_dir) / ".git"
+    if not git_dir.is_dir():
+        return False
+
+    try:
+        r = subprocess.run(
+            ["git", "-C", project_dir, "remote", "get-url", remote_name],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if r.returncode != 0:
+            return False
+    except Exception:
+        return False
+
+    for key in ("fetch", "push"):
+        try:
+            cur = subprocess.run(
+                ["git", "-C", project_dir, "config", "--get-all", f"remote.{remote_name}.{key}"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            existing = cur.stdout if cur.returncode == 0 else ""
+        except Exception:
+            existing = ""
+        if "refs/notes/agent-trace" in existing:
+            continue
+        try:
+            subprocess.run(
+                [
+                    "git",
+                    "-C",
+                    project_dir,
+                    "config",
+                    "--add",
+                    f"remote.{remote_name}.{key}",
+                    GIT_NOTES_REFSPEC,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=10,
+                check=False,
+            )
+        except Exception:
+            return False
+    return True