@heretek-ai/epistemic-swarm 0.7.19 → 0.7.21

package/plugins/opencode/tui.js

@@ -26,11 +26,174 @@ import {
   saveConfig,
   validateConfig,
 } from './config-io.js';
-import { OPENCODE_COMMANDS } from './index.js';
+import { OPENCODE_COMMANDS, SettingsRpc } from './index.js';
 
 const PLUGIN_ID = 'heretek.iumbtems.epistemic-swarm.tui';
 const REFRESH_MS = 5000;
 
+// ---------------------------------------------------------------------------
+// Phase 03 (opencode-settings-menu): RPC-preferred reads/writes, `changed`
+// subscription, UI-only prefs.
+//
+// The server plugin's `iumbtems.settings` RPC domain is the preferred path:
+// `api.client.rpc(SettingsRpc)` (the v2 TUI context carries `client:
+// OpenCodeClient`). When absent — or when an RPC call fails with a transport
+// error — the wizard/panel fall back to the direct-fs `config-io.js` path
+// with a visible degraded-path toast. Both paths share validation and the
+// expected-hash guard. Live refresh subscribes to the `changed` event; the
+// existing 5s mtime poll stays as the floor.
+//
+// UI preferences live in `api.storage.store(...)` (durable, synced across TUI
+// instances) and are NEVER run-affecting: only dialog conveniences such as
+// the last-save timestamp. Effective values always come from the RPC snapshot
+// or `.research/config.json`.
+// ---------------------------------------------------------------------------
+
+/** Live-refresh floor: the sidebar poll interval, in ms (unchanged). */
+export const SETTINGS_POLL_MS = REFRESH_MS;
+
+/** UI-only preferences key (TUI storage; never run-affecting). */
+export const UI_PREFS_KEY = 'iumbtems.ui.prefs';
+
+// Invariant (phase-03 R4c): UI prefs are write-only conveniences (e.g. the
+// last-save timestamp). NO read path — wizard, panel, or otherwise — consults
+// them when computing effective settings: effective values come exclusively
+// from the RPC snapshot or `.research/config.json`. `TestUiPrefsBoundary`
+// pins this: prefs deliberately named like config keys never surface in the
+// panel body or on disk. No behavior change by this comment.
+
+/**
+ * RPC subclient for the settings domain, or null when the host has no
+ * `client.rpc` (degraded direct-fs path). Never throws.
+ */
+export function getSettingsRpcClient(api) {
+  try {
+    const rpc = api?.client?.rpc;
+    if (typeof rpc !== 'function') return null;
+    return rpc.call(api.client, SettingsRpc);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Subscribe to the server `changed` event for live refresh. Returns the
+ * unsubscribe function, or null when the host has no RPC events (the 5s poll
+ * remains the floor). Never throws.
+ */
+export function subscribeSettingsChanged(api, onChanged) {
+  try {
+    const client = getSettingsRpcClient(api);
+    if (!client || !client.events || typeof client.events.on !== 'function') {
+      return null;
+    }
+    const unsub = client.events.on('changed', (event) => {
+      try {
+        if (typeof onChanged === 'function') onChanged(event);
+      } catch {
+        /* refresh callbacks are best-effort */
+      }
+    });
+    return typeof unsub === 'function' ? unsub : () => {};
+  } catch {
+    return null;
+  }
+}
+
+/** Read UI-only prefs ({} when the host has no TUI storage). Never throws. */
+export function readUiPrefs(api) {
+  try {
+    const store = api?.storage?.store;
+    if (typeof store !== 'function') return {};
+    const [state] = store.call(api.storage, UI_PREFS_KEY, { initial: {} });
+    return { ...(state || {}) };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Merge UI-only prefs (never run-affecting; false when the host has no TUI
+ * storage). Never throws.
+ */
+export async function writeUiPrefs(api, patch) {
+  try {
+    const store = api?.storage?.store;
+    if (typeof store !== 'function') return false;
+    const parts = store.call(api.storage, UI_PREFS_KEY, { initial: {} });
+    const mutate = parts && parts[1];
+    if (typeof mutate !== 'function') return false;
+    await mutate((draft) => {
+      Object.assign(draft, patch || {});
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Visible toast marking the degraded direct-fs path. */
+function degradedRpcToast(host, reason) {
+  wizardToast(
+    host,
+    'IUMBTEMS settings',
+    `Server RPC ${reason} — using direct file write (degraded path). ` +
+      'Changes still validate and apply to the next swarm run.'
+  );
+}
+
+/** Human-readable settings text for already-loaded rows (the RPC path). */
+function formatSettingRows(rows) {
+  try {
+    if (!rows || rows.length === 0) return 'IUMBTEMS settings: no schema available.';
+    const lines = rows.map((row) => {
+      const restartNote =
+        row.restart === 'next-run'
+          ? 'applies to next swarm run'
+          : `restart: ${row.restart}`;
+      const stale = row.deprecated ? ' (deprecated, display-only)' : '';
+      return `- ${row.label} (${row.key}): ${displayCell(row)} [${row.source}] — ${restartNote}${stale}`;
+    });
+    return ['IUMBTEMS settings (effective values):', ...lines].join('\n');
+  } catch {
+    return 'IUMBTEMS settings: unavailable (workspace unreadable).';
+  }
+}
+
+/**
+ * Effective settings body: RPC snapshot when available, direct-fs text
+ * otherwise. Never throws.
+ */
+async function effectiveSettingsBody(host, baseDir, env) {
+  let body = null;
+  const rpc = getSettingsRpcClient(host);
+  if (rpc) {
+    try {
+      const snap = await rpc.get();
+      if (snap && snap.config && typeof snap.config === 'object') {
+        // Provenance comes from the ON-DISK `raw`, not the merged effective
+        // `config` (every key is present there, which made every row `file`).
+        const rows = buildSettingRows({ ...snap.config }, snap.raw, env);
+        if (rows.length > 0) body = formatSettingRows(rows);
+      }
+    } catch {
+      /* fall through to the direct-fs read */
+    }
+  }
+  if (body === null) body = formatSettingsText(baseDir, env);
+  // R10: a malformed file must not render as silent defaults. Advisory local-fs
+  // check (the same rule the wizard warns on); surfaced in the panel body —
+  // never throws, never writes.
+  try {
+    if (isConfigMalformed(baseDir)) {
+      body = `⚠️ Could not parse ${baseDir}/config.json — showing defaults.\n\n${body}`;
+    }
+  } catch {
+    /* advisory only — a failed check must not break the panel */
+  }
+  return body;
+}
+
 /** Palette command opening the read-only settings status panel. */
 export const SETTINGS_PANEL_COMMAND_ID = 'iumbtems.swarm-settings';
 /** Palette command opening the settings dialog wizard. */
@@ -206,6 +369,26 @@ function SwarmSidebar(api, root) {
       }
     }, REFRESH_MS);
     onCleanup(() => clearInterval(timer));
+    // Live refresh on the server `changed` event; the poll above is the floor.
+    let unsub = null;
+    try {
+      unsub = subscribeSettingsChanged(api, () => {
+        try {
+          setSnapshot(readSwarmStatus(root));
+        } catch {
+          /* keep last snapshot */
+        }
+      });
+    } catch {
+      /* poll remains the floor */
+    }
+    onCleanup(() => {
+      try {
+        if (typeof unsub === 'function') unsub();
+      } catch {
+        /* unsubscribe is best-effort */
+      }
+    });
   });
   return box({}, [
     () => {
@@ -829,8 +1012,31 @@ export async function openSettingsWizard(host, root, opts = {}) {
       );
       return { ok: false, reason: 'no-dialog', written: false };
     }
-    const raw = readRawConfig(baseDir);
-    if (isConfigMalformed(baseDir)) {
+    // Preferred path: the server RPC snapshot. Absent `client.rpc` (or a
+    // failed RPC read) falls back to the direct-fs path with a visible toast.
+    let rpc = getSettingsRpcClient(host);
+    if (!rpc) degradedRpcToast(host, 'unavailable');
+    let raw;
+    let draft;
+    let startHash;
+    if (rpc) {
+      try {
+        const snap = await rpc.get();
+        if (!snap || typeof snap.config !== 'object') throw new Error('empty snapshot');
+        // R1: provenance uses the RPC's on-disk `raw` (null/absent -> {}),
+        // never the merged effective `config`.
+        raw = snap.raw && typeof snap.raw === 'object' ? snap.raw : {};
+        draft = JSON.parse(JSON.stringify(snap.config));
+        startHash = typeof snap.hash === 'string' ? snap.hash : null;
+      } catch {
+        degradedRpcToast(host, 'read failed');
+        rpc = null;
+      }
+    }
+    // B2 (phase-03 R6): the malformed-config warning fires on the RPC path
+    // too — the server snapshot degrades to defaults for a corrupt file, and
+    // silent defaults are not B2-compliant. Local fs read, advisory only.
+    if (rpc && isConfigMalformed(baseDir)) {
       wizardToast(
         host,
         'IUMBTEMS settings',
@@ -838,8 +1044,19 @@ export async function openSettingsWizard(host, root, opts = {}) {
           'Saving will replace the malformed file; cancel writes nothing.'
       );
     }
-    const startHash = configHash(baseDir);
-    const draft = loadConfig(baseDir);
+    if (!rpc) {
+      raw = readRawConfig(baseDir);
+      if (isConfigMalformed(baseDir)) {
+        wizardToast(
+          host,
+          'IUMBTEMS settings',
+          `Could not parse ${baseDir}/config.json — showing defaults. ` +
+            'Saving will replace the malformed file; cancel writes nothing.'
+        );
+      }
+      startHash = configHash(baseDir);
+      draft = loadConfig(baseDir);
+    }
     if (raw && rawHasLegacyPin(raw, draft.backend)) {
       wizardToast(
         host,
@@ -893,6 +1110,56 @@ export async function openSettingsWizard(host, root, opts = {}) {
           return { ok: false, reason: 'dialog-error', written: false };
         }
         if (!confirmed) continue;
+        // Preferred write path: the server RPC (validates + hash-guards
+        // server-side, mirrors storage, emits `changed`). Transport failures
+        // fall back to the direct-fs write below.
+        if (rpc) {
+          try {
+            const rpcInput = { updates: draft };
+            if (opts && opts.expected_hash !== undefined) {
+              rpcInput.expected_hash = opts.expected_hash;
+            }
+            if (opts && opts.expectedHash !== undefined) {
+              rpcInput.expectedHash = opts.expectedHash;
+            }
+            if (rpcInput.expected_hash === undefined && rpcInput.expectedHash === undefined) {
+              rpcInput.expectedHash = startHash;
+            }
+            const res = await rpc.set(rpcInput);
+            wizardToast(
+              host,
+              'IUMBTEMS settings',
+              'Saved via server RPC — applies to the next swarm run.'
+            );
+            try {
+              await writeUiPrefs(host, { lastSavedAt: new Date().toISOString() });
+            } catch {
+              /* UI prefs are best-effort */
+            }
+            return { ok: true, written: true, hash: (res && res.hash) || null };
+          } catch (err) {
+            if (err && (err.type === 'stale' || (err.data && err.data.current_hash !== undefined))) {
+              wizardToast(
+                host,
+                'IUMBTEMS settings',
+                'Config changed on disk since it was read; refusing the stale write. ' +
+                  'Re-open the wizard for a fresh snapshot — nothing was written.'
+              );
+              return { ok: false, reason: 'stale', written: false };
+            }
+            const failure = err && (err.rpcType || err.type);
+            if (failure === 'invalid' || failure === 'conflict') {
+              wizardToast(
+                host,
+                'IUMBTEMS settings',
+                `Save failed: ${(err && err.message) || err} — nothing was written.`
+              );
+              return { ok: false, reason: 'save-failed', written: false };
+            }
+            degradedRpcToast(host, 'write failed');
+            rpc = null;
+          }
+        }
         const guard =
           opts && (opts.expected_hash !== undefined || opts.expectedHash !== undefined)
             ? { expected_hash: opts.expected_hash, expectedHash: opts.expectedHash }
@@ -904,6 +1171,11 @@ export async function openSettingsWizard(host, root, opts = {}) {
             'IUMBTEMS settings',
             `Saved ${res.path} — applies to the next swarm run.`
           );
+          try {
+            await writeUiPrefs(host, { lastSavedAt: new Date().toISOString() });
+          } catch {
+            /* UI prefs are best-effort */
+          }
           return { ok: true, written: true, hash: res.hash };
         } catch (err) {
           if (err && err.code === 'CONFIG_STALE') {
@@ -941,7 +1213,7 @@ export async function openSettingsPanel(host, root, opts = {}) {
   try {
     const baseDir = researchDirOf(host, root);
     const env = (opts && opts.env) || process.env;
-    const body = formatSettingsText(baseDir, env);
+    const body = await effectiveSettingsBody(host, baseDir, env);
     let show = null;
     try {
       if (typeof host?.ui?.panel === 'function') show = host.ui.panel.bind(host.ui);

package/runner/mcp_server.py

@@ -145,6 +145,35 @@ def _allows_null(schema: Dict[str, Any]) -> bool:
     return types == "null"
 
 
+def _legacy_pin_migration_pending(base_dir: str) -> bool:
+    """Would the legacy-pin migration apply on the next write? (read-only)
+
+    Phase-04 R11: the `show` leg reports this WITHOUT persisting, so a read API
+    stays side-effect free. Mirrors `heal_config`'s decision — the on-disk file
+    carries a legacy ``["claude", "-p"]`` pin AND the would-be-persisted config
+    passes canonical validation (an invalid file is never healed, R1) — but
+    never writes.
+    """
+    try:
+        from skills.swarm_config.configure import (
+            load_config,
+            migrate_legacy_agent_backends,
+            validate_config,
+        )
+
+        cfg_file = Path(base_dir) / "config.json"
+        if not cfg_file.is_file():
+            return False
+        raw = json.loads(cfg_file.read_bytes().decode("utf-8"))
+        if not isinstance(raw, dict):
+            return False
+        if not migrate_legacy_agent_backends(raw):
+            return False
+        return not validate_config(load_config(base_dir))
+    except Exception:
+        return False
+
+
 def _handle_config(args: Dict[str, Any]) -> str:
     """Inspect or modify swarm parameters in .research/config.json.
 
@@ -154,10 +183,11 @@ def _handle_config(args: Dict[str, Any]) -> str:
     locked, validated, atomic, unknown-key-preserving) with an optional
     `expected_hash` guard (both `expected_hash` and `expectedHash` spellings).
     """
+    import hashlib
+
     from skills.swarm_config.configure import (
+        DEFAULT_CONFIG,
         ConfigError,
-        config_hash,
-        heal_config,
         load_config,
         merge_config,
         save_config,
@@ -167,10 +197,6 @@ def _handle_config(args: Dict[str, Any]) -> str:
 
     base_dir = str(_resolve_base_dir(args))
     cfg = load_config(base_dir)
-    # Persist a legacy ["claude", "-p"] agent pin migration so an OpenCode host
-    # stops silently spawning Claude on every run. `heal_config` refuses to
-    # persist a schema-rejected file (R1).
-    healed = heal_config(base_dir)
 
     # R4: both spellings must agree; never silently prefer one.
     snake = args.get("expected_hash")
@@ -240,7 +266,16 @@ def _handle_config(args: Dict[str, Any]) -> str:
         )
 
     if not updates:
-        return _tool_text({"status": "current", "config": cfg, "migrated": healed})
+        # R11: the show leg is strictly read-only — a settings panel reads
+        # through it, so it must never persist the legacy-pin migration. Report
+        # whether a migration is pending; only the write leg below heals.
+        return _tool_text(
+            {
+                "status": "current",
+                "config": cfg,
+                "migrated": _legacy_pin_migration_pending(base_dir),
+            }
+        )
 
     candidate = merge_config(cfg, updates)
     problems = validate_config(candidate)
@@ -255,6 +290,11 @@ def _handle_config(args: Dict[str, Any]) -> str:
             }
         )
 
+    # R12 (F1): do NOT heal before saving. The candidate is already migrated in
+    # memory (`load_config`) and `save_config` merges it over the on-disk bytes,
+    # so the legacy-pin migration persists as a side effect — while the caller's
+    # `expected_hash` guard still matches the bytes they read. A heal-before-save
+    # rewrote the file and turned a valid guarded write into a false `stale`.
     try:
         save_config(
             candidate,
@@ -269,12 +309,43 @@ def _handle_config(args: Dict[str, Any]) -> str:
             payload.update(exc.details)
         return _tool_text(payload)
 
+    # R10 (single read): derive BOTH the effective config and the hash from ONE
+    # read of the just-published bytes, so the storage mirror and the `changed`
+    # event can never receive an era-A config paired with an era-B hash.
+    # `save_config` publishes a fully defaults-merged, validated object
+    # atomically, so the bytes on disk are already the effective config; the
+    # earlier `load_config()` + `config_hash()` were two independent reads.
+    cfg_file = Path(base_dir) / "config.json"
+    try:
+        raw_bytes = cfg_file.read_bytes()
+    except OSError:
+        raw_bytes = None
+    if raw_bytes is None:
+        # A successful save always leaves bytes; keep the payload shape without
+        # a second read in this (unreachable) defensive branch.
+        return _tool_text(
+            {
+                "status": "updated",
+                "config": candidate,
+                "written_to": str(cfg_file),
+                "hash": None,
+            }
+        )
+    try:
+        parsed = json.loads(raw_bytes.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        parsed = None
+    effective = (
+        merge_config(DEFAULT_CONFIG, parsed)
+        if isinstance(parsed, dict)
+        else merge_config(DEFAULT_CONFIG, {})
+    )
     return _tool_text(
         {
             "status": "updated",
-            "config": load_config(base_dir),
-            "written_to": str(Path(base_dir) / "config.json"),
-            "hash": config_hash(base_dir),
+            "config": effective,
+            "written_to": str(cfg_file),
+            "hash": hashlib.sha256(raw_bytes).hexdigest(),
         }
     )
 

package/runner/research_swarm.py

@@ -146,7 +146,10 @@ def _verify_threshold(config: Optional[Dict[str, Any]]) -> float:
 
 
 def _config_child_env(
-    base_dir: Path, agent_cwd: str, config: Optional[Dict[str, Any]]
+    base_dir: Path,
+    agent_cwd: str,
+    config: Optional[Dict[str, Any]],
+    role: Optional[str] = None,
 ) -> Dict[str, str]:
     """Environment for a spawned agent child: base env + config passthrough.
 
@@ -158,6 +161,11 @@ def _config_child_env(
     * `cache_ttl_days`          -> IUMBTEMS_FETCH_TTL_DAYS (webcache, when set)
     * `search_timeout_s`        -> IUMBTEMS_SEARCH_TIMEOUT_S (search.py, when set)
     * `searxng_url`             -> SEARXNG_URL (search provider + searxng_mcp)
+    * `role`                    -> IUMBTEMS_AGENT_ROLE (S3 temperature spike: lets
+      a spawned `opencode run` child know its swarm role so the project
+      plugin's `session.hook("context")` can key per-role temperature off
+      `event.agent` — if the child loads the project plugin; absent/empty
+      role exports nothing)
     """
     cfg = config or {}
     env: Dict[str, str] = {
@@ -181,6 +189,8 @@ def _config_child_env(
     searxng = cfg.get("searxng_url")
     if isinstance(searxng, str) and searxng.strip():
         env["SEARXNG_URL"] = searxng.strip()
+    if role:
+        env["IUMBTEMS_AGENT_ROLE"] = str(role)
     return env
 
 
@@ -524,7 +534,7 @@ class SwarmRunner:
                 # IUMBTEMS_RESEARCH_DIR points agent-invoked skill scripts
                 # (search.py/hasher.py) at this workspace for retrieval telemetry;
                 # the cache/search keys ride the same env channel.
-                env=_config_child_env(self.base_dir, agent_cwd, self.config),
+                env=_config_child_env(self.base_dir, agent_cwd, self.config, role),
                 # stdin MUST be DEVNULL: `opencode run` reads piped stdin to
                 # EOF before starting, and the MCP server's inherited stdin
                 # pipe is held open by the harness — every agent hung forever

package/runner/schemas.py

@@ -311,6 +311,7 @@ CONFIG_DEFAULTS: Dict[str, Any] = {
     },
     "opencode_auto": None,
     "opencode_agent": None,
+    "mcp_servers": {},
 }
 
 
@@ -590,6 +591,23 @@ CONFIG: Dict[str, Any] = {
                 "agents.<role>.opencode_agent wins."
             ),
         },
+        "mcp_servers": {
+            "type": "object",
+            "default": copy.deepcopy(CONFIG_DEFAULTS["mcp_servers"]),
+            "x-label": "MCP Servers",
+            "x-scope": "dispatch",
+            "x-restart": "next-run",
+            "description": (
+                "Persisted toggle map for the plugin-controllable MCP server "
+                "set (bundled `iumbtems` server plus research servers declared "
+                "in the project OpenCode config). Keys are server names; "
+                "values are booleans (true = enabled, false = disabled). "
+                "Absent keys mean enabled. Applied via ctx.mcp.transform "
+                "(`disabled` reconcile); the catalog file "
+                "config/mcp-research-servers.json is never modified."
+            ),
+            "additionalProperties": {"type": "boolean"},
+        },
     },
 }