rterm-backend 3.1.4 → 3.1.6

package/bin/gybackend.cjs

@@ -285128,24 +285128,41 @@ var init_natsEventBus = __esm({
         if (a.tlsCa) tls.ca = a.tlsCa;
         return tls;
       }
-      /** Connect to NATS (idempotent). Wires lifecycle event handlers. */
+      /** Connect to NATS (idempotent). Wires lifecycle event handlers.
+       * Concurrent callers share one in-flight attempt; a failed attempt clears the
+       * slot so the next call retries (no permanent half-connected state). */
+      connectPromise = null;
       async connect() {
-        if (this.conn) return;
-        const connectFn = this.opts.connectFn ?? ((o) => (0, import_transport_node.connect)(o));
-        const authenticator = this.buildAuthenticator();
-        const tls = this.buildTls();
-        const copts = {
-          servers: this.opts.servers,
-          name: this.opts.name ?? "rterm-backend",
-          ...authenticator ? { authenticator } : {},
-          ...tls ? { tls } : {},
-          ...this.opts.maxReconnectAttempts !== void 0 ? { maxReconnectAttempts: this.opts.maxReconnectAttempts } : {},
-          ...this.opts.reconnectTimeWait !== void 0 ? { reconnectTimeWait: this.opts.reconnectTimeWait } : {},
-          ...this.opts.timeout !== void 0 ? { timeout: this.opts.timeout } : {}
-        };
-        this.conn = await connectFn(copts);
-        this.wireStatusHandlers(this.conn);
-        this.log(`[nats] connected to ${Array.isArray(this.opts.servers) ? this.opts.servers.join(",") : this.opts.servers}`);
+        if (this.conn && !this.conn.isClosed()) return;
+        if (this.conn) {
+          this.conn = null;
+        }
+        if (this.connectPromise) return this.connectPromise;
+        const attempt = (async () => {
+          const connectFn = this.opts.connectFn ?? ((o) => (0, import_transport_node.connect)(o));
+          const authenticator = this.buildAuthenticator();
+          const tls = this.buildTls();
+          const copts = {
+            servers: this.opts.servers,
+            name: this.opts.name ?? "rterm-backend",
+            ...authenticator ? { authenticator } : {},
+            ...tls ? { tls } : {},
+            ...this.opts.maxReconnectAttempts !== void 0 ? { maxReconnectAttempts: this.opts.maxReconnectAttempts } : {},
+            ...this.opts.reconnectTimeWait !== void 0 ? { reconnectTimeWait: this.opts.reconnectTimeWait } : {},
+            ...this.opts.timeout !== void 0 ? { timeout: this.opts.timeout } : {}
+          };
+          const c = await connectFn(copts);
+          if (c.isClosed()) throw new Error("NATS connection closed immediately after connect");
+          this.conn = c;
+          this.wireStatusHandlers(c);
+          this.log(`[nats] connected to ${Array.isArray(this.opts.servers) ? this.opts.servers.join(",") : this.opts.servers}`);
+        })();
+        this.connectPromise = attempt;
+        try {
+          await attempt;
+        } finally {
+          this.connectPromise = null;
+        }
       }
       /** Attach reconnect/disconnect/error/lame-duck handlers (best-effort). */
       wireStatusHandlers(conn) {
@@ -289757,6 +289774,8 @@ function constructPort(Ctor, path32, opts) {
 }
 var SerialBackend = class {
   instances = /* @__PURE__ */ new Map();
+  /** ids whose port errored (removed from instances but remembered as 'failed'). */
+  failedIds = /* @__PURE__ */ new Set();
   /** For tests: inject a fake serialport constructor/factory. */
   static setSerialModuleForTest(mod) {
     injectedSerial = mod;
@@ -289811,7 +289830,10 @@ var SerialBackend = class {
     port.on("error", (err) => {
       instance.dataCallback?.(`\x1B[31m\u2718 Serial error: ${err.message}\x1B[0m\r
 `);
+      instance.failed = true;
       instance.exitCallback?.(-1);
+      this.instances.delete(ptyId);
+      this.failedIds.add(ptyId);
     });
     return Promise.resolve(ptyId);
   }
@@ -289822,6 +289844,7 @@ var SerialBackend = class {
   resize(_ptyId, _cols, _rows) {
   }
   kill(ptyId) {
+    this.failedIds.delete(ptyId);
     const inst = this.instances.get(ptyId);
     if (!inst) return;
     this.instances.delete(ptyId);
@@ -289853,8 +289876,9 @@ var SerialBackend = class {
   }
   getInitializationState(ptyId) {
     const inst = this.instances.get(ptyId);
-    if (!inst) return void 0;
-    return inst.ready ? "ready" : void 0;
+    if (inst) return inst.ready ? "ready" : void 0;
+    if (this.failedIds.has(ptyId)) return "failed";
+    return void 0;
   }
   // --- Serial-specific controls (v3.0.5) ---
   /** Send a BREAK signal (Cisco password recovery / ROMMON). Default 500ms. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rterm-backend",
-  "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.",
+  "version": "3.1.6",
+  "description": "Headless AI-native backend for RTerm / neuralOS — v3.1.6: full-duplex Synapse agent (responder, emit/subscribe, EXT-REPUTATION scoring, EXT-GOVERNANCE approvals) — RTerm speaks all six Synapse primitives + both extensions. 11 plugins. Transports (SSH/serial/local), SQLite, and NATS libs install automatically.",
   "main": "bin/gybackend.cjs",
   "bin": { "gybackend": "bin/gybackend.cjs" },
   "license": "MIT",

package/plugins/synapse-bridge/index.mjs

@@ -19,6 +19,12 @@
 
 import { createRequire } from 'node:module'
 import { randomUUID } from 'node:crypto'
+import {
+  startResponder, buildRespond, executeSkill,
+  emitEvent, subscribeEvents,
+  ReputationStore, computeScore, updateRecord, newRecord,
+  requestApproval, respondApproval, startApprover,
+} from './synapseAgent.mjs'
 
 const require = createRequire(import.meta.url)
 const enc = new TextEncoder()
@@ -75,20 +81,47 @@ function buildAuthenticator(t, auth) {
   return undefined
 }
 
-let _conn = null
+// Connection cache keyed by config fingerprint — a settings change (different
+// server/auth/agentId) opens a NEW connection instead of reusing a stale one to
+// the wrong server. A failed connect clears the slot so the next call retries.
+const _conns = new Map() // key -> Promise<conn> | conn
+function _configKey(cfg) {
+  const servers = Array.isArray(cfg.servers) ? cfg.servers.join(',') : cfg.servers
+  const authKeys = cfg.auth ? Object.keys(cfg.auth).sort().join(',') : ''
+  return `${servers}|${cfg.agentId}|${authKeys}`
+}
+
 async function connectMesh(ctx) {
-  if (_conn && !_conn.isClosed()) return _conn
   const cfg = resolveConfig(ctx)
+  const key = _configKey(cfg)
+  const existing = _conns.get(key)
+  if (existing) {
+    const c = await existing
+    if (c && !c.isClosed()) return c
+    _conns.delete(key) // stale/closed — fall through and reconnect
+  }
   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
+  const p = (async () => {
+    try {
+      return await connectFn(copts)
+    } catch (e) {
+      _conns.delete(key) // don't cache a failed attempt — allow retry
+      throw e
+    }
+  })()
+  _conns.set(key, p)
+  return p
 }
 
-/** Test hook: inject a fake connection. */
-export function __setConnForTest(c) { _conn = c }
+/** Test hook: inject a fake connection for a given config (or clear all with null). */
+export function __setConnForTest(c, cfg) {
+  if (c === null || c === undefined) { _conns.clear(); return }
+  const key = _configKey(cfg ?? resolveConfig({ settings: {} }))
+  _conns.set(key, Promise.resolve(c))
+}
 
 // ─── Synapse envelope ───────────────────────────────────────────────────────
 
@@ -228,6 +261,109 @@ export function register(ctx) {
     }, log),
   })
 
+  // ─── full-duplex agent capabilities (responder, emit/subscribe, reputation, governance) ───
+  const repStore = new ReputationStore()
+  let responderStop = null
+
+  registerTool({
+    name: 'synapse_serve',
+    description: 'Start RTerm as a full Synapse agent: listen on mesh.agent.{id}.inbox and respond() to incoming Synapse requests by mapping them to RTerm skills (playbooks/tools via ctx.rtermSkills / getRtermSkills). Bidirectional federation — other agents can now task RTerm.',
+    params: {
+      skills: { type: 'object', description: 'Map of skillId -> async (input, ctx) => output, the skills RTerm serves', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      const nc = await connectMesh(ctx)
+      const serveCtx = { ...ctx, rtermSkills: p?.skills ?? ctx.rtermSkills ?? {} }
+      if (responderStop) responderStop() // idempotent: restart with fresh skills
+      responderStop = await startResponder(nc, cfg, serveCtx, log)
+      const skillIds = Object.keys(serveCtx.rtermSkills)
+      return { serving: true, inbox: `${cfg.prefix}.agent.${cfg.agentId}.inbox`, skills: skillIds, note: 'RTerm is now a full Synapse agent (responder live)' }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_emit',
+    description: 'Emit a formal Synapse event on mesh.event.{type} (fire-and-forget broadcast to subscribers).',
+    params: {
+      type: { type: 'string', description: 'Event type, e.g. ops.change.committed' },
+      payload: { type: 'object', description: 'Event payload' },
+    },
+    handler: async (p) => guarded(async () => {
+      if (!p?.type) return { error: 'synapse_emit needs a type' }
+      const nc = await connectMesh(ctx)
+      emitEvent(nc, cfg, p.type, p.payload ?? {})
+      return { emitted: `${cfg.prefix}.event.${p.type}` }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_subscribe',
+    description: 'Subscribe to Synapse event/task subjects (supports wildcards, e.g. mesh.event.> or mesh.task.>.update). Events feed the local reputation store and the synapse_mesh_event trigger.',
+    params: {
+      subject: { type: 'string', description: 'Subject pattern, e.g. mesh.event.> or mesh.task.>.update' },
+    },
+    handler: async (p) => guarded(async () => {
+      const subject = p?.subject ?? `${cfg.prefix}.task.>.update`
+      const nc = await connectMesh(ctx)
+      const stop = await subscribeEvents(nc, subject, (env, subj) => {
+        repStore.handleTaskUpdate(env)
+        if (typeof ctx.emitEvent === 'function') ctx.emitEvent({ source: 'synapse', subject: subj, env })
+      })
+      return { subscribed: subject, note: 'events feed the reputation store + synapse_mesh_event trigger' }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_reputation',
+    description: 'Read the local Synapse reputation store (EXT-REPUTATION): per (agent, skill) success_rate, speed_score, freshness, composite score. Optionally record an outcome or list ranked agents.',
+    params: {
+      agent: { type: 'string', optional: true },
+      skill: { type: 'string', optional: true },
+      minScore: { type: 'number', description: 'Only agents at/above this score (discover-ranked)', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      if (p?.agent && p?.skill) {
+        const rec = repStore.get(p.agent, p.skill)
+        return rec ?? { error: `no record for ${p.agent}::${p.skill}` }
+      }
+      const ranked = repStore.ranked(p?.minScore ?? 0)
+      return { count: ranked.length, agents: ranked.map((r) => ({ agent: r.agent_id, skill: r.skill, score: Number(r.score.toFixed(3)), successRate: Number(r.success_rate.toFixed(3)), speedScore: Number(r.speed_score.toFixed(3)), confidence: r.confidence })) }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_request_approval',
+    description: 'Request governance approval for a gated action (EXT-GOVERNANCE): publish mesh.approval.{taskId}.request and await the response. Use before a high-risk dispatched task.',
+    params: {
+      originalRequest: { type: 'object', description: 'The original request payload being gated' },
+      policyId: { type: 'string', optional: true },
+      ruleId: { type: 'string', optional: true },
+      reason: { type: 'string', description: 'Why approval is required' },
+      taskId: { type: 'string', optional: true },
+      timeout: { type: 'number', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      const nc = await connectMesh(ctx)
+      const r = await requestApproval(nc, cfg, { taskId: p?.taskId, originalRequest: p?.originalRequest, policyId: p?.policyId, ruleId: p?.ruleId, reason: p?.reason ?? 'RTerm action requires mesh approval', timeout: p?.timeout })
+      return r.approved ? { approved: true, approver: r.approver, taskId: r.taskId } : { approved: false, taskId: r.taskId, note: 'denied or timed out' }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_approve',
+    description: 'Act as a governance approver (EXT-GOVERNANCE): listen on mesh.approval.*.request and answer each per a policy (allow-all, deny-all, or a decide map). Other agents route their gated actions through RTerm for approval.',
+    params: {
+      policy: { type: 'string', description: 'allow-all | deny-all (default allow-all)', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      const nc = await connectMesh(ctx)
+      const policy = p?.policy ?? 'allow-all'
+      const decide = async () => ({ approved: policy !== 'deny-all', approver: `did:mesh:${cfg.agentId}` })
+      await startApprover(nc, cfg, decide, log)
+      return { approver: cfg.agentId, policy, listening: `${cfg.prefix}.approval.*.request` }
+    }, 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.',
@@ -246,7 +382,7 @@ export function register(ctx) {
     },
   })
 
-  log(`[synapse] synapse-bridge registered: 5 tools, 1 trigger, 1 panel (agent=${cfg.agentId}, prefix=${cfg.prefix})`)
+  log(`[synapse] synapse-bridge registered: 11 tools, 1 trigger, 1 panel (agent=${cfg.agentId}, prefix=${cfg.prefix}, full-duplex)`)
 }
 
 export default { register, resolveConfig, envelope, discoverAgents, dispatchTask, registerSelf }

package/plugins/synapse-bridge/plugin.json

@@ -1,14 +1,20 @@
 {
   "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.",
+  "description": "Synapse mesh bridge for RTerm — full-duplex Synapse agent: discover live agents, dispatch tasks, register RTerm as a mesh agent, AND serve as one (respond to inbound requests), emit/subscribe mesh events, EXT-REPUTATION scoring, and EXT-GOVERNANCE approvals. 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"
+    "synapse_agents_summary",
+    "synapse_serve",
+    "synapse_emit",
+    "synapse_subscribe",
+    "synapse_reputation",
+    "synapse_request_approval",
+    "synapse_approve"
   ],
   "triggers": [
     "synapse_mesh_event"

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

@@ -69,12 +69,12 @@ test('envelope has Synapse v0.3.0 shape', () => {
 
 // ─── register wiring ────────────────────────────────────────────────────────
 
-test('register wires 5 tools, 1 trigger, 1 panel', () => {
+test('register wires 11 tools, 1 trigger, 1 panel (full-duplex)', () => {
   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(tools.size, 11, 'tool count')
+  for (const n of ['synapse_health', 'synapse_discover', 'synapse_dispatch', 'synapse_register', 'synapse_agents_summary', 'synapse_serve', 'synapse_emit', 'synapse_subscribe', 'synapse_reputation', 'synapse_request_approval', 'synapse_approve']) 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')
@@ -161,6 +161,51 @@ test('synapse_mesh_event trigger matches only synapse-source events', () => {
   assert(!t.match({}), 'rejects empty')
 })
 
+// ─── connection cache (config-keyed, the stale-connection bug fix) ──────────
+
+test('connection is keyed by config — a settings change opens a NEW connection (no stale reuse)', async () => {
+  __setConnForTest(null)
+  const connA = fakeConn()
+  const connB = fakeConn()
+  const connsMade = []
+  // ctx whose natsConnect returns a different fake per call, tracking which config connected
+  const mkCtxMulti = (settings) => ({
+    settings: { synapse: settings },
+    natsConnect: async (copts) => { connsMade.push(copts); return connsMade.length === 1 ? connA : connB },
+    registerTool: () => {}, registerTrigger: () => {}, registerPanel: () => {}, log: () => {},
+  })
+  // connect with config A (server A)
+  const { discoverAgents: dA } = await import('./index.mjs')
+  connA._on('mesh.registry.discover', () => [])
+  await dA(mkCtxMulti({ url: 'nats://a:4222' }), {})
+  if (connsMade.length !== 1) throw new Error(`expected 1 connection for config A, got ${connsMade.length}`)
+  // same config A again — must REUSE (no new connection)
+  await dA(mkCtxMulti({ url: 'nats://a:4222' }), {})
+  if (connsMade.length !== 1) throw new Error(`expected reuse for same config A, got ${connsMade.length} connections`)
+  // config B (different server) — must open a NEW connection (the bug was reusing A's)
+  connB._on('mesh.registry.discover', () => [])
+  await dA(mkCtxMulti({ url: 'nats://b:4222' }), {})
+  if (connsMade.length !== 2) throw new Error(`expected a NEW connection for config B, got ${connsMade.length}`)
+})
+
+test('a failed connect is not cached — the next call retries', async () => {
+  __setConnForTest(null)
+  const conn = fakeConn()
+  conn._on('mesh.registry.discover', () => [])
+  let attempts = 0
+  const ctx = {
+    settings: { synapse: { url: 'nats://a:4222' } },
+    natsConnect: async () => { attempts++; if (attempts === 1) throw new Error('down'); return conn },
+    registerTool: () => {}, registerTrigger: () => {}, registerPanel: () => {}, log: () => {},
+  }
+  const { discoverAgents } = await import('./index.mjs')
+  let threw = false
+  try { await discoverAgents(ctx, {}) } catch { threw = true }
+  if (!threw) throw new Error('expected first attempt to throw')
+  await discoverAgents(ctx, {}) // retry succeeds
+  if (attempts !== 2) throw new Error(`expected 2 attempts (fail + retry), got ${attempts}`)
+})
+
 // ─── runner ─────────────────────────────────────────────────────────────────
 async function main() {
   let pass = 0, fail = 0

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

@@ -0,0 +1,236 @@
+import {
+  buildRespond, executeSkill, startResponder,
+  emitEvent, subscribeEvents,
+  ReputationStore, computeScore, updateRecord, newRecord, REP_WEIGHTS,
+  requestApproval, respondApproval, startApprover,
+} from './synapseAgent.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)}`) }
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+const CFG = { agentId: 'rterm-001', prefix: 'mesh' }
+
+// ─── fake NATS connection (pub/sub + request/reply) ─────────────────────────
+// NATS wildcard grammar: '*' matches one token, '>' matches one or more (suffix).
+function subjectMatches(pattern, subject) {
+  if (pattern === subject) return true
+  const p = pattern.split('.')
+  const s = subject.split('.')
+  for (let i = 0; i < p.length; i++) {
+    if (p[i] === '>') return true
+    if (i >= s.length) return false
+    if (p[i] !== '*' && p[i] !== s[i]) return false
+  }
+  return p.length === s.length
+}
+
+function fakeConn() {
+  const published = []
+  const subs = new Map()
+  const requests = new Map()
+  const deliver = (subject, data, respondFn) => {
+    for (const [pattern, fns] of subs) {
+      if (subjectMatches(pattern, subject)) {
+        for (const fn of fns) fn({ data, subject, respond: respondFn })
+      }
+    }
+  }
+  return {
+    isClosed: () => false,
+    published,
+    publish(subject, data) {
+      const env = JSON.parse(dec.decode(data))
+      published.push({ subject, env })
+      deliver(subject, data, (p) => { published.push({ subject: '_reply', env: JSON.parse(dec.decode(p)) }) })
+    },
+    subscribe(subject) {
+      return {
+        async *[Symbol.asyncIterator]() {
+          while (true) {
+            const m = await new Promise((res) => {
+              const l = subs.get(subject) ?? []; subs.set(subject, l); l.push(res)
+            })
+            yield m
+          }
+        },
+        unsubscribe: () => subs.delete(subject),
+      }
+    },
+    async request(subject, data, _o) {
+      const env = JSON.parse(dec.decode(data))
+      const h = requests.get(subject)
+      const reply = h ? h(env) : { payload: { approved: true, approver: 'did:mesh:approver' } }
+      return { data: enc.encode(JSON.stringify(reply)) }
+    },
+    _deliver(subject, env) {
+      const data = enc.encode(JSON.stringify(env))
+      deliver(subject, data, (p) => { published.push({ subject: '_reply', env: JSON.parse(dec.decode(p)) }) })
+    },
+    _onRequest(subject, h) { requests.set(subject, h) },
+  }
+}
+
+// ─── 1. RESPONDER ────────────────────────────────────────────────────────────
+
+test('buildRespond: output envelope has to/task_id/in_reply_to + output payload', () => {
+  const req = { id: 'req-1', from: 'caller-001', task_id: 'task-9', payload: { skill: 'x' } }
+  const r = buildRespond(req, CFG, { output: { result: 42 } })
+  eq(r.type, 'respond', 'type')
+  eq(r.to, 'caller-001', 'to = original from')
+  eq(r.task_id, 'task-9', 'task_id')
+  eq(r.in_reply_to, 'req-1', 'in_reply_to = original id')
+  eq(r.payload.output.result, 42, 'output payload')
+  assert(!r.payload.error, 'no error when output present')
+})
+
+test('buildRespond: error envelope has error payload, no output; output+error throws', () => {
+  const req = { id: 'r2', from: 'c', task_id: 't' }
+  const r = buildRespond(req, CFG, { error: { code: 3001, message: 'nf' } })
+  eq(r.payload.error.code, 3001, 'error code')
+  assert(!r.payload.output, 'no output when error present')
+  let threw = false
+  try { buildRespond(req, CFG, { output: {}, error: { code: 1 } }) } catch { threw = true }
+  assert(threw, 'output+error must throw')
+})
+
+test('executeSkill: known skill returns output; unknown returns 3001 SKILL_NOT_FOUND', async () => {
+  const ctx = { rtermSkills: { greet: async (inp) => ({ hello: inp.name }) } }
+  const ok = await executeSkill('greet', { name: 'mesh' }, ctx)
+  eq(ok.output.hello, 'mesh', 'skill output')
+  const nf = await executeSkill('nope', {}, ctx)
+  eq(nf.error.code, 3001, 'SKILL_NOT_FOUND code')
+})
+
+test('startResponder: inbound request executes skill + responds on reply inbox', async () => {
+  const nc = fakeConn()
+  const ctx = { rtermSkills: { status: async () => ({ up: true }) } }
+  const stop = await startResponder(nc, CFG, ctx)
+  nc._deliver('mesh.agent.rterm-001.inbox', { id: 'q1', from: 'caller-001', task_id: 't1', payload: { skill: 'status', input: {} } })
+  await new Promise((r) => setTimeout(r, 20))
+  const reply = nc.published.find((p) => p.subject === '_reply')
+  assert(reply, 'expected a respond on the reply inbox')
+  eq(reply.env.type, 'respond', 'respond type')
+  eq(reply.env.to, 'caller-001', 'respond to caller')
+  eq(reply.env.payload.output.up, true, 'skill output delivered')
+  stop()
+})
+
+// ─── 2. EMIT / SUBSCRIBE ─────────────────────────────────────────────────────
+
+test('emitEvent publishes a formal emit envelope on mesh.event.{type}', () => {
+  const nc = fakeConn()
+  emitEvent(nc, CFG, 'ops.change.committed', { changeId: 'chg-1' })
+  const pub = nc.published.find((p) => p.subject === 'mesh.event.ops.change.committed')
+  assert(pub, 'expected emit publish')
+  eq(pub.env.type, 'emit', 'emit type')
+  eq(pub.env.payload.changeId, 'chg-1', 'emit payload')
+})
+
+test('subscribeEvents invokes handler for each event on the subject', async () => {
+  const nc = fakeConn()
+  const seen = []
+  const stop = await subscribeEvents(nc, 'mesh.event.>', (env, subj) => seen.push({ env, subj }))
+  nc._deliver('mesh.event.>', { type: 'emit', payload: { n: 1 } })
+  await new Promise((r) => setTimeout(r, 20))
+  eq(seen.length, 1, 'one event seen')
+  stop()
+})
+
+// ─── 3. REPUTATION ───────────────────────────────────────────────────────────
+
+test('computeScore: perfect record scores high', () => {
+  const rec = newRecord('a1', 'respond')
+  for (let i = 0; i < 5; i++) updateRecord(rec, { status: 'completed', latencyMs: 100 })
+  const s = computeScore(rec)
+  eq(s.success_rate, 1, 'success_rate 1')
+  assert(s.score > 0.8, `high score expected, got ${s.score}`)
+  eq(s.confidence, 1.0, 'full confidence at >=min samples')
+})
+
+test('updateRecord: failures lower success_rate + score', () => {
+  const rec = newRecord('a2', 'respond')
+  updateRecord(rec, { status: 'completed', latencyMs: 100 })
+  updateRecord(rec, { status: 'failed' })
+  updateRecord(rec, { status: 'timeout' })
+  const s = computeScore(rec)
+  assert(s.success_rate < 0.5, `success_rate should be low, got ${s.success_rate}`)
+  assert(s.score < 0.7, `score should be lower, got ${s.score}`)
+})
+
+test('reputation: 3 consecutive SKILL_NOT_FOUND flags lying-agent + zeroes score', () => {
+  const rec = newRecord('liar', 'respond')
+  updateRecord(rec, { status: 'skill_not_found' })
+  updateRecord(rec, { status: 'skill_not_found' })
+  updateRecord(rec, { status: 'skill_not_found' })
+  assert(rec.flags.misleading_capabilities, 'lying-agent flag set')
+  eq(rec.flags.penalty_reason.includes('SKILL_NOT_FOUND'), true, 'penalty reason')
+  const s = computeScore(rec)
+  eq(s.score, 0, 'lying penalty zeroes the score')
+})
+
+test('ReputationStore: observe + ranked + handleTaskUpdate', () => {
+  const store = new ReputationStore()
+  store.observe('a1', 'respond', { status: 'completed', latencyMs: 50 })
+  store.observe('a1', 'respond', { status: 'completed', latencyMs: 60 })
+  store.observe('a2', 'respond', { status: 'failed' })
+  const rec = store.get('a1', 'respond')
+  eq(rec.successes, 2, 'two successes recorded')
+  // task_update event path
+  store.handleTaskUpdate({ payload: { agent: 'a1', skill: 'respond', status: 'completed', latencyMs: 40 } })
+  eq(store.get('a1', 'respond').successes, 3, 'task_update fed the store')
+  const ranked = store.ranked(0)
+  assert(ranked.length >= 2, 'ranked returns all')
+  eq(ranked[0].agent_id, 'a1', 'a1 (higher score) ranks first')
+})
+
+// ─── 4. GOVERNANCE ───────────────────────────────────────────────────────────
+
+test('requestApproval publishes approval_request + returns approved response', async () => {
+  const nc = fakeConn()
+  let captured
+  nc._onRequest('mesh.approval.task-1.request', (env) => { captured = env; return { payload: { approved: true, approver: 'did:mesh:approver-001' } } })
+  const r = await requestApproval(nc, CFG, { taskId: 'task-1', originalRequest: { skill: 'pay' }, reason: 'payment needs approval' })
+  eq(captured.type, 'approval_request', 'request type')
+  eq(captured.task_id, 'task-1', 'request task_id')
+  eq(captured.payload.reason, 'payment needs approval', 'reason')
+  eq(r.approved, true, 'approved')
+  eq(r.approver, 'did:mesh:approver-001', 'approver')
+})
+
+test('respondApproval publishes approval_response on mesh.approval.{taskId}.response', () => {
+  const nc = fakeConn()
+  const req = { id: 'ar-1', from: 'agent-bob-001', task_id: 'task-7' }
+  respondApproval(nc, CFG, req, { approved: false, approver: 'did:mesh:rterm-001' })
+  const pub = nc.published.find((p) => p.subject === 'mesh.approval.task-7.response')
+  assert(pub, 'expected approval_response publish')
+  eq(pub.env.type, 'approval_response', 'response type')
+  eq(pub.env.to, 'agent-bob-001', 'to original requester')
+  eq(pub.env.payload.approved, false, 'denied')
+})
+
+test('startApprover answers inbound approval requests per the decide fn', async () => {
+  const nc = fakeConn()
+  const stop = await startApprover(nc, CFG, async () => ({ approved: true, approver: 'did:mesh:rterm-001' }))
+  nc._deliver('mesh.approval.task-9.request', { id: 'ar-9', from: 'agent-x', task_id: 'task-9', type: 'approval_request', payload: {} })
+  await new Promise((r) => setTimeout(r, 20))
+  const pub = nc.published.find((p) => p.subject === 'mesh.approval.task-9.response')
+  assert(pub, 'expected approver to answer')
+  eq(pub.env.payload.approved, true, 'approved by decide fn')
+  stop()
+})
+
+// ─── 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/synapse-bridge/synapseAgent.mjs

@@ -0,0 +1,254 @@
+/**
+ * synapseAgent — full-duplex Synapse agent capabilities for RTerm/neuralOS.
+ *
+ * Implements the four pieces that turn RTerm from a Synapse *client* into a full
+ * Synapse *agent* (EXT-GOVERNANCE + EXT-REPUTATION aware):
+ *
+ *   1. RESPONDER — listen on mesh.agent.{id}.inbox and respond() to incoming
+ *      Synapse requests by mapping them to RTerm skills (playbooks/tools).
+ *   2. EMIT/SUBSCRIBE — formal Synapse `emit` on mesh.event.{type} + wildcard
+ *      subscribe to mesh.event.* / mesh.task.* streams.
+ *   3. REPUTATION (EXT-REPUTATION) — observe task outcomes and maintain a local
+ *      ReputationRecord per (agent, skill): success_rate, speed_score, freshness,
+ *      composite score with lying-penalty + confidence, per Formula 11.5.
+ *   4. GOVERNANCE (EXT-GOVERNANCE) — speak mesh.approval.{task_id}.request/.response:
+ *      request approval for gated actions and answer approval requests (approver side).
+ *
+ * Transport is the injected NATS connection from the plugin (connectMesh). All pure
+ * logic (score formula, response building, record updates) is dependency-free + testable.
+ */
+
+import { randomUUID } from 'node:crypto'
+import { envelope } from './index.mjs'
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+const j = (v) => enc.encode(JSON.stringify(v))
+const uj = (b) => JSON.parse(dec.decode(b))
+
+// ─── 1. RESPONDER ────────────────────────────────────────────────────────────
+
+/** Build a Synapse respond envelope (payload has output XOR error). */
+export function buildRespond(requestEnv, cfg, { output, error } = {}) {
+  if (output && error) throw new Error('respond must contain output OR error, not both')
+  const payload = error ? { error } : { output: output ?? {} }
+  return envelope('respond', payload, cfg, {
+    to: requestEnv?.from,
+    task_id: requestEnv?.task_id,
+    in_reply_to: requestEnv?.id,
+  })
+}
+
+/** Map a Synapse skill id to an RTerm handler. The plugin supplies handlers for
+ * the skills RTerm advertises (playbooks/tools). Returns {output} or {error}. */
+export async function executeSkill(skillId, input, ctx) {
+  const skills = (typeof ctx.getRtermSkills === 'function' ? ctx.getRtermSkills() : ctx.rtermSkills) || {}
+  const handler = skills[skillId]
+  if (!handler) {
+    return { error: { code: 3001, message: `SKILL_NOT_FOUND: ${skillId}`, retryable: false } }
+  }
+  try {
+    const output = await handler(input ?? {}, ctx)
+    return { output: output ?? {} }
+  } catch (e) {
+    return { error: { code: 5000, message: String(e?.message ?? e), retryable: true } }
+  }
+}
+
+/** Start the responder loop: subscribe to mesh.agent.{id}.inbox, execute each
+ * request, and respond on the reply inbox. Returns a stop function. */
+export async function startResponder(nc, cfg, ctx, log = () => {}) {
+  const inbox = `${cfg.prefix}.agent.${cfg.agentId}.inbox`
+  const sub = nc.subscribe(inbox)
+  let stopped = false
+  const loop = (async () => {
+    for await (const msg of sub) {
+      if (stopped) break
+      ;(async () => {
+        try {
+          const req = uj(msg.data)
+          const skillId = req?.payload?.skill
+          const input = req?.payload?.input
+          log(`[synapse] inbound request from ${req?.from} skill=${skillId} task=${req?.task_id}`)
+          const result = await executeSkill(skillId, input, ctx)
+          const respond = buildRespond(req, cfg, result)
+          msg.respond(j(respond))
+        } catch (e) {
+          try { msg.respond(j({ error: { code: 5000, message: String(e?.message ?? e), retryable: true } })) } catch { /* best-effort */ }
+        }
+      })()
+    }
+  })()
+  loop.catch(() => {})
+  return () => { stopped = true; try { sub.unsubscribe() } catch {} }
+}
+
+// ─── 2. EMIT / SUBSCRIBE ─────────────────────────────────────────────────────
+
+/** Emit a formal Synapse event on mesh.event.{type}. */
+export function emitEvent(nc, cfg, eventType, payload, extra = {}) {
+  nc.publish(`${cfg.prefix}.event.${eventType}`, j(envelope('emit', payload, cfg, extra)))
+}
+
+/** Subscribe to a Synapse event/task subject (supports wildcards). Returns stop fn. */
+export async function subscribeEvents(nc, subject, handler) {
+  const sub = nc.subscribe(subject)
+  const loop = (async () => {
+    for await (const msg of sub) {
+      try { handler(uj(msg.data), msg.subject) } catch { /* ignore malformed */ }
+    }
+  })()
+  loop.catch(() => {})
+  return () => { try { sub.unsubscribe() } catch {} }
+}
+
+// ─── 3. REPUTATION (EXT-REPUTATION) ──────────────────────────────────────────
+
+export const REP_WEIGHTS = { success: 0.7, speed: 0.2, freshness: 0.1 }
+export const REP_DEFAULTS = { maxLatencyMs: 30000, freshnessHalfLifeHours: 24, minSampleSize: 3 }
+
+/** A ReputationRecord for one (agent, skill) pair. */
+export function newRecord(agentId, skill) {
+  return {
+    agent_id: agentId, skill,
+    total: 0, successes: 0, failures: 0, timeouts: 0,
+    skill_not_found: 0, overloaded: 0, rate_limited: 0,
+    latencies_ms: [],
+    success_rate: 0, speed_score: 0, freshness: 1, score: 0, confidence: 0.5,
+    flags: { misleading_capabilities: false, consecutive_skill_not_found: 0, last_penalty_at: null, penalty_reason: null },
+    last_seen: null,
+  }
+}
+
+/** Compute composite score per Formula 11.5. Pure. */
+export function computeScore(rec, weights = REP_WEIGHTS, defaults = REP_DEFAULTS, now = Date.now()) {
+  const outcomes = rec.successes + rec.failures + rec.timeouts
+  const success_rate = rec.successes / Math.max(1, outcomes)
+  const avgLatency = rec.latencies_ms.length ? rec.latencies_ms.reduce((a, b) => a + b, 0) / rec.latencies_ms.length : 0
+  const speed_score = success_rate > 0 ? 1 - Math.min(1, Math.max(0, avgLatency / defaults.maxLatencyMs)) : 0
+  const hoursSince = rec.last_seen ? (now - rec.last_seen) / 3600000 : 0
+  const freshness = Math.exp(-hoursSince / defaults.freshnessHalfLifeHours)
+  const confidence = outcomes >= defaults.minSampleSize ? 1.0 : 0.5
+  const lying_penalty = rec.flags.misleading_capabilities ? 0.0 : 1.0
+  const raw = weights.success * success_rate + weights.speed * speed_score + weights.freshness * freshness
+  const score = raw * lying_penalty * confidence
+  return { success_rate, speed_score, freshness, confidence, score }
+}
+
+/** Update a record from an observed task outcome. Pure-ish (returns the mutated record).
+ * outcome: { status: 'completed'|'failed'|'timeout'|'skill_not_found'|'overloaded'|'rate_limited', latencyMs? } */
+export function updateRecord(rec, outcome, defaults = REP_DEFAULTS, now = Date.now()) {
+  rec.total += 1
+  rec.last_seen = now
+  const st = outcome.status
+  if (st === 'completed') {
+    rec.successes += 1
+    rec.flags.consecutive_skill_not_found = 0
+    if (typeof outcome.latencyMs === 'number') rec.latencies_ms.push(outcome.latencyMs)
+  } else if (st === 'failed') {
+    rec.failures += 1
+    rec.flags.consecutive_skill_not_found = 0
+  } else if (st === 'timeout') {
+    rec.timeouts += 1
+    rec.flags.consecutive_skill_not_found = 0
+  } else if (st === 'skill_not_found') {
+    rec.skill_not_found += 1
+    rec.flags.consecutive_skill_not_found += 1
+    if (rec.flags.consecutive_skill_not_found >= 3) {
+      rec.flags.misleading_capabilities = true
+      rec.flags.penalty_reason = 'repeated SKILL_NOT_FOUND (lying-agent)'
+      rec.flags.last_penalty_at = new Date(now).toISOString()
+    }
+  } else if (st === 'overloaded') {
+    rec.overloaded += 1 // recorded, not scored
+  } else if (st === 'rate_limited') {
+    rec.rate_limited += 1 // recorded, not scored
+  }
+  const s = computeScore(rec, REP_WEIGHTS, defaults, now)
+  rec.success_rate = s.success_rate
+  rec.speed_score = s.speed_score
+  rec.freshness = s.freshness
+  rec.confidence = s.confidence
+  rec.score = s.score
+  return rec
+}
+
+/** Local ReputationStore: keyed {agent}::{skill}, fed by task_update events. */
+export class ReputationStore {
+  constructor(defaults = REP_DEFAULTS) {
+    this.defaults = defaults
+    this.records = new Map()
+  }
+  key(agentId, skill) { return `${agentId}::${skill}` }
+  get(agentId, skill) { return this.records.get(this.key(agentId, skill)) }
+  observe(agentId, skill, outcome, now = Date.now()) {
+    const k = this.key(agentId, skill)
+    let rec = this.records.get(k)
+    if (!rec) { rec = newRecord(agentId, skill); this.records.set(k, rec) }
+    return updateRecord(rec, outcome, this.defaults, now)
+  }
+  /** discover-ranked: all records at/above minScore, sorted by score desc. */
+  ranked(minScore = 0) {
+    return [...this.records.values()].filter((r) => r.score >= minScore).sort((a, b) => b.score - a.score)
+  }
+  /** Feed a mesh.task.{id}.update event (type task_update with payload {agent, skill, status, latencyMs?}). */
+  handleTaskUpdate(env, now = Date.now()) {
+    const p = env?.payload ?? {}
+    if (!p.agent || !p.skill || !p.status) return null
+    return this.observe(p.agent, p.skill, { status: p.status, latencyMs: p.latencyMs }, now)
+  }
+}
+
+// ─── 4. GOVERNANCE (EXT-GOVERNANCE) ──────────────────────────────────────────
+
+/** Request approval for a gated action: publish mesh.approval.{taskId}.request and
+ * await the response. Returns { approved, approver } or { approved: false, error }. */
+export async function requestApproval(nc, cfg, { taskId, originalRequest, policyId, ruleId, reason, timeout = 30000 }) {
+  const tid = taskId ?? randomUUID()
+  const env = envelope('approval_request', {
+    original_request: originalRequest ?? {},
+    policy_id: policyId,
+    rule_id: ruleId,
+    reason,
+  }, cfg, { task_id: tid })
+  const msg = await nc.request(`${cfg.prefix}.approval.${tid}.request`, j(env), { timeout })
+  const reply = uj(msg.data)
+  const p = reply?.payload ?? reply
+  return { approved: p?.approved === true, approver: p?.approver, taskId: tid, raw: reply }
+}
+
+/** Answer an approval request (approver side): publish mesh.approval.{taskId}.response. */
+export function respondApproval(nc, cfg, requestEnv, { approved, approver }) {
+  const tid = requestEnv?.task_id
+  const env = envelope('approval_response', { approved: approved === true, approver }, cfg, {
+    to: requestEnv?.from,
+    task_id: tid,
+    in_reply_to: requestEnv?.id,
+  })
+  nc.publish(`${cfg.prefix}.approval.${tid}.response`, j(env))
+  return { answered: tid, approved: approved === true }
+}
+
+/** Start an approver loop: subscribe to mesh.approval.*.request and answer each per
+ * the supplied decide() function ({approved, approver} or a policy name). Returns stop fn. */
+export async function startApprover(nc, cfg, decide, log = () => {}) {
+  const sub = nc.subscribe(`${cfg.prefix}.approval.*.request`)
+  let stopped = false
+  const loop = (async () => {
+    for await (const msg of sub) {
+      if (stopped) break
+      ;(async () => {
+        try {
+          const req = uj(msg.data)
+          const decision = await decide(req)
+          respondApproval(nc, cfg, req, decision)
+          log(`[synapse] approval ${decision.approved ? 'granted' : 'denied'} for task ${req?.task_id}`)
+        } catch (e) {
+          log(`[synapse] approval handling error: ${e?.message ?? e}`)
+        }
+      })()
+    }
+  })()
+  loop.catch(() => {})
+  return () => { stopped = true; try { sub.unsubscribe() } catch {} }
+}