shellbrain 0.1.0__py3-none-any.whl

app/periphery/episodes/poller.py

@@ -0,0 +1,299 @@
+"""Repo-local background loop for episodic transcript sync."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import json
+import time
+from pathlib import Path
+from time import perf_counter
+from uuid import uuid4
+
+from app.boot.use_cases import get_uow_factory
+from app.core.use_cases.record_episode_sync_telemetry import record_episode_sync_telemetry
+from app.core.use_cases.sync_episode import sync_episode_from_host
+from app.periphery.episodes.source_discovery import (
+    SUPPORTED_HOSTS,
+    default_search_roots,
+    discover_active_host_session,
+    resolve_host_transcript_source,
+)
+from app.periphery.telemetry.sync_summary import build_episode_sync_records
+
+
+POLL_INTERVAL_SECONDS = 5
+IDLE_EXIT_SECONDS = 15 * 60
+
+
+@dataclass
+class _HostState:
+    """In-shellbrain state for one tracked host while the poller is alive."""
+
+    session_key: str
+    transcript_path: Path
+    last_mtime: float
+
+
+def main() -> int:
+    """Run the repo-local background episode sync loop."""
+
+    parser = argparse.ArgumentParser(prog="shellbrain-episode-poller")
+    parser.add_argument("--repo-id", required=True)
+    parser.add_argument("--repo-root", required=True)
+    args = parser.parse_args()
+
+    run_episode_poller(repo_id=args.repo_id, repo_root=Path(args.repo_root))
+    return 0
+
+
+def run_episode_poller(*, repo_id: str, repo_root: Path) -> None:
+    """Run until the repo appears idle for long enough."""
+
+    repo_root = repo_root.resolve()
+    known_state: dict[str, _HostState] = {}
+    last_change_at = time.monotonic()
+    uow_factory = get_uow_factory()
+
+    while True:
+        saw_change = False
+        for host_app in SUPPORTED_HOSTS:
+            search_roots = default_search_roots(repo_root=repo_root, host_app=host_app)
+            candidate = discover_active_host_session(
+                host_app=host_app,
+                repo_root=repo_root,
+                search_roots=search_roots,
+            )
+
+            if candidate is None:
+                if host_app in known_state:
+                    _record_missing_source(
+                        repo_root=repo_root,
+                        host_app=host_app,
+                        host_session_key=known_state[host_app].session_key,
+                        search_roots=search_roots,
+                        last_known_path=known_state[host_app].transcript_path,
+                    )
+                continue
+
+            transcript_path = Path(candidate["transcript_path"])
+            state = known_state.get(host_app)
+            session_changed = state is not None and state.session_key != candidate["host_session_key"]
+            if session_changed:
+                _close_episode(
+                    repo_id=repo_id,
+                    host_app=host_app,
+                    host_session_key=state.session_key,
+                    uow_factory=uow_factory,
+                )
+
+            mtime = transcript_path.stat().st_mtime if transcript_path.exists() else 0.0
+            should_sync = state is None or session_changed or state.last_mtime != mtime
+            known_state[host_app] = _HostState(
+                session_key=str(candidate["host_session_key"]),
+                transcript_path=transcript_path,
+                last_mtime=mtime,
+            )
+            if not should_sync:
+                continue
+
+            sync_started_at = perf_counter()
+            try:
+                with uow_factory() as uow:
+                    sync_result = sync_episode_from_host(
+                        repo_id=repo_id,
+                        host_app=host_app,
+                        host_session_key=str(candidate["host_session_key"]),
+                        uow=uow,
+                        search_roots=search_roots,
+                        last_known_path=transcript_path,
+                    )
+                _record_status(
+                    repo_root=repo_root,
+                    host_app=host_app,
+                    host_session_key=str(candidate["host_session_key"]),
+                    last_successful_sync_at=_utc_now().isoformat(),
+                    last_error=None,
+                )
+                _record_sync_telemetry_best_effort(
+                    uow_factory=uow_factory,
+                    repo_id=repo_id,
+                    host_app=host_app,
+                    host_session_key=str(candidate["host_session_key"]),
+                    thread_id=str(sync_result["thread_id"]),
+                    episode_id=str(sync_result["episode_id"]),
+                    transcript_path=str(sync_result["transcript_path"]),
+                    outcome="ok",
+                    error_stage=None,
+                    error_message=None,
+                    duration_ms=int((perf_counter() - sync_started_at) * 1000),
+                    imported_event_count=int(sync_result["imported_event_count"]),
+                    total_event_count=int(sync_result["total_event_count"]),
+                    user_event_count=int(sync_result["user_event_count"]),
+                    assistant_event_count=int(sync_result["assistant_event_count"]),
+                    tool_event_count=int(sync_result["tool_event_count"]),
+                    system_event_count=int(sync_result["system_event_count"]),
+                    tool_type_counts=dict(sync_result["tool_type_counts"]),
+                )
+                saw_change = True
+            except Exception as exc:
+                _record_status(
+                    repo_root=repo_root,
+                    host_app=host_app,
+                    host_session_key=str(candidate["host_session_key"]),
+                    last_successful_sync_at=None,
+                    last_error=str(exc),
+                )
+                _record_sync_telemetry_best_effort(
+                    uow_factory=uow_factory,
+                    repo_id=repo_id,
+                    host_app=host_app,
+                    host_session_key=str(candidate["host_session_key"]),
+                    thread_id=f"{host_app}:{candidate['host_session_key']}",
+                    episode_id=None,
+                    transcript_path=str(transcript_path),
+                    outcome="error",
+                    error_stage="sync",
+                    error_message=str(exc),
+                    duration_ms=int((perf_counter() - sync_started_at) * 1000),
+                    imported_event_count=0,
+                    total_event_count=0,
+                    user_event_count=0,
+                    assistant_event_count=0,
+                    tool_event_count=0,
+                    system_event_count=0,
+                    tool_type_counts={},
+                )
+
+        if saw_change:
+            last_change_at = time.monotonic()
+        elif time.monotonic() - last_change_at >= IDLE_EXIT_SECONDS:
+            break
+
+        time.sleep(POLL_INTERVAL_SECONDS)
+def _close_episode(*, repo_id: str, host_app: str, host_session_key: str, uow_factory) -> None:
+    """Close one active episode when a newer session replaces it."""
+
+    canonical_thread_id = f"{host_app}:{host_session_key}"
+    with uow_factory() as uow:
+        episode = uow.episodes.get_episode_by_thread(repo_id=repo_id, thread_id=canonical_thread_id)
+        if episode is None:
+            return
+        uow.episodes.close_episode(episode_id=episode.id, ended_at=_utc_now())
+
+
+def _record_missing_source(
+    *,
+    repo_root: Path,
+    host_app: str,
+    host_session_key: str,
+    search_roots: list[Path],
+    last_known_path: Path,
+) -> None:
+    """Persist a clear health record when one previously-known source disappears."""
+
+    try:
+        resolve_host_transcript_source(
+            host_app=host_app,
+            host_session_key=host_session_key,
+            search_roots=search_roots,
+            last_known_path=last_known_path,
+        )
+    except FileNotFoundError as exc:
+        _record_status(
+            repo_root=repo_root,
+            host_app=host_app,
+            host_session_key=host_session_key,
+            last_successful_sync_at=None,
+            last_error=str(exc),
+        )
+
+
+def _record_status(
+    *,
+    repo_root: Path,
+    host_app: str,
+    host_session_key: str,
+    last_successful_sync_at: str | None,
+    last_error: str | None,
+) -> None:
+    """Write one small repo-local health/status file."""
+
+    runtime_dir = repo_root / ".shellbrain"
+    runtime_dir.mkdir(parents=True, exist_ok=True)
+    status_path = runtime_dir / "episode_sync_status.json"
+    try:
+        status = json.loads(status_path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError):
+        status = {"repo_root": str(repo_root), "hosts": {}}
+
+    hosts = status.setdefault("hosts", {})
+    host_status = hosts.setdefault(host_app, {})
+    host_status["current_session_key"] = host_session_key
+    if last_successful_sync_at is not None:
+        host_status["last_successful_sync_at"] = last_successful_sync_at
+    host_status["last_error"] = last_error
+    status_path.write_text(json.dumps(status, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def _utc_now() -> datetime:
+    """Return a timezone-aware current UTC time."""
+
+    return datetime.now(timezone.utc)
+
+
+def _record_sync_telemetry_best_effort(
+    *,
+    uow_factory,
+    repo_id: str,
+    host_app: str,
+    host_session_key: str,
+    thread_id: str,
+    episode_id: str | None,
+    transcript_path: str | None,
+    outcome: str,
+    error_stage: str | None,
+    error_message: str | None,
+    duration_ms: int,
+    imported_event_count: int,
+    total_event_count: int,
+    user_event_count: int,
+    assistant_event_count: int,
+    tool_event_count: int,
+    system_event_count: int,
+    tool_type_counts: dict[str, int],
+) -> None:
+    """Persist one poller sync-run row without affecting the poller loop."""
+
+    try:
+        run, tool_types = build_episode_sync_records(
+            sync_run_id=str(uuid4()),
+            source="poller",
+            invocation_id=None,
+            repo_id=repo_id,
+            host_app=host_app,
+            host_session_key=host_session_key,
+            thread_id=thread_id,
+            episode_id=episode_id,
+            transcript_path=transcript_path,
+            outcome=outcome,
+            error_stage=error_stage,
+            error_message=error_message,
+            duration_ms=duration_ms,
+            imported_event_count=imported_event_count,
+            total_event_count=total_event_count,
+            user_event_count=user_event_count,
+            assistant_event_count=assistant_event_count,
+            tool_event_count=tool_event_count,
+            system_event_count=system_event_count,
+            tool_type_counts=tool_type_counts,
+        )
+        with uow_factory() as uow:
+            record_episode_sync_telemetry(uow=uow, run=run, tool_types=tool_types)
+    except Exception:
+        return
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

app/periphery/episodes/source_discovery.py

@@ -0,0 +1,66 @@
+"""Resolve local host transcript files for episodic ingestion."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from app.periphery.episodes.claude_code import (
+    find_latest_claude_code_session_for_repo,
+    resolve_claude_code_transcript_path,
+)
+from app.periphery.episodes.codex import find_latest_codex_session_for_repo, resolve_codex_transcript_path
+
+SUPPORTED_HOSTS = ("codex", "claude_code")
+
+
+def resolve_host_transcript_source(
+    *,
+    host_app: str,
+    host_session_key: str,
+    search_roots: Sequence[Path],
+    last_known_path: Path | None = None,
+) -> Path:
+    """Resolve the transcript file for one supported host session."""
+
+    search_roots = [Path(root) for root in search_roots]
+    if host_app == "codex":
+        return resolve_codex_transcript_path(
+            host_session_key=host_session_key,
+            search_roots=search_roots,
+            last_known_path=last_known_path,
+        )
+    if host_app == "claude_code":
+        return resolve_claude_code_transcript_path(
+            host_session_key=host_session_key,
+            search_roots=search_roots,
+            last_known_path=last_known_path,
+        )
+    raise ValueError(f"Unsupported host app for episode sync: {host_app}")
+
+
+def default_search_roots(*, repo_root: Path, host_app: str) -> list[Path]:
+    """Return bounded transcript search roots for one supported host."""
+
+    home = Path.home()
+    if host_app == "codex":
+        return [home / ".codex" / "sessions"]
+    if host_app == "claude_code":
+        return [home]
+    return [repo_root]
+
+
+def discover_active_host_session(
+    *,
+    host_app: str,
+    repo_root: Path,
+    search_roots: Sequence[Path],
+) -> dict | None:
+    """Discover the latest active session for one host and repo root."""
+
+    search_roots = [Path(root) for root in search_roots]
+    if host_app == "codex":
+        return find_latest_codex_session_for_repo(repo_root=repo_root, search_roots=search_roots)
+    if host_app == "claude_code":
+        return find_latest_claude_code_session_for_repo(repo_root=repo_root, search_roots=search_roots)
+    raise ValueError(f"Unsupported host app for episode sync: {host_app}")

app/periphery/episodes/tool_filter.py

@@ -0,0 +1,165 @@
+"""Deterministic filtering and summarization for host tool-result events."""
+
+from __future__ import annotations
+
+import re
+import shlex
+
+
+_NOISY_TOOLS = {"glob", "read", "grep", "search", "find", "ls", "pwd", "cat"}
+_MUTATION_TOOLS = {"edit", "write", "multiedit", "apply_patch"}
+_VALIDATION_FAMILIES = {
+    "pytest",
+    "py.test",
+    "go test",
+    "cargo test",
+    "npm test",
+    "pnpm test",
+    "yarn test",
+    "alembic",
+}
+_NOISY_COMMANDS = {"ls", "pwd", "cat", "rg", "grep", "find", "fd", "head", "tail", "sed"}
+_FAILED_PREFIXES = ("failed", "error", "exception")
+_MUTATION_PREFIXES = ("updated", "edited", "patched", "applied", "wrote")
+
+
+def should_keep_tool_result(
+    *,
+    tool_name: str | None,
+    status: str | None,
+    text: str | None,
+    summary: str | None = None,
+    command: str | None = None,
+    is_error: bool | None = None,
+) -> bool:
+    """Return whether one tool result carries durable episodic value."""
+
+    normalized_tool = (tool_name or "").strip().lower()
+    normalized_command = _command_family(command)
+    normalized_status = (status or "").strip().lower()
+    normalized_summary = (summary or "").strip().lower()
+    normalized_text = _compact_text(text).lower()
+
+    if is_error is True or normalized_status in {"error", "failed", "failure"}:
+        return True
+    if _extract_exit_code(text) not in {None, 0}:
+        return True
+    if normalized_tool in _MUTATION_TOOLS:
+        return True
+    if normalized_command in _VALIDATION_FAMILIES:
+        return True
+    if normalized_summary.startswith(_FAILED_PREFIXES) or normalized_summary.startswith(_MUTATION_PREFIXES):
+        return True
+    if normalized_text.startswith(_FAILED_PREFIXES) or normalized_text.startswith(_MUTATION_PREFIXES):
+        return True
+    if normalized_tool in _NOISY_TOOLS:
+        return False
+    if normalized_command in _NOISY_COMMANDS:
+        return False
+    return False
+
+
+def summarize_tool_result(
+    *,
+    tool_name: str | None,
+    status: str | None,
+    text: str | None,
+    summary: str | None = None,
+    command: str | None = None,
+    is_error: bool | None = None,
+) -> str:
+    """Build a compact, stable human-readable tool result summary."""
+
+    command_family = _command_family(command)
+    exit_code = _extract_exit_code(text)
+
+    if summary:
+        return _normalize_summary(summary)
+    if command_family in _VALIDATION_FAMILIES:
+        if is_error is True or (status or "").lower() in {"error", "failed", "failure"} or exit_code not in {None, 0}:
+            return f"{command_family} failed"
+        return f"{command_family} passed"
+
+    compact_text = _compact_text(text)
+    if compact_text:
+        return _normalize_summary(compact_text)
+    normalized_tool = (tool_name or "tool").strip().lower()
+    if normalized_tool in _MUTATION_TOOLS:
+        return f"{normalized_tool} updated file"
+    if is_error is True or (status or "").lower() in {"error", "failed", "failure"}:
+        return f"{normalized_tool} failed"
+    return f"{normalized_tool} completed"
+
+
+def _normalize_summary(value: str) -> str:
+    """Collapse one tool result into a short stable sentence fragment."""
+
+    compact = _compact_text(value)
+    lowered = compact.lower()
+    if ":" in compact:
+        prefix = compact.split(":", 1)[0].strip()
+        lowered_prefix = prefix.lower()
+        if (
+            any(token in lowered_prefix for token in ("failed", "error", "exception"))
+            or lowered_prefix.startswith(_MUTATION_PREFIXES)
+        ):
+            return prefix
+    if lowered.startswith("process exited with code"):
+        return compact.splitlines()[0].strip()
+    return compact
+
+
+def _compact_text(value: str | None) -> str:
+    """Drop wrapper noise and keep the first meaningful output line."""
+
+    if value is None:
+        return ""
+    for line in value.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.startswith("Chunk ID:"):
+            continue
+        if stripped.startswith("Wall time:"):
+            continue
+        if stripped.startswith("Original token count:"):
+            continue
+        if stripped == "Output:":
+            continue
+        return stripped
+    return ""
+
+
+def _command_family(command: str | None) -> str:
+    """Reduce one shell command into a stable family label when possible."""
+
+    if not command:
+        return ""
+    try:
+        tokens = shlex.split(command)
+    except ValueError:
+        tokens = command.split()
+    if not tokens:
+        return ""
+    lowered = [token.lower() for token in tokens]
+    head = lowered[0]
+    if head in {"python", "python3", "uv"} and len(lowered) >= 3 and lowered[1] == "-m":
+        return f"{lowered[1]} {lowered[2]}"
+    if head == "go" and len(lowered) >= 2:
+        return f"go {lowered[1]}"
+    if head == "cargo" and len(lowered) >= 2:
+        return f"cargo {lowered[1]}"
+    if head in {"npm", "pnpm", "yarn"} and len(lowered) >= 2:
+        return f"{head} {lowered[1]}"
+    return head
+
+
+def _extract_exit_code(text: str | None) -> int | None:
+    """Extract one exit status from wrapped shell output when present."""
+
+    if text is None:
+        return None
+    match = re.search(r"Process exited with code (\d+)", text)
+    if match is None:
+        return None
+    return int(match.group(1))

app/periphery/identity/__init__.py

@@ -0,0 +1 @@
+"""Caller-identity adapters for supported host runtimes."""

app/periphery/identity/claude_hook_install.py

@@ -0,0 +1,67 @@
+"""Install the official Claude SessionStart hook for Shellbrain caller identity."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+_SESSION_START_MATCHER = "startup|resume|clear|compact"
+_MANAGED_MARKER = "shellbrain-managed:session-start"
+
+
+def install_claude_hook(*, repo_root: Path) -> Path:
+    """Install or update one repo-local Claude settings file with the Shellbrain hook."""
+
+    repo_root = repo_root.resolve()
+    settings_path = repo_root / ".claude" / "settings.local.json"
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError):
+        settings = {}
+    if not isinstance(settings, dict):
+        settings = {}
+    hooks = settings.get("hooks")
+    if not isinstance(hooks, dict):
+        hooks = {}
+    session_start_entries = hooks.get("SessionStart")
+    if not isinstance(session_start_entries, list):
+        session_start_entries = []
+
+    managed_entry = {
+        "matcher": _SESSION_START_MATCHER,
+        "hooks": [
+            {
+                "type": "command",
+                "command": _managed_command(),
+            }
+        ],
+    }
+    replaced = False
+    for index, entry in enumerate(session_start_entries):
+        if not isinstance(entry, dict):
+            continue
+        nested_hooks = entry.get("hooks")
+        if not isinstance(nested_hooks, list):
+            continue
+        if any(_MANAGED_MARKER in str(item.get("command", "")) for item in nested_hooks if isinstance(item, dict)):
+            session_start_entries[index] = managed_entry
+            replaced = True
+            break
+    if not replaced:
+        session_start_entries.append(managed_entry)
+    hooks["SessionStart"] = session_start_entries
+    settings["hooks"] = hooks
+    settings_path.write_text(json.dumps(settings, indent=2, sort_keys=True), encoding="utf-8")
+    return settings_path
+
+
+def _managed_command() -> str:
+    """Return the Shellbrain-managed Claude SessionStart hook command."""
+
+    return (
+        "python -m app.periphery.identity.claude_runtime session-start "
+        f"# {_MANAGED_MARKER} uses CLAUDE_ENV_FILE to export SHELLBRAIN_HOST_APP=claude_code "
+        "and related Shellbrain identity variables"
+    )

app/periphery/identity/claude_runtime.py

@@ -0,0 +1,83 @@
+"""Claude runtime identity helpers and SessionStart hook entrypoint."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+
+from app.core.entities.identity import CallerIdentity, IdentityTrustLevel
+
+
+def resolve_trusted_claude_caller_identity() -> CallerIdentity | None:
+    """Resolve one trusted Claude caller from Shellbrain hook environment variables."""
+
+    if os.getenv("SHELLBRAIN_HOST_APP") != "claude_code":
+        return None
+    session_key = os.getenv("SHELLBRAIN_HOST_SESSION_KEY")
+    transcript_path = os.getenv("SHELLBRAIN_TRANSCRIPT_PATH")
+    if not session_key or not transcript_path:
+        return None
+    agent_key = os.getenv("SHELLBRAIN_AGENT_KEY") or None
+    if "/subagents/" in transcript_path and agent_key is None:
+        return CallerIdentity(
+            host_app="claude_code",
+            host_session_key=session_key,
+            trust_level=IdentityTrustLevel.UNSUPPORTED,
+        )
+    return CallerIdentity(
+        host_app="claude_code",
+        host_session_key=session_key,
+        agent_key=agent_key,
+        trust_level=IdentityTrustLevel.TRUSTED,
+    )
+
+
+def detect_claude_runtime_without_hook() -> bool:
+    """Return whether Claude seems present but trusted hook identity is missing."""
+
+    if os.getenv("SHELLBRAIN_HOST_APP") == "claude_code":
+        return False
+    return any(
+        os.getenv(name)
+        for name in ("CLAUDE_SESSION_ID", "CLAUDE_CODE_REMOTE_SESSION_ID", "CLAUDE_CODE_AGENT_NAME")
+    )
+
+
+def resolve_trusted_claude_transcript_path() -> Path | None:
+    """Return the trusted Claude transcript path injected by the Shellbrain hook when present."""
+
+    transcript_path = os.getenv("SHELLBRAIN_TRANSCRIPT_PATH")
+    if not transcript_path:
+        return None
+    return Path(transcript_path).expanduser().resolve()
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entrypoint for the Claude SessionStart hook helper."""
+
+    parser = argparse.ArgumentParser(prog="shellbrain-claude-runtime")
+    parser.add_argument("command", choices=("session-start",))
+    args = parser.parse_args(argv)
+    if args.command != "session-start":
+        return 2
+    payload = json.load(sys.stdin)
+    session_id = str(payload.get("session_id") or "")
+    transcript_path = str(payload.get("transcript_path") or "")
+    if not session_id or not transcript_path:
+        return 1
+    env_file = os.getenv("CLAUDE_ENV_FILE")
+    if not env_file:
+        return 0
+    with Path(env_file).open("a", encoding="utf-8") as handle:
+        handle.write("export SHELLBRAIN_HOST_APP=claude_code\n")
+        handle.write(f"export SHELLBRAIN_HOST_SESSION_KEY={session_id}\n")
+        handle.write(f"export SHELLBRAIN_TRANSCRIPT_PATH={transcript_path}\n")
+        handle.write(f"export SHELLBRAIN_CALLER_ID=claude_code:{session_id}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))