session-trail 0.2.0__py3-none-any.whl

agent_trail/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

agent_trail/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

agent_trail/adapters/__init__.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+from .base import BaseAdapter
+from .claude_code import ClaudeCodeAdapter
+from .codebuddy import CodeBuddyAdapter
+from .codex import CodexAdapter
+from .deepseek_harness import DeepSeekHarnessAdapter
+from .kimi_code import KimiCodeAdapter
+from .minimax_code import MiniMaxCodeAdapter
+from .opencode import OpenCodeAdapter
+from .pi import PiAdapter
+from .zcode import ZCodeAdapter
+
+
+def default_adapters(home: Path) -> list[BaseAdapter]:
+    return [
+        KimiCodeAdapter(home),
+        CodeBuddyAdapter(home),
+        PiAdapter(home),
+        DeepSeekHarnessAdapter(home),
+        MiniMaxCodeAdapter(home),
+        ZCodeAdapter(home),
+        OpenCodeAdapter(home),
+        CodexAdapter(home),
+        ClaudeCodeAdapter(home),
+    ]

agent_trail/adapters/base.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from pathlib import Path
+
+from ..models import ActivitySession, AdapterStatus, ResumePlan, ScanResult
+
+
+class BaseAdapter(ABC):
+    source: str
+    adapter_version: int = 1
+
+    def __init__(self, home: Path) -> None:
+        self.home = home
+        self._status = AdapterStatus(source=self.source, kind="unavailable")
+
+    @abstractmethod
+    def discover(self) -> AdapterStatus:
+        raise NotImplementedError
+
+    def status(self) -> AdapterStatus:
+        return self._status
+
+    def watch_roots(self) -> list[tuple[Path, bool]]:
+        """Directories to watch for change notifications as (path, recursive).
+
+        Defaults to no watching; adapters that read files should return the
+        directories that contain their sources so misses degrade to polling.
+        """
+        return []
+
+    @abstractmethod
+    def scan(self, previous_fingerprint: str | None, now: datetime) -> ScanResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def resume_plan(self, session: ActivitySession) -> ResumePlan:
+        raise NotImplementedError

agent_trail/adapters/claude_code.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from ..models import ActivitySession, AdapterStatus, ResumePlan, ScanResult
+from .base import BaseAdapter
+from .jsonl_utils import fingerprint_paths
+
+
+class ClaudeCodeAdapter(BaseAdapter):
+    source = "claude-code"
+    adapter_version = 1
+
+    @property
+    def root(self) -> Path:
+        return self.home / ".claude" / "projects"
+
+    def discover(self) -> AdapterStatus:
+        if not self.root.is_dir():
+            return AdapterStatus(source=self.source, kind="unavailable")
+        return AdapterStatus(
+            source=self.source,
+            kind="experimental",
+            message="session metadata format has not been verified",
+        )
+
+    def scan(self, previous_fingerprint: str | None, now: datetime) -> ScanResult:
+        discovery = self.discover()
+        if discovery.kind == "unavailable":
+            return ScanResult(discovery, None, [], True)
+        fingerprint = fingerprint_paths([], self.adapter_version)
+        return ScanResult(discovery, fingerprint, [], fingerprint != previous_fingerprint)
+
+    def resume_plan(self, session: ActivitySession) -> ResumePlan:
+        return ResumePlan(
+            kind="none",
+            workdir=session.workdir,
+            reason="Claude Code resume has not been verified",
+        )

agent_trail/adapters/codebuddy.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from ..models import ActivitySession, AdapterStatus, ResumePlan, ScanResult
+from .base import BaseAdapter
+from .jsonl_utils import fingerprint_paths, read_jsonl_metadata, to_utc_iso
+
+
+class CodeBuddyAdapter(BaseAdapter):
+    source = "codebuddy"
+    adapter_version = 1
+
+    @property
+    def projects_path(self) -> Path:
+        return self.home / ".codebuddy" / "projects"
+
+    def watch_roots(self) -> list[tuple[Path, bool]]:
+        return [(self.projects_path, True)]
+
+    def discover(self) -> AdapterStatus:
+        return AdapterStatus(
+            source=self.source,
+            kind="ok" if self.projects_path.is_dir() else "unavailable",
+        )
+
+    def scan(self, previous_fingerprint: str | None, now: datetime) -> ScanResult:
+        discovery = self.discover()
+        if discovery.kind == "unavailable":
+            return ScanResult(discovery, None, [], True)
+        paths = list(self.projects_path.glob("**/*.jsonl"))
+        fingerprint = fingerprint_paths(paths, self.adapter_version)
+        if fingerprint == previous_fingerprint:
+            return ScanResult(
+                AdapterStatus(source=self.source, kind="ok", record_count=len(paths)),
+                fingerprint,
+                [],
+                False,
+            )
+        sessions: list[ActivitySession] = []
+        error_count = 0
+        for path in paths:
+            result = read_jsonl_metadata(path, {"sessionId", "cwd", "timestamp"})
+            error_count += result.error_count
+            records = [item for item in result.records if item.get("timestamp") is not None]
+            if not records:
+                error_count += 1
+                continue
+            workdir = next((str(item["cwd"]) for item in reversed(result.records) if item.get("cwd")), "")
+            if not workdir:
+                error_count += 1
+                continue
+            session_id = str(records[0].get("sessionId") or path.stem)
+            timestamps = [float(item["timestamp"]) for item in records]
+            sessions.append(
+                ActivitySession(
+                    source=self.source,
+                    session_id=session_id,
+                    workdir=workdir,
+                    title=None,
+                    title_source="fallback",
+                    created_at=to_utc_iso(min(timestamps)),
+                    updated_at=to_utc_iso(max(timestamps)),
+                    source_locator=str(path),
+                    resume_kind="cli",
+                    resume_ref=session_id,
+                    adapter_version=self.adapter_version,
+                    source_fingerprint=fingerprint,
+                    last_scanned_at=now.isoformat(),
+                )
+            )
+        return ScanResult(
+            AdapterStatus(
+                source=self.source,
+                kind="ok",
+                record_count=len(sessions),
+                error_count=error_count,
+            ),
+            fingerprint,
+            sessions,
+            True,
+        )
+
+    def resume_plan(self, session: ActivitySession) -> ResumePlan:
+        if session.source_missing or session.resume_kind != "cli" or not session.resume_ref:
+            return ResumePlan(kind="none", workdir=session.workdir, reason="source unavailable")
+        return ResumePlan(
+            kind="cli",
+            executable="codebuddy",
+            args=("--resume", session.resume_ref),
+            workdir=session.workdir,
+        )

agent_trail/adapters/codex.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from contextlib import closing
+from datetime import datetime
+from pathlib import Path
+
+from ..models import ActivitySession, AdapterStatus, ResumePlan, ScanResult
+from .base import BaseAdapter
+from .jsonl_utils import fingerprint_paths, to_utc_iso
+from .sqlite_utils import connect_readonly
+
+
+class CodexAdapter(BaseAdapter):
+    source = "codex"
+    adapter_version = 1
+
+    @property
+    def root(self) -> Path:
+        return self.home / ".codex"
+
+    @property
+    def database_path(self) -> Path:
+        return self.root / "state_5.sqlite"
+
+    @property
+    def sessions_path(self) -> Path:
+        return self.root / "sessions"
+
+    def watch_roots(self) -> list[tuple[Path, bool]]:
+        return [(self.database_path.parent, False), (self.sessions_path, True)]
+
+    def discover(self) -> AdapterStatus:
+        available = self.database_path.is_file() or self.sessions_path.is_dir()
+        return AdapterStatus(source=self.source, kind="ok" if available else "unavailable")
+
+    def scan(self, previous_fingerprint: str | None, now: datetime) -> ScanResult:
+        discovery = self.discover()
+        if discovery.kind == "unavailable":
+            return ScanResult(discovery, None, [], True)
+        rollout_paths = list(self.sessions_path.glob("**/*.jsonl")) if self.sessions_path.is_dir() else []
+        database_paths = [self.database_path, Path(f"{self.database_path}-wal")]
+        fingerprint = fingerprint_paths(
+            [path for path in database_paths if path.is_file()] + rollout_paths,
+            self.adapter_version,
+        )
+        if fingerprint == previous_fingerprint:
+            return ScanResult(
+                AdapterStatus(source=self.source, kind="ok"), fingerprint, [], False
+            )
+        database_records = {}
+        if self.database_path.is_file():
+            try:
+                with closing(connect_readonly(self.database_path)) as connection:
+                    rows = connection.execute(
+                        "SELECT id, title, cwd, created_at, updated_at, rollout_path, archived "
+                        "FROM threads"
+                    ).fetchall()
+                for row in rows:
+                    database_records[str(row[0])] = row[1:]
+            except sqlite3.Error as error:
+                return ScanResult(self._error_status(error), None, [], True)
+        sessions: list[ActivitySession] = []
+        error_count = 0
+        for session_id, row in database_records.items():
+            try:
+                title, workdir, created, updated, rollout_path, archived = row
+                if not workdir:
+                    error_count += 1
+                    continue
+                sessions.append(
+                    ActivitySession(
+                        source=self.source,
+                        session_id=session_id,
+                        workdir=str(workdir),
+                        title=str(title) if title else None,
+                        title_source="native" if title else "fallback",
+                        created_at=to_utc_iso(created),
+                        updated_at=to_utc_iso(updated),
+                        source_locator=str(rollout_path),
+                        resume_kind="none",
+                        resume_ref=None,
+                        archived=bool(archived),
+                        adapter_version=self.adapter_version,
+                        source_fingerprint=fingerprint,
+                        last_scanned_at=now.isoformat(),
+                    )
+                )
+            except (TypeError, ValueError, OverflowError, OSError):
+                error_count += 1
+        for path in rollout_paths:
+            try:
+                metadata = self._rollout_metadata(path)
+                if metadata is None:
+                    error_count += 1
+                    continue
+                session_id = str(metadata.get("id") or "")
+                if not session_id or session_id in database_records or not metadata.get("cwd"):
+                    continue
+                created = metadata.get("timestamp")
+                sessions.append(
+                    ActivitySession(
+                        source=self.source,
+                        session_id=session_id,
+                        workdir=str(metadata["cwd"]),
+                        title=None,
+                        title_source="fallback",
+                        created_at=to_utc_iso(created) if created is not None else None,
+                        updated_at=to_utc_iso(path.stat().st_mtime),
+                        source_locator=str(path),
+                        resume_kind="none",
+                        resume_ref=None,
+                        adapter_version=self.adapter_version,
+                        source_fingerprint=fingerprint,
+                        last_scanned_at=now.isoformat(),
+                    )
+                )
+            except (OSError, UnicodeError, json.JSONDecodeError, TypeError, ValueError, OverflowError):
+                error_count += 1
+        return ScanResult(
+            AdapterStatus(
+                source=self.source,
+                kind="ok",
+                record_count=len(sessions),
+                error_count=error_count,
+            ),
+            fingerprint,
+            sessions,
+            True,
+        )
+
+    @staticmethod
+    def _rollout_metadata(path: Path) -> dict | None:
+        with path.open(encoding="utf-8") as handle:
+            for line in handle:
+                if not line.strip():
+                    continue
+                value = json.loads(line)
+                if not isinstance(value, dict) or value.get("type") != "session_meta":
+                    continue
+                payload = value.get("payload")
+                if not isinstance(payload, dict):
+                    return None
+                return {
+                    key: payload[key] for key in ("id", "timestamp", "cwd") if key in payload
+                }
+        return None
+
+    def _error_status(self, error: sqlite3.Error) -> AdapterStatus:
+        temporary = isinstance(error, sqlite3.OperationalError) and any(
+            word in str(error).lower() for word in ("locked", "busy")
+        )
+        return AdapterStatus(
+            source=self.source,
+            kind="error" if temporary else "incompatible",
+            message="database temporarily unavailable" if temporary else "database schema incompatible",
+        )
+
+    def resume_plan(self, session: ActivitySession) -> ResumePlan:
+        return ResumePlan(
+            kind="none",
+            workdir=session.workdir,
+            reason="Codex requires an unverified directory-trust decision",
+        )

agent_trail/adapters/deepseek_harness.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from ..models import ActivitySession, AdapterStatus, ResumePlan, ScanResult
+from .base import BaseAdapter
+from .jsonl_utils import fingerprint_paths, to_utc_iso
+
+
+class DeepSeekHarnessAdapter(BaseAdapter):
+    source = "deepseek-harness"
+    adapter_version = 1
+
+    @property
+    def index_path(self) -> Path:
+        return self.home / ".dsh-tui" / "session-index.json"
+
+    @property
+    def database_path(self) -> Path:
+        return self.home / ".dsh-tui" / "sessions.sqlite"
+
+    @property
+    def cache_path(self) -> Path:
+        return self.home / ".dsh" / "storages" / "session_projcache" / "sessions"
+
+    def watch_roots(self) -> list[tuple[Path, bool]]:
+        return [(self.index_path.parent, False), (self.cache_path, False)]
+
+    def discover(self) -> AdapterStatus:
+        available = (
+            self.index_path.is_file()
+            or self.database_path.is_file()
+            or self.cache_path.is_dir()
+        )
+        return AdapterStatus(source=self.source, kind="ok" if available else "unavailable")
+
+    def scan(self, previous_fingerprint: str | None, now: datetime) -> ScanResult:
+        discovery = self.discover()
+        if discovery.kind == "unavailable":
+            return ScanResult(discovery, None, [], True)
+        cache_paths = list(self.cache_path.glob("*.json")) if self.cache_path.is_dir() else []
+        paths = [
+            path
+            for path in (self.index_path, self.database_path)
+            if path.is_file()
+        ]
+        fingerprint = fingerprint_paths([*paths, *cache_paths], self.adapter_version)
+        if fingerprint == previous_fingerprint:
+            return ScanResult(
+                AdapterStatus(source=self.source, kind="ok", record_count=len(cache_paths)),
+                fingerprint,
+                [],
+                False,
+            )
+        indexed: dict[str, dict[str, Any]] = {}
+        error_count = 0
+        try:
+            raw_index = json.loads(self.index_path.read_text(encoding="utf-8"))
+            raw_entries = raw_index.get("entries", {})
+            entries = (
+                list(raw_entries.items())
+                if isinstance(raw_entries, dict)
+                else [(str(item.get("id") or item.get("sessionId") or ""), item) for item in raw_entries]
+            )
+            for session_id, entry in entries:
+                if not session_id or not isinstance(entry, dict):
+                    error_count += 1
+                    continue
+                derived = entry.get("derived", {})
+                if not isinstance(derived, dict):
+                    error_count += 1
+                    continue
+                indexed[str(session_id)] = {
+                    "title": derived.get("title"),
+                    "identity": derived.get("identity"),
+                }
+        except FileNotFoundError:
+            pass
+        except (OSError, UnicodeError, json.JSONDecodeError, TypeError, AttributeError):
+            error_count += 1
+        database_records: dict[str, dict[str, Any]] = {}
+        if self.database_path.is_file():
+            try:
+                connection = sqlite3.connect(
+                    f"{self.database_path.as_uri()}?mode=ro", uri=True
+                )
+                try:
+                    rows = connection.execute("SELECT id, created_at, cwd FROM sessions")
+                    database_records = {
+                        str(row[0]): {"created_at": row[1], "cwd": row[2]} for row in rows
+                    }
+                finally:
+                    connection.close()
+            except sqlite3.Error:
+                error_count += 1
+        cache_records: dict[str, dict[str, Any]] = {}
+        cache_files: dict[str, Path] = {}
+        for path in cache_paths:
+            try:
+                raw = json.loads(path.read_text(encoding="utf-8"))
+                identity = raw.get("record", {}).get("identity", {})
+                if not isinstance(identity, dict):
+                    error_count += 1
+                    continue
+                cache_id = path.stem
+                normalized_id = cache_id.removeprefix("session-")
+                if normalized_id in indexed or normalized_id in database_records:
+                    cache_id = normalized_id
+                cache_records[cache_id] = {
+                    key: identity[key] for key in ("createdAt", "cwd") if key in identity
+                }
+                cache_files[cache_id] = path
+            except (OSError, UnicodeError, json.JSONDecodeError, TypeError, AttributeError):
+                error_count += 1
+        sessions: list[ActivitySession] = []
+        session_ids = set(indexed) | set(database_records) | set(cache_records)
+        for session_id in sorted(session_ids):
+            index = indexed.get(session_id, {})
+            cache_id = session_id
+            database = database_records.get(session_id, {})
+            cache = cache_records.get(cache_id, {})
+            workdir = database.get("cwd") or cache.get("cwd")
+            if not workdir:
+                error_count += 1
+                continue
+            try:
+                raw_created = database.get("created_at") or cache.get("createdAt")
+                created_at = to_utc_iso(raw_created) if raw_created is not None else None
+                source_path = cache_files.get(cache_id) or self.index_path
+                updated_at = (
+                    to_utc_iso(source_path.stat().st_mtime)
+                    if source_path.is_file()
+                    else created_at
+                )
+                if updated_at is None:
+                    error_count += 1
+                    continue
+                title = index.get("title")
+                sessions.append(
+                    ActivitySession(
+                        source=self.source,
+                        session_id=session_id,
+                        workdir=str(workdir),
+                        title=str(title) if title else None,
+                        title_source="native" if title else "fallback",
+                        created_at=created_at,
+                        updated_at=updated_at,
+                        source_locator=str(source_path),
+                        resume_kind="none",
+                        resume_ref=None,
+                        adapter_version=self.adapter_version,
+                        source_fingerprint=fingerprint,
+                        last_scanned_at=now.isoformat(),
+                    )
+                )
+            except (OSError, TypeError, ValueError, OverflowError):
+                error_count += 1
+        return ScanResult(
+            AdapterStatus(
+                source=self.source,
+                kind="ok",
+                record_count=len(sessions),
+                error_count=error_count,
+            ),
+            fingerprint,
+            sessions,
+            True,
+        )
+
+    def resume_plan(self, session: ActivitySession) -> ResumePlan:
+        return ResumePlan(
+            kind="none",
+            workdir=session.workdir,
+            reason="DeepSeek Harness runtime and plugins are incompatible",
+        )

agent_trail/adapters/jsonl_utils.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class JsonlReadResult:
+    records: list[dict[str, Any]]
+    error_count: int
+
+
+def read_jsonl_metadata(path: Path, allowed_fields: set[str]) -> JsonlReadResult:
+    records: list[dict[str, Any]] = []
+    error_count = 0
+    with path.open(encoding="utf-8") as handle:
+        for line in handle:
+            if not line.strip():
+                continue
+            try:
+                value = json.loads(line)
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                error_count += 1
+                continue
+            if not isinstance(value, dict):
+                error_count += 1
+                continue
+            records.append({key: value[key] for key in allowed_fields if key in value})
+    return JsonlReadResult(records=records, error_count=error_count)
+
+
+def to_utc_iso(value: Any) -> str:
+    if isinstance(value, str):
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        return parsed.astimezone(timezone.utc).isoformat()
+    numeric = float(value)
+    if abs(numeric) >= 100_000_000_000:
+        numeric /= 1000
+    return datetime.fromtimestamp(numeric, timezone.utc).isoformat()
+
+
+def fingerprint_paths(paths: list[Path], adapter_version: int) -> str:
+    digest = hashlib.sha256(f"adapter:{adapter_version}\n".encode())
+    for path in sorted(paths, key=lambda item: str(item)):
+        stat = path.stat()
+        digest.update(f"{path}\0{stat.st_size}\0{stat.st_mtime_ns}\n".encode())
+    return digest.hexdigest()