@heretek-ai/epistemic-swarm 0.7.15 → 0.7.17

package/.claude-plugin/plugin.json

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

package/README.md

@@ -316,6 +316,26 @@ Every factual claim carries an explicit evidentiary tag:
 3. **Academic Tier**: Semantic Scholar / arXiv MCPs for DOI citation resolution.
 4. **Caching Tier**: Content-addressed SHA-256 storage (`skills/research_cache/hasher.py`).
 
+### Free-first provider ladder & cost safety
+
+OpenCode V2 hosts a plugin-registered **search provider** (`iumbtems-cached`) that resolves its upstream free-first and never overrides a deliberate `websearch.provider` or a provider you `/connect`ed. ("Cached" describes the evidence pipeline — `hasher.py` content-addresses full pages fetched via `webfetch` — not in-execute memoisation.)
+
+1. **`/connect`-ed provider** (integration store) — **metered**, credential lives in the host store.
+2. **BYO key** (`exa`/`firecrawl`/`parallel`/`tavily`/`tinyfish` via `EXA_API_KEY`/`FIRECRAWL_API_KEY`/`PARALLEL_API_KEY`/`TAVILY_API_KEY`/`TINYFISH_API_KEY`) — **metered** (vendor-billed).
+3. **Self-hosted SearXNG** (`SEARXNG_URL`) — free; availability requires the URL.
+4. **DuckDuckGo Lite** — free, zero-key, routed through `skills/epistemic_search/scripts/search.py` (anti-bot detection + telemetry).
+5. **Console** (hosted, `$0.01`/successful search) — **metered, never implicit**.
+
+Provider `execute()` returns **hits only** (`title`/`url`/`content`). Full page content must be fetched explicitly with the host `webfetch` tool and cached via `python3 skills/research_cache/hasher.py cache …`; **a snippet alone never witnesses a `[VERIFIED: <hash>]` claim**.
+
+Preflight prints the active provider, a free|metered classification, a **per-run** our-path search count + cost **estimate**, and `metered-mode: yes|no|unknown`. The reachability probe is excluded, so a zero-search run reports `our-path searches: 0`, and every metered rung logs its own event. Engine aliases are normalised before the probe (`ddg`/`DuckDuckGo`/`DDG`/whitespace all mean `duckduckgo`), so no spelling can skip the probe. It also gates availability mode-aware: `research`/`scout`/`darkharvest`/`hybrid` (and strict `brainstorm`, including `--domain-pack`) **HALT before any agent spawns** when no usable search exists (exit code 3 — deliberately distinct from argparse's usage-error 2); `audit`/internal `brainstorm` warn and proceed, and `--dry-run` validates and reports without halting. The workspace connection file (`.research/websearch-state.json`) is advisory: it is honoured only within a 24h TTL and never marks a provider usable without a resolvable credential. It is resolved in a **single read** (provider + advisory verdict together), only when the path is a **regular file**, and read with a bounded non-blocking guard — so a FIFO/device/symlink or a file swapped between reads can neither spoof host confirmation nor wedge preflight/`doctor`. Enable the opt-in per-search cost gate with `./install.sh --search-gate`, which adds:
+
+```jsonc
+{ "permissions": [ { "action": "websearch", "resource": "*", "effect": "ask" } ] }
+```
+
+Without the flag, `install.sh` never touches your permissions. If a `websearch` `deny` already exists the gate refuses to downgrade it (exit non-zero, config untouched), and resource-scoped websearch rules are preserved and reported — never silently deleted.
+
 ### Local Infrastructure (Optional)
 ```bash
 docker compose -f config/docker-compose.infra.yml up -d   # local SearXNG + Firecrawl

package/install.sh

@@ -5,9 +5,40 @@ REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 CLAUDE_DIR="$HOME/.claude"
 CLAUDE_JSON="$HOME/.claude.json"
 
+# Opt-in cost gate. With --search-gate we add ONE rule to the user's OpenCode
+# config: {action:"websearch", resource:"*", effect:"ask"}. The websearch
+# permission action uses the search query as the resource
+# [VERIFIED: 8bde98f3962fef9407abc4622660d9f52f0490de803151fcc0ce0f648f7c0bbe],
+# so every billable search prompts. Without the flag install.sh never touches
+# the permissions array. Manual equivalent (opencode.json):
+#   { "$schema": "https://opencode.ai/config.json",
+#     "permissions": [ { "action": "websearch", "resource": "*", "effect": "ask" } ] }
+SEARCH_GATE=0
+
+usage() {
+  cat <<'USAGE'
+Usage: install.sh [--search-gate]
+
+  --search-gate   Add {"action":"websearch","resource":"*","effect":"ask"} to the
+                  OpenCode config permissions so every search prompts before it
+                  can incur cost. Opt-in only; without it permissions are untouched.
+  -h, --help      Show this help.
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --search-gate) SEARCH_GATE=1 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "❌ Unknown option: $1" >&2; usage >&2; exit 2 ;;
+  esac
+  shift
+done
+
 echo "========================================================"
 echo "🚀 Installing Epistemic Swarm into Claude Code"
 echo "   Source: $REPO_DIR"
+[[ "$SEARCH_GATE" == "1" ]] && echo "   Search cost gate: ON (websearch -> ask)"
 echo "========================================================"
 
 # 1. Dependency checks
@@ -34,17 +65,22 @@ fi
 # 3. Patch ~/.claude.json mcpServers non-destructively
 if [[ -f "$CLAUDE_JSON" ]]; then
     echo "🔧 Merging research MCP servers into $CLAUDE_JSON..."
-    python3 - <<EOF
+    # Heredoc is QUOTED (<<'PY'): an unquoted heredoc runs command substitution
+    # on backticks in comments (e.g. "permissions") and breaks the install.
+    # Variables are passed through the environment instead.
+    CLAUDE_JSON="$CLAUDE_JSON" REPO_DIR="$REPO_DIR" python3 - <<'PY'
 import json
+import os
 from pathlib import Path
 
-claude_json_path = Path("$CLAUDE_JSON")
-mcp_config_path = Path("$REPO_DIR/config/mcp-research-servers.json")
+claude_json_path = Path(os.environ["CLAUDE_JSON"])
+repo_dir = os.environ["REPO_DIR"]
+mcp_config_path = Path(repo_dir) / "config" / "mcp-research-servers.json"
 
 try:
     with open(claude_json_path, 'r', encoding='utf-8') as f:
         claude_data = json.load(f)
-    
+
     with open(mcp_config_path, 'r', encoding='utf-8') as f:
         mcp_data = json.load(f)
 
@@ -56,9 +92,9 @@ try:
         # "runner/mcp_server.py" only works when cwd is the repo root.
         if server_name == "iumbtems":
             server_def = dict(server_def)
-            server_def["args"] = [str(Path("$REPO_DIR") / "runner" / "mcp_server.py")]
+            server_def["args"] = [str(Path(repo_dir) / "runner" / "mcp_server.py")]
             env = dict(server_def.get("env") or {})
-            env["PYTHONPATH"] = "$REPO_DIR"
+            env["PYTHONPATH"] = repo_dir
             server_def["env"] = env
 
         if server_name not in claude_data["mcpServers"]:
@@ -72,18 +108,20 @@ try:
     print("✅ ~/.claude.json successfully updated.")
 except Exception as e:
     print(f"⚠️ Non-critical warning merging MCP servers: {e}")
-EOF
+PY
 fi
 
 # 4. Patch ~/.claude/settings.json
 SETTINGS_JSON="$CLAUDE_DIR/settings.json"
 if [[ -f "$SETTINGS_JSON" ]]; then
     echo "🔧 Merging plugin settings into $SETTINGS_JSON..."
-    python3 - <<EOF
+    # Quoted heredoc: keep shell expansion out of the Python (see note above).
+    SETTINGS_JSON="$SETTINGS_JSON" python3 - <<'PY'
 import json
+import os
 from pathlib import Path
 
-settings_path = Path("$SETTINGS_JSON")
+settings_path = Path(os.environ["SETTINGS_JSON"])
 try:
     with open(settings_path, 'r', encoding='utf-8') as f:
         settings = json.load(f)
@@ -106,18 +144,24 @@ try:
     print("✅ ~/.claude/settings.json successfully updated.")
 except Exception as e:
     print(f"⚠️ Non-critical warning updating settings: {e}")
-EOF
+PY
 fi
 
 # 5. OpenCode V2 integration (plugins/agents/skills/mcp.servers — merge only)
 OPENCODE_JSON="$HOME/.config/opencode/opencode.json"
 echo "🔧 Merging OpenCode V2 configuration into $OPENCODE_JSON..."
-python3 - <<EOF
+# Quoted heredoc (<<'PY'): the comment text below contains backticks, which an
+# unquoted heredoc would execute as command substitution ("permissions: command
+# not found", "plugin: command not found", …). Variables go via the environment.
+REPO_DIR="$REPO_DIR" OPENCODE_JSON="$OPENCODE_JSON" SEARCH_GATE="$SEARCH_GATE" python3 - <<'PY'
+import fnmatch
 import json
+import os
 from pathlib import Path
 
-repo = Path("$REPO_DIR")
-oc_path = Path("$OPENCODE_JSON")
+repo = Path(os.environ["REPO_DIR"])
+oc_path = Path(os.environ["OPENCODE_JSON"])
+search_gate = os.environ.get("SEARCH_GATE", "0")
 PKG = "@heretek-ai/epistemic-swarm"
 OPTION_KEYS = {"search_engine", "max_iterations", "mode", "divergence_threshold"}
 
@@ -240,15 +284,190 @@ if "iumbtems" not in servers:
 else:
     print("   ℹ️ MCP server already configured: iumbtems")
 
+if search_gate == "1":
+    # Opt-in cost gate. V2 config key is `permissions` (a list of rules); the
+    # websearch action's resource is the search query, so "*" gates them all.
+    rules = cfg.get("permissions")
+    if rules is not None and not isinstance(rules, list):
+        # A non-list shape is not a V2 permissions list. Refuse LOUDLY rather
+        # than replacing it with a fresh list and silently dropping unrelated
+        # entries.
+        raise SystemExit(
+            "❌ opencode.json `permissions` is a "
+            f"{type(rules).__name__}, not a list; refusing to overwrite it. "
+            "Convert it to a list of {action, resource, effect} rules, then "
+            "re-run install.sh --search-gate."
+        )
+    if not isinstance(rules, list):
+        rules = cfg["permissions"] = []
+
+    def _is_websearch(rule):
+        return isinstance(rule, dict) and rule.get("action") == "websearch"
+
+    def _action_matches_websearch(rule):
+        # V2 actions support whole-value wildcards and the host resolves with
+        # last-match-wins, so `*` / `web*` also govern websearch queries.
+        action = rule.get("action") if isinstance(rule, dict) else None
+        return isinstance(action, str) and fnmatch.fnmatchcase(
+            "websearch", action
+        )
+
+    KNOWN_EFFECTS = {"allow", "ask", "deny"}
+
+    def _effect_known(rule):
+        effect = rule.get("effect")
+        return isinstance(effect, str) and effect in KNOWN_EFFECTS
+
+    # --- Safety: NEVER weaken an explicit deny. An existing websearch deny —
+    # literal action OR wildcard (`*`, `web*`), ANY resource — is stricter than
+    # the `ask` gate, and under last-match-wins our appended rule would win and
+    # silently downgrade it. The same holds for a matching rule whose effect is
+    # missing or not a known effect string: its safety cannot be determined.
+    # Preserve the config untouched and refuse loudly instead of rewriting a
+    # security decision the user made.
+    websearch_denies = [
+        r
+        for r in rules
+        if _action_matches_websearch(r)
+        and (r.get("effect") == "deny" or not _effect_known(r))
+    ]
+    if websearch_denies:
+        raise SystemExit(
+            "❌ opencode.json already denies websearch "
+            f"({json.dumps(websearch_denies)}); the --search-gate `ask` rule "
+            "would be WEAKER than it under last-match-wins, so install.sh "
+            "refuses to downgrade it and leaves your config untouched.\n"
+            "   The existing deny is already stricter than ask. If you really "
+            "want the ask gate instead, remove the websearch deny rule(s) "
+            "manually, then re-run `install.sh --search-gate`."
+        )
+
+    canonical = {"action": "websearch", "resource": "*", "effect": "ask"}
+    global_ws = [
+        r for r in rules if _is_websearch(r) and r.get("resource") == "*"
+    ]
+    # Resource-scoped websearch rules (resource != "*") are the user's explicit
+    # per-query decisions. NEVER silently drop them: keep every one and report
+    # it. Effective precedence is resolved below under last-match-wins — these
+    # rules are preserved verbatim, never rewritten.
+    scoped_ws = [
+        r
+        for r in rules
+        if _action_matches_websearch(r) and r.get("resource") != "*"
+    ]
+    for rule in scoped_ws:
+        if rule.get("effect") == "allow":
+            print(
+                "   ⚠️ Preserved resource-scoped websearch allow "
+                f"({json.dumps(rule)}): kept verbatim; effective precedence "
+                "is resolved below under last-match-wins."
+            )
+        else:
+            print(
+                "   ℹ️ Preserved existing websearch rule "
+                f"({json.dumps(rule)})"
+            )
+
+    if global_ws:
+        existing_ask = [r for r in global_ws if r.get("effect") == "ask"]
+        if existing_ask:
+            # An ask gate is already present. Keep it VERBATIM — rewriting it to
+            # the canonical shape would silently drop unknown keys (e.g. a
+            # user-added "note"), so preserve and report instead.
+            kept = existing_ask[0]
+            dropped = [r for r in global_ws if r is not kept]
+            for r in dropped:
+                print(
+                    "   ~ Dropped duplicate websearch '*' rule "
+                    f"({json.dumps(r)})"
+                )
+            drop_ids = {id(r) for r in dropped}
+            rules[:] = [r for r in rules if id(r) not in drop_ids]
+            # Ordering matters under last-match-wins: a later matching `allow`
+            # (scoped or wildcard-action) would override the preserved ask for
+            # overlapping queries. Move the gate last so it takes precedence,
+            # and say so loudly — this overrides an explicit per-query allow.
+            kept_index = next(i for i, r in enumerate(rules) if r is kept)
+            later_allow = [
+                r
+                for r in rules[kept_index + 1 :]
+                if _action_matches_websearch(r) and r.get("effect") == "allow"
+            ]
+            if later_allow:
+                rules.remove(kept)
+                rules.append(kept)
+                print(
+                    "   ⚠️ Moved websearch ask gate after later matching allow "
+                    f"({json.dumps(later_allow)}): the gate now takes "
+                    "precedence for overlapping queries under last-match-wins."
+                )
+            if kept == canonical:
+                print("   ℹ️ websearch ask-gate permission already configured")
+            else:
+                print(
+                    "   ℹ️ Preserved existing websearch ask rule with extra keys "
+                    f"({json.dumps(kept)}); not rewritten."
+                )
+        else:
+            # Only allow effects can reach here (deny/malformed abort above).
+            for r in global_ws:
+                print("   ~ replaced websearch allow (*) with ask")
+            drop_ids = {id(r) for r in global_ws}
+            rules[:] = [r for r in rules if id(r) not in drop_ids]
+            rules.append(canonical)
+    else:
+        # No literal global websearch rule. A broader ask already covering
+        # websearch means the gate is effectively in place — don't duplicate
+        # it, unless a later resource-scoped allow would override it.
+        global_matches = [
+            (i, r)
+            for i, r in enumerate(rules)
+            if _action_matches_websearch(r) and r.get("resource") == "*"
+        ]
+        last_global_index, last_global = (
+            global_matches[-1] if global_matches else (None, None)
+        )
+        later_scoped_allow = (
+            last_global is not None
+            and any(
+                i > last_global_index
+                and _action_matches_websearch(r)
+                and r.get("resource") != "*"
+                and r.get("effect") == "allow"
+                for i, r in enumerate(rules)
+            )
+        )
+        if (
+            last_global is not None
+            and last_global.get("effect") == "ask"
+            and not later_scoped_allow
+        ):
+            print(
+                "   ℹ️ websearch is already gated by a broader ask rule; "
+                "nothing to add"
+            )
+        else:
+            if later_scoped_allow:
+                print(
+                    "   ⚠️ Resource-scoped websearch allow follows the broader "
+                    "ask gate; appending canonical ask so the gate takes "
+                    "precedence for overlapping queries under last-match-wins."
+                )
+            rules.append(canonical)
+            print("   + Added websearch ask-gate permission (--search-gate)")
+else:
+    print("   ℹ️ permissions untouched (pass --search-gate to add the websearch ask rule)")
+
 oc_path.write_text(json.dumps(cfg, indent=2) + "\n", encoding="utf-8")
 print("✅ OpenCode configuration updated.")
-EOF
+PY
 
 echo ""
 echo "🎉 Epistemic Swarm installation complete!"
 echo "   - Interactive Grilling: run /grilling inside Claude Code"
 echo "   - Lateral Brainstorming: run /brainstorming inside Claude Code (skills/brainstorming)"
 echo "   - OpenCode V2: /swarm /grill /audit /scout /brainstorming via plugin commands"
+echo "   - Cost gate (opt-in): re-run with --search-gate to add a websearch ask rule"
 echo "   - Rebuild harness adapters: python3 scripts/build_adapters.py"
 echo "   - Headless Research Swarm: npx @heretek-ai/epistemic-swarm run \"<objective>\""
 echo "========================================================"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.7.15",
+  "version": "0.7.17",
   "description": "IUMBTEMS (Epistemic Swarm) — High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi (pi.dev), OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {
@@ -22,6 +22,9 @@
     "solid-js": "1.9.12",
     "@opentui/solid": ">=0.4.0 <0.6.0"
   },
+  "overrides": {
+    "@babel/core": "^7.29.6"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Heretek-AI/IUMBTEMS.git"