cogsession 0.1.0__py3-none-any.whl

cogsession/__init__.py

@@ -0,0 +1,2 @@
+"""CogSession — Session memory system for AI coding agents."""
+__version__ = "0.1.0"

cogsession/claims.py

@@ -0,0 +1,276 @@
+"""
+cogsession/claims.py
+
+Checkable claims: store the command that *proved* something, then re-run it.
+
+Everything else in this package records what was believed at a moment —
+decisions, dead ends, assumptions. None of it is ever re-checked, so the most
+expensive recurring failure is not a wrong decision. It is a right one that
+quietly stopped being true:
+
+  - a pull request description explaining a schema the code no longer has
+  - a source comment naming a constraint that moved
+  - a planning document one day old, read as current
+  - a test asserting a shape the implementation dropped
+  - a docstring contradicting its own function
+
+Each reduces to one sentence: *something was true when it was written and
+stopped being true.* A model cannot notice that from a transcript, and a human
+notices it in review, which is the expensive place.
+
+So a claim carries its own proof. Not a natural-language description of how to
+check it — a command, its expected output, and the commit it held at. When the
+files it touches change, re-run it. What comes back is not "you decided X" but
+"what you wrote about X is now false", which is the only version that is
+actionable.
+
+## On running stored commands
+
+Verification executes shell commands from `claims.json`. That is the same trust
+boundary as `.git/hooks`: local, developer-owned, not shared. Two guards make
+that boundary explicit rather than assumed:
+
+  - a claims file **tracked by git** is never executed, because a tracked file
+    can arrive from someone else
+  - every command runs with a timeout and its output is compared, never
+    interpreted
+
+Keep commands to cheap, read-only checks — `grep -c`, `test -f`, a fast unit
+test. A claim is a tripwire, not a build step.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+CLAIMS_FILE = "claims.json"
+DEFAULT_TIMEOUT = 20
+MAX_OUTPUT = 2000
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+@dataclass
+class Claim:
+    """One assertion, with the command that proves it.
+
+    `expect` is compared against stripped stdout. Leave it None to mean "the
+    command must merely succeed", which suits `test -f` or a test invocation
+    where the exit code is the whole signal.
+    """
+
+    claim: str
+    verified_by: str
+    expect: Optional[str] = None
+    watches: list = field(default_factory=list)   # paths whose change re-checks
+    asserted_in: str = ""                          # where the claim was made
+    at_commit: str = ""
+    recorded_at: str = field(default_factory=_now)
+    last_status: str = "unverified"                # holds | broken | error | unverified
+    last_checked: str = ""
+    last_output: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Claim":
+        known = {f for f in cls.__dataclass_fields__}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+
+@dataclass
+class CheckResult:
+    claim: Claim
+    status: str          # holds | broken | error
+    detail: str
+
+    @property
+    def broken(self) -> bool:
+        return self.status != "holds"
+
+
+class ClaimStore:
+    """Claims for one session, persisted as `claims.json` in its folder."""
+
+    def __init__(self, project_root: Path, session_id: str):
+        self.root = Path(project_root)
+        self.session_id = session_id
+        self.path = self.root / ".cogsessions" / session_id / CLAIMS_FILE
+
+    # ── Persistence ────────────────────────────────────────────────────
+
+    def load(self) -> list[Claim]:
+        if not self.path.exists():
+            return []
+        try:
+            raw = json.loads(self.path.read_text())
+        except (OSError, ValueError):
+            return []
+        return [Claim.from_dict(c) for c in raw.get("claims", []) if isinstance(c, dict)]
+
+    def save(self, claims: list[Claim]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(
+                {"session_id": self.session_id, "updated_at": _now(),
+                 "claims": [c.to_dict() for c in claims]},
+                indent=2,
+            )
+        )
+
+    def add(self, claim: Claim) -> Claim:
+        """Record a claim, replacing any earlier one with the same text.
+
+        Replacing rather than appending is deliberate: re-asserting something
+        means the current wording is what should be checked, and a store with
+        three versions of one claim cannot say which is live.
+        """
+        claims = [c for c in self.load() if c.claim != claim.claim]
+        claims.append(claim)
+        self.save(claims)
+        return claim
+
+    # ── Verification ───────────────────────────────────────────────────
+
+    def verify(self, only_if_changed: bool = False) -> list[CheckResult]:
+        """Re-run each claim's proof. Returns one result per claim checked."""
+        if _is_git_tracked(self.root, self.path):
+            return []
+
+        claims = self.load()
+        results: list[CheckResult] = []
+        for claim in claims:
+            if only_if_changed and not self._touched(claim):
+                continue
+            result = run_check(self.root, claim)
+            claim.last_status = result.status
+            claim.last_checked = _now()
+            claim.last_output = result.detail[:MAX_OUTPUT]
+            results.append(result)
+        if results:
+            self.save(claims)
+        return results
+
+    def _touched(self, claim: Claim) -> bool:
+        """Has anything this claim watches changed since it was recorded?
+
+        No commit and no watch list means "always check": a claim that cannot
+        say what would invalidate it is exactly the one worth re-running.
+        """
+        if not claim.at_commit:
+            return True
+        changed = _changed_since(self.root, claim.at_commit)
+        if changed is None:
+            return True
+        if not claim.watches:
+            return True
+        return any(
+            any(path == w or path.startswith(w.rstrip("/") + "/") for w in claim.watches)
+            for path in changed
+        )
+
+
+def run_check(project_root: Path, claim: Claim) -> CheckResult:
+    """Execute one claim's command and compare against `expect`."""
+    try:
+        proc = subprocess.run(
+            claim.verified_by,
+            shell=True,
+            cwd=str(project_root),
+            capture_output=True,
+            text=True,
+            timeout=DEFAULT_TIMEOUT,
+        )
+    except subprocess.TimeoutExpired:
+        return CheckResult(claim, "error", f"timed out after {DEFAULT_TIMEOUT}s")
+    except OSError as exc:
+        return CheckResult(claim, "error", f"could not run: {exc}")
+
+    got = (proc.stdout or "").strip()
+
+    if claim.expect is None:
+        if proc.returncode == 0:
+            return CheckResult(claim, "holds", "command succeeded")
+        return CheckResult(
+            claim, "broken",
+            f"exit {proc.returncode}: {(proc.stderr or got).strip()[:200]}",
+        )
+
+    if got == claim.expect.strip():
+        return CheckResult(claim, "holds", f"got {got!r}")
+    return CheckResult(
+        claim, "broken", f"expected {claim.expect.strip()!r}, got {got!r}"
+    )
+
+
+def format_report(results: list[CheckResult]) -> str:
+    """One short block, and only when something moved.
+
+    Silence when everything holds is the point. A report that appears every
+    session becomes furniture, and furniture is not read.
+    """
+    if not results:
+        return ""
+    broken = [r for r in results if r.broken]
+    if not broken:
+        return ""
+
+    held = len(results) - len(broken)
+    lines = [
+        f"[CogSession] {len(broken)} claim(s) no longer hold"
+        + (f", {held} still do" if held else "")
+        + ":"
+    ]
+    for r in broken:
+        lines.append(f"  ✗ {r.claim.claim}")
+        lines.append(f"    {r.detail}")
+        if r.claim.asserted_in:
+            lines.append(f"    asserted in: {r.claim.asserted_in}")
+        lines.append(f"    proof: {r.claim.verified_by}")
+    return "\n".join(lines)
+
+
+# ── git helpers ────────────────────────────────────────────────────────
+
+
+def _git(project_root: Path, *args: str) -> Optional[subprocess.CompletedProcess]:
+    try:
+        return subprocess.run(
+            ["git", "-C", str(project_root), *args],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+
+def _is_git_tracked(project_root: Path, path: Path) -> bool:
+    """Refuse to execute a claims file that could have come from someone else."""
+    proc = _git(project_root, "ls-files", "--error-unmatch", str(path))
+    return bool(proc and proc.returncode == 0)
+
+
+def _changed_since(project_root: Path, commit: str) -> Optional[list[str]]:
+    """Repo-relative paths changed since `commit`, including uncommitted work.
+
+    None means git could not answer, which callers treat as "check anyway".
+    Failing towards checking is right for a tripwire: a missed re-check is a
+    stale claim believed, while an extra one costs a `grep`.
+    """
+    diff = _git(project_root, "diff", "--name-only", commit)
+    if diff is None or diff.returncode != 0:
+        return None
+    paths = {p for p in diff.stdout.splitlines() if p}
+    status = _git(project_root, "status", "--porcelain")
+    if status and status.returncode == 0:
+        for line in status.stdout.splitlines():
+            if len(line) > 3:
+                paths.add(line[3:].strip().split(" -> ")[-1])
+    return sorted(paths)

cogsession/cli.py

@@ -0,0 +1,142 @@
+"""
+cogsession/cli.py
+
+`cogsession install` — wire the hooks into Claude Code after a package install.
+
+The MCP server gives an agent eleven tools it can call. The hooks are what make
+CogSession work *without being asked*: the session opening itself, the journal
+recording as work happens, claims re-checked when a session starts. Those live
+in `~/.claude/settings.json`, which a package install cannot write on its own.
+
+So this is the second half of `pip install cogsession`. Without it you get the
+tools and none of the recording, which is a quieter and worse product than the
+one described in the README.
+
+It is idempotent, backs up the settings file first, and prints what it changed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from cogsession.installer import HOOKS, hook_command, is_installed_on_path, merge_settings
+
+MCP_SERVER_NAME = "cogsession"
+
+
+def _register_mcp_server(repo_dir: Path | None) -> str:
+    """Register the MCP server with the Claude Code CLI, if it is present.
+
+    A missing `claude` binary is not an error. Plenty of people wire MCP servers
+    up by hand or use another client, and failing the whole install over an
+    optional convenience would be wrong.
+    """
+    claude = shutil.which("claude")
+    if claude is None:
+        return "  ~ `claude` not on PATH — register the MCP server yourself (see README)"
+
+    if repo_dir is not None:
+        command = [claude, "mcp", "add", MCP_SERVER_NAME, "--",
+                   "uv", "--directory", str(repo_dir), "run", MCP_SERVER_NAME]
+    else:
+        command = [claude, "mcp", "add", MCP_SERVER_NAME, "--", MCP_SERVER_NAME]
+
+    try:
+        result = subprocess.run(command, capture_output=True, text=True, timeout=30)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return f"  ~ could not register the MCP server: {exc}"
+
+    if result.returncode == 0:
+        return f"  ✓ MCP server registered as `{MCP_SERVER_NAME}`"
+    # Already-registered is the common non-zero case and is not a failure.
+    detail = (result.stderr or result.stdout).strip().splitlines()
+    return f"  ~ MCP server not registered: {detail[0] if detail else 'unknown reason'}"
+
+
+def install(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="cogsession install",
+        description="Wire CogSession's hooks into Claude Code.",
+    )
+    parser.add_argument(
+        "--repo",
+        type=Path,
+        default=None,
+        metavar="DIR",
+        help="Run the hooks from this checkout via uv, instead of the installed "
+             "console script. Use when working on CogSession itself.",
+    )
+    parser.add_argument(
+        "--claude-dir",
+        type=Path,
+        default=Path.home() / ".claude",
+        metavar="DIR",
+        help="Claude Code config directory (default: ~/.claude)",
+    )
+    parser.add_argument(
+        "--no-statusline",
+        action="store_true",
+        help="Do not offer to set the status line.",
+    )
+    parser.add_argument(
+        "--no-mcp",
+        action="store_true",
+        help="Only write the hooks; skip registering the MCP server.",
+    )
+    args = parser.parse_args(argv)
+
+    repo_dir = args.repo.resolve() if args.repo else None
+
+    if repo_dir is None and not is_installed_on_path():
+        print(
+            "cogsession-hook is not on PATH, so the hooks would not be able to run.\n"
+            "Either install the package (`pip install cogsession`) or point at a\n"
+            "checkout with `cogsession install --repo /path/to/cogsession`.",
+            file=sys.stderr,
+        )
+        return 1
+
+    settings = merge_settings(
+        args.claude_dir, repo_dir, set_statusline=not args.no_statusline
+    )
+
+    print("CogSession installed.\n")
+    print(f"  ✓ {len(HOOKS)} hooks written to {settings}")
+    print(f"    they run: {hook_command('<event>', repo_dir)}")
+
+    if not args.no_mcp:
+        print(_register_mcp_server(repo_dir))
+
+    print(
+        "\n  Add `.cogsessions/` to your .gitignore — that is where sessions are kept,\n"
+        "  and it is yours, not something to commit.\n"
+        "\n  Open a new session to pick it up. Existing sessions loaded their\n"
+        "  settings at start and will not see these hooks."
+    )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the `cogsession-admin` console script."""
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "install":
+        return install(argv[1:])
+
+    print(
+        "Usage: cogsession-admin install [options]\n"
+        "\n"
+        "  install   Wire CogSession's hooks into Claude Code.\n"
+        "\n"
+        "The MCP server itself is the `cogsession` command, which an MCP client\n"
+        "launches for you — it is not meant to be run by hand.",
+        file=sys.stderr,
+    )
+    return 0 if not argv else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cogsession/config.py

@@ -0,0 +1,102 @@
+"""
+cogsession/config.py
+
+All settings for CogSession.
+Project-level config lives in .cogsession.json at project root.
+Global config lives in ~/.cogsession/config.json
+"""
+
+import os
+import json
+import sys
+from pathlib import Path
+
+
+# ── Global defaults ───────────────────────────────────────────────────
+SESSIONS_DIR_NAME = ".cogsessions"
+CONFIG_FILE_NAME  = ".cogsession.json"
+
+# Where the handoff is delivered so the next session auto-loads it. Deliberately
+# the .local variant: it is auto-loaded like CLAUDE.md but is not committed, so
+# session state never enters a shared source file or dirties the working tree.
+HANDOFF_TARGET_NAME = "CLAUDE.local.md"
+
+
+DEFAULT_CONFIG = {
+    # Master switch — set false to completely disable
+    "enabled": True,
+
+    # Individual feature toggles — user can pick what they want
+    "features": {
+        "dead_ends":        True,   # Track approaches that failed
+        "assumptions":      True,   # Track what agent assumed but didn't verify
+        "token_map":        True,   # Tag decisions with context% when made
+        "error_graveyard":  True,   # Log errors + how they were resolved
+        "environment":      True,   # Snapshot run commands, ports, env vars
+        "file_cache":       True,   # Cache file reads to avoid duplicates
+        "danger_zones":     True,   # Flag files/areas that need care
+        "auto_diagram":     True,   # Generate Mermaid architecture diagram
+        "auto_handoff":     True,   # Auto-write handoff to CLAUDE.local.md (never a tracked file)
+        "session_search":   True,   # SQLite FTS across all sessions
+        "claim_checks":     True,   # Re-run the proof behind a recorded claim
+    },
+
+    # Context % thresholds
+    "thresholds": {
+        "warn_at":       65,    # First gentle warning
+        "alert_at":      75,    # Strong warning + suggestion
+        "checkpoint_at": 80,    # Auto-checkpoint fires
+    },
+
+    # How often to auto-save running state (every N tool calls)
+    "autosave_every_n_tools": 10,
+
+    # Files/paths to exclude from tracking
+    "exclude": [
+        "*.log", ".env", ".env.*",
+        "node_modules/", "__pycache__/",
+        ".git/", "*.pyc", "dist/", "build/"
+    ],
+
+    # Where session folder lives relative to project root
+    "session_dir": ".cogsessions",
+}
+
+
+def load_project_config(project_root: Path) -> dict:
+    """Load .cogsession.json from project root, merged with defaults."""
+    config = DEFAULT_CONFIG.copy()
+    config_file = project_root / CONFIG_FILE_NAME
+
+    if config_file.exists():
+        try:
+            user_config = json.loads(config_file.read_text())
+            # Deep merge features
+            if "features" in user_config:
+                config["features"].update(user_config["features"])
+            if "thresholds" in user_config:
+                config["thresholds"].update(user_config["thresholds"])
+            # Top-level overrides
+            for k, v in user_config.items():
+                if k not in ("features", "thresholds"):
+                    config[k] = v
+        except Exception as e:
+            print(f"[CogSession] Config parse error: {e}, using defaults", file=sys.stderr, flush=True)
+
+    return config
+
+
+def is_enabled(project_root: Path) -> bool:
+    """Quick check — is cogsession enabled for this project?"""
+    # Global disable via env var
+    if os.getenv("COGSESSION_DISABLED"):
+        return False
+
+    config = load_project_config(project_root)
+    return config.get("enabled", True)
+
+
+def feature_enabled(project_root: Path, feature: str) -> bool:
+    """Is a specific feature enabled?"""
+    config = load_project_config(project_root)
+    return config.get("features", {}).get(feature, True)

cogsession/distiller.py

@@ -0,0 +1,96 @@
+"""
+cogsession/distiller.py
+
+Observation into memory.
+Deterministic tier: extracts touched files, commands, test results, error text without LLM.
+Inferential tier: best-effort LLM extraction for handoff prose/decisions.
+"""
+
+from pathlib import Path
+from typing import Dict, Any, List
+import json
+from datetime import datetime, timezone
+
+from cogsession.session.models import Session, LogEntry, DeadEnd
+
+
+class Distiller:
+    """Pure functions converting transcript & hook observations into structured memory."""
+
+    @staticmethod
+    def process_deterministic_tool_use(
+        session: Session, tool_name: str, tool_input: Dict[str, Any], tool_response: Dict[str, Any]
+    ) -> None:
+        """Deterministic tier — runs on every tool call."""
+        ts = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+        if tool_name == "Read":
+            fp = tool_input.get("file_path", "")
+            if fp and fp not in session.files_read:
+                session.files_read.append(fp)
+                session.append_log(LogEntry(type="file_read", content=fp))
+
+        elif tool_name in ("Write", "Edit", "MultiEdit"):
+            fp = tool_input.get("file_path", "")
+            if fp:
+                if tool_name == "Write" and fp not in session.files_created:
+                    session.files_created.append(fp)
+                elif fp not in session.files_edited:
+                    session.files_edited.append(fp)
+                session.append_log(LogEntry(type="file_edit", content=fp))
+
+        elif tool_name == "Bash":
+            cmd = tool_input.get("command", "")
+            exit_code = tool_response.get("exit_code", 0)
+            output = tool_response.get("output", "")
+
+            # Log git operations
+            if cmd.startswith("git "):
+                session.append_log(LogEntry(type="git_op", content=cmd))
+
+            # Log test runs
+            if any(test_runner in cmd for test_runner in ("pytest", "npm test", "jest", "go test")):
+                session.append_log(LogEntry(type="test_run", content=cmd))
+                if "passed" in output or "failed" in output:
+                    # Update environment snapshot counts if present
+                    import re
+
+                    pass_match = re.search(r"(\d+)\s+passed", output)
+                    fail_match = re.search(r"(\d+)\s+failed", output)
+                    if pass_match:
+                        session.environment.test_passing = int(pass_match.group(1))
+                    if fail_match:
+                        session.environment.test_failing = int(fail_match.group(1))
+                    session.environment.test_command = cmd
+
+            # Extract tool errors
+            if exit_code != 0 and output:
+                error_type = "general_error"
+                if "ModuleNotFoundError" in output or "ImportError" in output:
+                    error_type = "import_error"
+                elif "SyntaxError" in output:
+                    error_type = "syntax_error"
+                elif "PermissionError" in output or "Permission denied" in output:
+                    error_type = "permission_error"
+                elif "FileNotFoundError" in output:
+                    error_type = "file_not_found"
+
+                session.append_log(
+                    LogEntry(
+                        type="error",
+                        content=cmd[:100],
+                        context_pct=session.token_pct_at_close,
+                    )
+                )
+
+                # Append dead end preview if command failed twice or produced obvious error
+                if exit_code != 0 and len(output) > 20:
+                    session.dead_ends.append(
+                        DeadEnd(
+                            timestamp=ts,
+                            tried=cmd[:100],
+                            why_failed=output[:150],
+                            use_instead="",
+                            context_pct=session.token_pct_at_close,
+                        )
+                    )