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

agent_trace/schemas/trace-record.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ujjalsharma100/agent-trace-cli/main/schemas/trace-record.schema.json",
+  "title": "TraceRecord",
+  "description": "One line in traces.jsonl. Schema 2.0: per-line full SHA-256 hashes give cryptographic uniqueness for deterministic attribution.",
+  "type": "object",
+  "required": ["version", "id", "timestamp", "tool", "files"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string",
+      "enum": ["2.0"]
+    },
+    "id": { "type": "string", "minLength": 1 },
+    "timestamp": { "type": "string", "description": "ISO-8601 timestamp" },
+    "tool": { "$ref": "#/$defs/tool" },
+    "files": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/fileEntry" }
+    },
+    "vcs": { "$ref": "#/$defs/vcs" },
+    "metadata": { "$ref": "#/$defs/metadata" }
+  },
+  "$defs": {
+    "tool": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string" },
+        "version": { "type": "string" }
+      }
+    },
+    "vcs": {
+      "type": "object",
+      "required": ["type", "revision"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "const": "git" },
+        "revision": { "type": "string", "minLength": 1 }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "edit_sequence": { "type": "integer" },
+        "session_id": { "type": "string" },
+        "tool_name": { "type": "string" },
+        "tool_use_id": { "type": "string" },
+        "is_creation": { "type": "boolean" }
+      }
+    },
+    "lineHash": {
+      "type": "object",
+      "required": ["line_offset", "hash"],
+      "additionalProperties": false,
+      "properties": {
+        "line_offset": { "type": "integer", "minimum": 0 },
+        "hash": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        }
+      }
+    },
+    "range": {
+      "type": "object",
+      "required": ["start_line", "end_line"],
+      "additionalProperties": false,
+      "properties": {
+        "start_line": { "type": "integer", "minimum": 1 },
+        "end_line": { "type": "integer", "minimum": 1 },
+        "content_hash": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "line_hashes": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/lineHash" }
+        }
+      }
+    },
+    "contributor": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string" },
+        "model_id": { "type": "string" }
+      }
+    },
+    "conversation": {
+      "type": "object",
+      "required": ["contributor", "ranges"],
+      "additionalProperties": false,
+      "properties": {
+        "contributor": { "$ref": "#/$defs/contributor" },
+        "ranges": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/range" }
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Opaque conversation identifier (sha256 over the original local transcript URL). Stable per-(machine, session); referenced everywhere transcripts are addressed."
+        },
+        "content_sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "SHA-256 of the transcript bytes at the moment this trace was recorded. Resolves to a blob in the per-project content-addressed cache."
+        }
+      }
+    },
+    "fileEntry": {
+      "type": "object",
+      "required": ["path", "conversations"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "conversations": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/conversation" }
+        }
+      }
+    }
+  }
+}

agent_trace/session.py

@@ -0,0 +1,136 @@
+"""
+Per-session manifest (~/.agent-trace/sessions/<session_id>.json) — project
+touch counts for cross-repo sessions (Phase 1b).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import time
+from typing import Any
+
+from .storage import get_sessions_dir
+
+
+def _sessions_dir():
+    return get_sessions_dir()
+
+
+class _SessionLock:
+    def __init__(self, session_id: str) -> None:
+        self.session_id = session_id
+        self._fp: Any = None
+
+    def __enter__(self) -> None:
+        _sessions_dir().mkdir(parents=True, exist_ok=True)
+        path = _sessions_dir() / f".{self.session_id}.lock"
+        self._fp = open(path, "a+")
+        if sys.platform != "win32":
+            import fcntl
+
+            fcntl.flock(self._fp.fileno(), fcntl.LOCK_EX)
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        if self._fp:
+            if sys.platform != "win32":
+                import fcntl
+
+                fcntl.flock(self._fp.fileno(), fcntl.LOCK_UN)
+            self._fp.close()
+            self._fp = None
+
+
+def _atomic_write(path: os.PathLike[str], text: str) -> None:
+    p = os.fspath(path)
+    d = os.path.dirname(p)
+    os.makedirs(d, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=".sess.", dir=d, text=True)
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(text)
+        os.replace(tmp, p)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def primary_project_id_for_session(session_id: str) -> str | None:
+    """Project id that received the most trace touches this session (nested-repo safe).
+
+    Used so summary hooks attribute to the same project as file-based traces when
+    the IDE workspace cwd is a parent folder but edits targeted an inner git repo.
+    """
+    if not session_id:
+        return None
+    path = _sessions_dir() / f"{session_id}.json"
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+    counts = data.get("edit_counts") if isinstance(data.get("edit_counts"), dict) else {}
+    if counts:
+        best: str | None = None
+        best_n = -1
+        for pid, n in counts.items():
+            if not isinstance(pid, str) or not pid:
+                continue
+            try:
+                v = int(n)
+            except (TypeError, ValueError):
+                continue
+            if v > best_n:
+                best_n = v
+                best = pid
+        if best is not None:
+            return best
+    projects = data.get("projects") if isinstance(data.get("projects"), list) else []
+    if len(projects) == 1 and isinstance(projects[0], str) and projects[0]:
+        return projects[0]
+    return None
+
+
+def touch_session_project(
+    session_id: str,
+    project_id: str,
+    *,
+    tool_name: str | None = None,
+    transcript_path: str | None = None,
+) -> None:
+    """Record that this session touched a project; bump edit counter."""
+    if not session_id or not project_id:
+        return
+    path = _sessions_dir() / f"{session_id}.json"
+    now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    with _SessionLock(session_id):
+        data: dict[str, Any]
+        if path.is_file():
+            try:
+                data = json.loads(path.read_text())
+            except (json.JSONDecodeError, OSError):
+                data = {}
+        else:
+            data = {}
+        data.setdefault("session_id", session_id)
+        data.setdefault("started_at", now)
+        data["ended_at"] = None
+        if tool_name:
+            data.setdefault("tool", {})["name"] = tool_name
+        if transcript_path:
+            data["transcript_path"] = transcript_path
+        projects: list[str] = list(data.get("projects") or [])
+        if project_id not in projects:
+            projects.append(project_id)
+        data["projects"] = projects
+        counts: dict[str, int] = dict(data.get("edit_counts") or {})
+        counts[project_id] = int(counts.get(project_id, 0)) + 1
+        data["edit_counts"] = counts
+        _atomic_write(path, json.dumps(data, indent=2) + "\n")

agent_trace/storage.py

@@ -0,0 +1,229 @@
+"""
+Central path resolution for agent-trace.
+
+All per-project runtime data lives under ``<AGENT_TRACE_HOME>/projects/<project_id>/``.
+
+``project_id`` is anchored to the repo's ``.git`` directory: a single-line
+``agent-trace-id`` file under ``git rev-parse --git-common-dir``. Worktrees
+of the same repo share the anchor (and therefore the data directory), and a
+rename of the repo on disk preserves the id since the file lives inside
+``.git``. Re-clones legitimately get a fresh id — fresh clones rely on
+``refs/notes/agent-trace`` for attribution, not on local data.
+
+When the anchor doesn't exist yet, we fall back to a path-derived id so
+``status`` / ``blame`` from un-init'd repos still resolve to *something*.
+``init`` and any other ``create=True`` resolution will write the anchor.
+
+``AGENT_TRACE_HOME`` overrides the default ``~/.agent-trace`` (used by tests).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import uuid
+from pathlib import Path
+
+
+def get_agent_trace_home() -> Path:
+    """Root of all global agent-trace state (respects ``AGENT_TRACE_HOME``)."""
+    env = os.environ.get("AGENT_TRACE_HOME")
+    if env:
+        return Path(env).expanduser()
+    return Path.home() / ".agent-trace"
+
+
+def get_global_config_file() -> Path:
+    return get_agent_trace_home() / "config.json"
+
+
+def get_projects_registry_file() -> Path:
+    return get_agent_trace_home() / "projects.json"
+
+
+def get_sessions_dir() -> Path:
+    return get_agent_trace_home() / "sessions"
+
+
+def get_detached_base_dir() -> Path:
+    return get_agent_trace_home() / "detached"
+
+
+def _sanitize_id(project_id: str) -> str:
+    """Defensive sanitization — path-derived ids are already dash-only,
+    but anything unexpected (``:``, ``\\``, residual ``/``) gets flattened."""
+    return project_id.replace(":", "_").replace("/", "-").replace("\\", "-")
+
+
+def path_to_project_id(repo_root: str) -> str:
+    """Derive a project_id from an absolute repo path (fallback only).
+
+    ``/Users/jane/Desktop/foo`` → ``-Users-jane-Desktop-foo`` (Claude-Code convention).
+    Used when no ``.git/agent-trace-id`` anchor exists. Once a project is
+    initialised, the anchor takes over and the path is no longer load-bearing.
+    """
+    canon = os.path.realpath(repo_root)
+    return canon.replace(os.sep, "-")
+
+
+# -------------------------------------------------------------------
+# Anchor (.git/agent-trace-id) — stable, worktree-aware project identity
+# -------------------------------------------------------------------
+
+ANCHOR_FILENAME = "agent-trace-id"
+
+
+def _git_common_dir(repo_dir: str) -> str | None:
+    """Return the shared ``.git`` directory for ``repo_dir``.
+
+    For ordinary repos this is ``<repo>/.git``. For linked worktrees,
+    ``--git-common-dir`` resolves to the main repo's ``.git`` so all
+    worktrees of the same repo share the anchor (and therefore the
+    project_id).
+    """
+    try:
+        r = subprocess.run(
+            ["git", "rev-parse", "--git-common-dir"],
+            cwd=repo_dir, capture_output=True, text=True, timeout=10,
+        )
+        if r.returncode != 0:
+            return None
+        p = r.stdout.strip()
+        if not p:
+            return None
+        if not os.path.isabs(p):
+            p = os.path.join(os.path.realpath(repo_dir), p)
+        return os.path.realpath(p)
+    except Exception:
+        return None
+
+
+def _anchor_path(git_common_dir: str) -> Path:
+    return Path(git_common_dir) / ANCHOR_FILENAME
+
+
+def _read_anchor(git_common_dir: str) -> str | None:
+    p = _anchor_path(git_common_dir)
+    try:
+        if not p.is_file():
+            return None
+        s = p.read_text().strip()
+        return s or None
+    except OSError:
+        return None
+
+
+def _generate_project_id() -> str:
+    """Fresh opaque project_id. ``at-<32 hex>``; safe as a directory name."""
+    return f"at-{uuid.uuid4().hex}"
+
+
+def _write_anchor(git_common_dir: str, project_id: str) -> bool:
+    try:
+        p = _anchor_path(git_common_dir)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(project_id + "\n")
+        return True
+    except OSError:
+        return False
+
+
+def get_project_dir(project_id: str) -> Path:
+    return get_agent_trace_home() / "projects" / _sanitize_id(project_id)
+
+
+def ensure_project_dir(project_id: str) -> Path:
+    d = get_project_dir(project_id)
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+# -------------------------------------------------------------------
+# Per-project file paths
+# -------------------------------------------------------------------
+
+def get_traces_path(project_id: str) -> Path:
+    return get_project_dir(project_id) / "traces.jsonl"
+
+
+def get_ledgers_path(project_id: str) -> Path:
+    return get_project_dir(project_id) / "ledgers.jsonl"
+
+
+def get_commit_links_path(project_id: str) -> Path:
+    return get_project_dir(project_id) / "commit-links.jsonl"
+
+
+def get_session_state_path(project_id: str) -> Path:
+    return get_project_dir(project_id) / "session-state.json"
+
+
+def get_session_summaries_path(project_id: str) -> Path:
+    """Append-only JSONL of per-session LLM summaries."""
+    return get_project_dir(project_id) / "session-summaries.jsonl"
+
+
+def get_project_config_path(project_id: str) -> Path:
+    return get_project_dir(project_id) / "project-config.json"
+
+
+def get_attribution_state_path(project_id: str) -> Path:
+    """Per-project attribution-window cursor (last commit timestamp seen)."""
+    return get_project_dir(project_id) / "attribution-state.json"
+
+
+# -------------------------------------------------------------------
+# Repo-dir → project_id resolution
+# -------------------------------------------------------------------
+
+def resolve_project_id(
+    repo_dir: str | os.PathLike[str] | None,
+    *,
+    create: bool = False,
+) -> str | None:
+    """Resolve a stable ``project_id`` for a repo directory.
+
+    Resolution order:
+      1. ``.git/agent-trace-id`` anchor (shared across worktrees of the
+         same repo). Survives ``mv`` of the repo on disk.
+      2. With ``create=True`` and no anchor present: generate a fresh
+         opaque id (``at-<32 hex>``) and write the anchor.
+      3. Path-derived fallback (``/Users/x/foo`` → ``-Users-x-foo``) for
+         un-init'd repos and non-git directories.
+
+    When ``create`` is True the registry also gets a metadata entry.
+    """
+    if repo_dir is None:
+        return None
+
+    from .trace import git_repo_root_for_path
+
+    root = git_repo_root_for_path(str(repo_dir))
+
+    if root:
+        # Inside a git repo — try the anchor.
+        common = _git_common_dir(root) or os.path.join(root, ".git")
+        pid = _read_anchor(common)
+        if pid is None and create:
+            pid = _generate_project_id()
+            _write_anchor(common, pid)
+        if pid is None:
+            # Un-init'd repo: behave like the legacy path-derived form so
+            # status/blame from a fresh checkout still resolves.
+            pid = path_to_project_id(root)
+
+        if create:
+            from .registry import register_project_metadata
+
+            register_project_metadata(root, pid)
+        return pid
+
+    # Not inside a git repo at all — keep the path-derived id (used by
+    # detached-edit handling and tests for non-repo paths).
+    real = os.path.realpath(str(repo_dir))
+    pid = path_to_project_id(real)
+    if create:
+        from .registry import register_project_metadata
+
+        register_project_metadata(real, pid)
+    return pid