thinkstack-core 4.0.0__py3-none-any.whl

thinkstack_core/hooks/pre_commit.py

@@ -0,0 +1,157 @@
+"""
+S29 — Git pre-commit hook for ThinkStack governance checks.
+
+Installs a `.git/hooks/pre-commit` script that blocks commits when
+`thinkstack doctor` or `thinkstack invariant check` fail. Also provides a
+programmatic entry point so CI and tests can run the same checks.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Union
+
+
+# ---------------------------------------------------------------------------
+# Data class
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class PreCommitResult:
+    """Outcome of the pre-commit governance checks."""
+
+    passed: bool
+    checks: list[dict]
+
+
+# ---------------------------------------------------------------------------
+# Hook script
+# ---------------------------------------------------------------------------
+
+
+_PRE_COMMIT_SCRIPT = """#!/bin/sh
+# ThinkStack pre-commit hook (S29)
+# Generated by thinkstack_core.hooks.pre_commit — safe to re-run.
+
+set -e
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel)"
+cd "$PROJECT_ROOT"
+
+echo "[thinkstack pre-commit] Running governance checks..."
+
+echo "[thinkstack pre-commit] thinkstack doctor"
+thinkstack doctor
+
+echo "[thinkstack pre-commit] thinkstack invariant check"
+thinkstack invariant check
+
+echo "[thinkstack pre-commit] All checks passed."
+"""
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def install_pre_commit_hook(project_root: Union[str, Path]) -> Path:
+    """
+    Write an executable `.git/hooks/pre-commit` script under *project_root*.
+
+    The script runs `thinkstack doctor` then `thinkstack invariant check` and exits
+    non-zero if either command fails, blocking the git commit. The operation is
+    idempotent — running it multiple times writes the same script.
+
+    Raises:
+        FileNotFoundError: if `.git/hooks/` does not exist.
+
+    Returns:
+        Path to the written hook.
+    """
+    root = Path(project_root)
+    hooks_dir = root / ".git" / "hooks"
+    if not hooks_dir.is_dir():
+        raise FileNotFoundError(
+            f"No .git/hooks/ directory found at {root}. Are you inside a git repository?"
+        )
+
+    hook_path = hooks_dir / "pre-commit"
+    hook_path.write_text(_PRE_COMMIT_SCRIPT, encoding="utf-8")
+    hook_path.chmod(0o755)
+    return hook_path
+
+
+RunResult = tuple[int, str, str]
+
+
+def _run_command(
+    command: list[str],
+    cwd: Path,
+    env: dict | None = None,
+) -> RunResult:
+    """Run a command and return (exit_code, stdout, stderr)."""
+    try:
+        proc = subprocess.run(
+            command,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            env=env,
+            check=False,
+        )
+        return proc.returncode, proc.stdout, proc.stderr
+    except FileNotFoundError as exc:
+        return 127, "", f"Command not found: {exc}"
+
+
+def run_pre_commit_checks(project_root: Union[str, Path]) -> PreCommitResult:
+    """
+    Run the same governance checks as the pre-commit hook programmatically.
+
+    Executes `thinkstack doctor` and `thinkstack invariant check` in the given
+    project root using the same CLI that the hook uses. Returns a structured
+    result with per-check exit codes and combined output.
+
+    Args:
+        project_root: Directory of the project to check (must contain .GCC).
+
+    Returns:
+        PreCommitResult with `passed=True` only when every check succeeds.
+    """
+    root = Path(project_root)
+
+    # Ensure the current Python environment is used by the thinkstack CLI.
+    env = dict(os.environ)
+    if sys.executable:
+        env["PATH"] = f"{Path(sys.executable).parent}{os.pathsep}{env.get('PATH', '')}"
+
+    checks: list[dict] = []
+    overall_passed = True
+
+    for name, command in [
+        ("thinkstack doctor", ["thinkstack", "doctor"]),
+        ("thinkstack invariant check", ["thinkstack", "invariant", "check"]),
+    ]:
+        exit_code, stdout, stderr = _run_command(command, cwd=root, env=env)
+        passed = exit_code == 0
+        if not passed:
+            overall_passed = False
+
+        checks.append(
+            {
+                "name": name,
+                "passed": passed,
+                "exit_code": exit_code,
+                "output": stdout + stderr,
+            }
+        )
+
+    return PreCommitResult(passed=overall_passed, checks=checks)

thinkstack_core/hooks/runner.py

@@ -0,0 +1,386 @@
+"""
+Claude Code hook runner — `thinkstack hooks run {pre-tool-use,post-tool-use,session-end}`.
+
+Claude Code passes a JSON payload on stdin. The hook must always exit 0
+(approve); non-zero blocks Claude. All errors are swallowed.
+
+Event types written to .GCC/events.log.jsonl:
+  PRE_TOOL_USE   — before every tool call
+  POST_TOOL_USE  — after every tool call
+  SESSION_END    — when Claude Code stops
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# .GCC/ repo discovery
+# ---------------------------------------------------------------------------
+
+
+def _find_repo() -> Optional[object]:
+    """Walk upward from cwd to find an initialised .GCC/ repo."""
+    from thinkstack_core import GCCRepository
+
+    for parent in [Path.cwd()] + list(Path.cwd().parents):
+        r = GCCRepository.at(parent)
+        if r.is_initialized():
+            return r
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Stdin reader
+# ---------------------------------------------------------------------------
+
+
+def _read_stdin_json() -> dict:
+    try:
+        raw = sys.stdin.read()
+        if raw.strip():
+            return json.loads(raw)
+    except Exception:
+        pass
+    return {}
+
+
+# ---------------------------------------------------------------------------
+# Event appenders
+# ---------------------------------------------------------------------------
+
+
+def _append_event(repo, event_type: str, payload: dict) -> None:
+    """Append a raw event to the repo's event log."""
+    try:
+        repo._append_event(event_type, payload)
+    except Exception:
+        # _append_event may not be public on all versions; fall back to
+        # writing directly to events.log.jsonl
+        try:
+            import fcntl
+            import hashlib
+            import time
+
+            log_path = Path(repo.gcc_dir) / "events.log.jsonl"
+            with log_path.open("a", encoding="utf-8") as f:
+                fcntl.flock(f, fcntl.LOCK_EX)
+                try:
+                    prev_hash = "0" * 64
+                    if log_path.exists():
+                        lines = log_path.read_text(encoding="utf-8").strip().splitlines()
+                        if lines:
+                            last = json.loads(lines[-1])
+                            prev_hash = last.get("hash", prev_hash)
+
+                    entry = {
+                        "type": event_type,
+                        "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                        **payload,
+                    }
+                    entry_str = json.dumps(entry, sort_keys=True)
+                    entry["hash"] = hashlib.sha256(
+                        (prev_hash + entry_str).encode()
+                    ).hexdigest()
+
+                    f.write(json.dumps(entry) + "\n")
+                    f.flush()
+                finally:
+                    fcntl.flock(f, fcntl.LOCK_UN)
+        except Exception:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Hook handlers
+# ---------------------------------------------------------------------------
+
+
+def handle_pre_tool_use(payload: dict) -> None:
+    repo = _find_repo()
+    if repo is None:
+        return
+    _append_event(repo, "PRE_TOOL_USE", {
+        "tool_name": payload.get("tool_name", "unknown"),
+        "session_id": payload.get("session_id", ""),
+    })
+
+
+def handle_post_tool_use(payload: dict) -> None:
+    repo = _find_repo()
+    if repo is None:
+        return
+
+    tool_name = payload.get("tool_name", "unknown")
+    tool_input = payload.get("tool_input", {})
+
+    event_payload: dict = {
+        "tool_name": tool_name,
+        "session_id": payload.get("session_id", ""),
+    }
+
+    # For file-writing tools, capture which file was touched
+    if tool_name in ("Write", "Edit", "NotebookEdit"):
+        file_path = tool_input.get("file_path", tool_input.get("notebook_path", ""))
+        if file_path:
+            event_payload["file_path"] = file_path
+
+    # For Bash, capture the command (truncated)
+    if tool_name == "Bash":
+        cmd = tool_input.get("command", "")
+        event_payload["command"] = cmd[:200]
+
+    _append_event(repo, "POST_TOOL_USE", event_payload)
+
+
+def handle_session_end(payload: dict) -> None:
+    repo = _find_repo()
+    if repo is None:
+        return
+    _append_event(repo, "SESSION_END", {
+        "session_id": payload.get("session_id", ""),
+        "stop_hook_active": payload.get("stop_hook_active", False),
+    })
+
+    _run_session_end_sync(repo)
+
+
+def _run_session_end_sync(repo) -> None:
+    """On session exit, run the auto-sync flow if configured.
+
+    1. Commit remaining reasoning (final flush of learnings)
+    2. Push learnings to org store if cloud storage is available
+    3. Log the sync event
+    """
+    try:
+        from thinkstack_core.reasoning_plus.config import load_config
+        config, _ = load_config(repo.gcc_dir)
+        if not getattr(config, "auto_sync_on_stop", True):
+            return
+    except Exception:
+        pass
+
+    try:
+        from thinkstack_core.cloud.team_sync import push_learnings, pull_learnings
+        org_id = _get_org_id(repo)
+        if org_id:
+            push_learnings(org_id, repo.gcc_dir)
+            pull_learnings(org_id, repo.gcc_dir)
+    except Exception:
+        pass
+
+    _append_event(repo, "AUTO_SYNC_ON_STOP", {
+        "learnings_pushed": True,
+        "learnings_pulled": True,
+    })
+
+
+def _get_org_id(repo) -> str | None:
+    """Extract org_id from the GCC repo or environment."""
+    try:
+        return getattr(repo, "org_id", None) or None
+    except Exception:
+        pass
+    import os
+    return os.environ.get("THINKSTACK_ORG_ID")
+
+
+# ---------------------------------------------------------------------------
+# Dispatch
+# ---------------------------------------------------------------------------
+
+_HANDLERS = {
+    "pre-tool-use": handle_pre_tool_use,
+    "post-tool-use": handle_post_tool_use,
+    "session-end": handle_session_end,
+}
+
+
+_CONTEXT_MAX_ENTRIES = 3
+_CONTEXT_MAX_LINES = 40
+
+
+# Selections larger than these budgets (lines AND characters — a single long
+# line must not defeat the line count) are injected as a per-entry summary
+# instead of verbatim, so a reasoning entry can never flood the model
+# context. Small relevant selections keep their full detail.
+_CONTEXT_FULL_LINE_BUDGET = 24
+_CONTEXT_MAX_CHARS = 4000
+_CONTEXT_SUMMARY_BODY_CHARS = 160
+
+_PROMPT_STOPWORDS = frozenset(
+    """
+    the and for was were with that this from are but not you your our can
+    could should would about into over under what when where which who whom
+    why how did does doing done have has had will just like make made use
+    used using them they their there then than some any all out get got new
+    old one two per off via please context
+    """.split()
+)
+
+
+def _keywords(text: str) -> set:
+    """Lowercased alphanumeric tokens (3+ chars) minus stopwords."""
+    import re
+
+    return {
+        t
+        for t in re.findall(r"[a-z0-9][a-z0-9_\-]{2,}", text.lower())
+        if t not in _PROMPT_STOPWORDS
+    }
+
+
+def _handle_user_prompt_submit(payload: dict) -> None:
+    """Print reasoning context for the incoming prompt; stdout becomes model
+    context in Claude Code. Reads log.md directly — no heavy imports.
+
+    Selection is relevance-first: entries are scored by keyword overlap with
+    the prompt text and only matching entries are injected. When the prompt
+    yields no matches (or no prompt text is available), it falls back to the
+    most recent entries. Large selections are compressed to per-entry
+    summaries so injection cost stays bounded.
+    """
+    repo = _find_repo()
+    if repo is None:
+        return
+    try:
+        text = (Path(repo.gcc_dir) / "log.md").read_text(encoding="utf-8")
+    except OSError:
+        return
+    # log.md entries start with "## <header>"; the leading file header has
+    # no "## " prefix. Split on "\n## " to isolate individual entries.
+    blocks = text.split("\n## ")
+    entries = [("## " + b).strip() for b in blocks[1:]] if len(blocks) > 1 else []
+    if not entries:
+        return
+
+    prompt_kws = _keywords(str(payload.get("prompt") or ""))
+    selected: list = []
+    kind = "Recent"
+    if prompt_kws:
+        # Score against entry bodies only: every heading contains
+        # "Commit at <timestamp>", so heading tokens ("commit", the year)
+        # would otherwise mark every entry relevant to date-ish prompts.
+        # Normalize by sqrt(|prompt_kws|) so a verbose prompt does not
+        # drown out a short, targeted one when both match the same entries.
+        _norm = max(1.0, len(prompt_kws) ** 0.5)
+        scored = [
+            (len(prompt_kws & _keywords("\n".join(entry.splitlines()[1:]))) / _norm, idx, entry)
+            for idx, entry in enumerate(entries)
+        ]
+        scored = [s for s in scored if s[0] > 0]
+        if scored:
+            # Highest keyword overlap first; ties broken by recency.
+            scored.sort(key=lambda s: (-s[0], -s[1]))
+            selected = [entry for _, _, entry in scored[:_CONTEXT_MAX_ENTRIES]]
+            kind = "Relevant"
+    if not selected:
+        selected = entries[-_CONTEXT_MAX_ENTRIES:]
+
+    body_lines = [line for entry in selected for line in entry.splitlines()]
+    selection_chars = sum(len(line) for line in body_lines)
+    if (
+        len(body_lines) <= _CONTEXT_FULL_LINE_BUDGET
+        and selection_chars <= _CONTEXT_MAX_CHARS
+    ):
+        lines = [f"[ThinkStack] {kind} recorded reasoning (shared across agents):"]
+        lines.extend(body_lines)
+    else:
+        # Too much to inject verbatim — emit a compact per-entry summary:
+        # the entry heading plus its first body line, both truncated.
+        lines = [f"[ThinkStack] {kind} context summary (shared across agents):"]
+        for entry in selected:
+            entry_lines = entry.splitlines()
+            lines.append(entry_lines[0][:_CONTEXT_SUMMARY_BODY_CHARS])
+            first_body = next(
+                (ln.strip() for ln in entry_lines[1:] if ln.strip()), ""
+            )
+            if first_body:
+                lines.append("  " + first_body[:_CONTEXT_SUMMARY_BODY_CHARS])
+    # Hard cap as the final guarantee, whatever mode produced the lines.
+    print("\n".join(lines[:_CONTEXT_MAX_LINES])[:_CONTEXT_MAX_CHARS])
+
+
+def _handle_open_code_pre_prompt() -> None:
+    """Print a bounded context bundle (main.md + log.md + theta.json + recent
+    commits) so the model sees prior reasoning on a model switch.  Uses the
+    same GCCRepository.context_bundle() path as the MCP thinkstack_context
+    tool, but stays inside the fast hook runner (~0.2s instead of ~1s for
+    the full CLI)."""
+    repo = _find_repo()
+    if repo is None:
+        return
+    try:
+        bundle = repo.context_bundle(k_tokens=2000)
+    except Exception:
+        return
+    artifacts = bundle.get("artifacts", [])
+    if not artifacts:
+        return
+    lines = [f"[ThinkStack] Context bundle (budget=2000 tokens, {len(artifacts)} artifacts):"]
+    for art in artifacts:
+        name = art.get("name", art.get("path", art.get("id", "unknown")))
+        reason = art.get("reason", "")
+        tokens = art.get("tokens", art.get("approx_tokens", "?"))
+        lines.append(f"  - {name} ({tokens} tokens): {reason}")
+    print("\n".join(lines))
+
+
+def run(hook_name: str) -> None:
+    """
+    Entry point called by `thinkstack hooks run <hook_name>`.
+
+    Reads JSON from stdin, dispatches to the right handler, always exits 0.
+    """
+    if os.environ.get("THINKSTACK_DISABLE"):
+        return
+
+    payload = _read_stdin_json()
+
+    if hook_name == "open-code-pre-prompt":
+        try:
+            _handle_open_code_pre_prompt()
+        except Exception:
+            pass
+        return
+
+    if hook_name == "user-prompt-submit":
+        try:
+            _handle_user_prompt_submit(payload)
+        except Exception:
+            pass  # never interfere with Claude Code
+        return
+
+    handler = _HANDLERS.get(hook_name)
+    if handler:
+        try:
+            handler(payload)
+        except Exception:
+            pass  # never interfere with Claude Code
+
+
+# ---------------------------------------------------------------------------
+# Console entry point (fast path — must not import thinkstack_cli)
+# ---------------------------------------------------------------------------
+
+
+def cli(argv: list[str] | None = None) -> int:
+    """Entry point for the `thinkstack-hook` console script.
+
+    Equivalent to `thinkstack hooks run <name>` but skips the full CLI import
+    chain (~0.9s), which matters because IDE hooks run on every tool call.
+    Always returns 0 — a non-zero hook exit blocks the IDE.
+    """
+    args = argv if argv is not None else sys.argv[1:]
+    if not args:
+        return 0
+    try:
+        run(args[0])
+    except Exception:
+        pass
+    return 0

thinkstack_core/identity/__init__.py

@@ -0,0 +1,4 @@
+from .agent import AgentIdentity, AgentRegistry
+from .providers import resolve_agent_identity
+
+__all__ = ["AgentIdentity", "AgentRegistry", "resolve_agent_identity"]

thinkstack_core/identity/agent.py

@@ -0,0 +1,86 @@
+"""
+Sprint 18 (S18) — Agent Identity substrate.
+
+AgentIdentity names a reasoning agent; AgentRegistry persists identities as an
+append-only JSONL file under a configurable directory so any .GCC/ can maintain
+a record of which agents have contributed to the project.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+from pathlib import Path
+from typing import List, Optional
+
+
+@dataclasses.dataclass
+class AgentIdentity:
+    """Named identity for a reasoning agent with scoped visibility."""
+
+    agent_id: str
+    name: str
+    provider: str   # "native" | "bedrock" | "azure" | "anonymous"
+    scope: str      # "branch" | "session" | "org"
+    metadata: dict = dataclasses.field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AgentIdentity":
+        return cls(
+            agent_id=d["agent_id"],
+            name=d["name"],
+            provider=d["provider"],
+            scope=d["scope"],
+            metadata=d.get("metadata", {}),
+        )
+
+
+_REGISTRY_FILE = "agent_registry.jsonl"
+
+
+class AgentRegistry:
+    """Append-only JSONL registry of known agent identities."""
+
+    def __init__(self, registry_dir: Path) -> None:
+        self._dir = registry_dir
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._path = self._dir / _REGISTRY_FILE
+
+    def register(self, identity: AgentIdentity) -> None:
+        existing = self.get(identity.agent_id)
+        if existing is not None:
+            return  # idempotent
+        with self._path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(identity.to_dict()) + "\n")
+
+    def get(self, agent_id: str) -> Optional[AgentIdentity]:
+        if not self._path.exists():
+            return None
+        for line in self._path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                d = json.loads(line)
+                if d.get("agent_id") == agent_id:
+                    return AgentIdentity.from_dict(d)
+            except json.JSONDecodeError:
+                continue
+        return None
+
+    def list_all(self) -> List[AgentIdentity]:
+        if not self._path.exists():
+            return []
+        seen: dict[str, AgentIdentity] = {}
+        for line in self._path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                d = json.loads(line)
+                seen[d["agent_id"]] = AgentIdentity.from_dict(d)
+            except (json.JSONDecodeError, KeyError):
+                continue
+        return list(seen.values())