@heretek-ai/epistemic-swarm 0.1.0 → 0.2.2

package/config/mcp_launcher.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""
+Intelligent MCP Server Launcher & Epistemic Fallback Proxy for IUMBTEMS.
+Safely detects API keys and endpoints:
+- If keys are present (via env or userConfig): launches the official MCP server.
+- If keys are absent: smoothly provides a zero-key JSON-RPC fallback MCP server
+  backed by DuckDuckGo Lite search and content-addressed SHA256 caching.
+Prevents startup crashes and missing environment variable errors in Claude Code.
+"""
+
+import sys
+import os
+import json
+import subprocess
+import shutil
+from typing import Dict, Any, List
+
+# Add parent dir to path for imports
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+PROJECT_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
+if PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, PROJECT_ROOT)
+
+def get_config_val(key: str, default: str = "") -> str:
+    """Retrieve config from env, userConfig, or defaults."""
+    env_val = os.environ.get(key)
+    if env_val:
+        return env_val
+    # Also check user_config format
+    user_cfg_val = os.environ.get(f"CLAUDE_PLUGIN_OPTION_{key.upper()}")
+    if user_cfg_val:
+        return user_cfg_val
+    return default
+
+def run_zero_key_mcp_server(service: str):
+    """Run lightweight JSON-RPC MCP server handling search and fetch without API keys."""
+    from skills.epistemic_search.scripts.search import search_duckduckgo
+    from skills.epistemic_search.scripts.fetch import fetch_and_cache
+
+    def send_response(response: Dict[str, Any]):
+        out = json.dumps(response)
+        sys.stdout.write(f"Content-Length: {len(out)}\r\n\r\n{out}")
+        sys.stdout.flush()
+
+    def send_json(response: Dict[str, Any]):
+        # Direct newline JSON-RPC for stdio transports
+        sys.stdout.write(json.dumps(response) + "\n")
+        sys.stdout.flush()
+
+    while True:
+        try:
+            line = sys.stdin.readline()
+            if not line:
+                break
+            line = line.strip()
+            if not line:
+                continue
+
+            # Check if line is Content-Length header or raw JSON
+            if line.startswith("Content-Length:"):
+                length = int(line.split(":")[1].strip())
+                # Read blank line
+                sys.stdin.readline()
+                body = sys.stdin.read(length)
+                req = json.loads(body)
+                use_headers = True
+            else:
+                req = json.loads(line)
+                use_headers = False
+
+            req_id = req.get("id")
+            method = req.get("method")
+            params = req.get("params", {})
+
+            if method == "initialize":
+                res = {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": {
+                        "protocolVersion": "2024-11-05",
+                        "serverInfo": {
+                            "name": f"epistemic-{service}-fallback",
+                            "version": "0.2.1"
+                        },
+                        "capabilities": {
+                            "tools": {}
+                        }
+                    }
+                }
+            elif method == "tools/list":
+                if service == "brave-search":
+                    tools = [
+                        {
+                            "name": "brave_web_search",
+                            "description": "Web search with DuckDuckGo fallback (zero API key required). Returns verifiable search results with titles, URLs, and snippets.",
+                            "inputSchema": {
+                                "type": "object",
+                                "properties": {
+                                    "query": {"type": "string", "description": "The search query terms"},
+                                    "count": {"type": "number", "description": "Number of results (1-20)", "default": 10}
+                                },
+                                "required": ["query"]
+                            }
+                        }
+                    ]
+                elif service == "firecrawl":
+                    tools = [
+                        {
+                            "name": "firecrawl_scrape",
+                            "description": "Scrape and extract clean markdown with automatic content-addressed SHA-256 caching into .research/sources/.",
+                            "inputSchema": {
+                                "type": "object",
+                                "properties": {
+                                    "url": {"type": "string", "description": "URL to scrape and cache"}
+                                },
+                                "required": ["url"]
+                            }
+                        }
+                    ]
+                else:
+                    tools = []
+
+                res = {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": {"tools": tools}
+                }
+            elif method == "tools/call":
+                tool_name = params.get("name")
+                args = params.get("arguments", {})
+
+                if tool_name in ("brave_web_search", "search"):
+                    q = args.get("query", "")
+                    count = args.get("count", 10)
+                    results = search_duckduckgo(query=q, max_results=count)
+                    text_out = json.dumps(results, indent=2)
+                    res = {
+                        "jsonrpc": "2.0",
+                        "id": req_id,
+                        "result": {
+                            "content": [{"type": "text", "text": text_out}]
+                        }
+                    }
+                elif tool_name in ("firecrawl_scrape", "scrape", "fetch"):
+                    target_url = args.get("url", "")
+                    content = fetch_and_cache(url=target_url)
+                    res = {
+                        "jsonrpc": "2.0",
+                        "id": req_id,
+                        "result": {
+                            "content": [{"type": "text", "text": content}]
+                        }
+                    }
+                else:
+                    res = {
+                        "jsonrpc": "2.0",
+                        "id": req_id,
+                        "error": {"code": -32601, "message": f"Tool {tool_name} not found"}
+                    }
+            elif method == "notifications/initialized":
+                continue
+            else:
+                res = {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "error": {"code": -32601, "message": f"Method {method} not handled"}
+                }
+
+            if use_headers:
+                send_response(res)
+            else:
+                send_json(res)
+
+        except Exception as e:
+            sys.stderr.write(f"[mcp-launcher] Error handling request: {e}\n")
+            break
+
+def main():
+    service = sys.argv[1] if len(sys.argv) > 1 else "brave-search"
+    npx_bin = shutil.which("npx")
+
+    if service == "brave-search":
+        api_key = get_config_val("BRAVE_SEARCH_API_KEY")
+        if api_key and npx_bin:
+            os.environ["BRAVE_SEARCH_API_KEY"] = api_key
+            os.execvp(npx_bin, [npx_bin, "-y", "@modelcontextprotocol/server-brave-search"])
+        else:
+            # Fall back to zero-key search proxy
+            run_zero_key_mcp_server("brave-search")
+
+    elif service == "firecrawl":
+        api_key = get_config_val("FIRECRAWL_API_KEY")
+        api_url = get_config_val("FIRECRAWL_API_URL", "https://api.firecrawl.dev")
+        if api_key and npx_bin:
+            os.environ["FIRECRAWL_API_KEY"] = api_key
+            os.environ["FIRECRAWL_API_URL"] = api_url
+            os.execvp(npx_bin, [npx_bin, "-y", "firecrawl-mcp"])
+        else:
+            # Fall back to zero-key readability fetcher + SHA-256 hasher
+            run_zero_key_mcp_server("firecrawl")
+
+    elif service == "searxng":
+        searxng_url = get_config_val("SEARXNG_URL", "http://localhost:8080")
+        searxng_script = os.path.join(SCRIPT_DIR, "searxng_mcp.py")
+        if os.path.exists(searxng_script):
+            os.environ["SEARXNG_URL"] = searxng_url
+            os.execvp("python3", ["python3", searxng_script])
+        else:
+            run_zero_key_mcp_server("searxng")
+    else:
+        sys.stderr.write(f"Unknown service: {service}\n")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/config/opencode-snippet.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "@heretek-ai/epistemic-swarm"
+  ],
+  "agent": {
+    "alpha-thesis": {
+      "description": "IUMBTEMS Proponent Agent: Gathers corroborating primary sources, benchmark results, and empirical proofs.",
+      "tools": {
+        "bash": true,
+        "read": true,
+        "write": true,
+        "grep": true,
+        "glob": true,
+        "task": true,
+        "iumbtems_verify_quote": true
+      }
+    },
+    "beta-redteam": {
+      "description": "IUMBTEMS Adversary Agent: Active falsification, red-teaming, hunting for counter-benchmarks, and edge-case failure modes.",
+      "tools": {
+        "bash": true,
+        "read": true,
+        "write": true,
+        "grep": true,
+        "glob": true,
+        "task": true,
+        "iumbtems_verify_quote": true
+      }
+    },
+    "epistemic-auditor": {
+      "description": "IUMBTEMS Synthesizer & Auditor: Verifies verbatim source quotes, downgrades unverified claims, and calculates divergence.",
+      "tools": {
+        "read": true,
+        "write": true,
+        "grep": true,
+        "glob": true,
+        "iumbtems_verify_quote": true
+      }
+    }
+  },
+  "skills": {
+    "paths": [
+      "./skills/grilling",
+      "./skills/research-cache"
+    ]
+  }
+}

package/extensions/pi/index.js

@@ -0,0 +1,90 @@
+/**
+ * IUMBTEMS: I Use My Brain To Express My Self
+ * Native Extension for Pi (pi.dev)
+ * 
+ * Exposes /grill and /swarm slash commands and epistemic verification tools in Pi.
+ */
+
+import { spawnSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PKG_ROOT = path.resolve(__dirname, '../..');
+
+export default function initPiExtension(pi) {
+  // Check if Pi extension API is available
+  if (!pi) return;
+
+  // 1. Register /swarm slash command
+  if (typeof pi.registerCommand === 'function') {
+    pi.registerCommand('swarm', {
+      description: 'Run IUMBTEMS dialectic research swarm on an objective',
+      usage: '/swarm <objective>',
+      handler: async (args, ctx) => {
+        const objective = args.trim();
+        if (!objective) {
+          ctx.output?.('⚠️ Please provide a research objective. Example: /swarm "ZK prover latency bounds"');
+          return;
+        }
+
+        ctx.output?.(`🌟 [IUMBTEMS] Dispatching Dialectic Swarm: "${objective}"...`);
+        const runnerPath = path.join(PKG_ROOT, 'runner/research_swarm.py');
+        const res = spawnSync('python3', [runnerPath, '--objective', objective], {
+          encoding: 'utf-8',
+          cwd: ctx.cwd || process.cwd(),
+          env: { ...process.env, PYTHONPATH: PKG_ROOT }
+        });
+
+        if (res.status === 0) {
+          ctx.output?.(res.stdout);
+          ctx.output?.('\n✅ Research complete! Summary written to .research/final_synthesis.md');
+        } else {
+          ctx.output?.(`❌ Swarm failed:\n${res.stderr || res.stdout}`);
+        }
+      }
+    });
+
+    // 2. Register /grill slash command
+    pi.registerCommand('grill', {
+      description: 'Launch Socratic grilling and decision tree frontier exploration',
+      usage: '/grill [--objective <text>]',
+      handler: async (args, ctx) => {
+        ctx.output?.('🧠 [IUMBTEMS] Launching Socratic Grilling decision tree...');
+        const treePath = path.join(PKG_ROOT, 'skills/grilling/socratic_tree.py');
+        const forwardArgs = args.trim() ? ['--objective', args.trim()] : ['--show-frontier'];
+        const res = spawnSync('python3', [treePath, ...forwardArgs], {
+          encoding: 'utf-8',
+          cwd: ctx.cwd || process.cwd()
+        });
+        ctx.output?.(res.stdout || res.stderr);
+      }
+    });
+  }
+
+  // 3. Register tool for epistemic quote verification
+  if (typeof pi.registerTool === 'function') {
+    pi.registerTool({
+      name: 'iumbtems_verify_quote',
+      description: 'Verify that an empirical claim quote matches verbatim text in the source cache',
+      parameters: {
+        type: 'object',
+        properties: {
+          hash: { type: 'string', description: 'SHA-256 hash of cached source' },
+          quote: { type: 'string', description: 'Verbatim quote string to verify' }
+        },
+        required: ['hash', 'quote']
+      },
+      execute: async ({ hash, quote }) => {
+        const hasherPath = path.join(PKG_ROOT, 'skills/research-cache/hasher.py');
+        const res = spawnSync('python3', [hasherPath, 'verify', '--hash', hash, '--quote', quote], {
+          encoding: 'utf-8'
+        });
+        return {
+          content: [{ type: 'text', text: res.stdout || res.stderr }]
+        };
+      }
+    });
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "WebSearch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"WebSearch intercepted by epistemic-swarm to enforce verified citation integrity. Use epistemic search (python3 ${CLAUDE_PLUGIN_ROOT}/skills/epistemic_search/scripts/search.py \\\"<query>\\\") instead.\"}}'"
+          }
+        ]
+      },
+      {
+        "matcher": "WebFetch",
+        "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.\"}}'"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.1.0",
-  "description": "Epistemic Swarm: High-Integrity Dialectic Research Agent Harness for Claude Code",
+  "version": "0.2.2",
+  "description": "IUMBTEMS: I Use My Brain To Express My Self — High-Integrity Dialectic Research Agent Harness for Claude Code, Pi (pi.dev), and OpenCode V2",
   "main": "bin/cli.js",
   "bin": {
-    "epistemic-swarm": "bin/cli.js",
-    "iumbtems": "bin/cli.js"
+    "iumbtems": "bin/cli.js",
+    "epistemic-swarm": "bin/cli.js"
+  },
+  "exports": {
+    ".": "./bin/cli.js",
+    "./opencode": "./plugins/opencode/index.js",
+    "./server": "./plugins/opencode/index.js",
+    "./pi": "./extensions/pi/index.js"
   },
   "publishConfig": {
     "access": "public"
@@ -19,26 +25,66 @@
   },
   "homepage": "https://github.com/Heretek-AI/IUMBTEMS#readme",
   "keywords": [
+    "iumbtems",
+    "i-use-my-brain-to-express-my-self",
+    "pi-package",
+    "opencode",
+    "opencode-plugin",
     "claude-code",
     "ai-agents",
+    "autonomous-agents",
+    "multi-agent-systems",
     "dialectic-swarm",
+    "dialectic",
     "epistemic-integrity",
     "research-harness",
+    "research-agent",
     "mcp",
+    "model-context-protocol",
+    "mcp-servers",
     "deep-research",
-    "socratic-grilling"
+    "socratic-grilling",
+    "socratic-questioning",
+    "fact-checking",
+    "red-teaming",
+    "citation-validation",
+    "hallucination-prevention",
+    "swarm-intelligence",
+    "code-audit",
+    "oss-scout",
+    "clean-room-engineering"
   ],
+  "pi": {
+    "extensions": [
+      "./extensions/pi/index.js"
+    ],
+    "skills": [
+      "./skills/grilling",
+      "./skills/research_cache",
+      "./skills/epistemic_search",
+      "./skills/swarm_config",
+      "./skills/code_audit",
+      "./skills/oss_scout"
+    ],
+    "prompts": [
+      "./prompts/*.md"
+    ]
+  },
   "author": "Heretek AI",
   "license": "Apache-2.0",
   "files": [
     "bin",
     "prompts",
     "skills",
+    "hooks",
     "config",
     "runner",
+    "extensions",
+    "plugins",
     ".claude-plugin",
     "install.sh",
     "README.md",
+    "MARKETPLACE.md",
     "LICENSE"
   ],
   "engines": {
@@ -46,6 +92,7 @@
   },
   "scripts": {
     "test": "python3 -m unittest discover -s runner/tests",
+    "validate:claude": "claude plugin validate --strict .claude-plugin/marketplace.json && claude plugin validate --strict .",
     "prepack": "python3 -m unittest discover -s runner/tests",
     "install-local": "bash install.sh"
   }

package/plugins/opencode/index.js

@@ -0,0 +1,149 @@
+/**
+ * IUMBTEMS: I Use My Brain To Express My Self
+ * Native Plugin for OpenCode V2 (opencode.ai)
+ * 
+ * Exposes dialectic swarm research tools, Socratic decision frontier calculation,
+ * and content-addressed quote verification directly into OpenCode V2 agents.
+ */
+
+import { spawnSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PKG_ROOT = path.resolve(__dirname, '../..');
+
+export function createOpenCodePlugin(context = {}) {
+  return {
+    id: "heretek.iumbtems.epistemic-swarm",
+    name: "IUMBTEMS Epistemic Swarm",
+    version: "0.1.0",
+    description: "I Use My Brain To Express My Self: Dialectic research swarm enforcing empirical verification",
+
+    server: (toolContext) => [
+      {
+        name: "iumbtems_swarm_research",
+        description: "Execute an autonomous dialectic research swarm on an objective using Agent Alpha (Thesis) and Agent Beta (Red Team).",
+        input: {
+          type: "object",
+          properties: {
+            objective: {
+              type: "string",
+              description: "The research question or hypothesis to investigate"
+            },
+            mock_mode: {
+              type: "boolean",
+              description: "Run in mock/dry-run mode without external API charges",
+              default: false
+            }
+          },
+          required: ["objective"]
+        },
+        options: { codemode: false },
+        execute: async (args) => {
+          const runnerPath = path.join(PKG_ROOT, "runner/research_swarm.py");
+          const cmdArgs = [runnerPath, "--objective", args.objective];
+          if (args.mock_mode) {
+            cmdArgs.push("--mock-claude");
+          }
+
+          const res = spawnSync("python3", cmdArgs, {
+            encoding: "utf-8",
+            cwd: toolContext?.cwd || process.cwd(),
+            env: { ...process.env, PYTHONPATH: PKG_ROOT }
+          });
+
+          return {
+            content: res.stdout || res.stderr,
+            status: res.status === 0 ? "success" : "error"
+          };
+        }
+      },
+
+      {
+        name: "iumbtems_verify_quote",
+        description: "Cryptographically verify whether a cited quote matches verbatim text inside the content-addressed source cache.",
+        input: {
+          type: "object",
+          properties: {
+            hash: {
+              type: "string",
+              description: "SHA-256 hash or prefix of the cached source"
+            },
+            quote: {
+              type: "string",
+              description: "The verbatim excerpt to verify"
+            }
+          },
+          required: ["hash", "quote"]
+        },
+        options: { codemode: false },
+        execute: async (args) => {
+          const hasherPath = path.join(PKG_ROOT, "skills/research-cache/hasher.py");
+          const res = spawnSync("python3", [hasherPath, "verify", "--hash", args.hash, "--quote", args.quote], {
+            encoding: "utf-8",
+            cwd: toolContext?.cwd || process.cwd()
+          });
+
+          return {
+            content: res.stdout || res.stderr,
+            status: res.status === 0 ? "verified" : "failed"
+          };
+        }
+      },
+
+      {
+        name: "iumbtems_socratic_frontier",
+        description: "Inspect or advance the Socratic grilling decision frontier for research framing.",
+        input: {
+          type: "object",
+          properties: {
+            objective: {
+              type: "string",
+              description: "Research objective to inspect"
+            },
+            settle_node: {
+              type: "string",
+              description: "Optional node ID to settle with an answer"
+            },
+            settle_answer: {
+              type: "string",
+              description: "Answer for the settled node"
+            }
+          }
+        },
+        options: { codemode: false },
+        execute: async (args) => {
+          const treePath = path.join(PKG_ROOT, "skills/grilling/socratic_tree.py");
+          const cmdArgs = [treePath];
+
+          if (args.settle_node && args.settle_answer) {
+            cmdArgs.push("--settle", args.settle_node, args.settle_answer);
+          } else if (args.objective) {
+            cmdArgs.push("--objective", args.objective, "--show-frontier");
+          } else {
+            cmdArgs.push("--show-frontier");
+          }
+
+          const res = spawnSync("python3", cmdArgs, {
+            encoding: "utf-8",
+            cwd: toolContext?.cwd || process.cwd()
+          });
+
+          return {
+            content: res.stdout || res.stderr
+          };
+        }
+      }
+    ],
+
+    setup: async (appContext) => {
+      // OpenCode V2 lifecycle hook
+      return { initialized: true, platform: "opencode-v2" };
+    }
+  };
+}
+
+const defaultPlugin = createOpenCodePlugin();
+export default defaultPlugin;

package/plugins/research-cache/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "research-cache",
+  "version": "0.2.0",
+  "description": "Content-addressed SHA256 Markdown source hashing and verbatim quote verification engine.",
+  "author": {
+    "name": "Heretek AI",
+    "email": "dev@heretek.ai"
+  },
+  "license": "Apache-2.0",
+  "repository": "https://github.com/Heretek-AI/IUMBTEMS",
+  "homepage": "https://github.com/Heretek-AI/IUMBTEMS#readme",
+  "skills": [
+    "./skills/research_cache"
+  ]
+}

package/plugins/socratic-grilling/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "socratic-grilling",
+  "version": "0.2.0",
+  "description": "Matt Pocock-style Socratic interrogation, premise inversion, and lateral exploration skill for Claude Code.",
+  "author": {
+    "name": "Heretek AI",
+    "email": "dev@heretek.ai"
+  },
+  "license": "Apache-2.0",
+  "repository": "https://github.com/Heretek-AI/IUMBTEMS",
+  "homepage": "https://github.com/Heretek-AI/IUMBTEMS#readme",
+  "skills": [
+    "./skills/grilling"
+  ]
+}