rterm-backend 3.1.3 → 3.1.4

package/bin/gybackend.cjs

@@ -374859,6 +374859,8 @@ function pickBackendSnapshot(raw) {
     agentspan: raw.agentspan,
     webIntel: raw.webIntel,
     nats: raw.nats,
+    synapse: raw.synapse,
+    numbat: raw.numbat,
     gateway: raw.gateway,
     layout: raw.layout,
     recursionLimit: raw.recursionLimit,
@@ -374940,6 +374942,8 @@ function normalizeBackendSettings(settings) {
   next.agentspan = normalizeAgentspanSettings(next.agentspan);
   next.webIntel = normalizeWebIntelSettings(next.webIntel);
   next.nats = normalizeNatsSettings(next.nats);
+  next.synapse = normalizeSynapseSettings(next.synapse);
+  next.numbat = normalizeNumbatSettings(next.numbat);
   next.schemaVersion = BACKEND_SETTINGS_SCHEMA_VERSION;
   return next;
 }
@@ -375158,6 +375162,41 @@ function normalizeNatsSettings(raw) {
     ...hasAuth ? { auth: auth2 } : {}
   };
 }
+function normalizeSynapseSettings(raw) {
+  const src = isObject5(raw) ? raw : {};
+  const url2 = typeof src.url === "string" && src.url.trim() ? src.url.trim() : void 0;
+  const servers = Array.isArray(src.servers) ? src.servers.filter((s) => typeof s === "string" && s.trim().length > 0).map((s) => s.trim()) : void 0;
+  const prefix = typeof src.prefix === "string" && src.prefix.trim() ? src.prefix.trim() : void 0;
+  const agentId = typeof src.agentId === "string" && src.agentId.trim() ? src.agentId.trim() : void 0;
+  const rawAuth = isObject5(src.auth) ? src.auth : void 0;
+  const str3 = (v) => typeof v === "string" && v.trim() ? v : void 0;
+  const authKeys = ["token", "tokenSecretRef", "username", "password", "passwordSecretRef", "nkeySeed", "jwt", "jwtSeed", "creds", "tlsCert", "tlsKey", "tlsCa"];
+  const auth2 = rawAuth ? Object.fromEntries(authKeys.filter((k) => str3(rawAuth[k])).map((k) => [k, str3(rawAuth[k])])) : void 0;
+  const hasAuth = auth2 && Object.keys(auth2).length > 0;
+  return {
+    enabled: src.enabled !== false,
+    ...url2 ? { url: url2 } : {},
+    ...servers && servers.length > 0 ? { servers } : {},
+    ...prefix ? { prefix } : {},
+    ...agentId ? { agentId } : {},
+    ...hasAuth ? { auth: auth2 } : {}
+  };
+}
+function normalizeNumbatSettings(raw) {
+  const src = isObject5(raw) ? raw : {};
+  const binaryPath = typeof src.binaryPath === "string" && src.binaryPath.trim() ? src.binaryPath.trim() : void 0;
+  const recordsPath = typeof src.recordsPath === "string" && src.recordsPath.trim() ? src.recordsPath.trim() : void 0;
+  const ingestToken = typeof src.ingestToken === "string" && src.ingestToken.trim() ? src.ingestToken.trim() : void 0;
+  const sev = typeof src.minSeverity === "string" ? src.minSeverity.toLowerCase() : "";
+  const minSeverity = ["info", "low", "medium", "high", "critical"].includes(sev) ? sev : void 0;
+  return {
+    enabled: src.enabled !== false,
+    ...binaryPath ? { binaryPath } : {},
+    ...recordsPath ? { recordsPath } : {},
+    ...ingestToken ? { ingestToken } : {},
+    ...minSeverity ? { minSeverity } : {}
+  };
+}
 function migrateBackendToV3(settings) {
   const next = { ...settings };
   delete next.language;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rterm-backend",
-  "version": "3.1.3",
-  "description": "Headless AI-native backend for RTerm / neuralOS — v3.1.3: settings.nats preserved through migration (NATS mesh now configurable). v3.1.2 added the comprehensive NATS event mesh (token/user-pass/NKey/JWT/creds/TLS auth, JetStream, Key-Value, request/reply). Transports (SSH/serial/local) and SQLite install automatically.",
+  "version": "3.1.4",
+  "description": "Headless AI-native backend for RTerm / neuralOS — v3.1.4: synapse-bridge (Synapse mesh interop: discover/dispatch/register mesh agents) + numbat-bridge (Numbat endpoint AI-agent detection → triggers) plugins. 11 plugins total. Transports (SSH/serial/local), SQLite, and NATS libs install automatically.",
   "main": "bin/gybackend.cjs",
   "bin": { "gybackend": "bin/gybackend.cjs" },
   "license": "MIT",

package/plugins/numbat-bridge/index.mjs

@@ -0,0 +1,229 @@
+/**
+ * numbat-bridge — RTerm ↔ Numbat (endpoint AI-agent detection) integration.
+ *
+ * Numbat = EDR for AI agents: endpoint visibility, CEL detection, forensic
+ * reconstruction. RTerm = control plane. This bridge wires them:
+ *   - DEPLOY: install/manage the numbat binary + hooks on hosts (via playbooks/exec).
+ *   - INGEST: accept Numbat findings (NDJSON records) delivered over HTTP or read
+ *     from a local records file, normalize them, and feed RTerm triggers.
+ *   - ACT: turn detections into governed actions (playbooks, MOP changes, incidents).
+ *
+ * Numbat detects; RTerm responds.
+ *
+ * Config (settings.numbat, or env):
+ *   enabled        — master switch (default true)
+ *   binaryPath     — path to the numbat binary (default "numbat" on PATH)
+ *   recordsPath    — local NDJSON records file to tail (default ~/.numbat/records.ndjson)
+ *   ingestToken    — bearer token the HTTP ingest endpoint requires (vault secretRef ok)
+ *   minSeverity    — only ingest findings at/above this severity (info|low|medium|high|critical)
+ */
+
+import { createRequire } from 'node:module'
+import { randomUUID } from 'node:crypto'
+
+const require = createRequire(import.meta.url)
+
+// ─── config ─────────────────────────────────────────────────────────────────
+
+export function resolveConfig(ctx = {}, env = process.env) {
+  const s = (typeof ctx.getSettings === 'function' ? ctx.getSettings() : ctx.settings) || {}
+  const b = s.numbat || {}
+  return {
+    enabled: b.enabled !== false,
+    binaryPath: b.binaryPath || env.NUMBAT_BIN || 'numbat',
+    recordsPath: b.recordsPath || env.NUMBAT_RECORDS || `${process.env.HOME}/.numbat/records.ndjson`,
+    ingestToken: b.ingestToken || undefined,
+    minSeverity: b.minSeverity || 'low',
+  }
+}
+
+const SEVERITY_ORDER = ['info', 'low', 'medium', 'high', 'critical']
+function severityAtLeast(sev, min) {
+  const i = SEVERITY_ORDER.indexOf(String(sev ?? 'info').toLowerCase())
+  const m = SEVERITY_ORDER.indexOf(String(min ?? 'low').toLowerCase())
+  return (i < 0 ? 0 : i) >= (m < 0 ? 0 : m)
+}
+
+// ─── record normalization ───────────────────────────────────────────────────
+
+/** Normalize a Numbat NDJSON record (event/finding/enforcement/indicator/scan) into
+ * a compact RTerm finding. Returns null for records that shouldn't be ingested. */
+export function normalizeRecord(rec, cfg) {
+  if (!rec || typeof rec !== 'object') return null
+  const type = rec.record_type ?? rec.type ?? 'event'
+  const severity = rec.severity ?? rec.rule_severity ?? rec.level ?? 'info'
+  // Only findings + high-signal events become trigger inputs; raw events are noise.
+  const isFinding = type === 'finding' || type === 'enforcement' || type === 'indicator'
+  if (!isFinding && type === 'event' && !severityAtLeast(severity, 'high')) return null
+  if (!severityAtLeast(severity, cfg.minSeverity)) return null
+  return {
+    id: rec.id ?? rec.record_id ?? randomUUID(),
+    source: 'numbat',
+    recordType: type,
+    severity,
+    ruleId: rec.rule_id ?? rec.rule?.id ?? undefined,
+    title: rec.title ?? rec.rule_name ?? rec.rule?.name ?? type,
+    agent: rec.agent ?? rec.agent_id ?? rec.source?.agent ?? undefined,
+    host: rec.host ?? rec.hostname ?? rec.source?.host ?? undefined,
+    summary: rec.summary ?? rec.description ?? rec.content_preview ?? undefined,
+    ts: rec.ts ?? rec.timestamp ?? new Date().toISOString(),
+    raw: rec,
+  }
+}
+
+/** Parse an NDJSON blob (one JSON record per line) into normalized findings. */
+export function parseNdjson(text, cfg) {
+  const out = []
+  for (const line of String(text ?? '').split(/\r?\n/)) {
+    const t = line.trim()
+    if (!t) continue
+    try { const n = normalizeRecord(JSON.parse(t), cfg); if (n) out.push(n) } catch { /* skip malformed */ }
+  }
+  return out
+}
+
+// ─── deploy (run numbat commands on a host) ─────────────────────────────────
+
+/** Build the numbat CLI argv for a deploy action. Pure — testable. */
+export function buildDeployCommand(action, opts = {}) {
+  const agent = opts.agent || 'codex'
+  switch (action) {
+    case 'inventory': return ['agents']
+    case 'scan': return opts.agent ? ['scan', '--agent', agent] : ['scan']
+    case 'install-monitor': return ['hook', 'install', '--agent', agent, '--emit', opts.emit ?? 'all']
+    case 'install-enforce': return ['hook', 'install', '--agent', agent, '--emit', opts.emit ?? 'all', ...(opts.rulesDir ? ['--rules-dir', opts.rulesDir] : []), '--enforce']
+    case 'status': return ['hook', 'status', '--agent', agent]
+    case 'uninstall': return ['hook', 'uninstall', '--agent', agent]
+    default: throw new Error(`unknown numbat deploy action: ${action}`)
+  }
+}
+
+/** Run a numbat command via the plugin's exec capability (local or remote host). */
+async function runNumbat(ctx, cfg, argv, target) {
+  const cmdline = [cfg.binaryPath, ...argv].map((a) => (/\s/.test(a) ? `"${a}"` : a)).join(' ')
+  // Prefer the plugin exec/runCommand capability when available (policy-gated).
+  if (typeof ctx.runCommand === 'function') {
+    return ctx.runCommand({ command: cmdline, target })
+  }
+  if (typeof ctx.exec === 'function') {
+    return ctx.exec(cmdline, { target })
+  }
+  // Local fallback via child_process.
+  const { execFile } = require('node:child_process')
+  return new Promise((resolve) => {
+    execFile(cfg.binaryPath, argv, { timeout: 60000 }, (err, stdout, stderr) => {
+      resolve({ ok: !err, exitCode: err?.code ?? 0, stdout: String(stdout ?? ''), stderr: String(stderr ?? ''), error: err ? String(err.message) : undefined })
+    })
+  })
+}
+
+// ─── plugin registration ────────────────────────────────────────────────────
+
+async function guarded(fn, log) {
+  try { return await fn() } catch (e) {
+    const msg = e?.message ?? String(e)
+    log?.(`[numbat] ${msg}`)
+    return { error: msg, hint: 'Is numbat installed? (go install github.com/perplexityai/numbat/cmd/numbat@latest, or download a release). Configure settings.numbat.' }
+  }
+}
+
+export function register(ctx) {
+  const { registerTool, registerTrigger, registerPanel, log } = ctx
+  const cfg = resolveConfig(ctx)
+
+  registerTool({
+    name: 'numbat_health',
+    description: 'Check the numbat binary is present and report its version + the configured records path.',
+    params: {},
+    handler: async () => guarded(async () => {
+      const r = await runNumbat(ctx, cfg, ['version'])
+      return { binaryPath: cfg.binaryPath, recordsPath: cfg.recordsPath, ...r }
+    }, log),
+  })
+
+  registerTool({
+    name: 'numbat_deploy',
+    description: 'Deploy/manage numbat on a host: inventory agents, scan, install monitor-only or enforce hooks, check status, or uninstall. Runs the numbat CLI via the policy-gated exec path (local or a target host).',
+    params: {
+      action: { type: 'string', description: 'inventory | scan | install-monitor | install-enforce | status | uninstall' },
+      agent: { type: 'string', description: 'Target agent (e.g. codex)', optional: true },
+      target: { type: 'string', description: 'Host/terminal to run on (default local)', optional: true },
+      rulesDir: { type: 'string', description: 'Custom rules dir (for enforce)', optional: true },
+      emit: { type: 'string', description: 'Emit mode (default all)', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      if (!p?.action) return { error: 'numbat_deploy needs an action' }
+      const argv = buildDeployCommand(p.action, p)
+      const r = await runNumbat(ctx, cfg, argv, p?.target)
+      return { action: p.action, argv, ...r }
+    }, log),
+  })
+
+  registerTool({
+    name: 'numbat_ingest',
+    description: 'Ingest Numbat NDJSON records (events/findings/enforcement/indicators) — normalize them into RTerm findings and fire the numbat_finding trigger for each. Pass ndjson text directly or read from the configured records file.',
+    params: {
+      ndjson: { type: 'string', description: 'NDJSON records (one JSON per line)', optional: true },
+      fromFile: { type: 'boolean', description: 'Read from recordsPath instead of inline ndjson', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      let text = p?.ndjson
+      if (!text && (p?.fromFile || !p?.ndjson)) {
+        const fs = require('node:fs')
+        try { text = fs.readFileSync(cfg.recordsPath, 'utf8') } catch { text = '' }
+      }
+      const findings = parseNdjson(text ?? '', cfg)
+      // Fire a trigger event per finding (the trigger engine routes these).
+      if (typeof ctx.emitEvent === 'function') {
+        for (const f of findings) ctx.emitEvent({ source: 'numbat', ...f })
+      }
+      return { ingested: findings.length, findings }
+    }, log),
+  })
+
+  registerTool({
+    name: 'numbat_findings_summary',
+    description: 'Summarize Numbat findings from the records file by severity + rule + agent (quick threat picture).',
+    params: {},
+    handler: async () => guarded(async () => {
+      const fs = require('node:fs')
+      let text = ''
+      try { text = fs.readFileSync(cfg.recordsPath, 'utf8') } catch { /* none */ }
+      const findings = parseNdjson(text, { ...cfg, minSeverity: 'info' })
+      const bySeverity = {}
+      const byRule = {}
+      const byAgent = {}
+      for (const f of findings) {
+        bySeverity[f.severity] = (bySeverity[f.severity] ?? 0) + 1
+        if (f.ruleId) byRule[f.ruleId] = (byRule[f.ruleId] ?? 0) + 1
+        if (f.agent) byAgent[f.agent] = (byAgent[f.agent] ?? 0) + 1
+      }
+      return { total: findings.length, bySeverity, byRule, byAgent, recordsPath: cfg.recordsPath }
+    }, log),
+  })
+
+  registerTrigger({
+    name: 'numbat_finding',
+    description: 'Fires when a Numbat detection (finding/enforcement/indicator, or high-severity event) is ingested. Use to auto-remediate: isolate the host, kill the agent, open an incident, or run a playbook.',
+    match: (event) => {
+      if (event?.source !== 'numbat') return false
+      return severityAtLeast(event.severity, 'medium')
+    },
+    action: 'propose-change',
+  })
+
+  registerPanel({
+    name: 'numbat-findings',
+    title: 'Numbat Findings',
+    render: (data) => {
+      const rows = (Array.isArray(data) ? data : []).map((f) =>
+        `<tr><td>${f.severity ?? ''}</td><td>${f.title ?? ''}</td><td>${f.agent ?? ''}</td><td>${f.host ?? ''}</td></tr>`
+      ).join('')
+      return `<div class="numbat-findings"><h3>Numbat Findings</h3><p>Records: ${cfg.recordsPath}</p><table><thead><tr><th>Severity</th><th>Title</th><th>Agent</th><th>Host</th></tr></thead><tbody>${rows}</tbody></table></div>`
+    },
+  })
+
+  log(`[numbat] numbat-bridge registered: 4 tools, 1 trigger, 1 panel (bin=${cfg.binaryPath})`)
+}
+
+export default { register, resolveConfig, normalizeRecord, parseNdjson, buildDeployCommand }

package/plugins/numbat-bridge/numbat-bridge.extreme.spec.mjs

@@ -0,0 +1,148 @@
+import { register, resolveConfig, normalizeRecord, parseNdjson, buildDeployCommand } from './index.mjs'
+
+const cases = []
+function test(n, r) { cases.push({ name: n, run: r }) }
+function assert(c, m) { if (!c) throw new Error(m ?? 'assertion failed') }
+function eq(a, b, m) { if (a !== b) throw new Error(`${m ?? 'eq'}: expected ${JSON.stringify(b)}, got ${JSON.stringify(a)}`) }
+
+function mkCtx(settings = {}, extra = {}) {
+  const tools = new Map(); const triggers = []; const panels = []; const logs = []; const emitted = []
+  const ctx = {
+    settings: { numbat: settings },
+    registerTool: (t) => tools.set(t.name, t),
+    registerTrigger: (t) => triggers.push(t),
+    registerPanel: (p) => panels.push(p),
+    log: (l) => logs.push(l),
+    emitEvent: (e) => emitted.push(e),
+    ...extra,
+  }
+  return { tools, triggers, panels, logs, emitted, ctx }
+}
+
+const CFG = { minSeverity: 'low' }
+
+// ─── config ─────────────────────────────────────────────────────────────────
+
+test('resolveConfig defaults', () => {
+  const c = resolveConfig({ settings: {} }, {})
+  eq(c.binaryPath, 'numbat', 'default binary')
+  eq(c.minSeverity, 'low', 'default minSeverity')
+  eq(c.enabled, true, 'enabled default')
+  assert(c.recordsPath.includes('.numbat'), 'records path under ~/.numbat')
+})
+
+// ─── normalizeRecord ────────────────────────────────────────────────────────
+
+test('normalizeRecord maps a finding record', () => {
+  const rec = { record_type: 'finding', severity: 'high', rule_id: 'cloud-metadata', agent: 'codex', host: 'web-01', summary: 'metadata access' }
+  const n = normalizeRecord(rec, CFG)
+  eq(n.source, 'numbat', 'source')
+  eq(n.recordType, 'finding', 'type')
+  eq(n.severity, 'high', 'severity')
+  eq(n.ruleId, 'cloud-metadata', 'ruleId')
+  eq(n.agent, 'codex', 'agent')
+  eq(n.host, 'web-01', 'host')
+})
+
+test('normalizeRecord drops low-signal raw events (noise)', () => {
+  const rec = { record_type: 'event', severity: 'info', summary: 'routine' }
+  eq(normalizeRecord(rec, CFG), null, 'info event dropped')
+})
+
+test('normalizeRecord keeps high-severity events', () => {
+  const rec = { record_type: 'event', severity: 'critical', summary: 'metadata 169.254.169.254' }
+  const n = normalizeRecord(rec, CFG)
+  assert(n, 'critical event kept')
+  eq(n.severity, 'critical', 'severity')
+})
+
+test('normalizeRecord enforces minSeverity', () => {
+  const rec = { record_type: 'finding', severity: 'low', rule_id: 'x' }
+  eq(normalizeRecord(rec, { minSeverity: 'high' }), null, 'low finding below high threshold dropped')
+  assert(normalizeRecord(rec, { minSeverity: 'low' }), 'low finding at low threshold kept')
+})
+
+// ─── parseNdjson ────────────────────────────────────────────────────────────
+
+test('parseNdjson parses multiple records, skips malformed', () => {
+  const nd = [
+    JSON.stringify({ record_type: 'finding', severity: 'high', rule_id: 'r1', agent: 'codex' }),
+    'not json',
+    JSON.stringify({ record_type: 'event', severity: 'info' }),
+    JSON.stringify({ record_type: 'indicator', severity: 'medium', rule_id: 'r2' }),
+  ].join('\n')
+  const out = parseNdjson(nd, CFG)
+  eq(out.length, 2, 'two findings (finding + indicator; info event + malformed dropped)')
+  eq(out[0].ruleId, 'r1', 'first rule')
+  eq(out[1].recordType, 'indicator', 'second type')
+})
+
+// ─── buildDeployCommand ─────────────────────────────────────────────────────
+
+test('buildDeployCommand builds correct argv per action', () => {
+  eq(JSON.stringify(buildDeployCommand('inventory')), JSON.stringify(['agents']), 'inventory')
+  eq(JSON.stringify(buildDeployCommand('scan', { agent: 'codex' })), JSON.stringify(['scan', '--agent', 'codex']), 'scan')
+  eq(JSON.stringify(buildDeployCommand('install-monitor', { agent: 'codex' })), JSON.stringify(['hook', 'install', '--agent', 'codex', '--emit', 'all']), 'install-monitor')
+  const en = buildDeployCommand('install-enforce', { agent: 'codex', rulesDir: './policy' })
+  assert(en.includes('--enforce'), 'enforce flag')
+  assert(en.includes('--rules-dir'), 'rules-dir flag')
+  eq(JSON.stringify(buildDeployCommand('status', { agent: 'codex' })), JSON.stringify(['hook', 'status', '--agent', 'codex']), 'status')
+})
+
+test('buildDeployCommand throws on unknown action', () => {
+  let threw = false
+  try { buildDeployCommand('bogus') } catch { threw = true }
+  assert(threw, 'expected throw')
+})
+
+// ─── register wiring ────────────────────────────────────────────────────────
+
+test('register wires 4 tools, 1 trigger, 1 panel', () => {
+  const { tools, triggers, panels, ctx } = mkCtx()
+  register(ctx)
+  eq(tools.size, 4, 'tool count')
+  for (const n of ['numbat_health', 'numbat_deploy', 'numbat_ingest', 'numbat_findings_summary']) assert(tools.has(n), `missing ${n}`)
+  eq(triggers.length, 1, 'trigger count')
+  eq(triggers[0].name, 'numbat_finding', 'trigger name')
+  eq(panels.length, 1, 'panel count')
+})
+
+// ─── ingest → trigger ───────────────────────────────────────────────────────
+
+test('numbat_ingest normalizes + emits a trigger event per finding', async () => {
+  const { tools, emitted, ctx } = mkCtx()
+  register(ctx)
+  const nd = [
+    JSON.stringify({ record_type: 'finding', severity: 'high', rule_id: 'cloud-metadata', agent: 'codex', host: 'web-01' }),
+    JSON.stringify({ record_type: 'finding', severity: 'medium', rule_id: 'r2', agent: 'cursor' }),
+  ].join('\n')
+  const r = await tools.get('numbat_ingest').handler({ ndjson: nd })
+  eq(r.ingested, 2, 'ingested count')
+  eq(emitted.length, 2, 'emitted events')
+  eq(emitted[0].source, 'numbat', 'event source')
+  eq(emitted[0].ruleId, 'cloud-metadata', 'event ruleId')
+})
+
+// ─── trigger match ──────────────────────────────────────────────────────────
+
+test('numbat_finding trigger matches numbat-source medium+ severity', () => {
+  const { triggers, ctx } = mkCtx()
+  register(ctx)
+  const t = triggers[0]
+  assert(t.match({ source: 'numbat', severity: 'high' }), 'matches high')
+  assert(t.match({ source: 'numbat', severity: 'medium' }), 'matches medium')
+  assert(!t.match({ source: 'numbat', severity: 'low' }), 'rejects low')
+  assert(!t.match({ source: 'other', severity: 'high' }), 'rejects other source')
+})
+
+// ─── runner ─────────────────────────────────────────────────────────────────
+async function main() {
+  let pass = 0, fail = 0
+  for (const c of cases) {
+    try { await c.run(); pass++; console.log(`PASS ${c.name}`) }
+    catch (e) { fail++; console.log(`FAIL ${c.name}: ${e?.message ?? e}`) }
+  }
+  console.log(`\n${pass}/${pass + fail} passed, ${fail} failed`)
+  if (fail > 0) process.exit(1)
+}
+main()

package/plugins/numbat-bridge/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "numbat-bridge",
+  "version": "1.0.0",
+  "description": "Numbat bridge for RTerm — deploy Numbat (endpoint AI-agent detection/EDR) to hosts, ingest its findings (NDJSON events/findings/enforcement/indicators), and fire RTerm triggers to auto-remediate (isolate host, kill agent, open incident, run playbook). Numbat detects; RTerm responds. Config in Settings (numbat block).",
+  "entry": "index.mjs",
+  "tools": [
+    "numbat_health",
+    "numbat_deploy",
+    "numbat_ingest",
+    "numbat_findings_summary"
+  ],
+  "triggers": [
+    "numbat_finding"
+  ],
+  "panels": [
+    "numbat-findings"
+  ],
+  "permissions": [
+    "exec"
+  ]
+}

package/plugins/synapse-bridge/index.mjs

@@ -0,0 +1,252 @@
+/**
+ * synapse-bridge — RTerm ↔ Synapse mesh interop.
+ *
+ * Lets RTerm speak the Synapse protocol (v0.3.0) over a shared NATS server:
+ * discover live mesh agents, dispatch tasks to them, and register RTerm itself
+ * as a mesh agent (bidirectional federation). Built on the same NatsEventBus
+ * conventions (auth, request/reply, JetStream) added in v3.1.2.
+ *
+ * Config (settings.synapse, or env):
+ *   url        — NATS server (default nats://localhost:4222)
+ *   servers    — array of urls (takes precedence)
+ *   prefix     — mesh subject prefix (default "mesh")
+ *   agentId    — this instance's mesh agent id (default "rterm-001")
+ *   auth       — { token | username/password | nkeySeed | jwt/jwtSeed | creds | tls* }
+ *   enabled    — master switch (default true when a server is configured)
+ *
+ * Secrets may be inline or `secretRef` pointers resolved via the vault.
+ */
+
+import { createRequire } from 'node:module'
+import { randomUUID } from 'node:crypto'
+
+const require = createRequire(import.meta.url)
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+const j = (v) => enc.encode(JSON.stringify(v))
+const uj = (b) => JSON.parse(dec.decode(b))
+
+// ─── config resolution ──────────────────────────────────────────────────────
+
+export function resolveConfig(ctx = {}, env = process.env) {
+  const s = (typeof ctx.getSettings === 'function' ? ctx.getSettings() : ctx.settings) || {}
+  const block = s.synapse || {}
+  const servers = Array.isArray(block.servers) && block.servers.length > 0
+    ? block.servers
+    : (block.url || env.SYNAPSE_NATS_URL || env.NATS_URL || 'nats://localhost:4222')
+  return {
+    servers,
+    prefix: block.prefix || 'mesh',
+    agentId: block.agentId || env.SYNAPSE_AGENT_ID || 'rterm-001',
+    auth: block.auth || undefined,
+    enabled: block.enabled !== false,
+  }
+}
+
+/** Resolve auth secrets through the vault when secretRef-style values are used. */
+function resolveAuth(ctx, auth) {
+  if (!auth) return undefined
+  const out = { ...auth }
+  if (out.passwordSecretRef && typeof ctx.getSecret === 'function') {
+    try { out.password = ctx.getSecret(out.passwordSecretRef); delete out.passwordSecretRef } catch { /* leave unset */ }
+  }
+  if (out.tokenSecretRef && typeof ctx.getSecret === 'function') {
+    try { out.token = ctx.getSecret(out.tokenSecretRef); delete out.tokenSecretRef } catch { /* leave unset */ }
+  }
+  return out
+}
+
+// ─── transport (lazy NATS connection) ───────────────────────────────────────
+
+function loadTransport() {
+  try { return require('@nats-io/transport-node') } catch {
+    throw new Error('NATS transport (@nats-io/transport-node) is not available in this build')
+  }
+}
+
+function buildAuthenticator(t, auth) {
+  if (!auth) return undefined
+  const e = new TextEncoder()
+  if (auth.creds) return t.credsAuthenticator(typeof auth.creds === 'string' ? e.encode(auth.creds) : auth.creds)
+  if (auth.jwt) return t.jwtAuthenticator(auth.jwt, typeof auth.jwtSeed === 'string' ? e.encode(auth.jwtSeed) : auth.jwtSeed)
+  if (auth.nkeySeed) return t.nkeyAuthenticator(typeof auth.nkeySeed === 'string' ? e.encode(auth.nkeySeed) : auth.nkeySeed)
+  if (auth.token) return t.tokenAuthenticator(auth.token)
+  if (auth.username !== undefined) return t.usernamePasswordAuthenticator(auth.username, auth.password ?? '')
+  return undefined
+}
+
+let _conn = null
+async function connectMesh(ctx) {
+  if (_conn && !_conn.isClosed()) return _conn
+  const cfg = resolveConfig(ctx)
+  const t = loadTransport()
+  const auth = buildAuthenticator(t, resolveAuth(ctx, cfg.auth))
+  const copts = { servers: cfg.servers, name: cfg.agentId, ...(auth ? { authenticator: auth } : {}) }
+  const connectFn = (typeof ctx.natsConnect === 'function') ? ctx.natsConnect : (o) => t.connect(o)
+  _conn = await connectFn(copts)
+  return _conn
+}
+
+/** Test hook: inject a fake connection. */
+export function __setConnForTest(c) { _conn = c }
+
+// ─── Synapse envelope ───────────────────────────────────────────────────────
+
+export function envelope(type, payload, cfg, extra = {}) {
+  return {
+    v: '0.3.0',
+    id: randomUUID(),
+    type,
+    ts: new Date().toISOString(),
+    from: cfg.agentId,
+    trace: { trace_id: randomUUID(), span_id: randomUUID() },
+    payload,
+    ...extra,
+  }
+}
+
+// ─── core ops ───────────────────────────────────────────────────────────────
+
+export async function discoverAgents(ctx, filter = {}) {
+  const cfg = resolveConfig(ctx)
+  const nc = await connectMesh(ctx)
+  const msg = await nc.request(`${cfg.prefix}.registry.discover`, j(envelope('discover', filter, cfg)), { timeout: 4000 })
+  const reply = uj(msg.data)
+  const agents = Array.isArray(reply) ? reply : (reply.payload?.agents ?? reply.payload ?? reply)
+  return Array.isArray(agents) ? agents : []
+}
+
+export async function dispatchTask(ctx, target, skill, input = {}, opts = {}) {
+  const cfg = resolveConfig(ctx)
+  const nc = await connectMesh(ctx)
+  const env = envelope('request', { skill, input }, cfg, { to: target, task_id: randomUUID() })
+  const msg = await nc.request(`${cfg.prefix}.agent.${target}.inbox`, j(env), { timeout: opts.timeout ?? 30000 })
+  return uj(msg.data)
+}
+
+export async function registerSelf(ctx, manifest = {}) {
+  const cfg = resolveConfig(ctx)
+  const nc = await connectMesh(ctx)
+  const payload = {
+    agent_id: cfg.agentId,
+    name: manifest.name || 'RTerm / neuralOS',
+    type: 'agent',
+    capabilities: manifest.capabilities || ['ops-automation', 'playbooks', 'fleet-orchestration', 'mop-changes'],
+    skills: manifest.skills || [],
+    endpoint: `${cfg.prefix}.agent.${cfg.agentId}.inbox`,
+    availability: 'online',
+    ...manifest,
+  }
+  nc.publish(`${cfg.prefix}.registry.register`, j(envelope('register', payload, cfg)))
+  return { registered: cfg.agentId, endpoint: payload.endpoint }
+}
+
+// ─── plugin registration ────────────────────────────────────────────────────
+
+async function guarded(fn, log) {
+  try { return await fn() } catch (e) {
+    const msg = e?.message ?? String(e)
+    log?.(`[synapse] ${msg}`)
+    return { error: msg, hint: 'Is the NATS server running and the synapse block configured? (settings.synapse.url, default nats://localhost:4222).' }
+  }
+}
+
+export function register(ctx) {
+  const { registerTool, registerTrigger, registerPanel, log } = ctx
+  const cfg = resolveConfig(ctx)
+
+  registerTool({
+    name: 'synapse_health',
+    description: 'Check connectivity to the Synapse mesh (NATS server) and report the configured agent id + subject prefix.',
+    params: {},
+    handler: async () => guarded(async () => {
+      const nc = await connectMesh(ctx)
+      return { connected: !nc.isClosed(), agentId: cfg.agentId, prefix: cfg.prefix, servers: cfg.servers }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_discover',
+    description: 'Discover live Synapse mesh agents and their skills via the registry (mesh.registry.discover). Optional filter by capabilities/skill_ids/availability.',
+    params: {
+      capabilities: { type: 'array', description: 'Capabilities to match (all-of)', optional: true },
+      skill_ids: { type: 'array', description: 'Skill ids to match (all-of)', optional: true },
+      availability: { type: 'string', description: 'e.g. online', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      const filter = {}
+      if (p?.capabilities) filter.capabilities = p.capabilities
+      if (p?.skill_ids) filter.skill_ids = p.skill_ids
+      if (p?.availability) filter.availability = p.availability
+      const agents = await discoverAgents(ctx, filter)
+      return { count: agents.length, agents }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_dispatch',
+    description: 'Dispatch a task to a Synapse mesh agent (mesh.agent.{id}.inbox) and await its response. The task is durably tracked in the mesh.',
+    params: {
+      target: { type: 'string', description: 'Target agent id (e.g. grip-cli-001)' },
+      skill: { type: 'string', description: 'Skill id from the target manifest' },
+      input: { type: 'object', description: 'Input payload for the skill', optional: true },
+      timeout: { type: 'number', description: 'Reply timeout ms (default 30000)', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      if (!p?.target || !p?.skill) return { error: 'synapse_dispatch needs target and skill' }
+      const response = await dispatchTask(ctx, p.target, p.skill, p.input ?? {}, { timeout: p.timeout })
+      return { target: p.target, skill: p.skill, response }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_register',
+    description: 'Register this RTerm/neuralOS instance as a Synapse mesh agent (mesh.registry.register) so other mesh agents can discover and dispatch to it.',
+    params: {
+      name: { type: 'string', optional: true },
+      capabilities: { type: 'array', optional: true },
+      skills: { type: 'array', optional: true },
+    },
+    handler: async (p) => guarded(async () => registerSelf(ctx, p ?? {}), log),
+  })
+
+  registerTool({
+    name: 'synapse_agents_summary',
+    description: 'Compact summary of live Synapse mesh agents (id, name, skill count, first skills) for quick situational awareness.',
+    params: {},
+    handler: async () => guarded(async () => {
+      const agents = await discoverAgents(ctx, {})
+      return {
+        count: agents.length,
+        agents: agents.map((a) => ({
+          id: a.id ?? a.agent_id ?? a.name,
+          name: a.name,
+          skillCount: (a.skills ?? a.capabilities ?? []).length,
+          skills: (a.skills ?? a.capabilities ?? []).slice(0, 5).map((s) => (typeof s === 'string' ? s : s.id ?? s.name)),
+        })),
+      }
+    }, log),
+  })
+
+  registerTrigger({
+    name: 'synapse_mesh_event',
+    description: 'Fires when a Synapse mesh event (task failure, reputation penalty, approval request) is observed. Use for cross-mesh remediation.',
+    match: (event) => event?.source === 'synapse',
+    action: 'propose-change',
+  })
+
+  registerPanel({
+    name: 'synapse-mesh-agents',
+    title: 'Synapse Mesh Agents',
+    render: (data) => {
+      const rows = (Array.isArray(data) ? data : []).map((a) =>
+        `<tr><td>${a.id ?? ''}</td><td>${a.name ?? ''}</td><td>${a.skillCount ?? ''}</td></tr>`
+      ).join('')
+      return `<div class="synapse-mesh"><h3>Synapse Mesh Agents</h3><p>Agent: ${cfg.agentId} · Prefix: ${cfg.prefix}</p><table><thead><tr><th>Id</th><th>Name</th><th>Skills</th></tr></thead><tbody>${rows}</tbody></table></div>`
+    },
+  })
+
+  log(`[synapse] synapse-bridge registered: 5 tools, 1 trigger, 1 panel (agent=${cfg.agentId}, prefix=${cfg.prefix})`)
+}
+
+export default { register, resolveConfig, envelope, discoverAgents, dispatchTask, registerSelf }

package/plugins/synapse-bridge/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "synapse-bridge",
+  "version": "1.0.0",
+  "description": "Synapse mesh bridge for RTerm — discover live Synapse agents, dispatch tasks to them, and register RTerm itself as a mesh agent (bidirectional federation). Speaks the Synapse protocol (v0.3.0) over a shared NATS server using the v3.1.2 auth/request-reply/JetStream transport. Config in Settings (synapse block); secrets via the vault.",
+  "entry": "index.mjs",
+  "tools": [
+    "synapse_health",
+    "synapse_discover",
+    "synapse_dispatch",
+    "synapse_register",
+    "synapse_agents_summary"
+  ],
+  "triggers": [
+    "synapse_mesh_event"
+  ],
+  "panels": [
+    "synapse-mesh-agents"
+  ],
+  "permissions": [
+    "exec"
+  ]
+}

package/plugins/synapse-bridge/synapse-bridge.extreme.spec.mjs

@@ -0,0 +1,174 @@
+import { register, resolveConfig, envelope, discoverAgents, dispatchTask, registerSelf, __setConnForTest } from './index.mjs'
+
+const cases = []
+function test(n, r) { cases.push({ name: n, run: r }) }
+function assert(c, m) { if (!c) throw new Error(m ?? 'assertion failed') }
+function eq(a, b, m) { if (a !== b) throw new Error(`${m ?? 'eq'}: expected ${JSON.stringify(b)}, got ${JSON.stringify(a)}`) }
+
+// ─── fake NATS connection ───────────────────────────────────────────────────
+function fakeConn() {
+  const published = []
+  const requests = new Map()
+  return {
+    isClosed: () => false,
+    publish(subject, data) { published.push({ subject, data: JSON.parse(new TextDecoder().decode(data)) }) },
+    async request(subject, data, _opts) {
+      const h = requests.get(subject)
+      const reply = h ? h(JSON.parse(new TextDecoder().decode(data))) : { ok: true }
+      return { data: new TextEncoder().encode(JSON.stringify(reply)) }
+    },
+    _on(subject, h) { requests.set(subject, h) },
+    published,
+    drain: async () => {},
+  }
+}
+
+function mkCtx(settings = {}, conn) {
+  const tools = new Map(); const triggers = []; const panels = []; const logs = []
+  const ctx = {
+    settings: { synapse: settings },
+    natsConnect: async () => conn,
+    registerTool: (t) => tools.set(t.name, t),
+    registerTrigger: (t) => triggers.push(t),
+    registerPanel: (p) => panels.push(p),
+    log: (l) => logs.push(l),
+  }
+  return { tools, triggers, panels, logs, ctx }
+}
+
+// ─── config ─────────────────────────────────────────────────────────────────
+
+test('resolveConfig defaults (url, prefix=mesh, agentId=rterm-001)', () => {
+  const c = resolveConfig({ settings: {} }, {})
+  eq(c.servers, 'nats://localhost:4222', 'default url')
+  eq(c.prefix, 'mesh', 'default prefix')
+  eq(c.agentId, 'rterm-001', 'default agentId')
+  eq(c.enabled, true, 'enabled default')
+})
+
+test('resolveConfig reads settings.synapse block', () => {
+  const c = resolveConfig({ settings: { synapse: { url: 'nats://h:4222', prefix: 'mesh', agentId: 'rterm-x', auth: { token: 't' } } } }, {})
+  eq(c.servers, 'nats://h:4222', 'url from settings')
+  eq(c.agentId, 'rterm-x', 'agentId from settings')
+  eq(c.auth.token, 't', 'auth token')
+})
+
+// ─── envelope ───────────────────────────────────────────────────────────────
+
+test('envelope has Synapse v0.3.0 shape', () => {
+  const cfg = { agentId: 'rterm-001' }
+  const e = envelope('discover', { capabilities: [] }, cfg)
+  eq(e.v, '0.3.0', 'protocol version')
+  eq(e.type, 'discover', 'type')
+  eq(e.from, 'rterm-001', 'from = agentId')
+  assert(e.id, 'has id')
+  assert(e.ts, 'has ts')
+  assert(e.trace?.trace_id && e.trace?.span_id, 'has trace context')
+  assert(e.payload, 'has payload')
+})
+
+// ─── register wiring ────────────────────────────────────────────────────────
+
+test('register wires 5 tools, 1 trigger, 1 panel', () => {
+  const conn = fakeConn()
+  const { tools, triggers, panels, ctx } = mkCtx({}, conn)
+  register(ctx)
+  eq(tools.size, 5, 'tool count')
+  for (const n of ['synapse_health', 'synapse_discover', 'synapse_dispatch', 'synapse_register', 'synapse_agents_summary']) assert(tools.has(n), `missing ${n}`)
+  eq(triggers.length, 1, 'trigger count')
+  eq(triggers[0].name, 'synapse_mesh_event', 'trigger name')
+  eq(panels.length, 1, 'panel count')
+})
+
+// ─── discover ───────────────────────────────────────────────────────────────
+
+test('synapse_discover returns agents from registry', async () => {
+  const conn = fakeConn()
+  conn._on('mesh.registry.discover', () => [
+    { id: 'grip-cli-001', name: 'Grip CLI', skills: [{ id: 'himalaya' }] },
+    { id: 'agentspan-001', name: 'Agentspan', skills: [{ id: 'status' }] },
+  ])
+  const { tools, ctx } = mkCtx({}, conn)
+  register(ctx)
+  const r = await tools.get('synapse_discover').handler({})
+  eq(r.count, 2, 'agent count')
+  eq(r.agents[0].id, 'grip-cli-001', 'first agent')
+})
+
+test('synapse_discover passes filter through to the envelope', async () => {
+  __setConnForTest(null)
+  const conn = fakeConn()
+  let captured
+  conn._on('mesh.registry.discover', (env) => { captured = env; return [] })
+  const { tools, ctx } = mkCtx({}, conn)
+  register(ctx)
+  await tools.get('synapse_discover').handler({ capabilities: ['chat'], availability: 'online' })
+  eq(captured.type, 'discover', 'envelope type')
+  eq(captured.payload.availability, 'online', 'filter availability')
+  assert(Array.isArray(captured.payload.capabilities), 'filter capabilities')
+})
+
+// ─── dispatch ───────────────────────────────────────────────────────────────
+
+test('synapse_dispatch sends request to agent inbox + returns response', async () => {
+  __setConnForTest(null)
+  const conn = fakeConn()
+  let captured
+  conn._on('mesh.agent.grip-001.inbox', (env) => { captured = env; return { stream: 'AGENT_INBOXES', seq: 42 } })
+  const { tools, ctx } = mkCtx({}, conn)
+  register(ctx)
+  const r = await tools.get('synapse_dispatch').handler({ target: 'grip-001', skill: 'respond', input: { text: 'hi' } })
+  eq(r.response.seq, 42, 'response seq')
+  eq(captured.type, 'request', 'envelope type')
+  eq(captured.to, 'grip-001', 'envelope to')
+  eq(captured.payload.skill, 'respond', 'skill')
+  eq(captured.payload.input.text, 'hi', 'input')
+})
+
+test('synapse_dispatch requires target + skill', async () => {
+  const conn = fakeConn()
+  const { tools, ctx } = mkCtx({}, conn)
+  register(ctx)
+  const r = await tools.get('synapse_dispatch').handler({})
+  assert(r.error, 'expected error for missing target/skill')
+})
+
+// ─── register self ──────────────────────────────────────────────────────────
+
+test('synapse_register publishes a register envelope to the registry', async () => {
+  __setConnForTest(null)
+  const conn = fakeConn()
+  const { tools, ctx } = mkCtx({ agentId: 'rterm-001' }, conn)
+  register(ctx)
+  const r = await tools.get('synapse_register').handler({ name: 'RTerm', capabilities: ['ops'] })
+  eq(r.registered, 'rterm-001', 'registered id')
+  const pub = conn.published.find((p) => p.subject === 'mesh.registry.register')
+  assert(pub, 'expected a register publish')
+  eq(pub.data.type, 'register', 'envelope type')
+  eq(pub.data.payload.agent_id, 'rterm-001', 'payload agent_id')
+  assert(pub.data.payload.endpoint.includes('rterm-001.inbox'), 'endpoint inbox')
+})
+
+// ─── trigger match ──────────────────────────────────────────────────────────
+
+test('synapse_mesh_event trigger matches only synapse-source events', () => {
+  const conn = fakeConn()
+  const { triggers, ctx } = mkCtx({}, conn)
+  register(ctx)
+  const t = triggers[0]
+  assert(t.match({ source: 'synapse' }), 'matches synapse source')
+  assert(!t.match({ source: 'other' }), 'rejects other source')
+  assert(!t.match({}), 'rejects empty')
+})
+
+// ─── runner ─────────────────────────────────────────────────────────────────
+async function main() {
+  let pass = 0, fail = 0
+  for (const c of cases) {
+    try { await c.run(); pass++; console.log(`PASS ${c.name}`) }
+    catch (e) { fail++; console.log(`FAIL ${c.name}: ${e?.message ?? e}`) }
+  }
+  console.log(`\n${pass}/${pass + fail} passed, ${fail} failed`)
+  if (fail > 0) process.exit(1)
+}
+main()