@heretek-ai/epistemic-swarm 0.4.0 → 0.4.2

package/.claude-plugin/plugin.json

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

package/install.sh

@@ -109,10 +109,98 @@ except Exception as e:
 EOF
 fi
 
+# 5. OpenCode V2 integration (plugin tuple, agents, MCP server — merge only)
+OPENCODE_JSON="$HOME/.config/opencode/opencode.json"
+echo "🔧 Merging OpenCode V2 configuration into $OPENCODE_JSON..."
+python3 - <<EOF
+import json
+from pathlib import Path
+
+repo = Path("$REPO_DIR")
+oc_path = Path("$OPENCODE_JSON")
+PKG = "@heretek-ai/epistemic-swarm"
+OPTION_KEYS = {"search_engine", "max_iterations", "mode", "divergence_threshold"}
+
+oc_path.parent.mkdir(parents=True, exist_ok=True)
+cfg = json.loads(oc_path.read_text(encoding="utf-8")) if oc_path.exists() else {}
+
+# --- plugin entry: tuple form [package, options]; repair bare-object form ---
+plugins = cfg.get("plugin", [])
+if not isinstance(plugins, list):
+    print("   ⚠️ 'plugin' is not a list; leaving untouched")
+    plugins = cfg.get("plugin", [])
+else:
+    repaired = []
+    i = 0
+    changed = False
+    while i < len(plugins):
+        item = plugins[i]
+        # Bare options object following our package string (or standalone):
+        # fold into a tuple instead of leaving an invalid entry.
+        if isinstance(item, dict) and set(item) & OPTION_KEYS:
+            prev_is_pkg = repaired and repaired[-1] == PKG
+            prev_is_tuple = (
+                repaired and isinstance(repaired[-1], list)
+                and repaired[-1] and repaired[-1][0] == PKG
+            )
+            if prev_is_pkg:
+                repaired[-1] = [PKG, item]
+                changed = True
+                print("   ~ Repaired bare options object into tuple entry")
+            elif prev_is_tuple:
+                merged = {**(repaired[-1][1] if len(repaired[-1]) > 1 else {}), **item}
+                repaired[-1] = [PKG, merged]
+                changed = True
+                print("   ~ Folded stray options into existing tuple entry")
+            else:
+                repaired.append([PKG, item])
+                changed = True
+                print("   ~ Attached stray options object to new tuple entry")
+        else:
+            repaired.append(item)
+        i += 1
+    if not any((p == PKG or (isinstance(p, list) and p and p[0] == PKG)) for p in repaired):
+        repaired.append([PKG, {"search_engine": "duckduckgo", "max_iterations": 2, "mode": "research"}])
+        changed = True
+        print(f"   + Added plugin entry: {PKG}")
+    else:
+        print(f"   ℹ️ Plugin entry already configured: {PKG}")
+    cfg["plugin"] = repaired
+
+# --- agents: merge snippet definitions, never overwrite user agents ---
+try:
+    snippet = json.loads((repo / "config" / "opencode-snippet.json").read_text(encoding="utf-8"))
+    agents = cfg.setdefault("agent", {})
+    for name, definition in snippet.get("agent", {}).items():
+        if name not in agents:
+            agents[name] = definition
+            print(f"   + Added agent: {name}")
+        else:
+            print(f"   ℹ️ Agent already configured: {name}")
+except Exception as e:
+    print(f"   ⚠️ Non-critical warning merging agents: {e}")
+
+# --- MCP server: absolute runner path (relative paths only work at repo root) ---
+mcp = cfg.setdefault("mcp", {})
+if "iumbtems" not in mcp:
+    mcp["iumbtems"] = {
+        "type": "local",
+        "command": ["python3", str(repo / "runner" / "mcp_server.py")],
+        "enabled": True,
+    }
+    print("   + Added MCP server: iumbtems")
+else:
+    print("   ℹ️ MCP server already configured: iumbtems")
+
+oc_path.write_text(json.dumps(cfg, indent=2) + "\n", encoding="utf-8")
+print("✅ OpenCode configuration updated.")
+EOF
+
 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 "   - 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.4.0",
+  "version": "0.4.2",
   "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": {
@@ -11,12 +11,17 @@
     ".": "./bin/cli.js",
     "./opencode": "./plugins/opencode/index.js",
     "./server": "./plugins/opencode/index.js",
+    "./tui": "./plugins/opencode/tui.js",
     "./pi": "./extensions/pi/index.js",
     "./omp": "./extensions/pi/index.js"
   },
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "solid-js": "1.9.12",
+    "@opentui/solid": ">=0.4.0 <0.6.0"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Heretek-AI/IUMBTEMS.git"

package/plugins/antigravity/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "epistemic-swarm",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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.0",
+  "version": "0.4.2",
   "description": "IUMBTEMS Epistemic Swarm: dialectic research, code audit, OSS scout, and lateral brainstorming for Gemini CLI.",
   "mcpServers": {
     "brave-search": {

package/plugins/opencode/index.js

@@ -12,6 +12,7 @@
  */
 
 import { spawnSync } from 'child_process';
+import { readFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
@@ -20,6 +21,15 @@ const __dirname = path.dirname(__filename);
 const PKG_ROOT = path.resolve(__dirname, '../..');
 const MCP_SERVER = path.join(PKG_ROOT, 'runner', 'mcp_server.py');
 
+/** Plugin version tracks package.json so it cannot drift across releases. */
+let PKG_VERSION = '0.0.0';
+try {
+  const pkg = JSON.parse(readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf-8'));
+  if (pkg && typeof pkg.version === 'string') PKG_VERSION = pkg.version;
+} catch {
+  // keep fallback; version is informational only
+}
+
 /** Uniform dispatch: one-shot MCP call, return OpenCode's {content, status}. */
 function callMcp(tool, args = {}, cwd) {
   const res = spawnSync(
@@ -224,7 +234,7 @@ const TOOL_CATALOG = [
       properties: {
         base_dir: {
           type: 'string',
-          description: 'Path to .research workspace',
+          description: 'Path to .research workspace (default: current directory)',
         },
       },
     },
@@ -239,7 +249,7 @@ const TOOL_CATALOG = [
         hash: { type: 'string', description: 'Content-addressed SHA-256 of the affected source' },
         event: { type: 'string', enum: ['RETRACTED', 'REVISED'] },
         note: { type: 'string', description: 'Why the source was retracted/revised' },
-        base_dir: { type: 'string' },
+        base_dir: { type: 'string', description: 'Path to .research workspace (default: current directory)' },
       },
       required: ['hash', 'event'],
     },
@@ -251,7 +261,7 @@ const TOOL_CATALOG = [
     input: {
       type: 'object',
       properties: {
-        base_dir: { type: 'string' },
+        base_dir: { type: 'string', description: 'Path to .research workspace (default: current directory)' },
         scope_ids: {
           type: 'array',
           items: { type: 'string' },
@@ -268,7 +278,7 @@ const TOOL_CATALOG = [
       type: 'object',
       properties: {
         pack: { type: 'string', description: 'Pack id: biopharma | quant | legal (or a path)' },
-        base_dir: { type: 'string' },
+        base_dir: { type: 'string', description: 'Path to .research workspace (default: current directory)' },
       },
       required: ['pack'],
     },
@@ -280,11 +290,11 @@ const TOOL_CATALOG = [
     input: {
       type: 'object',
       properties: {
-        base_dir: { type: 'string' },
+        base_dir: { type: 'string', description: 'Path to .research workspace (default: current directory)' },
         out: { type: 'string', description: 'Output path (default <base_dir>/brief.pcrb.json)' },
-        objective: { type: 'string' },
+        objective: { type: 'string', description: 'Research objective the brief must cover' },
         key: { type: 'string', description: 'HMAC key (prefer key_file or env IUMBTEMS_PCRB_KEY)' },
-        key_file: { type: 'string' },
+        key_file: { type: 'string', description: 'Path to file containing the HMAC key' },
       },
     },
   },
@@ -296,8 +306,8 @@ const TOOL_CATALOG = [
       type: 'object',
       properties: {
         brief: { type: 'string', description: 'Path to brief.pcrb.json' },
-        key: { type: 'string' },
-        key_file: { type: 'string' },
+        key: { type: 'string', description: 'HMAC key (prefer key_file or env IUMBTEMS_PCRB_KEY)' },
+        key_file: { type: 'string', description: 'Path to file containing the HMAC key' },
       },
       required: ['brief'],
     },
@@ -327,21 +337,297 @@ function normalizeArgs(tool, args = {}) {
   return a;
 }
 
+/**
+ * OpenCode slash-command catalog (Phase A discoverability).
+ *
+ * Mirrors the Pi/OMP/Gemini command surface. Each entry registers into
+ * `config.command[name] = {description, template}` via the server `config`
+ * hook (same pattern as @prevalentware/opencode-goal-plugin). `$ARGUMENTS`
+ * is the raw text after the slash command. Templates instruct the agent to
+ * call the corresponding canonical `iumbtems_*` tool — commands never
+ * reimplement tool logic.
+ */
+export const OPENCODE_COMMANDS = [
+  {
+    name: 'swarm',
+    description: 'Run IUMBTEMS dialectic research swarm on an objective',
+    template: [
+      'Run an IUMBTEMS dialectic research swarm.',
+      'Objective: $ARGUMENTS',
+      '1. If the objective is ambiguous, frame it first via iumbtems_socratic_frontier.',
+      '2. Execute iumbtems_swarm_research with {"objective": "<objective>"} (pass "mock_mode": true only for dry runs).',
+      '3. Summarize .research/final_synthesis.md, preserving [VERIFIED:<hash>] pointers.',
+    ].join('\n'),
+  },
+  {
+    name: 'grill',
+    description: 'Launch Socratic grilling and decision tree frontier exploration',
+    template: [
+      'Launch Socratic grilling on the decision frontier.',
+      'Objective: $ARGUMENTS (may be empty to inspect the current frontier)',
+      'Call iumbtems_socratic_frontier with {"objective": "<objective>", "file": ".research/frontier.json"}; omit "objective" to inspect.',
+      'Challenge premises, invert assumptions, and report open frontier nodes.',
+    ].join('\n'),
+  },
+  {
+    name: 'swarm-config',
+    description: 'Inspect or update Epistemic Swarm parameters (engine, depth, mode)',
+    template: [
+      'Inspect or update the Epistemic Swarm configuration.',
+      'Arguments: $ARGUMENTS (may be empty to inspect current settings)',
+      'Call iumbtems_config; map --engine/--depth/--mode/--show style flags to search_engine/max_iterations/mode, or pass through no arguments to inspect.',
+    ].join('\n'),
+  },
+  {
+    name: 'audit',
+    description: 'Run dialectic codebase architectural and security audit with line-level proof',
+    template: [
+      'Run an IUMBTEMS dialectic codebase audit (structural architect vs adversarial red-teamer).',
+      'Target: $ARGUMENTS (path, component, or empty for full-repository architecture and vulnerability audit)',
+      '1. Execute iumbtems_code_audit with {"target": "<target>"} (pass "mock_mode": true only for dry runs).',
+      '2. Summarize .research/code_audit_report.md with line-level proof pointers.',
+    ].join('\n'),
+  },
+  {
+    name: 'scout',
+    description: 'Scout open-source libraries, audit copyleft licenses, generate clean-room blueprints',
+    template: [
+      'Scout open-source solutions for the requested capability.',
+      'Feature: $ARGUMENTS',
+      '1. Execute iumbtems_oss_scout with {"feature": "<feature>"} (pass "mock_mode": true only for dry runs).',
+      '2. Report mature candidates, GPL/AGPL copyleft risks, and the clean-room blueprint in .research/oss_scout_report.md.',
+    ].join('\n'),
+  },
+  {
+    name: 'brainstorming',
+    description: 'Lateral brainstorming: novel feature vectors, paradigm inversions, falsifiable spikes',
+    template: [
+      'Run lateral brainstorming (divergent what-if ideation, never bug-fix lists).',
+      'Prompt: $ARGUMENTS (defaults to "Where do we go from here?" when empty)',
+      '1. Execute iumbtems_brainstorm with {"objective": "<prompt>"} (pass "mock_mode": true only for dry runs).',
+      '2. Report novel feature vectors, paradigm inversions, and falsifiable spikes from .research/brainstorm_report.md.',
+    ].join('\n'),
+  },
+  {
+    name: 'brainstorm',
+    description: 'Alias for /brainstorming',
+    template: [
+      'Alias for /brainstorming: run lateral brainstorming (divergent what-if ideation, never bug-fix lists).',
+      'Prompt: $ARGUMENTS (defaults to "Where do we go from here?" when empty)',
+      'Execute iumbtems_brainstorm with {"objective": "<prompt>"} and report feature vectors, paradigm inversions, and falsifiable spikes.',
+    ].join('\n'),
+  },
+];
+
+/**
+ * Register the command catalog into an OpenCode config object without
+ * overwriting user-defined commands of the same name. Exported for tests.
+ */
+export function registerOpenCodeCommands(cfg = {}) {
+  cfg.command ??= {};
+  for (const cmd of OPENCODE_COMMANDS) {
+    if (cfg.command[cmd.name]) continue;
+    cfg.command[cmd.name] = { description: cmd.description, template: cmd.template };
+  }
+  return cfg;
+}
+
+/** Tool map (object form) for the server hook; array catalog stays canonical. */
+function buildToolMap() {
+  return Object.fromEntries(
+    TOOL_CATALOG.map((tool) => [
+      tool.name,
+      {
+        ...tool,
+        options: { codemode: false },
+        execute: async (args = {}, toolContext) =>
+          callMcp(tool.name, normalizeArgs(tool.name, args), toolContext?.cwd),
+      },
+    ])
+  );
+}
+
+/**
+ * Phase C retention: session lifecycle hooks.
+ *
+ * Reference pattern: @prevalentware/opencode-goal-plugin subscribes via
+ * `context.event.subscribe({signal})`, detects idle as `session.idle` or an
+ * idle `session.status`, continues via `context.session.prompt`, and preserves
+ * state across compaction with the `experimental.session.compacting` hook.
+ * Every hook here is best-effort and never throws into the host.
+ */
+
+/** Idle detection matching the reference implementation. Exported for tests. */
+export function isIdleEvent(event) {
+  if (!event || typeof event.type !== 'string') return false;
+  if (event.type === 'session.idle') return true;
+  const status = event.properties?.status;
+  return (
+    event.type === 'session.status' &&
+    typeof status === 'object' &&
+    status !== null &&
+    status.type === 'idle'
+  );
+}
+
+function readJsonFile(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Last-write-wins degraded claims + requeue list. Pure fs reads. */
+export function readLedgerDegraded(root) {
+  const out = { stale: [], suspect: [], requeued: [], fingerprint: 'empty' };
+  try {
+    const ledger = readJsonFile(path.join(root, '.research', 'ledger', 'claim_status.json'));
+    if (Array.isArray(ledger)) {
+      const last = new Map();
+      for (const e of ledger) {
+        if (e && typeof e.claim_id === 'string') last.set(e.claim_id, e.to_status);
+      }
+      for (const [id, s] of last) {
+        if (s === 'STALE') out.stale.push(id);
+        else if (s === 'SUSPECT') out.suspect.push(id);
+      }
+      const lastAt = ledger.length > 0 ? ledger[ledger.length - 1]?.at : '';
+      out.fingerprint = `${ledger.length}:${lastAt}`;
+    }
+    const requeue = readJsonFile(path.join(root, '.research', 'requeue.json'));
+    if (Array.isArray(requeue)) {
+      out.requeued = requeue.map((e) => e?.scope_id).filter((s) => typeof s === 'string');
+    }
+  } catch {
+    /* unreadable workspace -> no degraded claims */
+  }
+  return out;
+}
+
+/**
+ * Compaction context preserving .research state. Returns null when there is
+ * no workspace (hook then pushes nothing).
+ */
+export function buildCompactionContext(root) {
+  try {
+    const cfg = readJsonFile(path.join(root, '.research', 'config.json'));
+    if (!cfg || typeof cfg !== 'object') return null;
+    const degraded = readLedgerDegraded(root);
+    const lines = [
+      'IUMBTEMS Epistemic Swarm workspace state (preserved across compaction):',
+      `- mode=${cfg.mode ?? '?'} engine=${cfg.search_engine ?? '?'} depth=${cfg.max_iterations ?? '?'}`,
+      `- degraded claims: ${degraded.stale.length} STALE, ${degraded.suspect.length} SUSPECT`,
+    ];
+    if (degraded.stale.length > 0) {
+      lines.push(`- STALE claim ids: ${degraded.stale.slice(0, 10).join(', ')}`);
+    }
+    if (degraded.requeued.length > 0) {
+      lines.push(`- scopes queued for re-run: ${degraded.requeued.slice(0, 10).join(', ')}`);
+    }
+    lines.push('- Continue with iumbtems_check_staleness when resuming audit work.');
+    return lines.join('\n');
+  } catch {
+    return null;
+  }
+}
+
+const NUDGE_MIN_INTERVAL_MS = 5 * 60 * 1000;
+const activeNudges = new Map();
+
+/**
+ * Handle one subscribed event: nudge once per ledger change when degraded
+ * claims exist. Returns true when a nudge was sent. Exported for tests.
+ */
+export function handleIdleEvent(host, root, state, event) {
+  try {
+    if (!isIdleEvent(event)) return false;
+    const sessionID = event?.properties?.sessionID ?? event?.sessionID;
+    if (typeof sessionID !== 'string' || !sessionID) return false;
+    const now = Date.now();
+    if (now - (state.lastNudgeAt || 0) < NUDGE_MIN_INTERVAL_MS) return false;
+    const degraded = readLedgerDegraded(root);
+    const total = degraded.stale.length + degraded.suspect.length;
+    if (total === 0) return false;
+    if (state.lastFingerprint === degraded.fingerprint) return false;
+    state.lastFingerprint = degraded.fingerprint;
+    state.lastNudgeAt = now;
+    const example = degraded.stale.slice(0, 5).join(', ');
+    Promise.resolve(
+      host.session.prompt({
+        sessionID,
+        text:
+          `IUMBTEMS staleness nudge: ${total} degraded claim(s) ` +
+          `(${degraded.stale.length} STALE, ${degraded.suspect.length} SUSPECT) in .research/ledger/claim_status.json` +
+          (example ? `, e.g. ${example}` : '') +
+          '. Run iumbtems_check_staleness and re-audit affected scopes, or reply that it is already handled.',
+      })
+    ).catch(() => {});
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Subscribe to session events for idle nudges. One subscription per root. */
+export function startStalenessNudge(host, root) {
+  try {
+    if (!host || typeof host.event?.subscribe !== 'function') return null;
+    if (typeof host.session?.prompt !== 'function') return null;
+    if (activeNudges.has(root)) return activeNudges.get(root).stop;
+    const abort = new AbortController();
+    const state = { lastFingerprint: null, lastNudgeAt: 0 };
+    const stop = () => {
+      try { abort.abort(); } catch { /* noop */ }
+      activeNudges.delete(root);
+    };
+    activeNudges.set(root, { stop });
+    (async () => {
+      try {
+        const sub = host.event.subscribe({ signal: abort.signal });
+        const it = sub[Symbol.asyncIterator]();
+        while (true) {
+          const { value, done } = await it.next();
+          if (done) break;
+          handleIdleEvent(host, root, state, value);
+        }
+      } catch {
+        /* aborted or host closed the stream */
+      }
+      activeNudges.delete(root);
+    })();
+    return stop;
+  } catch {
+    return null;
+  }
+}
+
 export function createOpenCodePlugin(context = {}) {
   return {
     id: 'heretek.iumbtems.epistemic-swarm',
     name: 'IUMBTEMS Epistemic Swarm',
-    version: '0.3.0',
+    version: PKG_VERSION,
     description:
       'I Use My Brain To Express My Self: High-integrity dialectic research, code audits, and open-source scouting',
 
-    server: (toolContext) =>
-      TOOL_CATALOG.map((tool) => ({
-        ...tool,
-        options: { codemode: false },
-        execute: async (args = {}) =>
-          callMcp(tool.name, normalizeArgs(tool.name, args), toolContext?.cwd),
-      })),
+    server: async () => ({
+      // Config hook: slash-command catalog (mirrors the goal plugin's
+      // registerDesktopCommands pattern; never overwrites user commands).
+      config: (cfg) => registerOpenCodeCommands(cfg),
+      // Tool map (object form, as in the reference implementation).
+      tool: buildToolMap(),
+      // Compaction hook: preserve .research state (best-effort, silent skip
+      // when no workspace is present so compaction never breaks).
+      'experimental.session.compacting': async (input, output) => {
+        try {
+          const root = input?.directory ?? input?.location?.directory ?? process.cwd();
+          const ctx = buildCompactionContext(root);
+          if (ctx && output && Array.isArray(output.context)) output.context.push(ctx);
+        } catch {
+          /* never break compaction */
+        }
+      },
+    }),
 
     setup: async (appContext) => {
       const opts = context.options || appContext?.options;
@@ -357,6 +643,21 @@ export function createOpenCodePlugin(context = {}) {
           callMcp('iumbtems_config', updates, appContext?.cwd);
         }
       }
+      // Phase C: idle staleness nudge (opt out with {staleness_nudge: false}).
+      // Subscribes only when the host exposes event/session; one per root.
+      try {
+        if ((opts?.staleness_nudge ?? true)) {
+          const host = {
+            event: appContext?.event || context.event,
+            session: appContext?.session || context.session,
+          };
+          const root =
+            appContext?.location?.directory || context.location?.directory;
+          if (root) startStalenessNudge(host, root);
+        }
+      } catch {
+        /* lifecycle hooks are best-effort */
+      }
       return { initialized: true, platform: 'opencode-v2' };
     },
   };