@heretek-ai/epistemic-swarm 0.4.2 → 0.4.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "High-Integrity Dialectic Research Agent Harness for Claude Code enforcing empirical evidence over parametric hallucination.",
   "author": {
     "name": "Heretek AI",

package/hooks/hooks.json

@@ -15,7 +15,28 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"WebFetch intercepted by epistemic-swarm to enforce content-addressed caching. Use epistemic fetch (python3 ${CLAUDE_PLUGIN_ROOT}/skills/epistemic_search/scripts/fetch.py \\\"<url>\\\") which automatically stores documents in .research/sources/<sha256>.md for mathematical auditability.\"}}'"
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/skills/epistemic_search/scripts/webcache.py\" gate"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "WebFetch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/skills/epistemic_search/scripts/webcache.py\" archive"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/skills/epistemic_search/scripts/webcache.py\" stats"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "IUMBTEMS: I Use My Brain To Express My Self — High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi, OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {

package/plugins/antigravity/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "epistemic-swarm",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "IUMBTEMS Epistemic Swarm: dialectic research, code audit, OSS scout, and lateral brainstorming for AntiGravity.",
   "author": "Heretek AI",
   "license": "Apache-2.0",

package/plugins/gemini/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "IUMBTEMS Epistemic Swarm: dialectic research, code audit, OSS scout, and lateral brainstorming for Gemini CLI.",
   "mcpServers": {
     "brave-search": {

package/runner/tests/test_webcache.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""Tests for the WebFetch cache-through gate (webcache.py + hooks.json)."""
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+WEBCACHE = PROJECT_ROOT / "skills" / "epistemic_search" / "scripts" / "webcache.py"
+
+
+def run_webcache(mode, payload=None, raw=None, cwd=None, env=None):
+    stdin = raw if raw is not None else json.dumps(payload or {})
+    merged = dict(__import__("os").environ)
+    if env:
+        merged.update(env)
+    return subprocess.run(
+        [sys.executable, str(WEBCACHE), mode],
+        input=stdin,
+        capture_output=True,
+        text=True,
+        cwd=str(cwd or PROJECT_ROOT),
+        env=merged,
+    )
+
+
+def seed_source(sources_dir, url, content, cached_at=None):
+    import hashlib
+
+    digest = hashlib.sha256(content.encode("utf-8")).hexdigest()
+    sources_dir.mkdir(parents=True, exist_ok=True)
+    sources_dir.joinpath(f"{digest}.md").write_text(content, encoding="utf-8")
+    sources_dir.joinpath(f"{digest}.json").write_text(
+        json.dumps(
+            {
+                "hash": digest,
+                "url": url,
+                "title": url,
+                "tier": "WEB_DOCUMENT",
+                "cached_at": cached_at
+                or datetime.now(timezone.utc).isoformat(),
+                "byte_size": len(content.encode("utf-8")),
+                "char_count": len(content),
+                "custom_metadata": {},
+            }
+        ),
+        encoding="utf-8",
+    )
+    return digest
+
+
+def hook_input(url, cwd):
+    return {"tool_name": "WebFetch", "tool_input": {"url": url}, "cwd": str(cwd)}
+
+
+class TestCanonicalization(unittest.TestCase):
+    def test_variants_resolve_to_one_entry(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            seed_source(
+                root / ".research" / "sources",
+                "https://example.com/p?a=1&b=2",
+                "hello cached",
+            )
+            for variant in [
+                "https://EXAMPLE.com/p?b=2&a=1#frag",
+                "https://example.com:443/p?a=1&b=2",
+            ]:
+                res = run_webcache("gate", hook_input(variant, root))
+                self.assertEqual(res.returncode, 0)
+                self.assertTrue(res.stdout.strip(), f"expected HIT for {variant}")
+                out = json.loads(res.stdout)
+                self.assertEqual(
+                    out["hookSpecificOutput"]["permissionDecision"], "deny"
+                )
+                self.assertIn("hello cached", out["hookSpecificOutput"]["additionalContext"])
+
+
+class TestGate(unittest.TestCase):
+    def test_miss_allows_silently(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            res = run_webcache(
+                "gate", hook_input("https://example.com/new-page", Path(tmp))
+            )
+            self.assertEqual(res.returncode, 0)
+            self.assertEqual(res.stdout.strip(), "")
+
+    def test_hit_serves_cache(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            digest = seed_source(
+                root / ".research" / "sources",
+                "https://code.claude.com/docs/en/hooks",
+                "# Hooks\n\nHook content here.",
+            )
+            res = run_webcache(
+                "gate", hook_input("https://code.claude.com/docs/en/hooks", root)
+            )
+            self.assertEqual(res.returncode, 0)
+            out = json.loads(res.stdout)
+            hook = out["hookSpecificOutput"]
+            self.assertEqual(hook["hookEventName"], "PreToolUse")
+            self.assertEqual(hook["permissionDecision"], "deny")
+            self.assertIn("Hook content here.", hook["additionalContext"])
+            self.assertIn(f"[VERIFIED: {digest[:16]}]", hook["additionalContext"])
+
+    def test_stale_allows_for_refresh(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            old = (datetime.now(timezone.utc) - timedelta(days=30)).isoformat()
+            seed_source(
+                root / ".research" / "sources",
+                "https://example.com/aging",
+                "old content",
+                cached_at=old,
+            )
+            res = run_webcache("gate", hook_input("https://example.com/aging", root))
+            self.assertEqual(res.returncode, 0)
+            self.assertEqual(res.stdout.strip(), "")
+
+    def test_malformed_input_fails_open(self):
+        for raw in ["", "not json{{{", '{"tool_input": {}}']:
+            res = run_webcache("gate", raw=raw)
+            self.assertEqual(res.returncode, 0, f"raw={raw!r} stderr={res.stderr}")
+            self.assertEqual(res.stdout.strip(), "")
+
+
+class TestArchive(unittest.TestCase):
+    def test_archive_writes_matching_pair(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            payload = {
+                "tool_name": "WebFetch",
+                "tool_input": {"url": "https://example.com/live"},
+                "tool_response": "# Live\n\nFresh body text.",
+                "cwd": str(root),
+            }
+            res = run_webcache("archive", payload)
+            self.assertEqual(res.returncode, 0, res.stderr)
+            self.assertEqual(res.stdout.strip(), "")
+            sources = root / ".research" / "sources"
+            md_files = list(sources.glob("*.md"))
+            self.assertEqual(len(md_files), 1)
+            import hashlib
+
+            digest = hashlib.sha256("# Live\n\nFresh body text.".encode("utf-8")).hexdigest()
+            self.assertEqual(md_files[0].name, f"{digest}.md")
+            meta = json.loads(sources.joinpath(f"{digest}.json").read_text(encoding="utf-8"))
+            self.assertEqual(meta["url"], "https://example.com/live")
+            self.assertEqual(meta["hash"], digest)
+            # Idempotent: archiving again writes the same pair.
+            res2 = run_webcache("archive", payload)
+            self.assertEqual(res2.returncode, 0)
+            self.assertEqual(len(list(sources.glob("*.md"))), 1)
+
+    def test_archive_round_trip_gate_hit(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            url = "https://example.com/roundtrip"
+            run_webcache(
+                "archive",
+                {
+                    "tool_input": {"url": url},
+                    "response": "Roundtrip body.",
+                    "cwd": str(root),
+                },
+            )
+            res = run_webcache("gate", hook_input(url, root))
+            out = json.loads(res.stdout)
+            self.assertEqual(out["hookSpecificOutput"]["permissionDecision"], "deny")
+            self.assertIn("Roundtrip body.", out["hookSpecificOutput"]["additionalContext"])
+
+
+class TestStats(unittest.TestCase):
+    def test_empty_is_silent(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            res = run_webcache("stats", {"cwd": str(Path(tmp))})
+            self.assertEqual(res.returncode, 0)
+            self.assertEqual(res.stdout.strip(), "")
+
+    def test_populated_reports_count(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            seed_source(root / ".research" / "sources", "https://a.example/1", "one")
+            seed_source(root / ".research" / "sources", "https://b.example/2", "two")
+            res = run_webcache("stats", {"cwd": str(root)})
+            out = json.loads(res.stdout)
+            self.assertIn("2 page(s) cached", out["hookSpecificOutput"]["additionalContext"])
+
+
+class TestHooksManifest(unittest.TestCase):
+    def test_hooks_json_wires_cache_through(self):
+        hooks = json.loads(
+            (PROJECT_ROOT / "hooks" / "hooks.json").read_text(encoding="utf-8")
+        )
+        pre = hooks["hooks"]["PreToolUse"]
+        webfetch_pre = [m for m in pre if m.get("matcher") == "WebFetch"]
+        self.assertEqual(len(webfetch_pre), 1)
+        pre_cmd = webfetch_pre[0]["hooks"][0]["command"]
+        self.assertIn("webcache.py", pre_cmd)
+        self.assertTrue(pre_cmd.rstrip().endswith("gate"))
+        post = hooks["hooks"]["PostToolUse"]
+        webfetch_post = [m for m in post if m.get("matcher") == "WebFetch"]
+        self.assertEqual(len(webfetch_post), 1)
+        post_cmd = webfetch_post[0]["hooks"][0]["command"]
+        self.assertIn("webcache.py", post_cmd)
+        self.assertTrue(post_cmd.rstrip().endswith("archive"))
+        session_start = hooks["hooks"].get("SessionStart", [])
+        self.assertTrue(
+            any("webcache.py" in h.get("command", "") and h.get("command", "").rstrip().endswith("stats") for m in session_start for h in m.get("hooks", []))
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/epistemic_search/scripts/webcache.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""Content-addressed WebFetch cache-through gate for Claude Code hooks.
+
+Replaces the blanket PreToolUse deny with the cache-through pattern
+(proven by theYahia/claude-webcache):
+
+  gate    (PreToolUse WebFetch): serve `.research/sources/<sha256>.md` hits
+          via deny + additionalContext (no network); allow misses/stale.
+  archive (PostToolUse WebFetch): store the live response as md + json
+          sidecar, same layout as SourceHasher (content-hash filename).
+  stats   (SessionStart): one-line cache summary via additionalContext.
+
+Fail-open everywhere: any error exits 0 with no output (allow), logging to
+stderr (visible with --debug). This is a citation-integrity control, not a
+security boundary.
+
+URL canonicalization (borrowed from webcache): lowercase host, strip default
+ports and fragments, sort query parameters — so formatting variance does not
+cause silent misses.
+
+TTL: sidecar `cached_at`; default 7 days (IUMBTEMS_FETCH_TTL_DAYS), 30 days
+for stable documentation domains. Inline cap for served hits: 12000 chars
+(IUMBTEMS_FETCH_MAX_INLINE), remainder via file pointer.
+"""
+
+import hashlib
+import json
+import os
+import sys
+import urllib.parse
+from datetime import datetime, timezone
+from pathlib import Path
+
+DEFAULT_TTL_DAYS = 7
+DOC_DOMAIN_TTL_DAYS = 30
+DOC_DOMAINS = (
+    "code.claude.com",
+    "docs.anthropic.com",
+    "platform.claude.com",
+    "docs.python.org",
+    "developer.mozilla.org",
+)
+DEFAULT_MAX_INLINE = 12000
+
+
+def log(msg):
+    sys.stderr.write(f"[webcache] {msg}\n")
+
+
+def canonical_url(url):
+    try:
+        p = urllib.parse.urlsplit(url.strip())
+        host = (p.hostname or "").lower()
+        if not host:
+            return None
+        port = p.port
+        if (p.scheme == "http" and port == 80) or (p.scheme == "https" and port == 443):
+            port = None
+        netloc = f"{host}:{port}" if port else host
+        query = urllib.parse.urlencode(
+            sorted(urllib.parse.parse_qsl(p.query, keep_blank_values=True))
+        )
+        return urllib.parse.urlunsplit((p.scheme or "https", netloc, p.path or "/", query, ""))
+    except Exception:
+        return None
+
+
+def domain_of(url):
+    try:
+        return (urllib.parse.urlsplit(url).hostname or "").lower()
+    except Exception:
+        return ""
+
+
+def ttl_days(url):
+    try:
+        override = int(os.environ.get("IUMBTEMS_FETCH_TTL_DAYS", ""))
+        return max(override, 0)
+    except ValueError:
+        pass
+    domain = domain_of(url)
+    if any(domain == d or domain.endswith("." + d) for d in DOC_DOMAINS):
+        return DOC_DOMAIN_TTL_DAYS
+    return DEFAULT_TTL_DAYS
+
+
+def max_inline():
+    try:
+        return max(int(os.environ.get("IUMBTEMS_FETCH_MAX_INLINE", "")), 1000)
+    except ValueError:
+        return DEFAULT_MAX_INLINE
+
+
+def research_dir(stdin_data):
+    base = stdin_data.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+    return Path(base) / ".research"
+
+
+def find_cached(sources_dir, url):
+    """Scan json sidecars for a matching canonical URL. Returns (md_path, meta) or None."""
+    canon = canonical_url(url)
+    if not canon or not sources_dir.is_dir():
+        return None
+    for sidecar in sources_dir.glob("*.json"):
+        try:
+            meta = json.loads(sidecar.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        if not isinstance(meta, dict):
+            continue
+        if canonical_url(str(meta.get("url", ""))) == canon:
+            md_path = sidecar.with_suffix(".md")
+            if md_path.exists():
+                return md_path, meta
+    return None
+
+
+def is_fresh(meta, url):
+    try:
+        cached_at = datetime.fromisoformat(str(meta.get("cached_at", "")))
+        if cached_at.tzinfo is None:
+            cached_at = cached_at.replace(tzinfo=timezone.utc)
+        age_days = (datetime.now(timezone.utc) - cached_at).total_seconds() / 86400
+        return age_days <= ttl_days(url)
+    except (ValueError, TypeError):
+        return False
+
+
+def cmd_gate(stdin_data):
+    """PreToolUse: serve fresh hits, allow everything else (fail-open)."""
+    tool_input = stdin_data.get("tool_input") or {}
+    url = tool_input.get("url", "")
+    if not url:
+        return None  # allow
+    sources_dir = research_dir(stdin_data) / "sources"
+    try:
+        found = find_cached(sources_dir, url)
+    except Exception as e:
+        log(f"cache lookup failed for {domain_of(url)}: {e}")
+        return None  # allow
+    if not found:
+        return None  # miss -> allow, PostToolUse archives
+    md_path, meta = found
+    if not is_fresh(meta, url):
+        log(f"stale entry for {domain_of(url)} ({meta.get('cached_at')}); allowing live fetch")
+        return None  # stale -> allow, PostToolUse refreshes
+    try:
+        content = md_path.read_text(encoding="utf-8")
+    except OSError as e:
+        log(f"cache read failed: {e}")
+        return None  # allow
+    cap = max_inline()
+    served = content if len(content) <= cap else content[:cap] + "\n\n[... truncated]"
+    body = (
+        f"<!-- EPISTEMIC_CACHE_HIT: {md_path.name} -->\n"
+        f"**Source URL:** {url}\n"
+        f"**Cached:** {meta.get('cached_at')}  **Content SHA-256:** `{meta.get('hash')}`\n"
+        f"**Verification Tag:** `[VERIFIED: {str(meta.get('hash', ''))[:16]}]`\n\n"
+        f"{served}\n"
+    )
+    if len(content) > cap:
+        body += f"\n(Full cached text in {md_path}; cite the file for passages beyond the excerpt.)\n"
+    log(f"cache HIT for {domain_of(url)} ({len(content)} chars, {md_path.name})")
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": (
+                "Served from the epistemic content cache (.research/sources); "
+                "no network fetch needed. Cite the cached file."
+            ),
+            "additionalContext": body,
+        }
+    }
+
+
+def extract_response_text(stdin_data):
+    """Defensively locate the tool response text across field-name variants."""
+    for key in ("tool_response", "response", "tool_result", "result", "output"):
+        val = stdin_data.get(key)
+        if isinstance(val, str) and val.strip():
+            return val
+        if isinstance(val, dict):
+            for sub in ("text", "content", "output"):
+                inner = val.get(sub)
+                if isinstance(inner, str) and inner.strip():
+                    return inner
+                if isinstance(inner, list):
+                    parts = [
+                        p.get("text", "") for p in inner
+                        if isinstance(p, dict) and isinstance(p.get("text"), str)
+                    ]
+                    if parts:
+                        return "\n".join(parts)
+    return ""
+
+
+def extract_url(stdin_data):
+    tool_input = stdin_data.get("tool_input") or stdin_data.get("input") or {}
+    if isinstance(tool_input, dict):
+        url = tool_input.get("url", "")
+        if url:
+            return url
+    # Fall back to a URL already recorded in a response envelope.
+    for key in ("tool_response", "response", "tool_result"):
+        val = stdin_data.get(key)
+        if isinstance(val, dict) and val.get("url"):
+            return val["url"]
+    return ""
+
+
+def cmd_archive(stdin_data):
+    """PostToolUse: store the live response as md + json sidecar."""
+    url = extract_url(stdin_data)
+    text = extract_response_text(stdin_data)
+    if not url or not text:
+        return None
+    try:
+        sources_dir = research_dir(stdin_data) / "sources"
+        sources_dir.mkdir(parents=True, exist_ok=True)
+        digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
+        sources_dir.joinpath(f"{digest}.md").write_text(text, encoding="utf-8")
+        sources_dir.joinpath(f"{digest}.json").write_text(
+            json.dumps(
+                {
+                    "hash": digest,
+                    "url": url,
+                    "title": url,
+                    "tier": "WEB_DOCUMENT",
+                    "cached_at": datetime.now(timezone.utc).isoformat(),
+                    "byte_size": len(text.encode("utf-8")),
+                    "char_count": len(text),
+                    "custom_metadata": {"via": "webfetch-hook"},
+                },
+                indent=2,
+            ),
+            encoding="utf-8",
+        )
+        log(f"archived {domain_of(url)} -> {digest[:16]} ({len(text)} chars)")
+    except Exception as e:
+        log(f"archive failed for {domain_of(url)}: {e}")
+    return None
+
+
+def cmd_stats(stdin_data):
+    """SessionStart: one-line cache summary; silent when empty."""
+    try:
+        sources_dir = research_dir(stdin_data) / "sources"
+        if not sources_dir.is_dir():
+            return None
+        md_files = list(sources_dir.glob("*.md"))
+        if not md_files:
+            return None
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": (
+                    f"epistemic-cache: {len(md_files)} page(s) cached in "
+                    f".research/sources — WebFetch hits are served from cache."
+                ),
+            }
+        }
+    except Exception as e:
+        log(f"stats failed: {e}")
+        return None
+
+
+def main(argv):
+    mode = argv[1] if len(argv) > 1 else "gate"
+    try:
+        raw = sys.stdin.read() if not sys.stdin.isatty() else ""
+        stdin_data = json.loads(raw) if raw.strip() else {}
+        if not isinstance(stdin_data, dict):
+            stdin_data = {}
+    except (ValueError, OSError):
+        stdin_data = {}
+    handler = {"gate": cmd_gate, "archive": cmd_archive, "stats": cmd_stats}.get(mode)
+    if handler is None:
+        log(f"unknown mode: {mode}")
+        return 0
+    try:
+        out = handler(stdin_data)
+    except Exception as e:
+        log(f"{mode} failed: {e}")
+        return 0  # fail-open
+    if out:
+        sys.stdout.write(json.dumps(out))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))